x402 V2 headers: PAYMENT‑REQUIRED, PAYMENT‑SIGNATURE and PAYMENT‑RESPONSE

The x402 V2 HTTP transport moves all protocol data into headers: the response body is left to the server. Each header value is a Base64-encoded JSON object. The object types themselves are defined in the V2 core specification. If you are new to the flow, start with What is x402?.

The three headers at a glance

Encoding: Base64 JSON

To read a header, Base64-decode the value and parse the result as UTF-8 JSON. To write one, serialize the object and Base64-encode it. A few practical points:

• Header names are case-insensitive in HTTP (RFC 9110, section 5.1). Some servers emit payment-required in lower case (the Settlens demo target does), so clients must match names case-insensitively.
• The specification examples use standard Base64 with padding. Settlens' decoder accepts the standard and URL-safe alphabets and refuses values longer than 131,072 characters.
• Do not rely on the response body. The transport says bodies are a server implementation concern; a V2 client reads the terms from the header.
• Large values can hit proxy and server header-size limits, so keep descriptions and extensions short.

PAYMENT-REQUIRED

Sent with HTTP 402 when a request carries no valid payment. It tells the client what the resource is and every way it can be paid.

PaymentRequired fields

Payment requirements: each accepts entry

ResourceInfo

url is required: it identifies the protected resource the payment is for. The optional fields are description, mimeType, serviceName (printable ASCII, at most 32 characters), tags (at most 5, each at most 32 characters) and iconUrl (absolute http or https URL, at most 2048 characters).

Decoded example

The response below is the example from the HTTP transport specification. The header value was produced at build time by encoding the decoded object underneath; it matches the specification byte for byte.

HTTP/1.1 402 Payment Required
Content-Type: application/json
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQQVlNRU5ULVNJR05BVFVSRSBoZWFkZXIgaXMgcmVxdWlyZWQiLCJyZXNvdXJjZSI6eyJ1cmwiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbS9wcmVtaXVtLWRhdGEiLCJkZXNjcmlwdGlvbiI6IkFjY2VzcyB0byBwcmVtaXVtIG1hcmtldCBkYXRhIiwibWltZVR5cGUiOiJhcHBsaWNhdGlvbi9qc29uIn0sImFjY2VwdHMiOlt7InNjaGVtZSI6ImV4YWN0IiwibmV0d29yayI6ImVpcDE1NTo4NDUzMiIsImFtb3VudCI6IjEwMDAwIiwiYXNzZXQiOiIweDAzNkNiRDUzODQyYzU0MjY2MzRlNzkyOTU0MWVDMjMxOGYzZENGN2UiLCJwYXlUbyI6IjB4MjA5NjkzQmM2YWZjMEM1MzI4YkEzNkZhRjAzQzUxNEVGMzEyMjg3QyIsIm1heFRpbWVvdXRTZWNvbmRzIjo2MCwiZXh0cmEiOnsibmFtZSI6IlVTREMiLCJ2ZXJzaW9uIjoiMiJ9fV19

{}

{
  "x402Version": 2,
  "error": "PAYMENT-SIGNATURE header is required",
  "resource": {
    "url": "https://api.example.com/premium-data",
    "description": "Access to premium market data",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:84532",
      "amount": "10000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "maxTimeoutSeconds": 60,
      "extra": {
        "name": "USDC",
        "version": "2"
      }
    }
  ]
}

Read it as: pay 10000 atomic units of the token at 0x036C…CF7e on Base Sepolia (eip155:84532), whose EIP-712 domain name is USDC, to 0x2096…287C, within 60 seconds, for https://api.example.com/premium-data. With 6 decimals, as USDC has, that is 0.01.

Extensions

Servers advertise optional features in extensions, and clients echo them in their payload. A client must include at least the info it received: it may append information but cannot delete or overwrite it.

PAYMENT-SIGNATURE

Sent by the client on the retried request. It carries the payment authorization for exactly one of the advertised options.

PaymentPayload fields

For the exact scheme on EVM chains with the default EIP-3009 transfer method, payload holds a 65-byte EIP-712 signature and the authorization it signs: from, to, value, validAfter, validBefore and a 32-byte nonce. The EIP-3009 guide explains each field and how the signature is built. Other transfer methods, such as Permit2, use a different payload shape.

{
  "x402Version": 2,
  "resource": {
    "url": "https://api.example.com/premium-data",
    "description": "Access to premium market data",
    "mimeType": "application/json"
  },
  "accepted": {
    "scheme": "exact",
    "network": "eip155:84532",
    "amount": "10000",
    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
    "maxTimeoutSeconds": 60,
    "extra": {
      "name": "USDC",
      "version": "2"
    }
  },
  "payload": {
    "signature": "0x2d6a7588d6acca505cbf0d9a4a227e0c52c6c34008c8e8986a1283259764173608a2ce6496642e377d6da8dbbf5836e9bd15092f9ecab05ded3d6293af148b571c",
    "authorization": {
      "from": "0x857b06519E91e3A54538791bDbb0E22373e36b66",
      "to": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "value": "10000",
      "validAfter": "1740672089",
      "validBefore": "1740672154",
      "nonce": "0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f13480"
    }
  }
}

PAYMENT-RESPONSE

Sent by the server with the final response, after settlement. It carries a settlement response.

{
  "success": true,
  "transaction": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "network": "eip155:84532",
  "payer": "0x857b06519E91e3A54538791bDbb0E22373e36b66"
}

{
  "success": false,
  "errorReason": "insufficient_funds",
  "transaction": "",
  "network": "eip155:84532",
  "payer": "0x857b06519E91e3A54538791bDbb0E22373e36b66"
}

settlement_pending is the one non-terminal error: the transaction was broadcast but its confirmation could not be established. The caller should reconcile on chain with the returned hash before deciding whether to retry. Every value of errorReason is listed in the x402 error codes reference.

Status codes

Validation pitfalls

The official schema in @x402/core 2.28.0 checks types and required fields, and is permissive about values. The table below was computed when this page was built: each row changes one field of the example above (the V1 row replaces the whole object), then runs the pinned SDK schema and Settlens' offline checks against it, with https://api.example.com/premium-data as the requested URL.

Three rows deserve a comment:

• Role constants. The core specification allows payTo to be a role constant such as "merchant". On eip155 networks Settlens requires a 20-byte address, because the to field of an EIP-3009 authorization is an address.
• V1 objects. The SDK schema accepts both protocol versions, so a V1 object passes it. A V2 header must carry x402Version: 2, which Settlens checks separately. The V1 to V2 migration guide maps every renamed field.
• Missing extra. No scan check fails, yet the exact EVM specification makes extra.name and extra.version required for EIP-3009: a client cannot build the signature without the token's EIP-712 name and version, and Settlens' offline verify-payment refuses to verify without them.

How Settlens checks each header

PAYMENT-REQUIRED

A passive scan sends the request without any payment header and runs these checks on the answer. The same content checks run offline when an agent passes the header to the MCP tool evaluate_payment_requirements.

PAYMENT-SIGNATURE

Passive scans never send this header, and Settlens refuses a user-supplied one. With the endpoint owner's authorization, the active probe sends one intentionally invalid value:

Separately, a captured authorization can be verified offline: the CLI's verify-payment reads a JSON file with the requirement and the payload (the same paymentRequirements and paymentPayload pair a server sends to /verify also works), and the MCP tool verify_payment_signature accepts the raw header value.

PAYMENT-RESPONSE

Settlens does not inspect PAYMENT-RESPONSE. It never completes a payment and never calls /settle, so an endpoint that behaves correctly never sends one to a scan.

Every check id, with its severity and remediation, is listed in the check reference. To run them against your own endpoint, see Assess or the CLI reference. To decode and check a single header in your browser, paste it into the x402 payment request checker.