---
url: https://findutils.com/guides/how-ai-agents-discover-and-call-paid-apis
title: "How AI Agents Discover and Call Paid APIs: A Practical x402 Buyer's Guide"
description: "A hands-on guide to wiring an AI agent to consume pay-per-call APIs over x402 — read a manifest, handle the 402 challenge, sign a USDC payment, and pick tools by price."
category: developer
content_type: guide
locale: en
read_time: 11
status: published
author: "codewitholgun"
published_at: 2026-05-15T10:30:00Z
updated_at: 2026-05-15T10:30:00Z
excerpt: "Most x402 guides cover the seller side — how to charge for your API. This one is the buyer side: how to give an AI agent the ability to find a paid API in a catalog, understand its price, settle a single call in USDC, and stay inside a budget. With working code."
tag_ids: ["developer-tools", "ai-agents", "x402", "agent-commerce", "api-consumption"]
tags: ["Developer Tools", "AI Agents", "x402", "Agent Commerce", "API Consumption"]
primary_keyword: "how ai agents call paid apis"
secondary_keywords: ["x402 client guide", "agent api discovery", "consume x402 api", "pay per call agent", "x402 manifest parsing", "ai agent budget control"]
tool_tag: "x402-config-generator"
related_tool: "x402-config-generator"
related_tools: ["x402-config-generator", "curl-to-code", "jwt-decoder", "api-docs-generator"]
---

## 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](/guides/x402-config-generator-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](/agents/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](/blog/x402-payment-protocol-api-monetization-guide/) 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:

```js
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:

```json
{
  "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:

```js
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:

```js
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`:**

```js
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: 'user@example.com' }),
});
const result = await res.json();
budget.record(tool.price_usdc);
```

**With `axios`:**

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

const api = wrapAxiosWithPayment(axios.create(), signer);
const { data } = await api.post(tool.url, { input: 'user@example.com' });
```

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:

```js
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](/agents/marketplace/).

---

## 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](/agents/marketplace/) — 100+ tools with per-call pricing.
- Read [API marketplaces for AI agents](/blog/api-marketplaces-for-ai-agents-how-agents-discover-and-pay-for-apis/) 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](/guides/x402-config-generator-setup-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.