What Is the x402 Payment Protocol?

Resources  ·  Concepts

x402 is an HTTP payment protocol built on one premise: payment and authentication are the same transaction. No API key, no account, no subscription. You send a request, receive the payment specification in the response header, pay it with a signed USDC transaction, and get the data — all over standard HTTP, in one cycle.

DocketLayer uses x402 with USDC on Solana for all paid endpoints. We also publish an MCP server that exposes the same court docket capabilities as the REST API. If you're integrating the API, this is worth a few minutes of your time — not because the protocol is complex, but because it changes assumptions you may carry over from conventional API authentication.

The Problem x402 Solves

Most APIs authenticate through API keys or OAuth tokens. Both models work well for developers building human-operated applications: sign up, get a credential, store it, include it with requests, pay the bill at the end of the month.

That model breaks down for autonomous agents. An agent can't sign up for an account. It can't complete an OAuth flow in a browser. It can hold a pre-issued API key, but someone has to provision it, rotate it when it expires, and manage the billing for the account it's attached to. Every query the agent makes is ultimately backstopped by a human-managed account somewhere upstream.

Subscriptions have the same problem in a different form. A subscription pays for capacity — a monthly allocation whether you use it or not. For agents with bursty, event-driven query patterns, that means either overpaying for headroom or scrambling against limits. Neither fits a system designed to query precisely when needed.

x402 removes the account entirely. Any caller that can construct and sign a valid USDC payment can use the API — no prior relationship required.

How the Protocol Works

An x402 transaction follows a four-step handshake over standard HTTP.

Step 1 — Initial request. The client sends a request to a paid endpoint with no authentication header. This is intentional: the client is asking the server what payment is required before committing to one.

Step 2 — 402 response. The server returns HTTP 402 with an X-Payment-Requirements header containing the payment specification as JSON: the required amount in USDC base units, destination wallet address, network, and asset. The client now has everything it needs to construct the payment.

HTTP/1.1 402 Payment Required
X-Payment-Requirements: {
  "x402Version": 1,
  "scheme": "exact",
  "network": "solana-mainnet",
  "maxAmountRequired": "990000",
  "payTo": "<destination_wallet>",
  "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "maxTimeoutSeconds": 300
}

Step 3 — Payment construction and retry. The client constructs a signed USDC transfer on Solana, wraps it in an x402 payment payload, base64-encodes it, and retries the original request with the encoded payment in the x402-payment header.

GET /v2/case?court_code=nysd&case_id=1:24-cv-09822
x402-payment: <base64_encoded_payment_payload>

Step 4 — Verification and response. The server simulates the transaction against the blockchain, verifies it's valid and correctly funded, processes the request, and returns the response. The transaction is then broadcast to settle on-chain as a separate, non-blocking step. The client gets its data without waiting for blockchain confirmation.

The key property is that the flow is entirely stateless from the client's perspective. No session to maintain, no token to store, no credential to rotate. Each request is self-contained. For a step-by-step implementation, see the How x402 Works guide.

x402 in DocketLayer

DocketLayer implements x402 with USDC on Solana mainnet. Every paid endpoint costs $0.99 per successful query. Failed requests — a 422 for a planned court, a 503 because a source portal is down, a 402 where payment couldn't be verified — are never charged.

Solana handles settlement for practical reasons: transaction fees are fractions of a cent, and finality is fast enough that we verify the transaction, return the data, and broadcast settlement without adding meaningful latency. USDC keeps query cost stable — $0.99 today is $0.99 when your agent runs next week.

Each signed transaction includes a recent blockhash, which Solana uses to bound transaction validity to roughly five minutes. This is the replay protection mechanism: a captured x402-payment header cannot be reused. No nonces or session tokens needed — the blockchain handles it.

The sandbox bypasses payment entirely. Add ?test=1 to any request or send X-DocketLayer-Test: 1 to get fixture data with no charge. Use it until your integration is solid, then switch to a funded wallet.

Why This Matters for Autonomous Agents

For anyone building an agent: a funded Solana wallet is the complete credential. No provisioning step, no credential store to manage, no account that can be suspended or rate-limited at the tier boundary.

This also composes naturally. Multiple agents can each hold their own wallet or share one — either way, there's no shared API key creating a single point of failure or rate-limit contention. Each query carries its own payment and is independently authorized. Cost attribution is on-chain, per wallet, per query, with no metering infrastructure required on your side.

For developers building on top of DocketLayer — wrapping it in a larger system, routing queries through an orchestration layer — the same principle applies. Any component in your stack that can hold a Solana wallet and sign a transaction can make API calls, without a credential injected from outside.