Glossary

x402 Glossary for Builders

Use this glossary when a tutorial says a term once and then expects you to remember it.

Core protocol terms

The easiest way to read x402 code is to separate HTTP words from payment words. HTTP moves the request, status, headers, and response. The payment scheme decides how a buyer signs, how a seller verifies, and how settlement happens on the selected network.

"x402 uses CAIP-2 standard network identifiers."
Primary source: x402 docs: Networks and Token Support
HTTP 402
The Payment Required status code. RFC 9110 reserves it for future use; x402 defines a practical payment negotiation pattern around it.
Buyer
The client, app, or agent requesting a paid resource and supplying a signed payment payload when it chooses to pay.
Seller
The resource server that declares payment requirements, verifies payment, and serves the paid resource after valid payment.
Payment requirements
The seller-declared options a buyer may satisfy, including scheme, price, network, destination, description, and content type.
Payment payload
The signed object a buyer sends back to prove it authorizes payment according to one selected requirement.
PAYMENT-REQUIRED
The payment challenge information communicated when a request needs payment. The x402 repository describes this as part of the typical flow.
PAYMENT-SIGNATURE
The header used in the repository flow for a retry that carries the buyer payment payload.
PAYMENT-RESPONSE
The response metadata returned after successful settlement in the repository flow.
Facilitator
An optional service that helps sellers verify payment payloads and submit settlement transactions.
Scheme
The payment mechanism selected by the buyer and seller, such as exact payment for a declared price.
Network identifier
A CAIP-2 style identifier such as eip155:8453 or eip155:84532, used so payment requirements are unambiguous across chains.
payTo
The seller receiving address for a payment requirement. It should be configuration, not a private key.
Settlement
The execution step that submits or finalizes the payment on the selected network after verification.
Idempotency
A retry safety property. The payment-identifier extension lets clients and servers associate retries with one logical payment.

Header names are part of the flow

The repository flow describes a seller returning payment-required data, a buyer retrying with a payment signature, and a seller returning payment response data after settlement. When you debug x402, capture headers as well as bodies. Otherwise you will miss the protocol state.

Money terms are operational terms

Price, network, destination, and scheme should be treated as production configuration. They deserve review, environment separation, and logs. A typo in a normal API description is embarrassing. A typo in a receive address or network identifier can become a payment incident.

Retry terms are safety terms

Idempotency is not an optimization. It is a payment safety feature for unreliable networks, process restarts, load-balanced servers, and impatient agents. If retries can happen, write down whether your server supports payment identifiers and what the buyer should do when it cannot confirm the outcome.

Sources used

  1. x402 docs: Introduction

    Defines x402 as an open payment standard for charging APIs and content directly over HTTP.

  2. x402 docs: HTTP 402

    Explains how x402 uses HTTP 402 to communicate payment requirements.

  3. x402 docs: Client / Server

    Summarizes client and server responsibilities in x402.

  4. x402 docs: Facilitator

    Defines facilitator responsibilities for payment verification and settlement.

  5. x402 docs: Networks and Token Support

    Documents CAIP-2 network identifiers and supported network namespaces.

  6. x402 docs: Payment-Identifier extension

    Documents idempotency support for retries without duplicate payment processing.

  7. x402 Foundation GitHub repository

    Open-source SDKs, examples, and the typical x402 request/payment/settlement flow.

  8. RFC 9110: HTTP Semantics, section 15.5.3

    The HTTP specification reserves status code 402 for future use.