x402 integration guide

┌──────────────┐     HTTP 402 + requirements    ┌──────────────────┐
│              │ ◄───────────────────────────── │                  │
│    Agent     │                                │   Your Server    │
│   (buyer)    │ ──────────────────────────────►│   + x402         │
│              │  request + PAYMENT-SIGNATURE    │   middleware     │
└──────────────┘                                └────────┬─────────┘
                                                         │
                                          ┌──────────────┼──────────────┐
                                          │              │              │
                                          ▼              ▼              ▼
                                   GET /supported  POST /verify  POST /settle
                                          │              │              │
                                          └──────────────┼──────────────┘
                                                         │
                                                  ┌──────▼───────┐
                                                  │  Facilitator │
                                                  │  (hosted)    │
                                                  └──────┬───────┘
                                                         │
                                                         │ on-chain settlement
                                                         ▼
                                                  ┌──────────────┐
                                                  │   Radius     │
                                                  │   Network    │
                                                  └──────────────┘

Mainnet:
  Chain ID:    723487
  CAIP-2:      eip155:723487
  RPC:         https://rpc.radiustech.xyz

Testnet:
  Chain ID:    72344
  CAIP-2:      eip155:72344
  RPC:         https://rpc.testnet.radiustech.xyz

SBC token:     0x33ad9e4bd16b69b5bfded37d8b5d9ff9aba014fb (6 decimals)

interface X402Config {
  asset: string;            // SBC token address
  network: string;          // CAIP-2 chain ID, e.g. "eip155:723487"
  payTo: string;            // Merchant wallet address (receives payments)
  facilitatorUrl: string;   // Facilitator base URL
  amount: string;           // Raw token units (6 decimals). "100" = 0.0001 SBC
  facilitatorApiKey?: string; // Optional API key if facilitator requires one
}

const config: X402Config = {
  asset: "0x33ad9e4bd16b69b5bfded37d8b5d9ff9aba014fb",
  network: "eip155:723487",
  payTo: "{{MERCHANT_WALLET_ADDRESS}}",
  facilitatorUrl: "https://facilitator.radiustech.xyz",
  amount: "100", // 0.0001 SBC per request
};

function buildPaymentRequired(config: X402Config, requestUrl: string) {
  return {
    x402Version: 2,
    error: "PAYMENT-SIGNATURE header is required",
    resource: {
      url: requestUrl,
      description: "Access to protected resource",
      mimeType: "application/json",
    },
    accepts: [
      {
        scheme: "exact",
        network: config.network,
        amount: config.amount,
        asset: config.asset,
        payTo: config.payTo,
        maxTimeoutSeconds: 300,
        extra: {
          // Use "erc2612" instead if using Stablecoin.xyz
          assetTransferMethod: "permit2",
          name: "Stable Coin",
          version: "1",
        },
      },
    ],
  };
}
 
function return402(config: X402Config, requestUrl: string): Response {
  const paymentRequired = buildPaymentRequired(config, requestUrl);
  return new Response("{}", {
    status: 402,
    headers: {
      "Content-Type": "application/json",
      "PAYMENT-REQUIRED": btoa(JSON.stringify(paymentRequired)),
    },
  });
}

type PaymentOutcome =
  | { status: "no-payment" }
  | { status: "invalid-header"; error: string }
  | { status: "verify-failed"; error: string }
  | { status: "settle-failed"; error: string }
  | { status: "settled"; transaction: string; payer: string; network: string };
 
async function processPayment(
  request: Request,
  config: X402Config
): Promise<PaymentOutcome> {
  // 1. Check for PAYMENT-SIGNATURE header
  const paymentHeader = request.headers.get("PAYMENT-SIGNATURE");
  if (!paymentHeader) {
    return { status: "no-payment" };
  }
 
  // 2. Decode base64 payment payload
  let paymentPayload: any;
  try {
    paymentPayload = JSON.parse(atob(paymentHeader));
  } catch {
    return { status: "invalid-header", error: "Failed to decode PAYMENT-SIGNATURE header" };
  }
 
  const paymentRequirements = {
    scheme: "exact",
    network: config.network,
    amount: config.amount,
    asset: config.asset,
    payTo: config.payTo,
    maxTimeoutSeconds: 300,
    extra: { name: "Stable Coin", version: "1" },
  };
 
  const body = {
    x402Version: 2,
    paymentPayload,
    paymentRequirements,
  };
 
  const headers: Record<string, string> = {
    "Content-Type": "application/json",
  };
  if (config.facilitatorApiKey) {
    headers["x-api-key"] = config.facilitatorApiKey;
  }
 
  // 3. Verify payment with facilitator
  const verifyRes = await fetch(`${config.facilitatorUrl}/verify`, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
  });
 
  if (!verifyRes.ok) {
    const err = await verifyRes.text();
    return { status: "verify-failed", error: err };
  }
 
  // 4. Settle payment on-chain
  const settleRes = await fetch(`${config.facilitatorUrl}/settle`, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
  });
 
  if (!settleRes.ok) {
    const err = await settleRes.text();
    return { status: "settle-failed", error: err };
  }
 
  const settleData = await settleRes.json();
  return {
    status: "settled",
    transaction: settleData.transaction,
    payer: settleData.payer,
    network: settleData.network,
  };
}

// worker.ts — Cloudflare Worker with x402 payment gating
 
interface Env {
  MERCHANT_WALLET: string;
  FACILITATOR_API_KEY?: string;
}
 
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const config: X402Config = {
      asset: "0x33ad9e4bd16b69b5bfded37d8b5d9ff9aba014fb",
      network: "eip155:723487",
      payTo: env.MERCHANT_WALLET,
      facilitatorUrl: "https://facilitator.radiustech.xyz",
      amount: "100", // 0.0001 SBC (6 decimals)
      facilitatorApiKey: env.FACILITATOR_API_KEY,
    };
 
    const outcome = await processPayment(request, config);
 
    switch (outcome.status) {
      case "no-payment":
        return return402(config, request.url);
 
      case "invalid-header":
        return new Response(
          JSON.stringify({ error: "Invalid payment header", detail: outcome.error }),
          { status: 400, headers: { "Content-Type": "application/json" } }
        );
 
      case "verify-failed":
        return new Response(
          JSON.stringify({ error: "Payment verification failed", detail: outcome.error }),
          { status: 402, headers: { "Content-Type": "application/json" } }
        );
 
      case "settle-failed":
        return new Response(
          JSON.stringify({ error: "Payment settlement failed", detail: outcome.error }),
          { status: 502, headers: { "Content-Type": "application/json" } }
        );
 
      case "settled":
        // Payment confirmed — deliver the resource
        const paymentResponse = {
          success: true,
          transaction: outcome.transaction,
          network: outcome.network,
          payer: outcome.payer,
        };
        return new Response(
          JSON.stringify({ data: { message: "Paid content delivered" } }),
          {
            status: 200,
            headers: {
              "Content-Type": "application/json",
              "PAYMENT-RESPONSE": btoa(JSON.stringify(paymentResponse)),
            },
          }
        );
    }
  },
};

GET https://facilitator.radiustech.xyz/supported

{
  "kinds": [
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:723487",
      "extra": {
        "assetTransferMethod": "permit2",
        "name": "Stable Coin",
        "version": "1"
      }
    }
  ],
  "extensions": ["eip2612GasSponsoring"],
  "signers": {}
}

async function validateFacilitator(
  facilitatorUrl: string,
  network: string,
  x402Version: number = 2
): Promise<boolean> {
  const res = await fetch(`${facilitatorUrl}/supported`);
  if (!res.ok) return false;
 
  const data = await res.json();
  return data.kinds.some(
    (k: any) => k.network === network && k.x402Version === x402Version
  );
}