Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agentcash.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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.

​
Copy for Agents

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

Paste into Claude Code, Cursor, or Codex.

​
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.
  • Use OpenAPI security + components.securitySchemes for auth declaration.
  • Add high-level guidance in info.x-guidance for user-friendly discovery.

​
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."
  },
  "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.
OrderSourceExpected Location
1OpenAPI document/openapi.json
2402 API ResponseCorrect 402 header response

​
Common Failure Reasons

These are the most frequent errors seen during registration.
ErrorLikely CauseFix
Not FoundOpenAPI not found at {origin}/openapi.jsonAdd an OpenAPI document at {origin}/openapi.json
Input/Output Schema MissingOperation has no input or output schemaAdd an input and output schema to the operation
No Payment Modes DetectedNo payment modes detected in the responseAdd a valid payment mode to the response (x402 or MPP)