x402: Get your endpoint discovered

This page is for developers who sell an API, a tool, or content over x402 on Celo and want agents to find it. A working 402 endpoint is invisible until it is described in a way agents can read and listed where agents look. There is no single index. Each one has its own entry rule, and this page lists them.

Prerequisites

A resource server that returns 402 Payment Required on Celo. Set one up on the x402 page first.
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.

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.
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	One `POST` with your origin; the crawler probes it every 30 minutes	A public origin that answers with a 402
8004scan	Register an ERC-8004 identity whose registration file lists your endpoints and sets `x402Support`	An identity on Celo
Buy catalog	Ask for a listing with the buy-skill issue form	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.

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.

// Celo mainnet (42220). Node 20+. npm i express @x402/express @x402/core @x402/evm @x402/extensions
import express from "express";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { HTTPFacilitatorClient, type RoutesConfig } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { bazaarResourceServerExtension, declareDiscoveryExtension } from "@x402/extensions/bazaar";

const facilitator = new HTTPFacilitatorClient({
  url: "https://api.x402.celo.org",
  createAuthHeaders: async () => {
    const h = { "X-API-Key": process.env.X402_API_KEY! };
    return { verify: h, settle: h, supported: h };
  },
});

const server = new x402ResourceServer(facilitator)
  .register("eip155:42220", new ExactEvmScheme())
  .registerExtension(bazaarResourceServerExtension);

const routes: RoutesConfig = {
  "GET /weather": {
    accepts: {
      scheme: "exact",
      network: "eip155:42220",
      payTo: "0xYourSellerPayoutAddress",
      price: {
        amount: "10000", // $0.01; USDC has 6 decimals
        asset: "0xcebA9300f2b948710d2653dD7B07f33A8B32118C", // Celo mainnet USDC, 6 decimals
        extra: { name: "USDC", version: "2" },
      },
    },
    description: "Current weather for a city",
    mimeType: "application/json",
    extensions: declareDiscoveryExtension({
      input: { city: "Lagos" },
      inputSchema: { properties: { city: { type: "string" } }, required: ["city"] },
      output: { example: { city: "Lagos", tempC: 31, sky: "haze" } },
    }),
  },
};

const app = express();
app.use(paymentMiddleware(routes, server));
app.get("/weather", (req, res) => res.json({ city: req.query.city, tempC: 31, sky: "haze" }));
app.listen(3000);

An unpaid GET /weather?city=Lagos returns 402 with an empty {} body. The payment requirements travel base64-encoded in the PAYMENT-REQUIRED response header. Decoded (abridged here), that header carries the price in accepts and the description in extensions.bazaar:

{
  "resource": { "url": "http://localhost:3000/weather?city=Lagos", "description": "Current weather for a city", "mimeType": "application/json" },
  "accepts": [{ "network": "eip155:42220", "amount": "10000", "asset": "0xcebA9300f2b948710d2653dD7B07f33A8B32118C" }],
  "extensions": {
    "bazaar": {
      "info": {
        "input": { "type": "http", "method": "GET", "queryParams": { "city": "Lagos" } },
        "output": { "type": "json", "example": { "city": "Lagos", "tempC": 31, "sky": "haze" } }
      },
      "schema": { "...": "JSON Schema generated from the declaration" }
    }
  }
}

Write the description for an agent that is deciding whether to call you: what the endpoint returns and when to use it, in under 500 characters. The HTTP method comes from the route key, so "GET /weather" declares a GET. For a POST route, use a key such as "POST /summarize", and pass bodyType: "json" and the example body as input.

Register with agent402.tools

One request lists your origin at once, and Celo has its own market page 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.

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

Register an ERC-8004 identity

Agents that look up sellers on 8004scan 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 covers registration and the registry addresses.

Ask for a listing in the Buy catalog

Buy’s catalog is curated. Open a listing request with the buy-skill issue form with your origin, a one-paragraph description, the price, and the networks and tokens you accept.

Troubleshooting

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 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
`@x402/extensions` on npm	npmjs.com/package/@x402/extensions
agent402.tools seller page	agent402.tools/sell
8004scan	8004scan.io
Buy	usebuy.ai

x402: Agent Payments - Set up the resource server this page assumes
ERC-8004: Agent Trust Protocol - Identity and reputation for the seller behind the endpoint
Attribution Tags - Credit on-chain activity back to your app
MPP - Machine Payments Protocol: charge USDC per request over HTTP

Quickstart

Agents

Mini Apps

Network info

Guides

Tools

Reference

x402: Get your endpoint discovered

Prerequisites

How it works

Describe your endpoint in the 402

Register with agent402.tools

Register an ERC-8004 identity

Ask for a listing in the Buy catalog

Troubleshooting

Resources

​Prerequisites

​How it works

​Describe your endpoint in the 402

​Register with agent402.tools

​Register an ERC-8004 identity

​Ask for a listing in the Buy catalog

​Troubleshooting

​Resources

​Related

Prerequisites

How it works

Describe your endpoint in the 402

Register with agent402.tools

Register an ERC-8004 identity

Ask for a listing in the Buy catalog

Troubleshooting

Resources

Related