Skip to content

docs(x402): put the API key before the code example and end "check that it works" with a paid Sepolia settlement #2413

Open

Description

@GigaHierz

What happens

On build/agents/x402.mdx (last changed by #2397, merged 2026-10-21) the order is:

  1. "Pointing a Resource Server at It" — code example reading X402_API_KEY
  2. "Getting an API Key"
  3. "Check that it works" — an unpaid curl that returns 402 and, as the page says, "needs no API key"

A reader who copies the example and runs the check gets a green result without ever creating a key. The facilitator's /verify and /supported are open and only /settle needs the key, so the integration looks healthy until a real buyer pays.

This is the path one seller took: 8 public hosts advertising 1,062 Celo routes, 15 of 15 paid attempts by an independent buyer refused at /settle with 401 Missing X-API-Key, zero USDC moved (vet402 public ledger, 2026-10-19 → 10-26). The page already states the fact ("an integration can look healthy until its first settlement"); the order defeats it.

Suggested fix

  • Move "Getting an API Key" above the code example and make X402_API_KEY a stated prerequisite.
  • End "Check that it works" with a paid step on Celo Sepolia through the key (the Celo Composer template's pnpm api:buy already does this), so the check fails without a key.
  • One sentence at the first mention of /verify: verifying succeeds without a key; settling does not.

The same reorder is a box on the facilitator repo's docs/RESOURCE_SERVER.md (celo-org/x402-facilitator#369).

Acceptance criteria

  • Key section precedes the code example
  • "Check that it works" ends with a paid Sepolia settlement and names the 401 a keyless seller would see
  • mint validate and mint broken-links pass

Refs #2263, #2397.

Activity

  1. self-assigned this
    on Oct 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions