llms.txt for Paid APIs: What Goes In and What Stays Out

An llms.txt for paid APIs has a narrower job than most guides suggest. It is a short Markdown file at the root of your domain that tells a language model what your service does and where the authoritative documents live. It is not the place to publish the price of a call, and treating it as one is how a provider ends up quoting a rate the gateway stopped charging weeks ago.

What llms.txt is, and who actually reads it

The format is a proposal, not a ratified standard. A file at `/llms.txt` opens with a heading naming the project, a one-paragraph summary, optional prose, and then sections of Markdown links, each with a short note on what the linked page contains. A section titled Optional marks links a reader can skip when context is tight.

Who fetches it is uneven. Coding assistants and agent frameworks that pull documentation into context use it as an index. General answer engines have shown little sign of relying on it. For a provider, that means the file is worth maintaining, but it should be written for a reader that is about to build an integration, not for a ranking algorithm.

That reader has three questions: what does this endpoint do, how do I call it, and what will it cost. The first two can be answered in prose. The third cannot, at least not reliably.

Why payment terms do not belong in the prose file

Prices, accepted assets, networks and payment recipients change on a different schedule from capability descriptions. A capability sentence written in spring is usually still true in autumn. A per-call price written in spring is a liability by the time the gateway has been reconfigured twice.

Many llms.txt templates for APIs encourage listing a cost next to every endpoint. The problem is that nothing enforces what the file says. An agent that reads a stale price from llms.txt and then receives a different one in a 402 challenge has two sources that disagree, and no way to tell which one you meant. In the worst case it budgets against the wrong number and rejects a call it could afford, or approves one it should have priced again.

The fix is structural rather than editorial. The prose file names the job and points to the machine-readable source that carries live terms. For an x402 endpoint, that source is the discovery document your gateway publishes, plus the payment requirements returned on an unpaid request. Both are generated from the same configuration that settles the call, so they cannot drift away from it.

A split that holds up: prose file versus discovery document

Divide the content by how often it changes and by what has to enforce it.

The llms.txt file carries:

• One sentence per capability, written in the language a buyer uses for the task.
• Links to the OpenAPI document, the discovery document and the authentication guide.
• Material limits that change whether the endpoint fits a task, such as accepted input types or a maximum batch size.
• A pointer to where live payment terms are returned, with no amount stated.
• A changelog link and the date the file was last regenerated.

The discovery document carries:

• The resource URL, method and callable input schema for each paid endpoint.
• The output schema or a representative example.
• The payment requirements the route returns today.
• Stable identifiers that let an index replace an old record instead of stacking a new one beside it.

Anything that would become wrong when a deploy changes configuration belongs in the second list. Anything an editor would still sign off on after a pricing change belongs in the first. The field-level detail of the second list is covered in the guide to the metadata agents actually read. The point here is narrower: the prose file should never duplicate it.

Writing capability lines that match how agents ask

The most useful line in the file is the one that describes what a single call returns. Agents arrive with a task, not a vendor name, so the line should read like the task. "Returns the registered name, address and status for a company registration number" matches more requests than "business data platform", and it tells the buyer what one call delivers.

A few rules keep these lines useful:

• Start with the verb and the object: returns, validates, converts, extracts.
• Name the input the caller must already have.
• Name one limit that would disqualify the endpoint for some tasks.
• Leave out claims about speed or accuracy unless you link to a measurement someone else can check.

That last rule matters more for paid endpoints than free ones. A buyer weighing two providers will discount any claim it cannot verify, and an unsupported "fastest" in a text file reads exactly like an unsupported "fastest" on a landing page. Measured latency and success rate come from observed calls, not from the provider's own description, which is the argument behind crawler-readable API catalogs that state where each number came from.

Generating the file instead of editing it

A hand-edited llms.txt drifts for the same reason a hand-edited price list does. Generate it from the source that produces your route table and your discovery document, and regenerate it on every deploy that changes either one.

A practical release check has three steps:

• Fetch `/llms.txt` without credentials and confirm every link resolves.
• Confirm each capability line maps to a route that still exists.
• Search the file for currency symbols, token names and network names, and fail the build if any appear outside the pointer to live terms.

The third check sounds blunt, but it is the cheapest way to enforce the rule. If a price has to appear somewhere a human reads it, put it on a page rendered from live configuration, which is the approach behind agent-readable API pricing.

Apiosk applies the same split to its own site. The llms.txt at apiosk.com describes what the service does and links to the gateway. For payment terms, it sends the reader to `https://gateway.apiosk.com/.well-known/x402` with the instruction to use the terms the live gateway returns. The file does not list a chain, a token or a price.

What llms.txt cannot do for discovery

Being described well in a text file is not the same as being found. An agent that searches by capability does not crawl provider domains one at a time looking for llms.txt. It queries an index. Your file helps once an agent or a developer already has your domain, and it does little for the buyer who has never heard of you.

Discovery at the level of the job happens in catalogues. Apiosk's `GET /v1/discover?q=…` takes the task as a query and returns a candidate set, each with a stable `candidate_id`. It also sweeps external x402 sources and returns those hits separately in an `external_candidates` block, without an ID. Those records are unreviewed and unmeasured, and they cannot be passed to `/v1/compare` or `/v1/decide`. A well-written llms.txt does not move an endpoint from the second group into the first.

Where Apiosk fits

Apiosk works downstream of the prose file. Once you are listed as a reviewed provider on Apiosk, your endpoints become candidates that `/v1/discover` can return for a task. `/v1/compare` scores them against other candidates on price, settlement rail, input compatibility and, where enough calls have been proxied, measured latency and success rate. `/v1/decide` picks one provider and names the exact constraint that removed each of the others.

Every score is relative to the candidates in that one comparison and arrives with the weights that produced it. Apiosk does not measure result quality or provider terms, and says so in the response rather than scoring those dimensions as zero.

Keep llms.txt short, generated and explicit about where the live terms are. Let the discovery document carry the contract, let the gateway carry the price, and let the comparison be made by someone other than the provider being compared.