Publish x402 V2 service discovery metadata so facilitators can automatically find and index your API's payment requirements without manual configuration
Implement the x402 V2 discovery extension by exposing a well-known endpoint (typically /.well-known/x402.json) on your API domain containing your service metadata: accepted chains, accepted assets, price per endpoint, facilitator preferences, and contact information
Structure the discovery document per the x402 V2 discovery specification: include an array of resource objects each mapping a URL pattern to its payment requirements (amount, asset, chain, facilitator address)
Add the Link: </.well-known/x402.json>; rel=payment-discovery header to all your API responses so clients that encounter your API for the first time can immediately locate the discovery document without prior knowledge
Register your service with the x402 Foundation's facilitator network by submitting your discovery URL; facilitators in the network will crawl and index your service, making it visible to agent clients that use facilitator-driven service discovery
Monitor the discovery endpoint for facilitator crawl requests in your access logs; use crawl frequency as a proxy for how many agent clients are evaluating your service before initiating payment flows
Known gotchas
The discovery document is publicly readable and reveals your pricing structure; do not include any secrets or internal infrastructure details — treat it as a public advertisement, not a configuration file
If you update prices or accepted chains in the discovery document, facilitators that have cached the old version may continue to send payments for the old price; include a version field in the document and validate that incoming payment amounts match the current version's pricing before accepting
Some agent clients skip discovery and hard-code payment parameters from previous interactions with your API; publishing a discovery document does not guarantee all clients will use it — always validate payment parameters at the API level regardless of what the discovery document advertises
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp