Client & Server

How agents and services interact through b402

b402 follows a client-server model over HTTP. The client (buyer/agent) pays for resources, and the server (seller/service) enforces payment before serving them.

Client = the HTTP requester (buyer, agent, bot). Server = the HTTP responder (seller, API, service provider).

Client (Buyer)

The client initiates requests to b402-enabled endpoints. Clients include:

• AI agents operating autonomously with their own wallets
• Applications making programmatic payments
• Scripts and bots consuming paid APIs

What the Client Does

1. Sends request to a b402-enabled endpoint
2. Receives 402 with payment requirements (amount, token, recipient)
3. Signs EIP-712 payload authorizing the token transfer
4. Resends request with X-PAYMENT header containing the signed payload
5. Receives resource along with settlement confirmation in X-PAYMENT-RESPONSE

Clients never need accounts, API keys, or sessions. Payment is the authentication.

Client Code Example

import { B402 } from 'b402-sdk';

const b402 = new B402('mainnet');

// First request gets 402 with payment requirements
const response = await fetch('https://api.example.com/premium-data');
if (response.status === 402) {
  const requirements = await response.json();

  // Sign and pay
  const result = await b402.pay(wallet, {
    amount: requirements.amount,
    token: requirements.token,
    recipient: requirements.payTo,
  });
}

Server (Seller)

The server provides resources behind a payment gate. Servers include:

• API endpoints, data feeds, compute services
• Content providers and paywalled resources
• Any HTTP service that wants to charge per-request

What the Server Does

1. Receives request from a client
2. Returns 402 Payment Required if no valid payment is attached
3. Forwards payment to the facilitator’s /verify endpoint
4. Calls /settle to execute the on-chain transfer
5. Serves the resource once settlement is confirmed

Server Code Example

Using the Facilitator API directly:

const express = require('express');
const app = express();
app.use(express.json());

app.post('/premium-data', async (req, res) => {
  const { paymentPayload } = req.body;

  // 1. Verify the payment
  const verifyRes = await fetch('https://facilitatorv3.b402.ai/verify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ paymentPayload }),
  });
  const { isValid } = await verifyRes.json();
  if (!isValid) return res.status(402).json({ error: 'Payment required' });

  // 2. Settle on-chain
  const settleRes = await fetch('https://facilitatorv3.b402.ai/settle', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ paymentPayload }),
  });
  const { success, transaction } = await settleRes.json();
  if (!success) return res.status(500).json({ error: 'Settlement failed' });

  // 3. Serve the resource
  res.json({ data: 'premium content', txHash: transaction });
});

Communication Flow

Every transaction is atomic, verifiable, and independent of session state.

Two Payment Models

b402 supports two wallet types, each with a different settlement mechanism:

EOA (Externally Owned Account)

• Standard Ethereum wallet (MetaMask, private key)
• Client signs EIP-712 payload
• Facilitator calls transferWithAuthorization() on the Relayer contract
• Requires prior token approval for the Relayer

Smart Wallet (ERC-7579 Nexus)

• Deterministic smart contract wallet deployed per-user
• Client signs a UserOperation hash
• Facilitator submits to ERC-4337 bundler with paymaster sponsorship
• No prior approval needed (batched in the UserOp)
• Gasless for the user

See the Wallet concept page for details on both models.