Listing an API in an x402 Directory

Listing an API in an x402 directory means publishing more than a payable URL. The directory entry must give an automated buyer enough information to find one operation, construct its request, understand its result and inspect the current payment requirements without filling gaps from your marketing site.

That makes the entry an offer, not a bookmark. A bookmark sends the buyer somewhere else. A useful listing keeps the resource identity, call contract and commercial terms together so the next action is deterministic.

Start with one resource, not one company

An x402 directory organizes payable resources. Your provider name can establish ownership, but it does not tell an agent what one purchase does. Each entry should describe a bounded operation such as returning one normalized company profile for a submitted domain.

Keep the resource URL stable. It is the identity to which directory updates, payment requirements and usage observations attach. If two routes accept different inputs or return materially different results, publish two entries. Combining them under a broad product description forces the buyer to rediscover the operation after finding the listing.

The current x402 discovery vocabulary includes the resource identifier, resource type, protocol version, accepted payment requirements, last update and extension data. Directory implementations can add service names, tags or other retrieval fields. Those additions help search, but they do not replace the core resource record.

This is narrower than publishing an x402 discovery document. The document is a provider-owned discovery surface. The directory entry is the indexed unit a buyer retrieves beside other offers. Both should describe the same deployed operation.

Write the description as a job specification

Directory search starts from a task. Write the description in the vocabulary of the result, not the vocabulary of your product category. “Return one VAT registration status for a submitted identifier” gives a buyer an action, input and output. “Compliance intelligence platform” does not.

Use tags to support filtering, not to carry the whole meaning. A tag such as `compliance` is too broad to distinguish verification from monitoring or document extraction. The description should remain useful when the provider name and tags are removed.

Before publishing, test the wording against three questions:

• What information does the buyer already have?
• What operation will the endpoint perform with it?
• What does one successful response contain?
• Which nearby operation is outside this entry?

Keep the same answer in your route metadata, directory listing and API documentation. The provider checklist for getting found by agents explains why inconsistent capability names can split one offer into several weak search records.

Make the request constructible from the entry

A matching description earns inspection. The input metadata decides whether the buyer can act. State the HTTP method and place each parameter in its real location. Name required fields, data types, allowed values, formats and units. For a request body, publish the object properties rather than a generic “JSON payload” label.

The Bazaar extension vocabulary supports input information and a schema alongside the payment declaration. Treat that schema as executable metadata. Generate it from the same source as the deployed validator where practical. If the route changes from an optional field to a required one, update the listing in the same release.

An input example is useful only when it passes the live rules. Test it without privileged headers or local defaults. An agent following the example should either reach the expected payment challenge or receive a documented validation error. It should not have to infer a missing country, date format or enum value.

Check these fields as one unit:

• Stable absolute resource URL and HTTP method.
• Precise task description and service identity.
• Required path, query, header and body inputs.
• Types, formats, allowed values and safe examples.
• Successful response media type and stable output fields.
• Current payment requirements returned by the deployed route.
• Protocol version, update time and useful search tags.

A directory may accept an incomplete record syntactically. That does not make it operationally complete. Your release check should ask whether a cold client can build the request, not only whether the JSON validates.

State the output boundary before the payment boundary

The buyer needs to know what one paid call returns. Publish the response media type and stable top-level fields. State limits that affect selection, such as whether the result is one record or a list. Do not turn the output description into a result-quality claim.

Apiosk does not measure result quality or provider terms. For reviewed candidates, it can compare price, settlement rail and input compatibility, plus latency and success rate when enough calls have been proxied. Unmeasured dimensions are dropped from the weighting and named, never assigned zero.

Keep those observed facts separate from your directory declaration. The listing describes the callable contract. Measurements describe recorded behavior. A buyer needs both sources to remain identifiable.

Keep payment requirements attached to the live route

Payment requirements complete the offer. The directory record can expose the accepted scheme, amount representation, network, asset, recipient and timeout information supplied by the x402 resource. Those values must agree with the payment challenge returned by the deployed endpoint.

Do not maintain payment terms as hand-written copy in several places. Rails and terms change. An unpaid request to the public resource should remain the release-time check, and the gateway's `/.well-known/x402` response is the live source of truth for Apiosk payment terms. The x402 integration page shows the connection path without replacing that live response.

Also validate against the specific directory you want to enter. A protocol-valid resource can still fail a directory's ingestion rules because the declared method, route pattern or extension shape does not match the public endpoint. Test the public URL, inspect the payment challenge and then confirm the indexed entry itself. A successful settlement and a visible directory record are separate observations.

Preserve the reviewed and external boundary

Being present in an x402 directory proves that a discovery source has a record. It does not prove that Apiosk has reviewed the provider, normalized its charging unit, mapped its inputs or measured its delivery behavior.

`GET /v1/discover?q=…` can sweep external x402 sources. Those results appear in `external_candidates` without a stable `candidate_id`. They are unreviewed, unmeasured and not settleable through Apiosk, so they cannot chain into `/v1/compare` or `/v1/decide`.

That boundary lets providers gain discovery reach without giving the directory entry more authority than it has earned. The distinction between reviewed and unreviewed API listings is an operational state, not a judgment about the endpoint's quality.

Where Apiosk fits

Apiosk provides a reviewed catalogue path for providers that already have a bounded, callable offer. You can list your API on Apiosk with the capability, request contract, output boundary and public payment metadata needed to evaluate the route.

Reviewed results from `/v1/discover` receive stable candidate IDs. Those IDs can move into `/v1/compare`, where each 0–100 score is relative to that candidate set and ships with its weights and per-dimension contributions. `/v1/decide` returns the selected provider, the rule that picked it, every rejected candidate with the exact constraint that removed it and the runners-up in order.

The directory entry remains the first contract. Give one resource a precise job description, executable inputs, an honest output boundary and payment requirements that match the live route. That is what turns a URL into an offer an agent can carry forward.