How AI Agents Discover and Call Paid APIs: A Practical x402 Buyer's Guide

How AI Agents Discover and Call Paid APIs

This guide is the buyer's side of agent commerce. Plenty of material — including our own x402 setup guide — covers how to charge for an API. Far less covers the other half: how to give an agent the ability to consume one. That is what you will build here.

By the end you will have an agent that can:

• Discover available tools by reading a machine-readable catalog
• Understand each tool's price before spending anything
• Handle the HTTP 402 Payment Required challenge automatically
• Settle a single call in USDC and use the result
• Stay inside a per-task spending budget

We will use the FindUtils agent tool marketplace as the live example — 100+ deterministic utilities, each priced per call — but the pattern applies to any x402 endpoint.

New to the protocol itself? Read what x402 is and how it works first. This guide assumes you know the 402 flow exists and focuses on the client code.

Step 1: Discover — Read the Catalog

An agent should never hard-code an endpoint URL. It should read a catalog and decide. Most x402 publishers expose a manifest at a well-known path:

async function loadCatalog(origin) {
  const res = await fetch(`${origin}/.well-known/x402-manifest.json`);
  if (!res.ok) throw new Error(`No manifest at ${origin}`);
  const manifest = await res.json();
  return manifest.endpoints; // [{ tool_id, url, price_usdc, description, ... }]
}

const catalog = await loadCatalog('https://findutils.com');
console.log(`Discovered ${catalog.length} tools`);

Each catalog entry is written for a machine consumer:

{
  "tool_id": "email-validate",
  "url": "https://api.findutils.com/api/tools/email-validate/execute",
  "method": "POST",
  "price_usdc": "0.0002",
  "description": "Validate an email address: syntax, MX records, disposable detection."
}

Note what is absent: no API key field, no signup URL, no rate-plan tier. Access is acquired by paying, not by registering.

Step 2: Select — Let the Agent Pick the Right Tool

Discovery is only useful if the agent can choose. Two strategies, often combined:

Keyword / capability match — cheap and deterministic, good for a known need:

function findTool(catalog, need) {
  return catalog
    .filter(t => t.description.toLowerCase().includes(need))
    .sort((a, b) => Number(a.price_usdc) - Number(b.price_usdc))[0];
}

const tool = findTool(catalog, 'email');
// → email-validate at $0.0002

LLM-driven selection — pass the catalog (tool_id + description + price) to the model and let the planner choose. This handles fuzzy needs ("I need to clean up this messy text") that keyword matching misses. Keep the list you pass small — filter by category first so you are not spending tokens on 100 irrelevant descriptions.

Either way, sort by price as a tiebreaker. When two tools satisfy the need, the cheaper one is almost always the right default.

Step 3: Budget — Gate Spending Before the Call

An agent with a wallet and no budget is a liability. Put a ceiling check between selection and execution:

class SpendGuard {
  constructor(maxUsdc) {
    this.max = maxUsdc;
    this.spent = 0;
  }
  canAfford(priceUsdc) {
    return this.spent + Number(priceUsdc) <= this.max;
  }
  record(priceUsdc) {
    this.spent += Number(priceUsdc);
  }
}

const budget = new SpendGuard(0.05); // 5 cents per task

if (!budget.canAfford(tool.price_usdc)) {
  throw new Error(`Tool ${tool.tool_id} would exceed task budget`);
}

This is the single most important piece of buyer-side code. The payment layer will happily settle every call an agent makes — the budget is the only thing that stops a planning loop from draining a wallet.

Step 4: Pay — Handle the 402 Challenge

You do not write the payment handshake by hand. The x402 client SDKs wrap your HTTP client and do it transparently: the first response is 402, the SDK reads the payment requirements, signs an EIP-712 USDC authorization for the exact amount, and replays the request.

With fetch:

import { wrapFetchWithPayment } from 'x402-fetch';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY);
const payFetch = wrapFetchWithPayment(fetch, account);

const res = await payFetch(tool.url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ input: '[email protected]' }),
});
const result = await res.json();
budget.record(tool.price_usdc);

With axios:

import { wrapAxiosWithPayment } from '@x402/axios';
import axios from 'axios';

const api = wrapAxiosWithPayment(axios.create(), signer);
const { data } = await api.post(tool.url, { input: '[email protected]' });

The agent code reads as a normal API call. The 402 round trip, the signature, and the replay all happen inside the wrapper.

Step 5: Put It Together — A Reusable callTool Helper

Wrap discovery, selection, budgeting, and payment into one function the agent's planner can call whenever it hits a capability gap:

async function callTool(need, input, { catalog, payFetch, budget }) {
  const tool = findTool(catalog, need);
  if (!tool) throw new Error(`No tool found for: ${need}`);

  if (!budget.canAfford(tool.price_usdc)) {
    throw new Error(`Skipping ${tool.tool_id}: over budget`);
  }

  const res = await payFetch(tool.url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(input),
  });
  if (!res.ok) throw new Error(`${tool.tool_id} failed: ${res.status}`);

  budget.record(tool.price_usdc);
  return res.json();
}

// The agent now treats any deterministic sub-task as a marketplace call:
const validation = await callTool('email', { input: address }, ctx);
const hash = await callTool('hash', { input: payload, algorithm: 'sha256' }, ctx);

The planner no longer needs a hashing library, an email validator, or a CSV parser bundled in. It needs a catalog and a budget.

Using the MCP Surface Instead

If your agent is MCP-aware (Claude Desktop, OpenClaw, or any MCP client), you can skip the manifest-parsing code entirely. Point the client at mcp.findutils.com and the same catalog appears as native MCP tools — tools/list is your discovery step, and the x402 payment is negotiated per tools/call. Use the REST path when you control the HTTP client; use MCP when the agent framework already speaks it. Both reach the same catalog.

A Buyer-Side Checklist

Before you let an agent loose with a wallet, confirm:

• The wallet is scoped. Fund a dedicated agent wallet with a small balance. Never hand an agent a key to a wallet that holds more than a task's worth of value.
• Every task has a budget ceiling. A SpendGuard (or equivalent) sits between tool selection and execution. No exceptions.
• Selection prefers cheaper tools. Sort candidates by price_usdc; a 50× price gap between two equivalent tools is real money at agent call volumes.
• Deterministic work goes to deterministic tools. Do not ask an LLM to encode, hash, or reformat data — a per-call utility is exact, auditable, and costs a fraction of a cent.
• Failures are handled, not retried blindly. A failed call still cost a payment attempt; log it and fall back rather than looping.

Where to Go Next

You now have the buyer's side of agent commerce: discover a catalog, select by capability and price, gate spending, and settle a call in one signature. To explore further:

• Browse a live catalog at the FindUtils agent tool marketplace — 100+ tools with per-call pricing.
• Read API marketplaces for AI agents for the bigger picture of how the discovery layer is forming.
• If you also want to sell a capability into this ecosystem, the x402 config generator guide covers the publisher side.

The pattern is small once it clicks: an agent that can read a catalog and sign a payment can acquire any deterministic capability at runtime, for a fraction of a cent, without a human ever opening a signup page.