x402-starter

Paywall your Cloudflare Worker for AI agents in 5 minutes.

Drop-in x402 starter. Agents pay per call in USDC — no signup, no API keys, no human in the loop. Comes with Coinbase x402 Bazaar discoverability and an MCP manifest pre-wired so Coinbase-connected agents can find your API automatically.

What you get out of the box

• A Cloudflare Worker that returns HTTP 402 Payment Required for paid routes until the caller settles a USDC micropayment
• Bazaar-discoverable routes (the non-obvious bit — without discoverable: true + schemas, even settled payments never list)
• A /mcp manifest so MCP clients and Coinbase AgentKit auto-discover your tools
• One example paid endpoint (GET /api/echo) you replace with your real API
• HTTPS-forced redirects, JSON-or-HTML root discovery, health check

5-minute quick start

git clone <this repo> my-paid-api
cd my-paid-api
npm install
npm run dev          # paywall OFF by default — iterate locally

Hit http://localhost:8787/api/echo?msg=hi — you'll get a 200 with the echo. That's your free dev loop.

Flip the paywall on (testnet)

1. Edit wrangler.jsonc:

   "X402_ENABLED": "true",
   "X402_NETWORK": "base-sepolia",
   "PAY_TO": "0xYOUR_TESTNET_WALLET",
   "PRICE_PER_CALL": "$0.01"

2. npm run deploy
3. Hit /api/echo — you'll get HTTP 402 with the payment challenge.

base-sepolia uses the default public facilitator. No keys needed. This is the right setup for development and demos.

Flip to mainnet (real USDC)

1. Get a Coinbase CDP Secret API key at portal.cdp.coinbase.com.
2. Set the two secrets:

   npx wrangler secret put CDP_API_KEY_ID      # paste the key id when prompted
   npx wrangler secret put CDP_API_KEY_SECRET  # paste the secret when prompted

3. Set X402_NETWORK to "base" in wrangler.jsonc, set PAY_TO to your real Base wallet, and redeploy.

Without the CDP keys on mainnet, the 402 challenge still issues but payments cannot settle. Set both secrets before going live.

Adding your own paid endpoints

Two places to edit src/index.ts:

1. The handler — add a route under /api/*:

   app.get("/api/wash", async (c) => {
     // your logic
     return c.json({ ... });
   });

2. The paywall config — add the same path to routes in applyPaywall() so it gets paywalled AND Bazaar-discoverable:

   "/api/wash": {
     price: env.PRICE_PER_CALL,
     network: env.X402_NETWORK,
     config: {
       discoverable: true,
       description: "Wash/sybil screen for any Base address",
       inputSchema: { queryParams: { address: { type: "string" } } },
       outputSchema: { type: "object", properties: { sybil_score: { type: "number" } } },
     },
   },

3. The MCP manifest — add a tools[] entry with the same name/endpoint/price_usd so MCP clients see it.

That's it. The middleware path matcher (/api/*) catches everything under /api, so only step 1 is structurally required — but skipping steps 2 and 3 means agents won't find your endpoint, which is most of the value.

Going beyond echo

This template is intentionally minimal — one example endpoint, no business logic. The patterns it shows (Bazaar config, MCP manifest, free landing + JSON discovery, HTTPS forcing, lazy app build) are the load-bearing parts. Wire in your D1 / KV / Workers AI / Durable Objects as needed.

Pricing

x402-hono accepts dollar-formatted strings: "$0.01", "$0.05", "$1.00". Internally x402 settles in micro-USDC (six decimals), so "$0.01" becomes 10000 units. Different routes can charge different prices — set them per-route in the routes config.

License

MIT. Use it, fork it, ship it.