The x402 protocol resurrects HTTP status code 402 (Payment Required) to let agents pay per API request. Instead of OAuth tokens or API keys tied to monthly billing, an agent attaches cryptographic payment proof to each HTTP request header. The protocol splits payment negotiation from service delivery across two requests, which creates new boundaries for replay prevention, policy enforcement, and service validation.
The Two-Request Flow
The first request asks for a paid resource without payment material. The server responds with 402 Payment Required and a JSON payload describing the price, network, resource path, and expiration timestamp.
The second request repeats the original path but adds a PAYMENT-SIGNATURE header containing signed payment proof. If valid, the server returns 200 OK with the resource and a PAYMENT-RESPONSE header confirming the facilitator result.
GET /v1/report/42 HTTP/1.1
Host: paid-ai-api.example
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: {"amount":"0.01","network":"base","resource":"/v1/report/42","expiresAt":"2026-05-25T09:31:00Z"}
GET /v1/report/42 HTTP/1.1
Host: paid-ai-api.example
PAYMENT-SIGNATURE: <signed-payload>
HTTP/1.1 200 OK
PAYMENT-RESPONSE: <facilitator-result>
Content-Type: application/jsonThis two-step pattern keeps standard HTTP client libraries compatible. The agent sees a 402, constructs payment proof, and retries with the signature header. No custom transport layer required.
Where Payment Proof Ends
The PAYMENT-SIGNATURE header carries a signed message that proves the agent authorized a specific payment amount for a specific resource at a specific time. The signature typically covers:
- Payment amount and currency or token
- Target resource path
- Expiration timestamp
- Network identifier (e.g., Base, Ethereum L2)
- Nonce or unique request ID
The server validates the signature against the agent’s public key or wallet address. If the signature is valid and the payment clears through the facilitator (a payment processor or smart contract), the request proceeds.
Payment proof does not encode business logic. It does not say “allow 10 requests per hour” or “reject requests from this IP range.” Those decisions belong to the policy layer.
Replay Attack Prevention
A valid payment signature could be copied and reused for multiple requests. The protocol prevents this with three mechanisms:
Nonce binding: Each payment signature includes a unique nonce. The server tracks used nonces and rejects duplicates. This requires server-side state but keeps the attack surface small.
Timestamp expiration: The expiresAt field in the 402 response limits signature validity to a short window (often 60 seconds). Expired signatures are rejected even if the nonce is fresh.
Resource path binding: The signature covers the exact resource path. A signature for /v1/report/42 cannot be reused for /v1/report/43. This prevents bulk replay across endpoints.
The combination means an attacker must compromise the agent’s signing key to generate new valid signatures. Copying existing signatures yields no advantage.
Policy Enforcement Layers
x402 separates payment validation from access control. The protocol confirms the agent paid, but it does not decide whether the agent should be allowed to pay in the first place.
| Layer | Responsibility | Implementation |
|---|---|---|
| Protocol | Validate signature, check nonce, verify expiration | Server middleware |
| Policy | Rate limits, quota, IP allowlists, agent identity | Application logic |
| Service | Business rules, data access, response formatting | API handler |
An agent might pass payment validation but fail policy checks. For example, the server might enforce a rate limit of 100 requests per hour per wallet address. The 101st request would have a valid payment signature but would be rejected at the policy layer with a 429 status code.
This separation lets service providers change policy without modifying the payment protocol. An API might start with no rate limits, add per-wallet quotas later, and eventually introduce tiered pricing based on agent reputation, all without touching the x402 flow.
Service Validation After Payment
The agent paid before receiving the resource. If the server returns an error or incomplete data, the agent needs a way to validate service delivery and potentially dispute the charge.
The PAYMENT-RESPONSE header provides a facilitator receipt. This receipt is a signed message from the payment processor confirming the transaction. The agent can store this receipt and compare it against the HTTP response.
If the server returns 500 Internal Server Error after accepting payment, the agent has proof of payment without proof of delivery. The facilitator can mediate disputes by checking whether the server logged a successful response for that transaction ID.
For streaming responses (e.g., LLM token generation), the protocol becomes more complex. The agent might pay upfront for 1,000 tokens but receive only 200 before the connection drops. The facilitator needs to track partial delivery and issue refunds or credits. This requires the server to send periodic delivery confirmations as the stream progresses.
Rate Limiting Without API Keys
Traditional API key systems tie rate limits to the key. If an agent shares its key or the key leaks, the rate limit is shared or exhausted by an attacker.
x402 ties rate limits to the wallet address or public key used to sign payment proofs. Each agent has a unique cryptographic identity. The server tracks request counts per identity without issuing or managing API keys.
This model works well for agent-to-agent payments where the calling agent is itself a service. The agent does not need to register with the API provider or store a secret key. It uses its existing wallet to sign payments.
A tradeoff is that wallet addresses are pseudonymous, not anonymous. If an agent reuses the same address across multiple services, those services can correlate activity. Privacy-conscious agents need to rotate addresses or use privacy-preserving payment networks.
Metadata Attachment
The payment signature can include arbitrary metadata fields. This lets agents attach context to each request without polluting the HTTP query string or body.
Example metadata:
- Agent version or framework identifier
- Upstream request ID for tracing
- Policy preferences (e.g., “do not log this request”)
- Reputation score from a third-party oracle
The server can use this metadata for logging, analytics, or conditional logic. For example, an API might offer lower prices to agents with high reputation scores. The agent includes its reputation proof in the payment metadata, and the server validates the proof before applying the discount.
Metadata is signed along with the payment proof, so the server knows it came from the agent and was not tampered with in transit.
// Agent constructs signed payload with metadata
const payload = {
amount: "0.01",
network: "base",
resource: "/v1/report/42",
nonce: generateNonce(),
expiresAt: Date.now() + 60000,
metadata: {
agentVersion: "orchestrator-v2.3",
traceId: "req-abc-123",
reputationProof: signedReputationToken
}
};
const signature = sign(payload, agentPrivateKey);Failure Modes
Facilitator downtime (High Impact): If the payment processor is unavailable, the server cannot validate payment proofs. The agent sees 402 responses but cannot complete the second request. The server can cache recent payment validations and allow a grace period, but this introduces replay risk. This directly impacts the service validation question: without a live facilitator, agents cannot verify that payment cleared before the API processes the request.
Clock skew (Operational): If the agent’s clock is ahead of the server’s clock, the agent might generate a signature with an expiration timestamp in the future. The server rejects it as invalid. Agents need NTP or a similar time sync mechanism.
Gas price spikes (Operational): On-chain payments can become expensive during network congestion. The agent might pay more in transaction fees than the API resource costs. Off-chain facilitators (e.g., state channels, rollups) mitigate this but add complexity.
Partial delivery disputes (High Impact): Streaming responses create ambiguity about what was delivered. The facilitator needs detailed logs from both agent and server to resolve disputes. This increases operational overhead.
Technical Verdict
Use x402 if your agent infrastructure already manages wallet keys and you operate in a multi-agent ecosystem where per-request micropayments make economic sense. It works well for public APIs consumed by autonomous agents that cannot pre-register or store secrets, and when you want to avoid the overhead of API key management, OAuth flows, or monthly billing reconciliation.
Avoid x402 if your API serves primarily human users who expect traditional authentication, if you need sub-millisecond latency (payment validation adds round-trip overhead), if your agent framework does not support Ed25519 or secp256k1 key rotation, or if your deployment environment cannot securely store private keys (e.g., serverless functions with ephemeral storage). The protocol also assumes reliable facilitator uptime: if your payment processor has an SLA below 99.9%, expect user-facing failures during outages.
The two-request flow and replay prevention mechanisms are solid, but the lack of standardized facilitator APIs means each implementation will handle disputes and partial delivery differently. Expect integration friction until the ecosystem matures.