Become discoverable

Why This Matters

If agents can’t discover your API, they can’t call it. Bulletproof discovery turns your endpoint from merely listed to reliably invocable. When metadata and runtime 402 behavior agree, agents succeed on the first pass. You get fewer AgentCash failures, less debugging churn, and more real agent traffic.

Publish OpenAPI as the canonical machine-readable contract.
Treat runtime 402 challenge behavior as the final source of truth.

If you build with AgentCash Router, skip the manual work below: the router generates a compliant /openapi.json and /llms.txt from your route definitions, and the runtime 402 behavior matches by construction.

Copy for Agents

Paste this directly into your coding agent. It should handle discovery implementation and validation end-to-end.

Discovery Strategy

OpenAPI is the canonical discovery format. Use it for the cleanest machine-readable contract and best agent compatibility. The x-payment-info fields are a superset of the IETF API payment spec. The fields do not collide, so your service is still compatible if you already follow the IETF standard. Expected location: GET /openapi.json Requirements:

Top-level fields: openapi, info.title, info.x-guidance, info.version, paths.
For paid operations: responses.402 and x-payment-info.
Set x-payment-info.protocols (array of protocol objects) and one pricing mode (fixed or dynamic) with currency.
Keep OpenAPI x-payment-info.price.amount in decimal USD; use token atomic units only in runtime x402 accepts[].amount (for USDC, 0.01 => "10000").
Use OpenAPI security + components.securitySchemes for auth declaration.
Add high-level guidance in info.x-guidance for user-friendly discovery.

Recommended:

info.contact.email: your contact email. Lets you verify ownership of your origin, allows users to contact you, and lets you customize your merchant pages on Poncho.

Minimal valid example

{
  "openapi": "3.1.0",
  "info": {
    "title": "My API",
    "version": "1.0.0",
    "description": "example demo server",
    "x-guidance": "Use POST /api/search for neural web search. Accepts a JSON body with a 'query' field.",
    "contact": {
      "email": "you@example.com"
    }
  },
  "x-discovery": {
    "ownershipProofs": ["<proof-1>"]
  },
  "paths": {
    "/api/search": {
      "post": {
        "operationId": "search",
        "summary": "Search - Neural search across the web",
        "tags": ["Search"],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" },
          "protocols": [{ "x402": {} }, { "mpp": { "method": "", "intent": "", "currency": "" } }]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": { "type": "string", "minLength": 1, "description": "The query string for the search" }
                },
                "required": ["query"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": { "type": "array", "items": { "type": "object" } }
                  },
                  "required": ["results"]
                }
              }
            }
          },
          "402": { "description": "Payment Required" }
        }
      }
    }
  }
}

Discovery Precedence

AgentCash uses the OpenAPI document at /openapi.json to discover your API. It will also check the runtime 402 challenge behavior to ensure it is correct.

Order	Source	Expected Location
1	OpenAPI document	`/openapi.json`
2	402 API Response	`Correct 402 header response`

Common Failure Reasons

These are the most frequent errors seen during registration.

Error	Likely Cause	Fix
`Not Found`	OpenAPI not found at `{origin}/openapi.json`	Add an OpenAPI document at `{origin}/openapi.json`
`Input/Output Schema Missing`	Operation has no input or output schema	Add an input and output schema to the operation
`No Payment Modes Detected`	No payment modes detected in the response	Add a valid payment mode to the response (x402 or MPP)
`Expected 402, got 400`	Request validation rejected the unauthenticated probe before payment middleware ran	Let probes reach the `402` challenge before body/query validation, or add schemas/examples that let probes send valid input
`WWW-Authenticate Header Missing`	Invalid, missing, or proxy-stripped MPP challenge header	Return `WWW-Authenticate` on MPP `402` responses and preserve it through proxies
`Realm Mismatch`	MPP realm points at a Railway/internal host or another non-public origin	Set the realm to the public origin agents call

Introduction

For API Providers

Router

For Agents

Become discoverable

Why This Matters

Copy for Agents

Discovery Strategy

Minimal valid example

Discovery Precedence

Common Failure Reasons

​Why This Matters

​Copy for Agents

​Discovery Strategy

​Minimal valid example

​Discovery Precedence

​Common Failure Reasons

Why This Matters

Copy for Agents

Discovery Strategy

Minimal valid example

Discovery Precedence

Common Failure Reasons