Paid APIs and x402 agent payments

Charge per API call in USDC. Wrap a route with the SettleKit middleware and an unpaid request returns HTTP 402 Payment Required with machine-readable requirements. The caller pays, retries with proof, and gets the response. No API keys. No prepaid plans.

Why it matters

API businesses usually force buyers into:

text
monthly subscription + API key + prepaid plan

But AI agents need:

text
discover endpoint -> pay small amount -> get result

SettleKit makes a paid API as easy as adding middleware.

Wrap a handler with withSettleKitPayment

withSettleKitPayment is framework-agnostic: it takes a config and returns a wrapper around any web Fetch handler ((Request) => Response). The config requires the price, the settlement network, your payTo address, the productId for usage attribution, and a host-supplied verify function that confirms the payment on-chain.

app/api/research/route.tsts
import { withSettleKitPayment } from "@settlekit/x402";
import type { PaymentProof, PaymentRequirements } from "@settlekit/x402";

// Host-supplied verifier: confirm the on-chain USDC transfer matches the
// challenge. In production this calls @settlekit/circle or @settlekit/arc.
async function verify(
  proof: PaymentProof,
  requirements: PaymentRequirements,
) {
  const paidEnough = Number(proof.amount) >= Number(requirements.amount);
  const nonceMatches = proof.nonce === requirements.nonce;
  return paidEnough && nonceMatches
    ? { ok: true }
    : { ok: false, reason: "payment_mismatch" };
}

export const GET = withSettleKitPayment({
  price: "0.005",
  currency: "USDC",
  productId: "prod_research_api",
  network: "arc", // "arc" | "base" | "ethereum"
  payTo: "0xYourUsdcPayoutWallet",
  verify,
})(async function handler(_req: Request) {
  return Response.json({ answer: "Paid research result" });
});

The 402 challenge

On an unpaid call the middleware reads the X-Payment header. If it is absent or malformed, it returns a 402 whose body and X-Payment-Required header carry the PaymentRequirements — scheme, amount, asset, network, payTo, productId, resource, and a one-time nonce the caller must echo back.

unpaid request -> 402http
GET /api/research
-->
HTTP/1.1 402 Payment Required
X-Payment-Required: {"scheme":"x402","amount":"0.005","asset":"USDC",
  "network":"arc","payTo":"0x...","productId":"prod_research_api",
  "resource":"https://api.acme.dev/api/research","nonce":"..."}

The paid retry

The caller pays the USDC transfer, base64-encodes a PaymentProof into the X-Payment header, and retries. The middleware parses the header, runs your verify, and on success runs the handler before firing the optional settleAndMeter hook.

encode the proof and meter usagets
import { encodePaymentHeader } from "@settlekit/x402";

const header = encodePaymentHeader({
  txHash: "0xabc...",
  from: "0xBuyerWallet",
  amount: "0.005",
  network: "arc",
  nonce: "<nonce from the 402 challenge>",
});

await fetch("https://api.acme.dev/api/research", {
  headers: { "X-Payment": header },
});

Pass settleAndMeter in the config to record a usage event after each successful paid call. Errors thrown there are swallowed so metering can never corrupt a served response.

List it for agents

To make a paid endpoint discoverable by AI agents with a machine-readable schema and price, publish it as an agent service.