{
  "openapi": "3.1.0",
  "info": {
    "title": "Kit Finder by Agentropolis",
    "version": "0.1.0",
    "summary": "Describe your project; get a ranked, trust-scored stack of agent tools and paid APIs (fit + trust only, no first-party boost).",
    "description": "Describe your project in plain English; get a ranked shortlist of tools for each thing it needs: MCP servers, x402 / MPP paid APIs and agent kits from the Agentropolis catalog, each with price, payment-verified trust score, why it fits, and risky-seller flags (wash trading, unproven paid sellers, wide price ranges), plus an estimated stack cost per run and a link out to the x402 Bazaar. Ranked by fit + trust only: Agentropolis's own kits get no boost and paid placement is never read. Advisory. $0.05 USDC per call.",
    "contact": {
      "name": "Agentropolis",
      "email": "hello@agentropolis.io",
      "url": "https://agentropolis.io"
    },
    "x-guidance": "POST /api/find with {description}; use needs[].picks in rank order, read flags before paying a seller, check stack_cost_per_run against your budget."
  },
  "servers": [
    {
      "url": "https://seenly-kit-finder.vercel.app"
    }
  ],
  "paths": {
    "/api/find": {
      "post": {
        "operationId": "findKits",
        "summary": "Ranked tool stack for a plain-English project description (advisory)",
        "description": "$0.05 USDC per call on Base mainnet. Invalid → 422 before payment. Settles only on success (fetch failures are not charged).",
        "tags": [
          "Kit Finder"
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.05"
          },
          "protocols": [
            {
              "x402": {}
            }
          ],
          "rails": [
            {
              "protocol": "x402",
              "version": 2,
              "scheme": "exact",
              "network": "eip155:8453",
              "networkName": "Base mainnet",
              "asset": "USDC",
              "assetAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
              "amount": "50000",
              "priceUsd": "0.05",
              "payTo": "0xeE6239F3E17bEBe5e89F21F29D74D68CAa0d78CE",
              "facilitator": "Coinbase CDP (gas sponsored; payer needs no ETH)",
              "header": "PAYMENT-SIGNATURE"
            }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FindRequest"
              },
              "examples": {
                "project": {
                  "value": {
                    "description": "An AI research agent that searches the web, scrapes about 20 pages, summarizes them, and emails me a daily report on competitors in the solar panel market.",
                    "budget_per_run_usd": 0.5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ranked tool stack",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FindResult"
                }
              }
            }
          },
          "402": {
            "description": "Payment required (x402 v2)"
          },
          "404": {
            "description": "Source not found (not charged)"
          },
          "413": {
            "description": "Source too large (not charged)"
          },
          "422": {
            "description": "invalid_request (not charged)"
          },
          "429": {
            "description": "rate_limited"
          },
          "502": {
            "description": "Source host unavailable (not charged)"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "FindRequest": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "minLength": 12,
            "maxLength": 2000,
            "description": "Plain-English description of your project / agent and what it needs to do."
          },
          "budget_per_run_usd": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000,
            "description": "Optional: your per-run tool budget in USD (the result says whether the suggested stack fits)."
          },
          "paid_only": {
            "type": "boolean",
            "description": "Optional: only paid (x402 / MPP) tools."
          },
          "max_results": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5,
            "description": "Optional: picks per need (default 3)."
          },
          "requestKey": {
            "type": "string",
            "maxLength": 128
          }
        },
        "required": [
          "description"
        ]
      },
      "FindResult": {
        "type": "object",
        "example": {
          "kit": "seenly.kit-finder",
          "advisory": true,
          "summary": "The agent needs web search, page scraping and email sending.",
          "needs": [
            {
              "need": "web search",
              "why": "Find competitor news and pages each day.",
              "calls_per_run": 1,
              "searched": [
                "web search API",
                "search engine"
              ],
              "picks": [
                {
                  "rank": 1,
                  "id": "x402.you-com-search-api",
                  "name": "You.com Search API",
                  "kind": "http_api",
                  "listing_url": "https://agentropolis.io/listing/x402.you-com-search-api",
                  "price": "$0.005–$0.11 per call (x402)",
                  "price_usd": {
                    "min": 0.005,
                    "max": 0.11
                  },
                  "trust": {
                    "score": 89,
                    "evidence": "verified_non_wash_payments"
                  },
                  "fit": 95,
                  "score": 91.8,
                  "why": "General web search returning ranked results an agent can scrape next.",
                  "flags": [
                    "wide_price_range: $0.005–$0.11 per call (x402); check the live 402 before paying"
                  ],
                  "buy": {
                    "how": "Pay per call with x402 through the Agentropolis relay (non-custodial) or call the seller directly.",
                    "relay": "https://agentropolis.io/api/v1/call/x402.you-com-search-api"
                  }
                }
              ]
            }
          ],
          "stack_cost_per_run": {
            "min_usd": 0.105,
            "max_usd": 0.21,
            "basis": "Top pick per need x estimated calls per run, from listed prices. Seller runtime 402 challenges are authoritative.",
            "unpriced_needs": [
              "email sending"
            ],
            "budget_usd": 0.5,
            "within_budget": true
          },
          "risky_sellers": [],
          "also_search": [
            {
              "name": "Coinbase Agentic.Market (x402 Bazaar)",
              "url": "https://agentic.market/?q=web%20search",
              "note": "Link-out only. We do not cache or republish CDP Bazaar data."
            }
          ],
          "fairness": "Ranked by fit + trust only. Agentropolis's own kits get no boost; paid placement is never read.",
          "check_version": "kit-finder-0.1.0"
        }
      }
    }
  }
}