How does an AI agent find an API?

An AI agent can discover an API through a supplied tool list, documentation, or a machine-readable catalog. A catalog makes comparison more explicit by listing capabilities, endpoints, and input requirements. It does not remove the need to check trust, price, and permissions.

This article explains the discovery step before a paid request. The x402 payment article covers payment separately.

An agent needs answers to four questions:

  1. What operation does the service perform?
  2. Which inputs does the endpoint accept?
  3. What authorization or payment does it require?
  4. What should happen if the service fails?

Browser-capable agents can use human-facing pages. Structured descriptions reduce the amount of page interpretation needed, but they are not the only discovery method.

What an Agent Marketplace Actually Is

An API marketplace can provide a website for human selection and a structured catalog for software. The same service can support both workflows.

For automated selection, an API marketplace needs a machine-readable index. A paid-per-request catalog should describe these properties:

  1. Programmatic discovery. A structured catalog, such as JSON, can describe each identifier, operation, endpoint, and current payment rule.
  2. Clear payment terms. For a per-request service, publish enough information to evaluate the request cost before payment. Other commercial models need their own authorization rules.
  3. Supported settlement. An endpoint can accept payment as an access condition. It can also require authentication, identity checks, or other conditions.

These properties support automated selection within an approved budget. For an email check, the client can find an endpoint, inspect its inputs, confirm the current price, and submit a request. Discovery, payment negotiation, and retries can require additional requests.

Discovery and payment use separate contracts

The x402 introduction describes payment for resources over HTTP. A server returns payment requirements, and a compatible client submits a payment payload. Verification and settlement precede the protected result.

Discovery is an additional step. The Bazaar documentation describes a discovery extension for endpoints and MCP tools. Support depends on the selected server and facilitator.

FindUtils also publishes a payment manifest. Treat its shape as the FindUtils catalog contract. Do not assume every x402 provider publishes the same well-known file.

A directory listing is an input to selection, not an endorsement. Confirm the endpoint, operator, and current payment requirements before authorizing a request.

The Anatomy of a Machine-Readable Listing

A directory needs a documented schema, but different directories can use different schemas. This example illustrates possible fields. It is not a current FindUtils price or a protocol-defined schema:

JSON
1
2
3
4
5
6
7
8
9
{
  "tool_id": "email-validate",
  "description": "Validate an email address: syntax, domain MX records, disposable detection.",
  "url": "https://api.example.com/email-validate",
  "method": "POST",
  "price_usdc": "0.0002",
  "network": "eip155:8453",
  "currency": "USDC"
}

Every field exists for the agent, not for you:

  • tool_id is a stable handle the agent can store and reuse.
  • description is written for an LLM — it states the capability and its limits plainly, so the planner can decide whether this tool fits the current step.
  • price_usdc lets the agent do budget math before it spends anything.
  • network and currency tell the agent's wallet exactly how to settle.

This example omits an API key. A real endpoint defines its own authentication needs. Read the current payment requirements rather than treating a cached catalog price as authority.

What This Means If You Build Agents

If you are building an autonomous agent, the marketplace layer changes how you think about capabilities:

  • Stop bundling everything. You do not need to ship a hashing library, a CSV parser, a screenshot renderer, and a unit converter inside your agent. You need a budget and the ability to read a catalog.
  • Treat capability as a runtime decision. When the planner hits a step it cannot do, it should query a catalog, not fail. The marketplace is your fallback for any deterministic sub-task.
  • Price-gate your tool selection. Give the agent a per-task spend ceiling and let it prefer cheaper listings. A $0.0001 tool and a $0.005 tool are both "an API call" to a human, but a 50× difference matters when an agent makes thousands of calls.
  • Prefer deterministic tools for deterministic work. Asking an LLM to base64-encode a string burns tokens and can be wrong. A $0.0001 marketplace call is exact and auditable. Offload anything mechanical.

What This Means If You Build APIs

If you publish an API, the marketplace layer is a new distribution channel — but only if your API is legible to a machine:

  • Publish a catalog. Document your chosen discovery format and link to current schemas. A custom manifest can help clients that explicitly support it.
  • Write descriptions for the planner. Your endpoint description is no longer marketing copy — it is a prompt fragment an LLM uses to decide whether to call you. State the capability, the input, and the limits. Vague descriptions get skipped.
  • Price each endpoint explicitly. "Contact us" is invisible to an agent. A per-call number in the manifest is a listing; everything else is a brochure.
  • Document access requirements. State any account, wallet, allowlist, or approval step before a client spends money.

FindUtils publishes supported operations through its API catalog and payment manifest. Check those records for current coverage and terms. Not every browser tool has a programmatic interface.

A review checklist before a paid call

Review discovery and execution separately. A clear listing can still point to an unavailable endpoint or stale terms.

  1. Resolve the endpoint from an allowed domain.
  2. Validate the input schema before attaching private data.
  3. Read the current payment requirements.
  4. Check the network, asset, recipient, and maximum spend.
  5. Define retry behavior before the first attempt.
  6. Keep the request identifier and payment result for reconciliation.

A timeout can occur after a service accepts work or settles payment. Do not assume a retry is free or idempotent. Use the provider’s documented request and payment identifiers.

For FindUtils, open the REST catalog to confirm the operation. Use the MCP catalog when the client supports MCP. The paid-API workflow guide explains the wider sequence.