Paywalls for the Agentic Web: Building an x402 Service on Bit2

HTTP has reserved status code 402 "Payment Required" for thirty years and almost never used it. The agentic web finally gives it a reason to exist, and bit2 gives x402 the one thing it was missing: a payment anyone can verify, instantly, without calling anyone else.

The clearing and coordination layer x402 was missing

When a person hits a paywall, they reach for a credit card and usually sign up for an account on the site. When an autonomous agent hits one, it has neither. The agentic web needs a way to charge for a single request (an API call, a file, an inference) and to be paid for it in the same breath, with no need to authenticate and no third party deciding whether the money is real.

x402 is the revival of that idea. It turns HTTP's dormant `402` status into a payment handshake. A server answers an unpaid request with `402` and a machine-readable description of what to pay; the client pays and retries with the payment attached; the server verifies and serves the content. But x402 is only a protocol for carrying a payment. It says nothing about what the payment is, or how the server convinces itself the payment is genuine. That is a settlement problem, and most settlement rails force a bad trade: trust a payment processor, wait for global consensus, or keep a channel open and online.

Bit2 closes the gap: as a client-side-validation network, every payment travels with a compact zero-knowledge proof. The receiver verifies it directly, against the chain's commitments, without replaying the whole network's history, calling back to the payer, or handing the payment to a processor to clear. That is exactly what x402 needs.

This suits what a paywall actually charges: small, per-request amounts. For those, a receiver can act on a payment the moment it verifies, taking a timestamper's bonded pre-confirmation rather than waiting for the on-chain confirmation that settles finality underneath.

We have packaged this into `@bit2/x402`, an Express middleware that turns any endpoint into a pay-per-request resource in a single line of code. Here is how the pieces fit together.

How a bit2 paywall works

Picture a storefront that sells a premium digital asset (say, a high-resolution wallpaper) and wants to be paid per download. The buyer pays with their own bit2 client (their wallet), using a browser extension as the wallet UI to approve the payment; the storefront page runs the exchange around it. Agents skip the UI and talk to the client's API directly. The whole exchange is seven steps over two requests: a 402 challenge, then a paid retry.

1. Request. The buyer's browser asks for the gated resource. No payment is attached yet.
2. Challenge. The server, through the `@bit2/x402` middleware, generates a fresh DID (a single-use destination identifier that privately names the receiving account) and replies `402 Payment Required` with the x402 terms: the price, the asset, the DID to pay, and an expiry.
3. Build the payment. The buyer's page passes the DID and amount to the wallet UI for approval. Once approved, the buyer's bit2 client makes the transfer so it can later be proven and assembles a payment proof addressed to that DID, which goes back to the page.
4. Resubmit. The page retries the original request, now carrying the proof in the x402 `PAYMENT-SIGNATURE` header.
5. Match. The server matches the proof's DID to the open challenge (confirming it is unexpired, unconsumed, and that the amount covers the price), then passes the proof to its own bit2 client.
6. Verify. The bit2 client verifies the payment's zero-knowledge proof independently, confirming the funds are real and have not been spent before.
   The middleware never touches the cryptography itself, it simply relays the client's verdict.
7. Deliver. On success the server marks the challenge consumed and returns the content along with a `PAYMENT-RESPONSE` receipt.

The architecture

Four components, cleanly separated by responsibility:

• The bit2 client. The only piece that touches keys and cryptography. It is effectively the wallet. Each side runs one: the seller's wallet generates DIDs and verifies proofs, whereas the buyer's wallet makes payments and builds those proofs. The client exposes a small HTTP API with the endpoints needed to generate a DID, build a proof, and verify a proof (among others).
• The control layer. What drives the bit2 client over its HTTP API: the bit2 browser extension, which gives a person a wallet UI, or an autonomous agent that calls the API directly.
• The @bit2/x402 middleware. Sits in front of the seller's routes. It speaks x402 to the outside world and delegates every cryptographic decision to the seller's bit2 client.
• x402 itself. The HTTP envelope (the `402`, the `PAYMENT-SIGNATURE`, the `PAYMENT-RESPONSE`) that carries everything above between buyer and seller.

BUYER                                          SELLER
┌────────────────────────┐                     ┌────────────────────────┐
│  browser + wallet UI   │  GET ────────────▶  │     website / API      │
│           │            │  ◀──────── 402+DID  │ + @bit2/x402 (paywall) │
│           │ transfer   │  GET+proof ──────▶  │           │ verify     │
│           ▼            │  ◀──── 200+content  │           ▼            │
│   payer bit2 client    │                     │  receiver bit2 client  │
└────────────────────────┘                     └────────────────────────┘

Top to bottom, the arrows are the x402 exchange in order.

What's not here matters too: no payment processor, no shared database, no open channel between buyer and seller, and the two clients never talk to each other.

Why bit2 underneath x402

x402 will run on many rails, but bit2 brings the properties agentic commerce actually needs. Payments are verifiable and non-interactive: the receiver settles on its own, and the payer can go offline the moment after paying. Verification is client-side and immediate: the receiver checks a succinct zero-knowledge proof, with no need to replay the whole transaction history. It is also cheap and private at scale: a few bytes per payment on L1, room for billions of accounts, and a DID that hides the receiver. A Lightning paywall needs a live payment channel, a rollup paywall typically waits for a confirmation block. A bit2 paywall needs just a proof in a header.

What integration looks like

Putting a price on one of your own endpoints is mostly wiring. The SDK does the protocol for you. Here's the whole setup, end to end over plain HTTP:

• Run a bit2 client as your receiver. It is your wallet and your verifier: it generates the per-request DIDs and validates incoming proofs, exposing the small HTTP API the middleware drives. You point the middleware at its URL, the only connection you configure.
• Add the `@bit2/x402` middleware. This is `@bit2/x402`, the Express middleware that collapses the entire x402 handshake into a single call:

// js
    app.use(await createBit2PaymentMiddleware(
      { "GET /download": { amount: "0.01", token: "USDT" } },   // route -> price in usdt
      { bit2ClientUrl: process.env.BIT2_CLIENT_URL },
    ));

The example prices in USDT, but the charge token is your choice: every bit2 payment carries its own token id. You give it a map of routes to prices and the URL of your bit2 client; it generates the DIDs, returns the `402`, matches presented proofs to open challenges, and delegates verification to your client. That is the whole server change. There's no hosted checkout to redirect to, and no processor account or webhooks to manage.

• Drop in the buyer-facing payment flow. The browser needs a little frontend: code to request the resource, read the `402`, present the amount, DID, and countdown, collect the proof, attach it as the `PAYMENT-SIGNATURE` header, and unlock the content on `200`. The runnable storefront demo ships all of it, so you can lift its page as a starting point. The buyer's payment UI comes from the bit2 wallet extension: it builds the proof and hands it to the page to submit. (An agent skips the page and the wallet UI, and just makes the calls itself.)

After thirty years, `402` finally has a settlement layer behind it. For an agentic web that needs to pay per request, that is the part that was missing.