Lab L-001 · protocol v2

Learn x402 by performing one payment.

How do I learn x402? Run one protocol v2 loop before you memorize the SDK. Request a paid resource with ordinary HTTP. Read the 402. Decode PAYMENT-REQUIRED: a PaymentRequired object with x402Version 2, a resource, and an accepts array. Choose one advertised accept, put a PaymentPayload in PAYMENT-SIGNATURE, and retry. In the default authorization flow the server verifies, serves, then settles, and returns PAYMENT-RESPONSE. This page is that lab. It is not a live wallet, and it is not the protocol field guide — that isdocs.x402.organdx402docs.com.

Protocol objects rechecked against the x402 v2 specification, HTTP transport spec, and official docs on 2026-09-19. Amounts, addresses, and the example signature are copied from the published v2 specification. The weather body and SDK package names are copied from the official seller and buyer quickstarts. x402 Academy is an independent educational publication. It is not affiliated with or endorsed by the x402 Foundation, Coinbase, Cloudflare, or the Linux Foundation.

Tutorial theater

Your first x402 v2 payment

Seat: buyer · no wallet in this browser

Buyer seat

What you hold

Empty-handed GET. You have not chosen a scheme. You have not seen a price.

Seller / facilitator

What they are doing

The /weather handler is behind payment middleware. It will not run yet.

HTTP wire

GET /weather HTTP/1.1
Host: api.example.com
Accept: application/json

Lab notebook

  1. An ordinary GET is allowed to come back 402. That is the start of the lesson, not a failed integration.
  2. The offer lives in PAYMENT-REQUIRED: Base64 of a PaymentRequired object, not in a custom X- header.
  3. x402Version is 2. resource is its own object. accepts[] is the menu. Networks are CAIP-2, not "base-sepolia".
  4. The retry carries PAYMENT-SIGNATURE: a PaymentPayload with accepted (what you chose) and payload (scheme data).
  5. Default payment flow is authorization: verify (read-only), then the resource, then settle, then respond.
  6. PAYMENT-RESPONSE is the receipt. The JSON body is the resource. Log both. Do not treat the body as proof of payment.

Why a theater, not a spec table

x402 is easy to mislearn from a snippet. A snippet that still says X-PAYMENT and network: "base-sepolia" will install, and a mixed facilitator may even answer it. That is how v1 stays current in people’s heads. This lab makes the v2 names the only names that advance the scene. The flow simulator still exists for sequence review. The x402docs field guide still exists for headers, schemes, and production caveats. The Lesson is the hour in class where you have to do the GET.

What v2 changed that this lab will not let you skip

SurfaceV1, shown here only as a trapV2, what this lab accepts
Client payment headerX-PAYMENTPAYMENT-SIGNATURE
Server offer / receiptOften implied by the body or X-PAYMENT-RESPONSEPAYMENT-REQUIRED and PAYMENT-RESPONSE
Networkbase-sepoliaeip155:84532 (CAIP-2)
Version fieldx402Version: 1x402Version: 2
Packagesx402-express, x402-fetch@x402/express, @x402/fetch, @x402/core, @x402/evm

The migration guide is the source for that table. The HTTP transport spec is the source for the three headers: each is Base64 of JSON, respectively a PaymentRequired, PaymentPayload, and SettlementResponse. The v2 specification is the source for the objects on the wire pane, including amount 10000, asset 0x036CbD53842c5426634e7929541eC2318f3dCF7e, payTo 0x209693Bc6afc0C5328bA36FaF03C514EF312287C, and network eip155:84532.

What you type after you can perform it

The theater never runs this code. It is the official v2 seller and buyer shape, copied from the current quickstarts, so the lab and the first commit agree on package names and CAIP-2 IDs. The seller snippet uses the official price: "$0.001" sugar. The wire pane uses the specification’s example atomic amount 10000. Those are two sourced figures, not a conversion claimed by this page.

Seller notebook

import express from "express";
import { paymentMiddleware } from "@x402/express";
import { x402ResourceServer, HTTPFacilitatorClient } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";

const app = express();
const facilitator = new HTTPFacilitatorClient({
  url: "https://x402.org/facilitator",
});
const server = new x402ResourceServer(facilitator);
server.register("eip155:*", new ExactEvmScheme());

app.use(paymentMiddleware({
  "GET /weather": {
    accepts: [{
      scheme: "exact",
      price: "$0.001",
      network: "eip155:84532",
      payTo: process.env.EVM_RECEIVE_ADDRESS,
    }],
    description: "Weather data",
    mimeType: "application/json",
  },
}, server));

app.get("/weather", (_req, res) => {
  res.json({ report: { weather: "sunny", temperature: 70 } });
});

Buyer notebook

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));

const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const response = await fetchWithPayment("http://localhost:4021/weather");

What this sitting proves

Proved in the lab

  • An unpaid GET can be the correct first act.
  • V2 offers travel in PAYMENT-REQUIRED as PaymentRequired with x402Version 2, resource, and accepts[].
  • Clients pay an advertised accept, on PAYMENT-SIGNATURE, not a v1 X-PAYMENT header or a v1 network string.
  • Default ordering is verify (read) → resource → settle (write) → PAYMENT-RESPONSE.

Not proved

  • A live facilitator, funded wallet, or onchain transfer. The amount, addresses, signature, and transaction hash are the specification’s published example.
  • Upto, batch-settlement, upfront, or escrow. Those are real v2 mechanisms; this lab advertised exact with the default authorization flow.
  • Retry safety. Use the payment-identifier extension before you automate a second attempt.

Questions this lab is for

How do I learn x402?

Perform one v2 payment loop before you memorize the SDK. Request a paid resource with ordinary HTTP, read the 402, decode PAYMENT-REQUIRED, choose an accepts entry your client can pay, retry with PAYMENT-SIGNATURE, and inspect PAYMENT-RESPONSE. Then type the same loop in the quickstart and harden it on the seller and buyer-agent tracks. Use docs.x402.org and x402docs.com when you need field-level reference.

What is a simple x402 example?

GET a JSON route. Receive HTTP 402 with a PaymentRequired object (x402Version 2, a resource, and an accepts array). Select exact on eip155:84532. Retry with a PaymentPayload in PAYMENT-SIGNATURE. In the default authorization flow the server verifies, serves the JSON, settles, and returns PAYMENT-RESPONSE. The Lesson stages that loop. It does not broadcast a transaction.

Is The Lesson x402 v1 or v2?

V2. The theater uses PAYMENT-REQUIRED, PAYMENT-SIGNATURE, and PAYMENT-RESPONSE; CAIP-2 network IDs such as eip155:84532; x402Version 2; a resource object separate from accepts; and the scoped packages @x402/express, @x402/fetch, @x402/core, and @x402/evm. X-PAYMENT and "base-sepolia" are the v1 names, shown here only as traps.

Does this page send a real payment?

No. Nothing leaves the browser. Addresses, the atomic amount 10000, the example signature, and the example transaction hash are copied from the published x402 v2 specification. The weather body matches the official seller quickstart. This is a teaching specimen, not a facilitator transcript and not a wallet session.

How is The Lesson different from the flow simulator and from x402docs?

The flow simulator is a sequence stepper. The Lesson is a lab you perform: you issue the request, fail two v1 traps, and choose the advertised accept before the 200 is allowed to exist. x402docs.com is the protocol field guide — headers, schemes, and production caveats. This academy teaches the loop; that site and docs.x402.org own the spec.

Cite the HTTP objects on this page as an illustrative specimen copied from the x402 v2 specification, never as an observed facilitator transcript or a confirmed onchain payment.

Sources used

  1. 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.

  2. x402 HTTP transport (v2)

    Maps PaymentRequired, PaymentPayload, and SettlementResponse onto PAYMENT-REQUIRED, PAYMENT-SIGNATURE, and PAYMENT-RESPONSE as Base64 JSON.

  3. x402 docs: HTTP 402

    Explains how x402 uses HTTP 402 to communicate payment requirements.

  4. x402 docs: Migration Guide V1 to V2

    Header rename (X-PAYMENT → PAYMENT-SIGNATURE), CAIP-2 networks, and scoped packages (@x402/core, @x402/express, @x402/evm).

  5. x402 docs: Payment Schemes

    exact (fixed price), upto (usage cap), and batch-settlement (escrow and later redemption). The Lesson uses exact because the advertised resource has a fixed price.

  6. x402 docs: Quickstart for Sellers

    Official seller setup, package installation, testnet defaults, and payment middleware examples.

  7. x402 docs: Quickstart for Buyers

    Official buyer setup, client package installation, and fetch/axios payment wrappers.

  8. x402 docs: Facilitator

    Defines facilitator responsibilities for payment verification and settlement.

  9. RFC 9110: HTTP Semantics, section 15.5.3

    The HTTP specification reserves status code 402 for future use.