How Agents Find and Assess a Paid API
Follow a company-data lookup from discovery listing to valid request and live payment terms, with the information a buyer needs at each step.
A 402 Payment Required can tell an agent what a request costs. It cannot give the agent a reason to request your URL.
Suppose you sell a company-data lookup. An agent researching a Dutch supplier needs to find the offer, determine whether its coverage fits, and construct a valid request. Only then can a payment challenge help it buy.
This hypothetical lookup follows one possible route: a discovery listing points to a public description and HTTP interface, the client checks the offer, then it requests the seller's endpoint. Agents can use other routes. The seller's job is to make the chosen path complete enough to use without private context.
A listing points the buyer to an offer
The x402 v2 specification defines Bazaar discovery endpoints that can list and search x402-enabled resources. A listing can expose a resource URL and accepted payment requirements. It gives a client somewhere to look; it does not promise that a buyer will find, trust, or purchase the resource.
For our lookup, the listing should lead to a stable description of company coverage and the operation that serves it. The seller continues to host the endpoint and fulfill its requests. A catalog entry does neither job.
The agent still has a fit decision. If the lookup covers only US companies, a Dutch supplier task should stop here. That rejection is useful: the buyer learned the limit before sending a paid request.
One offer across three surfaces
The agent needs a complete path before it can buy.
Find
Public page and discovery listing
Does this lookup cover Dutch companies?
Assess
HTTP operation and sample response
Which registry number should I send, and what does no match mean?
Transact
Live payment requirement
Is a valid no-match attempt billable under these live terms?
Describe the result before the buyer pays
For the example, assume the service covers Dutch companies identified by their registry number. Its public page explains the available fields, the refresh interval, and known gaps. It shows a safe sample response with the source timestamp so the buyer can assess freshness.
Publish the purchase unit just as plainly. Suppose the illustrative price is €0.01 per valid lookup attempt, including an attempt that finds no match. Say that before the buyer expects a guaranteed company record. A no-match response is then a defined outcome of the purchase. An invalid registry-number format is rejected before paid execution.
The price in this example is invented to explain the unit; it is not recuut pricing. A real seller can choose a different model. How to Price an API for AI Agents explains that decision. Discovery needs enough of the rule for a buyer to judge the offer.
Keep the description available without login or payment. Ordinary links from relevant product and documentation pages make it reachable. A sitemap can help a crawler enumerate it, but search visibility is only one possible discovery channel. Neither a public page nor a directory entry establishes demand.
Give software enough detail to construct one request
For an HTTP API, the OpenAPI Specification provides a standard description of operations, inputs, responses, and other interface details. Our lookup needs one operation with a documented registry-number input and examples of both a match and a no-match response.
Explain the response fields and errors, including unsupported coverage and invalid input. State whether the operation merely reads data or causes a side effect. If the buyer needs a credential in addition to payment, describe how it obtains that credential before asking it to spend.
The interface description and public offer should agree. A page promising Dutch coverage beside an interface example that accepts only US identifiers leaves the buyer to resolve the contradiction. Payment middleware cannot fix that.
Do not add another manifest simply because a format exists. Add the description that the discovery route and client actually use, then verify that it contains enough information to reach a valid operation.
Confirm the live terms at the payment boundary
The client now requests the lookup endpoint with a valid input. If payment is required, the x402 HTTP transport carries the canonical payment requirement in the Base64-encoded PAYMENT-REQUIRED response header.
That live requirement tells the client which payment combinations the server accepts for this request. The earlier listing may have become stale. The buyer should compare the live requirement with its spending permission and the offer it assessed before signing a supported payment payload.
Keep a stable resource identity across the public description, interface, and accepted offer. Update descriptions when coverage or behavior changes, and preserve the offer revision used by a purchase. A moved endpoint needs redirects and updated references; an old purchase still needs to be explainable.
For the lookup, the buyer should reach payment knowing what a match and a no-match response mean. The seller should be able to connect the paid request to that same advertised operation.
Test the path with an unfamiliar client
Give a new client only the public listing or descriptor. Ask it to find the coverage, construct the Dutch registry-number request, predict the two valid outcomes, and identify the charging unit. It should then be able to inspect the payment challenge without purchasing merely to learn those facts.
Failures locate the next edit. If the client finds the description but cannot construct a valid request, repair the interface explanation. If a valid request reaches payment but stops there, inspect the live terms, supported payment methods, and payment errors. If purchase succeeds but the result differs from the sample, repair the offer or fulfillment.
Measure those boundaries separately. A fetched descriptor is evidence of access, not a sale. Keep probes separate from buyer activity and collect only the data needed to diagnose the path. Demand claims need measured buyer behavior.
To prepare this offer with recuut, start with one API or piece of content you already host. Define its protected resource, price, and API contract revision where applicable. Confirm the supported discovery channels and listing behavior for the integration you choose. A useful listing starts with an offer worth requesting.