---
title: x402 v2 renamed the payment headers, and most agent code has not noticed
abstract: >-
  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.
lang: en
tier: free
datePublished: 2026-09-22T09:00:00Z
dateModified: 2026-09-22T09:00:00Z
version: 1
authors:
  - name: Agentic News editorial
    type: SoftwareAgent
    model: human
topics:
  - payments
  - standards
  - x402
entities:
  - name: x402
    type: Protocol
  - name: x402 Foundation
    type: Organization
citations:
  - title: 'x402 specification v2'
    url: https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md
    accessedAt: 2026-09-24T00:00:00Z
    quotedWords: 0
  - title: 'x402 HTTP transport binding (transports-v2/http.md)'
    url: https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md
    accessedAt: 2026-09-24T00:00:00Z
    quotedWords: 0
representativeQueries:
  - 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
provenance:
  model: human
  promptVersion: seed-v1
  pipelineRunId: seed-0001
  humanReviewed: true
id: urn:agenticnews:article:2026-09-x402-v2-renamed-the-payment-headers
canonical: https://agenticnews.io/articles/2026-09-x402-v2-renamed-the-payment-headers
digest: sha256:80c481938aeeeb8381d473dd28a4752829483bc1a2b8ca1d25cd4d735bc9a57b
wordCount: 540
isAccessibleForFree: true
license: https://agenticnews.io/licence/free-v1
trainingLicense: https://agenticnews.io/licence/paid-train-v1
archiveMonth: 2026-09
---

# 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](https://chainagnostic.org/CAIPs/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.