How to build an agent-payable API

If you already have a working HTTP endpoint — a transcript service, a screenshot API, a niche dataset lookup — you are 80% of the way to a machine-payable API. The remaining 20% is wiring x402 in front of it so autonomous agents can pay per call without anyone in your team provisioning an account first.

This guide walks through the full path: pricing the endpoint, returning a 402, verifying and settling the payment, adding a free tier for evaluation, and listing the result in an agent API marketplace.

1. Pick a price and a network

Per-call pricing is the unit of account in agentic commerce. Aim for the smallest amount an agent would happily spend without a budget check — typically between $0.001 and $0.05 per call for content APIs.

USDC on Base mainnet is the default network today: cheap gas, sub-second finality, and the x402 ecosystem has the most facilitator support there. USDC has 6 decimals, so $0.005 is the atomic string "5000".

2. Return a 402 when there is no X-PAYMENT

Your handler reads the X-PAYMENT header. If it is absent, you respond 402 with an accepts array describing exactly what payment you will take. The shape is identical across providers — that is what makes the protocol useful.

const requirements = {
  scheme: "exact",
  network: "base",
  maxAmountRequired: "5000", // $0.005 USDC, 6 decimals
  resource: `${origin}/api/transcripts`,
  asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
  payTo: "0xYourMerchantAddress",
  maxTimeoutSeconds: 60,
  extra: { name: "USDC", version: "2" },
};

if (!request.headers.get("x-payment")) {
  return Response.json(
    { x402Version: 1, error: "payment_required", accepts: [requirements] },
    { status: 402 },
  );
}

3. Verify and settle with a facilitator

You don't broadcast the transfer yourself. You hand the decoded payment to a facilitator — typically the default x402 facilitator or one you trust — which verifies the EIP-3009 signature and submits the on-chain transfer.

import { useFacilitator } from "x402/verify";
import { decodePayment } from "x402/schemes";

const decoded = decodePayment(request.headers.get("x-payment")!);
const facilitator = useFacilitator(); // or useFacilitator({ url: TESTNET_URL })

const verify = await facilitator.verify(decoded, requirements);
if (!verify.isValid) return reply402(verify.invalidReason);

const settle = await facilitator.settle(decoded, requirements);
if (!settle.success) return reply402(settle.errorReason);

// Settled. settle.transaction is the on-chain tx hash.

Return your real response with an X-PAYMENT-RESPONSE header carrying the base64-encoded receipt. Agents log this for their own bookkeeping.

4. Add a free tier (optional but powerful)

A free tier lets agents try the endpoint before committing budget. The simplest pattern is N free calls per identity hash (IP + user-agent SHA-256) stored in a table. Once exhausted, the next call returns 402 and the paid path takes over.

Keep the free tier small — three to ten calls is plenty. Its job is evaluation, not subsidy.

5. Publish discovery files

Two files turn your endpoint into something an agent can find and use without human help:

• /.well-known/x402 — the manifest. Networks, assets, endpoints, prices, and a link to your OpenAPI spec.
• /openapi.json — a normal OpenAPI 3.1 spec with one extra section: x-x402 at the root describing payTo, asset, and network so an agent can configure payment from the spec alone.

Agent runtimes and any agent API marketplace crawler can consume both files and auto-generate a tool. This is the whole reason to bother with x402 instead of inventing your own scheme.

6. List it in an agent API marketplace

Once your manifest is live, submit it to an agent API marketplace so agents discover it during planning, not after a failed call. A good marketplace will crawl your /.well-known/x402, validate that your 402 responses match the manifest, and surface the endpoint in agent-facing search.

From there your endpoint behaves like any other machine-payable API: revenue accrues on every call, no invoicing, no rate-limit emails, no Stripe disputes.