> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aifinpay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Help agents discover paid routes

> Publish paid routes, prices, scopes and instruction links on the same origin as your API.

An agent arriving at your domain needs two things: a catalog of what it can
request, and instructions for paying. A general AiFinPay skill cannot know
which routes your website monetizes.

## Publish a public catalog

Serve `GET /.well-known/x402.json` without requiring payment. With Express:

```ts theme={null}
import { aifpDiscovery } from "@aifinpay/gate";

app.use(aifpDiscovery({
  merchantId: "mrch_your_site",
  resources: [
    { resource: "/api/agent/search", tier: "standard", scope: "exact", name: "Search" },
  ],
}));
```

For Next.js or another framework, return `buildDiscoveryDocument(options)`
from your own route handler. Mount the gate separately; the discovery helper
neither protects routes nor scans your router automatically. Feed both from
the same resource configuration.

Each discovery resource contains its path, tier, unit price and receipt scope.
Quote and pay endpoint URLs identify where to negotiate payment. Chain,
asset, amount and expiry come from a fresh quote.

Also publish an API catalog or OpenAPI document with HTTP methods, parameters
and response schemas. Knowing `/api/agent/search` exists does not tell an agent
whether the required argument is `q` or `query`.

## Link from the website

Put readable links in `/llms.txt`, for example (replace the example origin):

```text theme={null}
# Example API

- [Paid routes and prices](https://api.example.com/.well-known/x402.json)
- [API methods and parameters](https://api.example.com/api/agent)
- [AiFinPay payer instructions](https://raw.githubusercontent.com/AiFinPay/skill/main/agent/skills/aifinpay/SKILL.md)
```

Resolve relative links against the page's origin. If your consumers need
absolute links, generate them from the configured public origin for that
environment. A staging site must not send agents to a production catalog
that has not been deployed. Keep these files accessible to agent user agents.
An HTTP `Link` header or a visible developer link can provide another entry.

A request to an actual gated route also returns HTTP 402 with resource,
price, scope and payment steps. Read the linked client's capabilities before
assuming that wallet creation enables automatic payment.

## Where discovery is stored

| Information | Source | Who updates it? |
| - | - | - |
| General payer and merchant instructions | Public `AiFinPay/skill` repository and npm package | AiFinPay; installed copies need a client update |
| Bundled MCP instructions | `aifinpay://skill` resource | AiFinPay MCP release; reconnect after upgrading |
| Self-hosted paid route catalog | Partner's app configuration, rendered by `buildDiscoveryDocument` / `aifpDiscovery` | Partner updates config and redeploys |
| `/llms.txt`, API parameters and website links | Partner's site | Partner |
| Hosted gateway resource configuration | Merchant account/control plane | Merchant through the dashboard or API |

The self-hosted discovery helper does **not** save a file or synchronize its
resource array with the dashboard. Its Express response is generated at
middleware initialization and can be cached for five minutes. Updating a
linked skill at a stable URL does not require a site redeploy; changing an
installed gate or embedded URL does.

## Verify before inviting agents

From each deployed origin, follow `/llms.txt` links and confirm that discovery
and the API catalog return 200. Compare the listed resources with real gate
mounts. Request a protected route as an agent and check the 402's merchant,
resource, price, minimum batch and scope. Then verify payment support against
the installed client and the quoted route. A working 402 alone proves only
that the paywall is reachable.