Why is discovery the hard part?#
Paying is solved. An agent with a funded wallet can pay for an HTTP request in one round trip. See what x402 is.
Finding something worth paying for is not. An agent needs to know that an endpoint exists, what it does, what it costs, and whether anyone else has successfully paid it. None of that is in the payment protocol, and no single source has all four.
Route 1: a facilitator's catalogue#
Most facilitators publish a list of the resources they have seen or registered. It is the most obvious place to look and the easiest to query.
It is also the most incomplete, in a way that is worth stating precisely. Catalogues record what publishers registered with that facilitator. A publisher who takes payments through a facilitator with no directory, or who never registered, is absent. Not unlisted, simply unrecorded.
Measured in September 2026: across three days, 1,950 wallets were paid in settlements that a named facilitator relayed, and only 641 of them appeared as a payTo in any catalogue being crawled. Two thirds of the live sellers were invisible to directory-only discovery.
Route 2: ask the host#
A publisher can describe itself at a well-known path on its own domain. This is the question no directory asks, and it is often the only place the full picture exists.
Three documents are worth requesting:
| Document | What it gives you |
|---|---|
/.well-known/x402 | The publisher's own list of priced endpoints |
/.well-known/agent-card.json | Identity: who runs this, what it claims to do |
A live 402 from the endpoint | The authoritative price and payTo, as the server states it today |
Important
The live 402 is the authority, not the document. A catalogue entry can be stale and a self-published manifest can omit the payee entirely. The terms you should pay against are the ones the server returns when you ask it.
Two traps when you implement this. The HTTP status decides, not the content type. Some hosts answer 404 with content-type: application/json, so a parser that trusts the type reads a "not found" page as a document. And a declared price is in dollars while an x402 accepts amount is in the asset's smallest unit; confusing them is a factor-of-a-million error that still looks like a plausible number.
Route 3: the chain#
Every x402 settlement is a public on-chain event, so the record of who actually got paid does not depend on anyone registering anything. This is the only route that cannot be gamed by omission.
The difficulty is telling an x402 payment apart from any other gasless transfer. The EIP-3009 AuthorizationUsed marker is not a reliable test on its own. It was being emitted around 1,600 times per 10,000 Base blocks in December 2024, five months before x402 was announced.
The usable discriminator is who submitted the transaction. On the common x402 path the sender is the facilitator rather than the payer, so a settlement relayed by a facilitator in a public registry is strong evidence; one sent by the payer itself is not. Measured by Roundhouse on Base in 2026, 84.3% of markers at the chain tip came from a registry facilitator, against 2.9% in October 2025.
Route 4: what does an index that joins them add?#
The three routes above answer different questions and each one is wrong on its own. A catalogue knows what exists but not what works; the chain knows what was paid but not what it bought; the host knows what it sells but not whether anyone bought it.
Joining them is what Roundhouse does, and the join is the product: a settlement record, the service it paid for, the identity behind the wallet, and the facilitator that relayed it, in one query.
# Services, with price and observed activity
curl https://api.roundhouseai.io/v0/endpoints
# What a specific wallet has actually been paid
curl https://api.roundhouseai.io/v0/merchants/0xYourAddressThe same surfaces are browsable: services is the priced directory, agents is the identity side, and flow of funds is what settled in the last few minutes.
How do I make my own service discoverable?#
The short answer is below; the full checklist covers each route and what it misses.
In the order that pays off fastest.
- Return a well-formed 402. Every discovery route eventually asks your endpoint directly. If the
acceptsarray is wrong or thepayTois missing, nothing downstream can fix it. - Publish
/.well-known/x402. It costs one static file and it is the only route that does not depend on a third party having noticed you. - Register with a facilitator that publishes a catalogue. This is how you reach the agents that only look there.
- Take one real payment. Until a settlement exists, you are a claim. After it, you are in the on-chain record whether or not anyone indexed you.
- Register an ERC-8004 identity if you want the wallet to resolve to a name rather than an address.
Frequently asked questions#
How does an AI agent find an API to call?#
Through a facilitator catalogue, a publisher's own /.well-known documents, the on-chain settlement record, or an index that joins all three. Catalogue-only discovery misses most live sellers. Measured in September 2026, roughly two thirds of wallets being paid through named facilitators were in no catalogue.
Do agents need an account to use a discovered service?#
No, if the service speaks x402. The agent pays per request with a signed stablecoin authorisation and never registers. That is what makes same-session discovery and purchase possible at all.
How can I tell whether a service is real before paying it?#
Check whether it has been paid before. A settlement record shows which wallets actually received payments, how often and how recently, which is a far stronger signal than a directory listing. Roundhouse publishes this per service and per wallet.
What is ERC-8004 and do I need it?#
ERC-8004 is an on-chain registry that binds an agent identity to a wallet, so payments resolve to a name rather than a bare address. It is not required to take x402 payments; it is how you become identifiable once you do.
Is there an API for discovering x402 services?#
Yes. GET /v0/endpoints returns the priced directory with observed activity, and answers without a credential. GET /v0/merchants/<address> returns what a specific wallet has been paid, and takes a key. GET /v0/test/x402 mints one for $0.01 over x402 with no account behind it. The API reference has the full set.
Where to check this yourself#
The discovery figures above are measurements with a stated window, not estimates, and the underlying record is public. Re-run them against the data API, an index whose numbers cannot be checked is just another catalogue.