x402-base-verify

On-chain USDC payment verification for Base mainnet. No API keys. No external services. Zero dependencies.

Built from the payment infrastructure powering zambo.dev Day Pass — verifying live USDC transactions in production since 2026.

---

What is x402?

x402 is a protocol built on HTTP status code 402 ("Payment Required") that enables micropayments at the HTTP layer. Instead of a Stripe checkout page or a PayPal flow, an API returns a 402 with payment instructions. The client (human or AI agent) sends crypto, then retries with the transaction hash in a header.

This library handles the verification half: given a tx hash, confirm that the right amount of USDC actually landed in the right wallet on Base.

---

Install

npm install x402-base-verify
# or
pnpm add x402-base-verify

---

Usage

Verify a payment

import { verifyUsdcPayment } from "x402-base-verify";

const result = await verifyUsdcPayment({
  txHash:        "0xabc123...",
  toAddress:     "0xYourWalletAddress",
  minAmountUsdc: 1.49,
});

if (result.valid) {
  console.log(`Payment confirmed: ${result.amountUsdc} USDC via ${result.rpc}`);
  // grant access
} else {
  console.log(`Payment invalid: ${result.reason}`);
  // e.g. "insufficient_usdc: sent 1.000000, need 1.49"
  // e.g. "transaction_not_found_on_base"
  // e.g. "no_usdc_transfer_to_target_wallet_in_tx"
}

Build a 402 response

import { buildPaymentRequired } from "x402-base-verify";

router.post("/api/premium-feature", async (req, res) => {
  const txHash = req.headers["x-payment-hash"] as string | undefined;

  if (!txHash) {
    const { status, body } = buildPaymentRequired({
      toAddress:  "0xYourWalletAddress",
      priceUsdc:  1.49,
      product:    "Premium Feature Access",
      tagline:    "$1.49 USDC. Instant. No account needed.",
    });
    res.status(status).json(body);
    return;
  }

  const payment = await verifyUsdcPayment({
    txHash,
    toAddress:     "0xYourWalletAddress",
    minAmountUsdc: 1.49,
  });

  if (!payment.valid) {
    res.status(402).json({ error: "invalid_payment", reason: payment.reason });
    return;
  }

  // payment verified — do the thing
  res.json({ success: true });
});

Full x402 Express middleware

import { verifyUsdcPayment, buildPaymentRequired } from "x402-base-verify";
import type { Request, Response, NextFunction } from "express";

function x402Guard(toAddress: string, priceUsdc: number) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const txHash = req.headers["x-payment-hash"] as string | undefined;

    if (!txHash) {
      const { status, body } = buildPaymentRequired({ toAddress, priceUsdc });
      res.status(status).json(body);
      return;
    }

    const result = await verifyUsdcPayment({ txHash, toAddress, minAmountUsdc: priceUsdc });

    if (!result.valid) {
      res.status(402).json({ error: "payment_verification_failed", reason: result.reason });
      return;
    }

    next();
  };
}

// Use it:
router.post("/api/generate", x402Guard("0xYourWallet", 0.10), handleGenerate);

---

API

verifyUsdcPayment(options) → Promise<VerifyResult>

Option	Type	Default	Description
txHash	string	required	Base mainnet transaction hash (0x...)
toAddress	string	required	Expected recipient wallet address
minAmountUsdc	number	0	Minimum USDC required (human-readable)
rpcs	string[]	3 public RPCs	Base RPC endpoints to try in order
timeoutMs	number	9000	Per-RPC timeout in ms
failOpen	boolean	false	Return valid: true if all RPCs time out

VerifyResult:

{
  valid: boolean;
  reason?: string;       // why it failed
  amountUsdc?: number;   // actual amount transferred
  rpc?: string;          // which RPC confirmed it
  failedOpen?: boolean;  // true if fail-open triggered
}

buildPaymentRequired(options) → { status: 402, body: object }

Builds a standard x402 payment-required response body with step-by-step instructions.

---

How it works

1. Calls eth_getTransactionReceipt on Base via JSON-RPC (no API key needed — public nodes)
2. Scans the transaction logs for an ERC-20 Transfer event from the USDC contract
3. Checks that the to field matches your wallet and the amount meets the minimum
4. Falls back through multiple RPC endpoints automatically

The USDC contract on Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

---

Why no API key?

Base exposes public JSON-RPC endpoints. For verifying payments you don't need an Alchemy or Infura key — the public nodes are reliable enough for single-tx lookups. If you need higher throughput, pass your own RPCs in the rpcs option.

---

License

MIT

Built by Brennan Zambo · @zambodotdev