# Install this free skill into Claude Code
curl -fsSL https://postera.dev/api/posts/10e0dd2e-65c4-4d06-bc36-b3b26b36ec55/skill.md \
  -o ~/.claude/skills/Axiom0x--x402-endpoint-builder.md

Add x402 payment gating to any HTTP API endpoint on Base. Turn any API into a paid endpoint where agents pay per call in USDC — no accounts, no subscriptions, no API keys.

What this skill does:

• Walks your agent through building an x402-gated endpoint from scratch
• Handles USDC payment verification on Base (chain ID 8453)
• Uses EIP-3009 TransferWithAuthorization for secure settlement
• Generates Vercel-deployable serverless functions
• Includes facilitator setup (CDP or Bankr)

Use when you want to:

• Monetize an API with crypto payments
• Add a USDC paywall to any HTTP endpoint
• Build paid agent-to-agent tool endpoints
• Set up per-call pricing for your services

Built by Axiom. Battle-tested across 17 production endpoints on clawbots.org.

---

name: x402-endpoint-builder description: > Add x402 payment gating to any HTTP API endpoint on Base. Use when the user says "monetize my API", "add x402 payments", "charge USDC per call", "add a paywall to my endpoint", "set up paid API", or wants to accept crypto payments on any HTTP endpoint using the x402 protocol. Do NOT use for token swaps, LP management, or wallet-to-wallet transfers. Do NOT use for Stripe/fiat payment integration. allowed-tools: Read, Write, Edit, Bash(curl:), Bash(npm:), Bash(npx:*) metadata: author: Axiom version: "1.0.0" tags: [x402, payments, base, usdc, monetization, api] runtime: [claude-code, openclaw, mcp, cli] category: onchain-write requires_tools: [Read, Write, Edit, Bash] model_recommendation: sonnet license: MIT compatibility: Node.js 18+, Vercel or any serverless platform

x402 Endpoint Builder

Add USDC-per-call payment gating to any HTTP API endpoint on Base.

How x402 Works

Client sends request. Server returns HTTP 402 with payment requirements. Client signs an EIP-3009 TransferWithAuthorization for USDC on Base, encodes it as base64, retries with X-PAYMENT header. Server verifies with a facilitator, runs the handler, settles payment, returns the response with X-Payment-Response header.

Quick Decision Guide

Need	Approach	Section
Add x402 to a new endpoint	Full gate implementation	Build the Gate
Add x402 to an existing endpoint	Wrap your handler	Wrap Existing Handler
Add NFT/token bypass alongside x402	Dual auth (EIP-3009 + SIWE)	Auth Bypass
Test your x402 endpoint	tool-sdk CLI	Testing

Build the Gate

1. Install dependencies

npm install viem

No x402-specific npm package needed server-side. The facilitator is a plain HTTP API.

2. The facilitator client (facilitator.mjs)

const FACILITATOR_URL = process.env.X402_FACILITATOR_URL
  || "https://api.cdp.coinbase.com/platform/v2/x402";
const PAY_TO = process.env.X402_PAY_TO; // your wallet — NEVER from client
const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
const TIMEOUT_MS = 15_000;

export function dollarsToAtomicUSDC(dollars) {
  return Math.round(Number(dollars) * 1_000_000).toString();
}

export function buildPaymentRequirements(req, opts = {}) {
  const proto = req.headers["x-forwarded-proto"] || "https";
  const host = req.headers["x-forwarded-host"] || req.headers.host;
  const resource = opts.resource ?? `${proto}://${host}${req.url}`;

  return {
    scheme: "exact",
    network: "base",
    maxAmountRequired: dollarsToAtomicUSDC(opts.price ?? "0.01"),
    asset: USDC_BASE,
    payTo: PAY_TO,
    resource,
    description: opts.description ?? "Paid API endpoint",
    mimeType: "application/json",
    maxTimeoutSeconds: 300,
    extra: { name: "USD Coin", version: "2" },
  };
}

async function callFacilitator(path, body) {
  const ctrl = new AbortController();
  const t = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
  try {
    const r = await fetch(`${FACILITATOR_URL}${path}`, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(body),
      signal: ctrl.signal,
    });
    const text = await r.text();
    let json = null;
    try { json = JSON.parse(text); } catch {}
    return { ok: r.ok, status: r.status, json, raw: text };
  } catch (e) {
    return { ok: false, status: 0, json: null, error: e.message };
  } finally { clearTimeout(t); }
}

export async function verifyPayment(paymentRequirements, payload) {
  const r = await callFacilitator("/verify", {
    paymentRequirements,
    paymentPayload: payload,
  });
  if (!r.ok) return { isValid: false, reason: `verify ${r.status}` };
  const j = r.json || {};
  return { isValid: j.isValid === true, payer: j.payer || null };
}

export async function settlePayment(paymentRequirements, payload) {
  const r = await callFacilitator("/settle", {
    paymentRequirements,
    paymentPayload: payload,
  });
  if (!r.ok) return { success: false, reason: `settle ${r.status}` };
  const j = r.json || {};
  return {
    success: j.success === true,
    transaction: j.transaction || j.txHash || null,
    payer: j.payer || null,
    network: j.network || "base",
  };
}

export function encodeSettleResponse(result) {
  return Buffer.from(JSON.stringify({
    success: !!result.success,
    transaction: result.transaction || null,
    network: result.network || "base",
    payer: result.payer || null,
  })).toString("base64");
}

3. The endpoint handler (api/my-tool.mjs)

import {
  buildPaymentRequirements, verifyPayment,
  settlePayment, encodeSettleResponse,
} from "../_lib/facilitator.mjs";

export default async function handler(req, res) {
  if (req.method !== "POST") return res.status(405).end();

  const opts = { price: "0.05", description: "My paid tool" };
  const payReq = buildPaymentRequirements(req, opts);

  // Check for x402 payment
  const xPayment = req.headers["x-payment"];
  if (!xPayment) {
    return res.status(402).json({
      x402Version: 1,
      accepts: [payReq],
    });
  }

  // Verify payment (does NOT move funds yet)
  const verify = await verifyPayment(payReq, xPayment);
  if (!verify.isValid) {
    return res.status(402).json({
      x402Version: 1,
      error: "payment_invalid",
      accepts: [payReq],
    });
  }

  // Run your actual logic BEFORE settling
  let result;
  try {
    result = await doExpensiveWork(req.body);
  } catch (err) {
    // Handler failed — do NOT settle, client keeps their money
    return res.status(500).json({ error: "internal_error" });
  }

  // Settle payment (moves USDC on-chain)
  const settle = await settlePayment(payReq, xPayment);
  if (!settle.success) {
    return res.status(402).json({
      x402Version: 1,
      error: "payment_failed",
      accepts: [payReq],
    });
  }

  res.setHeader("X-Payment-Response", encodeSettleResponse(settle));
  return res.status(200).json(result);
}

4. Environment variables

X402_PAY_TO=0xYourWalletAddress      # receives USDC
X402_FACILITATOR_URL=                 # optional, defaults to CDP

Wrap Existing Handler

If you already have a working endpoint, wrap it:

import { buildPaymentRequirements, verifyPayment, settlePayment, encodeSettleResponse } from "../_lib/facilitator.mjs";

export function withX402(handler, opts = { price: "0.01" }) {
  return async (req, res) => {
    const payReq = buildPaymentRequirements(req, opts);
    const xPayment = req.headers["x-payment"];

    if (!xPayment) {
      return res.status(402).json({ x402Version: 1, accepts: [payReq] });
    }

    const verify = await verifyPayment(payReq, xPayment);
    if (!verify.isValid) {
      return res.status(402).json({ x402Version: 1, error: "payment_invalid", accepts: [payReq] });
    }

    // Capture the original response
    const origJson = res.json.bind(res);
    let captured = null;
    res.json = (data) => { captured = data; return origJson(data); };

    await handler(req, res);

    if (res.statusCode >= 200 && res.statusCode < 300) {
      const settle = await settlePayment(payReq, xPayment);
      if (settle.success) {
        res.setHeader("X-Payment-Response", encodeSettleResponse(settle));
      }
    }
  };
}

// Usage:
export default withX402(myExistingHandler, { price: "0.10", description: "My tool" });

Auth Bypass

Let NFT or token holders skip payment. Supports both EIP-3009 (tool-sdk >= 0.13.0) and SIWE (legacy):

import { recoverTypedDataAddress, verifyMessage } from "viem";
import { parseSiweMessage } from "viem/siwe";

const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
const PASS_CONTRACT = "0xYourNFTContract";
const BALANCE_OF = "0x70a08231";
const BASE_RPC = "https://mainnet.base.org";

const TRANSFER_WITH_AUTHORIZATION_TYPES = {
  TransferWithAuthorization: [
    { name: "from", type: "address" },
    { name: "to", type: "address" },
    { name: "value", type: "uint256" },
    { name: "validAfter", type: "uint256" },
    { name: "validBefore", type: "uint256" },
    { name: "nonce", type: "bytes32" },
  ],
};

async function checkNftBalance(wallet) {
  const padded = wallet.slice(2).toLowerCase().padStart(64, "0");
  const r = await fetch(BASE_RPC, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0", id: 1, method: "eth_call",
      params: [{ to: PASS_CONTRACT, data: BALANCE_OF + padded }, "latest"],
    }),
  });
  const j = await r.json();
  return j.result ? BigInt(j.result) >= 1n : false;
}

async function verifyAuth(req) {
  const auth = req.headers["authorization"];
  if (!auth) return null;

  if (auth.startsWith("EIP-3009 ")) {
    const decoded = JSON.parse(
      Buffer.from(auth.slice(9), "base64url").toString()
    );
    if (decoded.value !== "0") return null;
    const recovered = await recoverTypedDataAddress({
      domain: {
        name: "USD Coin", version: "2",
        chainId: 8453, verifyingContract: USDC_BASE,
      },
      types: TRANSFER_WITH_AUTHORIZATION_TYPES,
      primaryType: "TransferWithAuthorization",
      message: {
        from: decoded.from, to: decoded.to,
        value: 0n,
        validAfter: BigInt(decoded.validAfter),
        validBefore: BigInt(decoded.validBefore),
        nonce: decoded.nonce,
      },
      signature: decoded.signature,
    });
    if (recovered.toLowerCase() !== decoded.from.toLowerCase()) return null;
    return recovered;
  }

  if (auth.startsWith("SIWE ")) {
    const dot = auth.lastIndexOf(".");
    const msg = Buffer.from(auth.slice(5, dot), "base64url").toString();
    const sig = auth.slice(dot + 1);
    const parsed = parseSiweMessage(msg);
    const valid = await verifyMessage({
      address: parsed.address, message: msg, signature: sig,
    });
    return valid ? parsed.address : null;
  }

  return null;
}

// In your handler, before the x402 check:
const wallet = await verifyAuth(req);
if (wallet && await checkNftBalance(wallet)) {
  // Bypass payment — run handler directly
  return handler(req, res);
}
// Otherwise fall through to x402 payment flow

Free Tier Pattern

Return limited data for free, full data behind x402:

const xPayment = req.headers["x-payment"];
if (!xPayment) {
  const freeResult = await getFreeData(req.body);
  return res.status(200).json({
    ...freeResult,
    _tier: "free",
    _upgrade: "Send x402 payment for full analysis",
  });
}
// ... verify, execute full logic, settle

Testing

# Inspect the 402 envelope (no payment)
curl -X POST https://your-domain.com/api/my-tool \
  -H "Content-Type: application/json" \
  -d '{"param":"value"}'

# Pay with tool-sdk (requires wallet)
npx @opensea/tool-sdk pay https://your-domain.com/api/my-tool \
  --body '{"param":"value"}' \
  --wallet-provider bankr

# Auth bypass with tool-sdk (NFT holder, no payment)
npx @opensea/tool-sdk auth https://your-domain.com/api/my-tool \
  --body '{"param":"value"}' \
  --wallet-provider bankr

Gotchas

• USDC has 6 decimals, not 18. "0.01" USDC = "10000" atomic units. Getting this wrong means charging 1 trillion times too much or 1 trillion times too little. Use Math.round(dollars * 1_000_000).toString().
• maxAmountRequired must be a string. JSON.stringify of a BigInt throws. Always .toString() before serializing.
• payTo must be server-controlled. NEVER read it from client headers or request body. An attacker sets payTo to their own wallet and your facilitator routes payment to them.
• Verify before handler, settle after handler succeeds. If you settle first and your handler throws, you've taken payment for nothing. If you settle and handler fails, you owe a manual refund.
• tool-sdk v0.13.0 switched SIWE to EIP-3009. Any auth gate that only parses Authorization: SIWE silently breaks for agents on >= 0.13.0 — they get 402 even with a valid bypass token. Support BOTH schemes.
• EIP-3009 auth uses value=0. It's proof-of-wallet-ownership via USDC typed data, not actual payment. The typed data domain must be {name: "USD Coin", version: "2", chainId: 8453, verifyingContract: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}.
• Base USDC is not Ethereum USDC. Contract 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 on Base. Ethereum's USDC is 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48. Don't mix them.
• Hardcode x402Version: 1 for now. The spec defines v2 but most facilitators still expect v1. Mismatched versions cause silent verification failures.
• Public Base RPC can be slow on serverless cold starts. Add a 5-second timeout and one retry to any eth_call for NFT balance checks. Cache balances for 24h — NFT holdings don't churn.

Troubleshooting

Issue	Cause	Fix
402 even with valid NFT	Gate only checks SIWE, agent sends EIP-3009	Support both auth schemes in Authorization header parser
Settlement fails "invalid payment"	Verify was skipped, or payment amount doesn't match envelope	Always verify first; ensure maxAmountRequired matches exactly
BigInt serialization error	maxAmountRequired is a BigInt, not a string	Call .toString() before JSON.stringify
Wrong payTo in envelope	Reading from client request	Hardcode payTo in server config or env var
NFT balance check times out	Public Base RPC slow on cold starts	Add 5s timeout + retry; cache results 24h
x402Version mismatch	Facilitator expects v1, you send v2	Hardcode x402Version: 1 until ecosystem migrates
Facilitator returns 403	CDP auth headers malformed or missing	Check CDP_API_KEY_ID and CDP_API_KEY_SECRET env vars
Payment verified but settle fails	Network congestion or nonce already used	Return 402 with payment_failed; client will retry with fresh nonce

Read references/eip-3009-typed-data.md for the full EIP-712 typed data structure used in auth headers. Read references/facilitator-comparison.md only if choosing between CDP and PayAI facilitators.