Learn by doing · protocol v2

Learn x402 by performing one payment.

How do I learn x402? Run one protocol v2 loop. Request a paid resource with ordinary HTTP, read the 402, decode PAYMENT-REQUIRED, choose an advertised accept, retry with PAYMENT-SIGNATURE, and inspect PAYMENT-RESPONSE. The Lesson is that lab. Official docs and the x402docs field guide remain the protocol reference.

Open The LessonStart quickstartOpen x402 docs

Featured lab · L-001

The Lesson

A tutorial theater, not a spec desk. You issue the GET, fail the v1 header trap, pick exact on eip155:84532, and only then is a 200 allowed to exist.

  1. GET /weather
  2. 402 + PAYMENT-REQUIRED
  3. PAYMENT-SIGNATURE retry
  4. verify → resource → settle
  5. 200 + PAYMENT-RESPONSE

Free tools

Practice the flow before you wire a wallet.

Phase 2 adds browser-only teaching tools: a flow simulator, a stack-specific quickstart configurator, and a scheme quiz with reread recommendations.

how does x402 work

x402 Flow Simulator

Step through a full x402 exchange from the first unpaid request through the 402 challenge, signed retry, verification, settlement, and final 200 response.

x402 quickstart

x402 Quickstart Configurator

Pick a framework and network to generate a tailored, copy-paste x402 seller quickstart sequence with explanatory notes.

learn x402

Payment Scheme Quiz

Check your understanding of x402 roles, headers, schemes, networks, facilitator responsibilities, and retry safety.

Course map

Follow the learning path in order.

The concept is deliberately split by role. Sellers enforce payment requirements. Buyer agents discover and pay. Facilitators simplify verification and settlement. Projects make the pieces real.

01The LessonPerform one x402 v2 payment loop in a tutorial theater before you copy SDK snippets.02QuickstartSee the 402 challenge, payment retry, and successful response as one mental model.03Seller trackAdd x402 payment requirements to an API route and test the unpaid and paid paths.04Buyer agent trackWrap a client so it can discover requirements, sign a payload, and retry automatically.05Facilitator trackUnderstand verification, settlement, duplicate settlement protection, and production boundaries.06ProjectsBuild small checkpoints that prove your x402 integration works end to end.

What this site teaches

x402 is not a checkout page. It is an HTTP-native handshake on protocol v2: a client asks for a resource, the server replies 402 with a PaymentRequired object in PAYMENT-REQUIRED, the client retries with a PaymentPayload in PAYMENT-SIGNATURE, and the server returns the resource after verification and settlement, with PAYMENT-RESPONSE as the receipt. That makes it useful for paid APIs and for agents that need to pay per request without creating accounts first.

This academy stays in tutorial mode. When you need exhaustive field definitions, current SDK signatures, or network-specific production rules, usedocs.x402.org as the reference source.

"The 402 (Payment Required) status code is reserved for future use."
Primary source: RFC 9110, section 15.5.3

x402 gives that reserved status code an implementation pattern for programmatic payments. The Linux Foundation page also documents that the x402 project was contributed by Coinbase and established as a Linux Foundation Projects series.

Where to go next

If you have not walked a v2 loop yet, open The Lesson. If you already know the HTTP flow, jump to the seller track. If you are building autonomous clients, start with the buyer agent track. If you need to explain verification and settlement to a teammate, read thefacilitator track before you wire production traffic.

How do I learn x402?

Perform one v2 payment loop in The Lesson: ordinary GET, HTTP 402, decode PAYMENT-REQUIRED, choose an advertised accept, retry with PAYMENT-SIGNATURE, then watch verify, the resource, settle, and PAYMENT-RESPONSE. Type the same loop in the quickstart. Use docs.x402.org and x402docs.com for field-level reference.

What is a simple x402 example?

A paid JSON route on testnet. Unpaid requests return 402 with a v2 PaymentRequired object. The client selects exact on eip155:84532, retries with PAYMENT-SIGNATURE, and reads the resource plus PAYMENT-RESPONSE. The Lesson stages that example without sending a real payment.

Is x402 Academy the protocol specification?

No. This site teaches by doing. Official docs at docs.x402.org and the independent field guide at x402docs.com own current protocol reference, including v1 to v2 migration.

Sources used

  1. x402 docs: Introduction

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

  2. x402 Protocol Specification v2

    Canonical v2 schemas: PaymentRequired, PaymentPayload, SettlementResponse, VerifyResponse, facilitator /verify and /settle, and authorization/upfront/escrow flows. Protocol version field is 2 as of the 2025-12-09 v2.0 spec date.

  3. x402 Foundation GitHub repository

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

  4. RFC 9110: HTTP Semantics, section 15.5.3

    The HTTP specification reserves status code 402 for future use.

  5. Linux Foundation: x402 Foundation

    Governance note that the project was contributed by Coinbase and established as an LF Projects series.

  6. agenteconomy.to data

    Public agent-payment dashboard; homepage adoption figures are a dated July 6, 2026 snapshot.