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

# Become discoverable

> Build once, register reliably, and keep your resources discoverable by agents.

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

export const discoveryPrompt = `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.

Contact email (recommended):
- Ask the user for their contact email and add it as info.contact.email in the openapi.json.
- This lets them verify ownership of their origin, allows users to contact them, and lets them customize their merchant pages on Poncho.

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.`;

export const PromptAccordion = () => {
  const {useState} = React;
  const [open, setOpen] = useState(false);
  const [copied, setCopied] = useState(false);
  return <div className="prompt-accordion">
      <div onClick={() => setOpen(!open)} style={{
    display: "flex",
    alignItems: "center",
    gap: 8,
    padding: "14px 16px",
    cursor: "pointer",
    userSelect: "none"
  }}>
        <span className="prompt-accordion-icon" style={{
    fontSize: 12,
    transform: open ? "rotate(90deg)" : "rotate(0deg)",
    transition: "transform 0.15s"
  }}>▶</span>
        <svg className="prompt-accordion-icon" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
          <polyline points="4 17 10 11 4 5" /><line x1="12" y1="19" x2="20" y2="19" />
        </svg>
        <span className="prompt-accordion-label" style={{
    fontSize: 14
  }}>Paste into your coding agent</span>
        <button onClick={async e => {
    e.stopPropagation();
    try {
      await navigator.clipboard.writeText(discoveryPrompt);
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    } catch {}
  }} style={{
    marginLeft: "auto",
    display: "inline-flex",
    alignItems: "center",
    background: "#309637",
    color: "#fff",
    border: "none",
    borderRadius: 6,
    padding: "6px",
    cursor: "pointer"
  }}>
          {copied ? <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><polyline points="20 6 9 17 4 12" /></svg> : <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2" /><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" /></svg>}
        </button>
      </div>
      {open && <pre className="prompt-accordion-expanded" style={{
    margin: 0,
    padding: "0 16px 16px",
    whiteSpace: "pre-wrap",
    wordBreak: "break-word",
    fontSize: 13,
    lineHeight: 1.6
  }}>{discoveryPrompt}</pre>}
    </div>;
};

<PromptAccordion />

## 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](https://paymentauth.org/draft-payment-discovery-00.txt). 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.

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](https://tryponcho.com).

### Minimal valid example

```json theme={null}
{
  "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) |