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:
monthly subscription + API key + prepaid planBut AI agents need:
discover endpoint -> pay small amount -> get resultSettleKit 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.
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.
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.
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.