Skip to content

docs(x402): drop discovery indexes that do not list Celo endpoints #2408

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
GigaHierz merged 3 commits into from
Oct 22, 2026
Merged

docs(x402): drop discovery indexes that do not list Celo endpoints #2408

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
36907dc
docs(x402): drop discovery indexes that do not list Celo endpoints
GigaHierz Oct 21, 2026
bc722cd
docs(x402): apply review suggestions on discovery page
GigaHierz Oct 22, 2026
921c838
Merge branch 'main' into GigaHierz/celo-x402-roles-review
GigaHierz Oct 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 7 additions & 22 deletions build/agents/x402-get-discovered.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,24 +9,24 @@ This page is for developers who sell an API, a tool, or content over [x402](/bui
## Prerequisites

- A resource server that returns `402 Payment Required` on Celo. Set one up on the [x402 page](/build/agents/x402#pointing-a-resource-server-at-it) first.
- A public HTTPS origin. Indexes probe your endpoint from the outside, and some probe it every hour.
- A public HTTPS origin. Indexes probe your endpoint from the outside, and agent402.tools probes it every 30 minutes.
- Node.js 20 or later and the v2 packages: `@x402/express`, `@x402/core`, `@x402/evm`, `@x402/extensions`.

## How it works

Discovery has two halves.

1. **Self-description.** The x402 `bazaar` extension lets your 402 response carry the shape of the endpoint: the HTTP method, an example input, a JSON schema for it, and an example output. Facilitators and crawlers that understand the extension catalog the endpoint from the 402 itself, so an agent can call it correctly the first time.
2. **Registration.** Each index decides what it lists. Some crawl an origin you submit, one lists only endpoints that settle through its own facilitator, and one reads on-chain agent identities.
2. **Registration.** Each index decides what it lists. One crawls an origin you submit, one reads on-chain agent identities, and one is a curated catalog.

| Index | How an endpoint gets in | What it requires |
|---|---|---|
| [agent402.tools](https://agent402.tools/sell) | One `POST` with your origin; the crawler probes it hourly | A public origin that answers with a 402 |
| [Coinbase x402 discovery](https://docs.cdp.coinbase.com/x402/seller/get-discovered) | Automatic after a paid call settles through Coinbase's facilitator | Coinbase's facilitator settles on Base, Base Sepolia, Polygon, Arbitrum, World and Solana. Listings without a settlement for 30 days are removed |
| [x402scan](https://www.x402scan.com/resources/register) | Submit the URL; it is added if it returns a valid challenge | Registration accepts Base and Solana resources |
| [agent402.tools](https://agent402.tools/sell) | One `POST` with your origin; the crawler probes it every 30 minutes | A public origin that answers with a 402 |
| [8004scan](https://8004scan.io) | Register an [ERC-8004](/build/agents/8004) identity whose registration file lists your endpoints and sets `x402Support` | An identity on Celo |
| [Buy catalog](https://usebuy.ai) | Ask for a listing with the [buy-skill issue form](https://github.com/celo-org/buy-skill/issues/new?template=list-your-service.yml) | A public origin, a description, a price, and the networks and tokens you accept |

The extension is named `bazaar` after Coinbase's Bazaar, but Coinbase's Bazaar and x402scan do not list Celo-only offers, so they are not covered here.

@palango palango Oct 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit, take it or leave it: the bazaar spec doesn't say the name comes from Coinbase's Bazaar, and "Coinbase's Bazaar" appears twice. Maybe: "Coinbase's Bazaar, which shares the extension's name, and x402scan do not list Celo-only offers, so this page does not cover them."


## Describe your endpoint in the 402

Register the `bazaar` extension on the resource server and declare the shape of each route. The block below runs against the Celo facilitator and answers an unpaid request with a 402 that carries the description.
Expand Down Expand Up @@ -101,25 +101,14 @@ Write the `description` for an agent that is deciding whether to call you: what

## Register with agent402.tools

One request lists your origin. The crawler probes the x402 surface hourly and ranks listings by health.
One request lists your origin at once, and Celo has [its own market page](https://agent402.tools/celo) there. The crawler re-probes the x402 surface every 30 minutes and ranks listings by crawl health, then by distinct payers and price. Its own router pays sellers only on chains it holds wallets for, and Celo is not one of them, so buyers pay a Celo-only seller directly rather than through the router.

```bash
curl -X POST https://agent402.tools/api/index/register \
-H 'content-type: application/json' \
-d '{"origin":"https://api.example.com"}'
```

## List in Coinbase's discovery index

Coinbase's index adds an endpoint automatically after a paid call has settled through Coinbase's facilitator. It removes resources that go 30 days without a settlement, and endpoints that stop returning `402`. That facilitator settles on Base, Base Sepolia, Polygon, Arbitrum, World and Solana, so an offer that only settles on Celo is not listed. To appear there:

1. Follow [Coinbase's seller guide](https://docs.cdp.coinbase.com/x402/seller/get-discovered) to add an offer on one of those networks and settle it through Coinbase's facilitator.
2. Keep at least one paid call a month on the offer that settles there.

## Register on x402scan

Submit the endpoint URL at [x402scan.com/resources/register](https://www.x402scan.com/resources/register). It is added when the URL returns a valid x402 challenge. Registration accepts resources on Base and Solana, so an endpoint that only offers Celo is not accepted there.

## Register an ERC-8004 identity

Agents that look up sellers on [8004scan](https://8004scan.io) read the on-chain registry. Register an identity on Celo, list your endpoints under `services` in the registration file, and set `x402Support` to `true`. The [ERC-8004 page](/build/agents/8004) covers registration and the registry addresses.
Expand All @@ -133,19 +122,15 @@ Buy's catalog is curated. Open a listing request with the [buy-skill issue form]
| Symptom | Cause | Fix |
|---|---|---|
| The 402 has no `extensions` block | The extension is not registered on the server, or the route has no `extensions` entry | Call `registerExtension(bazaarResourceServerExtension)` and add `extensions: declareDiscoveryExtension(...)` to the route |
| agent402.tools shows nothing after an hour | The origin needs authentication before it answers 402, or it is not reachable from the public internet | Return the 402 to an unauthenticated request; check the origin from outside your network |
| A Coinbase listing disappeared | No settlement through Coinbase's facilitator for 30 days, or the endpoint stopped returning `402` | Make a paid call on the offer that settles there, and return `402` to unpaid requests. A failed health probe only drops a curated endpoint from the featured tier; it stays in the general Bazaar and returns when it recovers |
| x402scan rejects the URL | Registration accepts Base and Solana resources | Add an offer on one of those networks, or use the other indexes |
| agent402.tools shows nothing after registering | The origin needs authentication before it answers 402, or it is not reachable from the public internet | Return the 402 to an unauthenticated request; check the origin from outside your network |

## Resources

| Resource | Link |
|----------|------|
| x402 `bazaar` extension specification | [github.com/x402-foundation/x402](https://github.com/x402-foundation/x402/blob/main/specs/extensions/bazaar.md) |
| `@x402/extensions` on npm | [npmjs.com/package/@x402/extensions](https://www.npmjs.com/package/@x402/extensions) |
| Coinbase seller guide | [docs.cdp.coinbase.com/x402/seller/get-discovered](https://docs.cdp.coinbase.com/x402/seller/get-discovered) |
| agent402.tools seller page | [agent402.tools/sell](https://agent402.tools/sell) |
| x402scan resource registration | [x402scan.com/resources/register](https://www.x402scan.com/resources/register) |
| 8004scan | [8004scan.io](https://8004scan.io) |
| Buy | [usebuy.ai](https://usebuy.ai) |

Expand Down
Loading