x402 v2 renamed the payment headers, and most agent code has not noticed
Version 2 of x402 replaced the single X-PAYMENT header with a three-header exchange and moved network identifiers to CAIP-2. The spec changed in December 2025; the tutorials did not. Agents built from published examples will send a header no conforming resource server reads.
A rename is a breaking change when the reader is a machine
The x402 v2 HTTP transport binding defines three headers, each carrying a base64-encoded payload:
| Header | Direction | Payload |
|---|---|---|
PAYMENT-REQUIRED |
server → client | PaymentRequired |
PAYMENT-SIGNATURE |
client → server | PaymentPayload |
PAYMENT-RESPONSE |
server → client | SettlementResponse |
Version 1 had one: X-PAYMENT. An agent that learned the protocol from a v1
example will attach X-PAYMENT to its retry, and a v2 resource server will
treat that request exactly as it treats a request with no payment at all — by
returning another 402. There is no error that says “you used the old header
name”. The failure presents as an infinite retry loop with a payment attached
that nobody reads.
This is the part of the agentic-commerce story that gets undersold. Human developers recover from a rename in minutes because the 404 in their browser sends them to the changelog. An autonomous buyer has no changelog reflex. It has the header name that was in its context window when it was built.
CAIP-2 is the other silent break
v2 also moved network identification to
CAIP-2 identifiers — eip155:8453
rather than a bare chain name, solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp rather
than solana-mainnet. Alongside that, PaymentPayload and PaymentRequired
were restructured, with resource description split out into a separate
ResourceInfo object.
Taken together these are not cosmetic. A client that constructs its payload from a v1 mental model produces a document that fails schema validation at the facilitator, which means the failure surfaces one hop away from the code that caused it.
What a resource server should do about it
Three things, none of them expensive.
First, do not accept the v1 header. It is tempting to read X-PAYMENT as a
fallback and be generous. Resist it: a server that silently accepts both teaches
the ecosystem that the rename did not happen, and it is the only party in the
exchange with an incentive to be strict.
Second, say which version you speak, in the challenge. The 402 response is
the one message every client is guaranteed to read before it pays. Version
information there is worth more than the same information in documentation.
Third, check the facilitator’s /supported endpoint at deploy time, not at
request time. It returns the protocol versions, schemes, networks and
extensions the facilitator will actually settle. Advertising a payment option
your facilitator has not confirmed produces a 402 the client can satisfy and the
server cannot honour — the worst available outcome, because the client has
signed something.
The broader pattern
x402 is a vendor specification with real production deployment, which is a better place to be than most of the agentic stack. But the version-two rename illustrates the structural problem with building an economy on documents that move faster than their readers. The agents buying access were, in many cases, built from a snapshot of the web taken before the change landed.
The mitigation is not slower specifications. It is machine-readable version negotiation in the protocol’s own error path — which x402 has, in the challenge, and which client implementations should be reading rather than assuming.
Sources
This article answers
- which HTTP headers does x402 version 2 use for payment
- why is my X-PAYMENT header being ignored by an x402 server
- what changed between x402 v1 and v2