Agent integration

Developer hub

• Quickstart: pay for an API call with x402

  Call a marketplace endpoint, get an HTTP 402 challenge, sign USDC on Base and retry — with @x402/fetch, @x402/axios, Python httpx, or raw HTTP.

• Framework recipes: x402 tools for agent frameworks

  Wrap the paid fetch in a tool for Vercel AI SDK, LangChain, LangGraph, OpenAI Agents SDK and Coinbase AgentKit, or connect the MCP server from Claude Desktop, Cursor and Codex.

• Patterns: budgets, retries, intents, caching, free tier

  Production patterns for agents paying per call: per-run budget caps, safe retries, intent step pricing, caching and reading free-tier billing info.

• Sandbox: test x402 payments on Base Sepolia

  Dry-run the full x402 flow with testnet USDC at /api/sandbox/v1/{slug}: same slugs and amounts, Base Sepolia, deterministic fixture data, no live calls.

• API reference and discovery documents

  Machine-readable specs for Marketplace for AI Agents: OpenAPI, catalog, x402 manifest, MCP endpoint, error codes and legal pages.

• Error codes

  HTTP status codes returned by the marketplace gateway and whether each one is charged.

If your agent was asked to find X

Told to get a YouTube transcript, search the web, check flight prices, or look up a product? Cold start in four steps:

• 1Fetch /api/public/v1/catalog.json — every endpoint, parameter, and result key in one JSON call.
• 2Or connect the MCP server at /mcp (no auth) and call list_apis.
• 3Call the matching endpoint with no payment header — the first 3 calls per agent identity are free.
• 4After that the same call returns HTTP 402 with exact x402 payment requirements.

Overview

Every endpoint follows the same contract:

• ·First 3 calls per agent identity are free.
• ·After that, requests without a valid X-PAYMENT header return HTTP 402.
• ·Settlement is in USDC on Base mainnet via the x402 protocol.
• ·Successful paid responses include an X-PAYMENT-RESPONSE header with the settlement receipt.

Free tier

Each agent identity gets 3 free calls in total across all endpoints, scoped by IP + User-Agent. Successful free-tier responses return an X-Free-Calls-Remaining header. Recognised agent runtimes get those 3 calls outright; unknown or generic clients also get 3 per identity but draw from a site-wide budget of 100 successful free calls per UTC day, after which unpaid calls return 402 with free_tier_global_exhausted. Crawlers, monitors and browsers get no free calls. This is intended for evaluation. Production agents should set up payment immediately and not rely on the free tier.

x402 payment

When the free tier is exhausted, the server replies with HTTP 402 and an accepts array describing the payment requirements:

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 1,
  "error": "payment_required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "3000",
      "resource": "https://marketplaceforaiagents.com/api/public/v1/{endpoint}",
      "description": "Marketplace API call",
      "mimeType": "application/json",
      "payTo": "0x05e82e03753c7bc99fb24d10a876cce53f24b7b7",
      "maxTimeoutSeconds": 60,
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": { "name": "USDC", "version": "2" }
    }
  ]
}

Sign an EIP-3009 USDC authorization for maxAmountRequired, base64-encode the x402 payment payload, and resend the request with that string in the X-PAYMENT header.

Client setup

The x402 v2 client @x402/fetch handles the signing + retry loop (more clients in the quickstart):

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const fetchPaid = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});

// Replace {endpoint} with youtube-transcripts, google-search, google-news, etc.
const res = await fetchPaid("https://marketplaceforaiagents.com/api/public/v1/youtube-transcripts?video_id=0e3GPea1Tyg");
const data = await res.json();

Fund the wallet with USDC on Base. No gas required — facilitators relay settlement.

Receipts

Successful paid responses include an X-PAYMENT-RESPONSE header. Base64-decode it to get the settlement transaction hash, network, and payer address for your own bookkeeping.

Errors

Error responses are always JSON. 402 bodies include the same accepts array as the initial challenge so agents can re-derive payment without re-fetching the spec.