x402 Checker

What does the x402 checker test?

The checker probes your live endpoints — the same Machine Payments and Bazaar Discovery checks as a full AgentGrade scan:

• Live 402 response — at least one endpoint answers with HTTP 402 and a payment challenge.
• Challenge decodable — the 402 carries valid, parseable payment terms: x402Version and accepts[] (v1 JSON body, or the v2 base64 PAYMENT-REQUIRED header).
• Terms complete — payTo (where the money goes) and amount (how much) are present; an agent can't pay a challenge that omits either.
• /.well-known/x402.json exists — the discovery file (a widely used community convention; the official spec’s discovery path is the facilitator Bazaar API) is served and lists your paid services.
• Discovery fields valid — provider name, network, facilitator, payTo, and at least one service with method and path.
• Bazaar discoverability — services declare extensions.bazaar.discoverable with input/output schemas, so catalog indexes can list them.

What is x402?

x402 is the HTTP 402 payment standard coined by Coinbase, now stewarded by the x402 Foundation: a paid endpoint answers an unpaid request with status 402 and a machine-readable challenge quoting the price, network, asset, and recipient (a JSON body in v1; a base64-encoded PAYMENT-REQUIRED header in v2). The agent's wallet inspects the terms, attaches a signed payment proof, and retries — per-call micropayments negotiated entirely in HTTP, no API keys or accounts. See the x402 guide and the Bazaar & discovery guide for implementation walkthroughs.

A valid /.well-known/x402.json example

{
  "x402Version": 2,
  "name": "example.com",
  "network": "base",
  "facilitator": "coinbase",
  "payTo": "0xYourWalletAddress",
  "services": [
    {
      "method": "POST",
      "path": "/your-paid-endpoint",
      "description": "What this endpoint does",
      "amount": "0.50",
      "extensions": { "bazaar": { "discoverable": true } }
    }
  ]
}

Common x402 mistakes

The undecodable header

A Payment-Required header that isn't valid base64, or decodes to something that isn't JSON. Agents give up immediately — the challenge must round-trip through atob + JSON.parse.

Empty accepts[]

A 402 with no payment options tells an agent it must pay but not how. Every challenge needs at least one accepts entry with network, amount, asset, and payTo.

Missing or misnamed discovery fields

/.well-known/x402.json with wallet instead of payTo, or a missing facilitator, fails strict parsers. The field names are the convention parsers expect — get them exactly right.

Declared but not discoverable

Services listed without extensions.bazaar.discoverable: true and schemas can't be indexed by catalogs — agents searching for a service like yours won't find it.

Testnet in production

A testnet: true flag left on in production means agents quoting real payments get test-network terms. Fine while developing, a silent revenue bug after launch.

Frequently asked questions

My API is paid but returns 401, not 402 — do I pass?

No. 401 means "authenticate," which sends agents to a signup page they can't complete. 402 with a machine-readable challenge is what lets an agent pay programmatically. You can serve both: 402 with payment options for agents, alongside your existing key-based auth.

Do I need cryptocurrency to support 402 payments?

No. x402 settles in stablecoins, but the same 402 pattern works with the Machine Payments Protocol from Stripe and Tempo — its Stripe card method (WWW-Authenticate: Payment method="stripe", satisfied by a Shared Payment Token) involves no blockchain at all. The checker detects x402, MPP-style, and L402 challenges alike.

How is this different from a full AgentGrade scan?

This page runs the payments and discovery slice of the full scan. The complete scan covers 70+ checks including MCP, llms.txt, OpenAPI, content negotiation, and infrastructure.