x402 Discovery Document for API Providers

An x402 discovery document is the landing page an automated buyer can read without rendering a website. For an API provider, the test is simple: can one ingestion pass identify the job, construct a valid request, understand the result and inspect the payment requirements without fetching missing context?

That is a stricter standard than merely returning valid JSON. A crawler can accept a record that an agent still cannot use. The endpoint may appear in an index, yet fail to enter a serious candidate set because its description is vague, its schema is incomplete or its payment details have drifted away from the live route.

Treat every resource as a complete buying record

Discovery systems work with resources, not company homepages. Each record should represent one callable endpoint or tool and carry enough information to evaluate that paid action on its own.

The current x402 vocabulary separates the resource identifier, resource type, protocol version, accepted payment requirements, update time and extension metadata. Bazaar discovery adds callable input and output information so a buyer can move from finding a resource to using it. A provider-owned `/.well-known/x402` document can publish the same operational unit at the provider boundary.

Do not make the buyer infer the paid action from a product name. “Data platform” is a vendor category. “Return one normalized company profile for a submitted domain” is a job an agent can match to a task. This distinction is central to how AI agents discover APIs: the buyer starts with work to perform, not a preferred supplier.

A complete resource record should expose:

• A stable absolute resource URL and the HTTP method.
• A short description of the result, written in task language.
• Required path, query, header or body inputs with types.
• A realistic input example that satisfies the required fields.
• The output media type plus a schema or representative example.
• Current payment requirements returned for that resource.
• Provider identity, documentation links, tags and an update time.

If one item cannot be known at discovery time, name the boundary. An explicit omission is easier to handle than a field that looks complete but is stale.

Make the input contract executable

Most ingestion failures happen after discovery. The record matched the query, but the agent cannot turn its task into a request. A body field lacks a type. A required query parameter is presented only inside prose. The example leaves out the value that selects the operation.

Keep the machine contract close to the resource. For an HTTP endpoint, state the method and place parameters under the correct location. Mark required fields. Include enum values where the route enforces them. Give examples that are syntactically valid and safe to inspect. If the body is an object, describe its properties rather than presenting one opaque blob.

The same discipline applies when you already maintain an API specification. OpenAPI extensions for paid agent APIs can help document commercial behavior, but ingestion should not depend on a crawler joining several loosely related pages. Reuse your schema generation where possible and publish the callable subset inside the discovery record.

Validate examples against the real request validator in release checks. A copied example that no longer passes is worse than no example because it gives the buyer a confident path to a failed call.

Describe the output before asking for payment

An agent cannot judge value from an input schema alone. It needs to know what one successful call returns. Publish an output media type and enough structure to distinguish the endpoint from another candidate performing a nearby job.

For a structured response, name the stable top-level fields and their types. A representative example helps when the schema allows broad objects, but the example must not contain secrets, customer data or invented guarantees. State material limits in the resource description when they change whether the output fits the task.

Keep result quality claims out of the discovery record unless you have a defined, reproducible measure. Apiosk does not measure result quality or provider terms. It can compare recorded price, settlement rail, input compatibility and, where enough proxied calls exist, measured latency and success rate. Unknown dimensions are dropped from the weighting and named rather than scored as zero.

That separation protects the provider as well as the buyer. The document states what the endpoint returns. Observed delivery data states how the endpoint has behaved. Neither should be rewritten as a claim about subjective quality.

Keep payment terms live and attached to the route

Payment data changes more often than capability text. A static article or copied integration guide will eventually drift. The discovery resource should therefore carry the payment requirements associated with the current route, including the scheme, amount representation, asset, network, recipient and timeout fields the gateway returns.

Do not maintain a second hand-written list of supported rails. For Apiosk, `https://gateway.apiosk.com/.well-known/x402` is the live source of truth for payment terms. The copy-paste x402 integration examples show how to connect, but the gateway response is authoritative when an agent evaluates a purchase.

This is also why API payment catalogs for AI agents need update timestamps and stable resource identifiers. A crawler must be able to replace an old record, not accumulate several versions of the same endpoint and guess which one can settle.

Run three checks whenever price or routing configuration changes:

• Fetch the public discovery URL without credentials and confirm a successful JSON response.
• Match each advertised resource, method and schema to the deployed route.
• Trigger an unpaid request and compare its live payment requirements with the discovery entry.

The checks should fail the release when a protected route disappears from the document or the two payment descriptions diverge.

Test the document as a cold reader

A useful ingestion test begins with an empty cache. Fetch the document once, select one item and refuse to consult the marketing site. Can a program identify the task, build a request and explain what the response will contain? Can it tell which payment terms are current? Can it distinguish a provider name from a capability name?

Also test retrieval language. Use the phrases a buyer puts in a task, not only your internal product labels. Short tags help filtering, but the description and schemas carry the actual meaning. Avoid stuffing synonyms into every field. One precise job statement plus concrete input and output names creates a stronger match than a paragraph of category terms.

Finally, check boundaries across discovery sources. Apiosk's `/v1/discover` can sweep external x402 sources, but those hits appear in a separate `external_candidates` block. They are unreviewed, unmeasured, lack a stable `candidate_id` and cannot chain into `/v1/compare` or `/v1/decide`. Being found is not the same as being eligible for comparison or settlement.

Where Apiosk fits

Apiosk gives providers two routes into discovery. You can list an API on Apiosk for a reviewed catalogue entry, or submit an existing x402-native API through its public discovery URL. The gateway publishes its current catalogue at `/.well-known/x402`, while `/v1/discover` turns task language into a candidate set.

Reviewed candidates receive stable IDs and can move into comparison and decision. The comparison shows relative 0–100 scores for that candidate set, the active weights and each contribution. The decision response returns the selected provider, the rule that chose it, rejected candidates with their exact constraints and ordered runners-up.

Your discovery document has one job before any of that can happen: make the paid endpoint legible in a single read. Publish a complete resource, validate it against the deployed route and keep the live payment requirements attached to the same record.