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. 
Implement AgentCash discovery for this server and make it pass.

Discovery strategy:
Your api should expose an OpenAPI document at /openapi.json, which abides by the OpenAPI specification,
with several additional fields required for AgentCash discovery.
You can use the @agentcash/discovery package to validate your OpenAPI document.

Validation commands:
npx -y @agentcash/discovery@latest discover "$TARGET_URL"
npx -y @agentcash/discovery@latest check "$TARGET_URL"


This will yield warnings regarding the discovery document and how it can be improved.

Schema guidance (important):
- Each invocable route should expose an input schema.
- In OpenAPI, define requestBody.content["application/json"].schema.
- This is required for reliable agent invocation and robust listing behavior.
- Add high-level guidance in info.x-guidance for agent-friendly discovery. This document should explain to an agent how to use your API at a high level.

OpenAPI payable operation must include ALL:
- x-payment-info with:
  - protocols: array of protocol objects, e.g. [{ "x402": {} }, { "mpp": { "method": "", "intent": "", "currency": "" } }]
  - price object with mode, currency, and pricing fields:
    - fixed: { price: { mode: "fixed", currency: "USD", amount: "<amount>" } }
    - dynamic: { price: { mode: "dynamic", currency: "USD", min: "<min>", max: "<max>" } }
    Legacy flat format still works: { pricingMode: "fixed", price: "<amount>" }
  - IMPORTANT: for fixed pricing use "amount" in the price object (not "value")
- responses: { "402": { description: "Payment Required" } }

Workflow:
1) Validate your OpenAPI document with the @agentcash/discovery package.
2) Fix your OpenAPI document until it passes validation.
3) Register your server on MppScan or X402Scan once it passes validation.

​
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 — if you already follow the IETF standard, your service is still compatible and you can define both without conflict. 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 a 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)