SKILL.md Raw

x402 paywall

Goal: selected routes answer 402 Payment Required with payment requirements until the client retries with a valid X-PAYMENT header; then the facilitator verifies and settles the payment and the route runs normally.

1. Collect

Which routes, and the price of each (in USD, e.g. $0.01).
The receiving wallet (payTo) — an address the user controls. Never generate or store a private key for receiving.
Network: base (recommended, cheap gas) or another network listed by GET http://localhost:3000/x402/supported.
A facilitator key (fk_…) from the DeepNexus Facilitator console, stored as DEEPNEXUS_FACILITATOR_KEY in the environment.

2. Express / Node

npm install x402-express

import { paymentMiddleware } from "x402-express";

const facilitator = {
  url: "http://localhost:3000/x402",
  createAuthHeaders: async () => {
    const h = { Authorization: `Bearer ${process.env.DEEPNEXUS_FACILITATOR_KEY}` };
    return { verify: h, settle: h, supported: {} };
  },
};

app.use(
  paymentMiddleware(
    process.env.PAY_TO,
    {
      "GET /api/forecast": { price: "$0.01", network: "base", config: { description: "7-day forecast" } },
      "POST /api/summarize": { price: "$0.05", network: "base" },
    },
    facilitator,
  ),
);

Register the middleware before the routes it protects. For Hono use x402-hono, for Next.js x402-next (middleware.ts) — same arguments.

3. Other frameworks (manual)

If the request has no X-PAYMENT header, return 402 with {"x402Version":1,"accepts":[requirements],"error":"X-PAYMENT header is required"}. For USDC on Base: asset 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, extra {"name":"USD Coin","version":"2"}, maxAmountRequired in 6-decimal units ($0.01 → "10000").
Otherwise base64-decode the header to paymentPayload and POST {url}/verify with {x402Version:1, paymentPayload, paymentRequirements}. If isValid is false, return 402 with error: invalidReason.
Run the handler. Only if it succeeds, POST {url}/settle with the same body. On success add header X-PAYMENT-RESPONSE: base64(JSON settle response).

4. Test

curl -i https://localhost:3000/api/forecast   # expect 402 and an "accepts" array

Then pay with an x402 client (see the x402-client skill) using a funded test wallet, and confirm the settlement hash on the block explorer.

Pitfalls