x402 payment protocol

x402 payment protocol

x402 is the core of Otonix machine-to-machine payments.

It turns payment into a standard HTTP negotiation.

The idea

1. Client requests a paid resource.

2. Server replies 402 Payment Required with exact payment requirements.

3. Client pays USDC on-chain.

4. Client retries the same request with a payment proof.

Networks and assets

• Network: Base mainnet (eip155:8453)

• Asset: USDC on Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

• Treasury: 0x36363e573a3b5d4C22b6A64ef3080E5C101E685F

• x402 version: 2

Full flow (domain registration example)

1

1) Request the resource (no payment proof)

POST /api/vercel/register

curl -i -X POST "https://app.otonix.tech/api/vercel/register" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","expectedPrice":9.99}'

2

2) Receive 402 Payment Required

The server returns:

• HTTP status: 402

• Header: X-Payment-Required: <base64(requirements)>

• Body: requirements in JSON

{
  "error": "payment_required",
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "maxAmountRequired": "9990000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x36363e573a3b5d4C22b6A64ef3080E5C101E685F"
    }
  ],
  "resource": "/api/vercel/register",
  "description": "Domain registration: example.com ($9.99 USDC)",
  "extra": {
    "orderId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "amountUSDC": 9.99
  }
}

maxAmountRequired is in USDC 6 decimals.

• 9.99 USDC → 9990000

3

3) Send USDC on-chain

Send a USDC transfer to the treasury on Base.

Wait for transaction confirmation.

You must keep:

• txHash

• payer address

• orderId

4

4) Retry with payment proof

Send the same request body.

Attach X-Payment with base64-encoded JSON:

X-Payment: <base64(json)>

curl -sS -X POST "https://app.otonix.tech/api/vercel/register" \
  -H "Content-Type: application/json" \
  -H 'X-Payment: eyJ0eEhhc2giOiIweGFiYy4uLiIsInBheWVyIjoiMHg3NDIuLi4iLCJvcmRlcklkIjoiYTFiMi4uLiJ9' \
  -d '{"domain":"example.com","expectedPrice":9.99}'

5

5) Server verifies then delivers

The server verifies all items below.

If valid, it returns 201 Created with a receipt.

Payment proof format

X-Payment is base64 of a JSON string.

{
  "txHash": "0xabc123def456...",
  "payer": "0x742d35Cc6634C0532925a3b844Bc9e7595f...",
  "orderId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}

Creating X-Payment (copy/paste)

You must send the raw base64 string as the header value.

macOS / Linux

PROOF_JSON='{"txHash":"0xabc...","payer":"0x742...","orderId":"a1b2..."}'
X_PAYMENT=$(printf '%s' "$PROOF_JSON" | base64 | tr -d '\n')

curl -sS -X POST "https://app.otonix.tech/api/vercel/register" \
  -H "Content-Type: application/json" \
  -H "X-Payment: $X_PAYMENT" \
  -d '{"domain":"example.com","expectedPrice":9.99}'

Linux (GNU coreutils)

Verification rules (server-side)

The server must verify all of the following:

• orderId exists and is not expired (15-min TTL).

• orderId is bound to this endpoint resource.

• txHash has never been used before (replay protection).

• On-chain receipt.from matches payer.

• USDC Transfer amount is >= 99% of required amount.

• Transaction status is success on Base.

Order consumption should happen only after all checks pass. This keeps the flow idempotent.

On-chain verification (USDC Transfer)

Typical verifier logic:

1. Fetch transaction receipt from Base RPC.

2. Check receipt.status === "success".

3. Check receipt.from === proof.payer.

4. Find a Transfer log:

   • log.address === USDC contract

   • topics[0] === 0xddf252ad... (Transfer signature)

   • recipient topic matches treasury address

5. Decode log.data as uint256.

6. Convert to USDC: amount = value / 1e6.

7. Compare with required amount.

x402 configuration endpoint

GET /api/x402/config

{
  "treasuryAddress": "0x36363e573a3b5d4C22b6A64ef3080E5C101E685F",
  "usdcContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "chainId": 8453,
  "network": "eip155:8453",
  "facilitatorUrl": "https://x402.org/facilitator"
}

Paid endpoints

• POST /api/vercel/register — domain registration (dynamic price)

• POST /api/cherry/servers/:projectId — VPS provisioning (dynamic price)

Order security model (implementation notes)

• Each 402 generates a unique orderId using crypto.randomBytes(16).toString("hex").

• Orders expire after 15 minutes.

• Orders should be auto-cleaned (example: every 60 seconds).

• Orders are bound to the endpoint resource string (resource binding).

• Each txHash must be single-use (replay protection).

Common 402 error variants

All of these return 402.

• payment_required — first request, missing X-Payment.

• payment_invalid — expired/invalid order id.

• payment_invalid — resource mismatch.

• payment_invalid — tx hash already used.

• payment_invalid — on-chain tx failed.

• payment_invalid — payer mismatch.

• payment_invalid — insufficient amount.

TypeScript client integration

This snippet follows the expected request pattern.

TypeScript

import { executeX402Payment, type X402Config, type PaymentStepFn } from "@/lib/x402-client";

const config: X402Config = {
  treasuryAddress: "0x36363e573a3b5d4C22b6A64ef3080E5C101E685F",
  usdcContract: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  chainId: 8453,
  network: "eip155:8453",
  facilitatorUrl: "https://x402.org/facilitator",
  protocol: "x402",
};

const onStep: PaymentStepFn = (step) => {
  // "signing" | "sending" | "confirming" | "verifying"
  console.log(`Payment step: ${step}`);
};

const response = await executeX402Payment(
  "https://app.otonix.tech/api/vercel/register",
  "POST",
  { domain: "myagent.com", expectedPrice: 9.99 },
  wallets,
  walletAddress,
  config,
  onStep,
);

if (response.ok) {
  const result = await response.json();
  console.log("Domain registered:", result);
}

Transaction recording

Every successful x402 payment should produce a transaction record.

{
  "type": "debit",
  "amount": 9.99,
  "currency": "USDC",
  "description": "Domain registration: example.com",
  "status": "completed",
  "fromAddress": "0x742d35Cc...",
  "toAddress": "0x36363e573a3b5d4C22b6A64ef3080E5C101E685F",
  "txHash": "0xabc123...",
  "metadata": {
    "category": "domain",
    "domain": "example.com",
    "expectedPrice": 9.99,
    "orderId": "a1b2c3d4...",
    "protocol": "x402",
    "chainId": 8453
  }
}