Help agents discover paid routes

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:

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):

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

Get started

Pay for services

Charge for your API

Reference

Help agents discover paid routes

Publish a public catalog

Link from the website

Where discovery is stored

Verify before inviting agents

​Publish a public catalog

​Link from the website

​Where discovery is stored

​Verify before inviting agents

Publish a public catalog

Link from the website

Where discovery is stored

Verify before inviting agents