nohumans.directory

Guides › Selling to AI agents, part 3

Why paid APIs fail AI agents, and how to make yours deliver

Published 31 October 2026. Figures are from our purchase records as published on that date, one latest attempt per endpoint.

We don’t just list paid APIs: we buy from them, with real USDC, and publish what happened. So far we have tried to buy from 6,478 endpoints. About six in ten of those that asked for payment delivered. The rest failed in a small number of ways, and almost every one of them is fixable by the seller in an afternoon.

This guide goes through those failures, with the fix for each, and ends with a prompt that has your AI assistant check your API for all of them. It works for any x402 API, not only ones built with part 1.

The failures we see most, and the fixes

1. It asked for payment again after being paid (464 endpoints)

The agent pays, and the API answers “402 Payment Required” again, as if nothing arrived. Usually the money never moved: when we audited 651 failed purchases on-chain, 515 had never settled. It points to a broken payment check on the seller’s side: wrong network, wrong token, a mistyped key, or a payment service that rejects every payment.

Fix: make one real paid call yourself before anyone else does. And when a payment is refused, say why in the 402’s error field, so the buyer’s agent can tell a broken seller from a bad payment.

2. Nobody could tell what to send it (370 endpoints)

The API rejected the request as bad input, and nothing it published said what good input looks like. An agent cannot guess your parameters.

Fix: describe your inputs where agents read them: an input schema and a real example in the payment challenge’s discovery extension, the same example in your listing, and a free /sample route that shows the answer.

3. The address or the method was wrong (404: 273, 405: 131)

The listed URL no longer existed, or the API only answered POST when it was listed for GET (or the other way round) — sometimes before payment, sometimes after.

Fix: keep paid URLs stable, update your listing when you move one, and answer the method you are listed with. If a route must be POST, say so in the listing.

4. It took the payment, then crashed (5xx after payment: 146)

The payment went in and the server answered with an error. The worst version is an API that settles the payment first and runs the work second: then the buyer pays for the crash.

Fix: settle only after a successful answer. The standard x402 middleware already works this way; keep it, and never charge for an error.

5. The price was not the listed price (97 endpoints)

The live 402 asked for more than the listing said. Agents with a spending limit skip it, and trust drops.

Fix: change the price in one place and update your listing the same day.

6. The answer was old, empty or broken (stale data 88, invalid JSON 41, empty body 21, timeouts 36)

The API answered, but not with something usable: data older than it claimed, a body that was not JSON, nothing at all, or no answer before the buyer gave up.

Fix: return valid JSON every time, include a timestamp when freshness matters, and answer quickly. If the upstream data is slow, say so in your description rather than timing out.

Some failures are ours, not the seller’s: our own client cannot pay every kind of x402 offer yet. We count those separately. All counts and definitions: paid verification and method.

The prompt

Copy this into your AI assistant, with your paid URL. It checks your API for every failure above and fixes what it finds with you.

Audit my paid API for AI agents before anyone pays it. It uses x402. Here is the address of the paid route: [your paid URL, with a real example input]. I am a beginner: explain each finding in plain words and fix it with me.

Check these, one by one, and tell me pass or fail for each:
1. Unpaid call: it answers HTTP 402 with a payment-required header naming Base, USDC, my wallet and the price I meant.
2. The free check at https://api.nohumans.directory/v1/check (POST {"endpoint_url": "<my paid URL>"}) says it would verify, and the price and network it reads are right.
3. Inputs are described where an agent can read them: the discovery extension has an input schema and a real example, and the example input works.
4. A free /sample route shows a real example answer without payment.
5. Bad or missing input returns a clear 4xx error and is never charged: payment settles only after a successful answer.
6. The paid route answers the method it is listed with (GET or POST), and the URL does not change.
7. The answer is valid JSON, never empty, and says how fresh the data is when freshness matters.
8. It answers well within 10 seconds.
9. The price in my listing and the price in the 402 are the same.

Do not ask for my wallet recovery phrase or private key; none of these checks need it. Then list what to fix, most important first, and fix it with me.

Prove it delivers

A checklist is a promise. Agents choose on evidence. When you list your API with us, the $0.25 listing fee includes one real purchase of your endpoint (when it costs $0.05 or less), and the result is published on your listing. Agents reading our records can then tell an API we have bought from and seen deliver from one we have only seen online.

Sources: nohumans.directory purchase records (/v1/stats, read 31 October 2026); settlement audit of failed purchases, correction #26.

Your next step

Your AI assistant can also search our directory itself, through our MCP server: https://api.nohumans.directory/mcp (in Claude Code: claude mcp add --transport http nohumans https://api.nohumans.directory/mcp).

Selling to AI agents: the series

  1. Build your first paid API for AI agents, with one prompt
  2. What AI agents are looking for, and where nobody serves them yet
  3. Why paid APIs fail AI agents, and how to make yours deliver (you are here)