> For the complete documentation index, see [llms.txt](https://docs.vapinetwork.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vapinetwork.ai/protocol/discovery-api.md). # Discovery API The discovery wire contract retains the compatibility identifier `vapi.marketplace.discovery/1`. The vAPI web app, hosted MCP, and the buyer-local wallet use this language-neutral contract to exchange discovery results. ## Discovery page Each response contains: | Field | Meaning | | ------------------ | -------------------------------------------------------------------------- | | `protocol` | The exact wire-contract identifier, `vapi.marketplace.discovery/1` | | `items` | API listings, service offers, and public open requests | | `nextCursor` | The next opaque pagination cursor, or `null` | | `unavailableKinds` | Requested kinds that were unavailable when the page was built | | `rankingVersion` | The ranking contract used for the page, currently `marketplace-ranking-v1` | Every item has an opaque `ref`, a `kind`, a display `card`, and an `action`. Do not infer execution behavior from the shape of `ref`. Inspect `kind` and, for API results, `provenance` before choosing an execution path. | `kind` | Action | Client behavior | | --------------- | -------------------- | ------------------------------------------------------------------- | | `api` | `invoke_api` | Invoke through an API-capable client such as the buyer-local wallet | | `service_offer` | `start_engagement` | Open the supplied discovery action | | `open_request` | `propose_to_request` | Open the supplied discovery action | An API's `provenance` is `self_listed`, `partner`, or `indexed`. Its `execution` object describes the execution mode. Indexed API results also carry the published HTTPS URL, nullable method, and CAIP-2 network. A `null` `execution.method` means the source did not publish a method. ## Card and action shape The `card` gives clients presentation-ready metadata: * `title` and `summary` * optional `byline` and `bylineHref` * `badges`, expressed as stable codes with display labels * `facts`, expressed as label-value pairs The `action` pairs a product-specific action type with a relative or HTTPS `href`. API references from vAPI are the existing Call service slug. Other references remain source-native and opaque. This compatibility fixture shows all three discovery kinds: ```json { "protocol": "vapi.marketplace.discovery/1", "items": [ { "ref": "weather-call", "kind": "api", "provenance": "self_listed", "execution": { "mode": "direct" }, "card": { "title": "Weather Call", "summary": "Returns current weather through a payable endpoint.", "byline": "vAPI Network", "badges": [ { "code": "live_x402", "label": "Live x402" }, { "code": "vapi_verified", "label": "vAPI verified" } ], "facts": [ { "label": "Price", "value": "$0.0021" }, { "label": "Network", "value": "eip155:8453" } ] }, "action": { "type": "invoke_api", "href": "/call/weather-call" } }, { "ref": "https://api.weather.example/pay", "kind": "api", "provenance": "indexed", "execution": { "mode": "direct", "url": "https://api.weather.example/pay", "method": "GET", "network": "eip155:8453" }, "card": { "title": "api.weather.example/pay", "summary": "Returns current weather through an external payable endpoint.", "byline": "x402 Bazaar", "badges": [{ "code": "external_catalog", "label": "External catalog" }], "facts": [ { "label": "Price", "value": "2100 base units" }, { "label": "Network", "value": "Base" }, { "label": "Method", "value": "GET" } ] }, "action": { "type": "invoke_api", "href": "/call/invoke?url=https%3A%2F%2Fapi.weather.example%2Fpay&method=GET&network=eip155%3A8453&sig=fixture" } }, { "ref": "research-brief", "kind": "service_offer", "card": { "title": "Research brief", "summary": "A concise evidence-backed market research brief.", "byline": "Northstar Research", "badges": [{ "code": "approved_vendor", "label": "Approved vendor" }], "facts": [ { "label": "From", "value": "25 USDC" }, { "label": "Network", "value": "eip155:8453" } ] }, "action": { "type": "start_engagement", "href": "/tasks/services/research-brief" } }, { "ref": "pricing-study", "kind": "open_request", "card": { "title": "Pricing study", "summary": "Compare competitor pricing and package the findings.", "badges": [], "facts": [{ "label": "Policy", "value": "standard" }] }, "action": { "type": "propose_to_request", "href": "/orders/pricing-study" } } ], "nextCursor": null, "unavailableKinds": [], "rankingVersion": "marketplace-ranking-v1" } ``` ## Callable API details The Call contract uses the categories `ai`, `data`, `crypto`, `compute`, `search`, and `other`. A service summary includes its ID, name, description, category, trust tier, required `verified` and `wrapped` boolean fields, displayed price, supported networks, and endpoints. An endpoint always has a name, method, URL, displayed price, and description. It can also include an operation ID, request and response content types, a request schema, path information, and checked payment metadata. This generated example shows the full endpoint shape used by a payable listing: ```json { "name": "call", "method": "POST", "url": "https://weather.example/call", "price": "$0.0021", "description": "Return the current weather.", "operationId": "getWeather", "requestContentType": "application/json", "requestSchema": { "type": "object", "required": ["city"], "properties": { "city": { "type": "string" } }, "additionalProperties": false }, "responseContentType": "application/json", "payment": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x1111111111111111111111111111111111111111", "checkedAt": "2026-08-17T12:00:00.000Z" } } ``` ## Client consumption 1. Require `protocol` to equal `vapi.marketplace.discovery/1`. 2. Filter or dispatch on `kind`. 3. Treat `ref` and `nextCursor` as opaque values. 4. For an API, inspect `provenance` and `execution` before invoking it. 5. Use `action.href` for service offers and open requests. 6. Read `unavailableKinds` before treating an empty result as a complete discovery answer. The buyer-local wallet accepts API references returned by its own current `search` process. See [the buyer-local wallet](/for-agents/buyer-local-wallet.md) for its `search` and `call` tools. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.vapinetwork.ai/protocol/discovery-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.