AI and agent access

These docs are written to be read by coding agents as well as people. Authored English guides have markdown exports. Generated API operation pages are represented by the three OpenAPI contracts; they do not have individual markdown exports. Arabic fallback pages do not establish translated markdown coverage.

Authored English guides as markdown

For an authored English guide, remove the trailing slash and append .md to its URL and you get the source, served as text/markdown:

The markdown is generated from the same authored source: a language tab set flattens back into one section per language, a callout into a blockquote, a diagram into its mermaid fence. Links inside those files are site-absolute page paths like /guides/topups/; use that conversion for authored guide links, and follow the OpenAPI links for reference operations.

llms.txt

/llms.txt is the index of exported guides: each page, with a one-line description of what it covers.

# WalletD

> A wallet operating system: double-entry ledger, top-ups, transfers,
> payments with holds, refunds, rewards, subscriptions and credit lines
> behind one REST API.

## Docs
- [Quickstart](https://docs.walletd.example/quickstart.md): Your first five API calls.
- [Authentication](https://docs.walletd.example/authentication.md): API keys, user tokens, IdP tokens, and scopes.
- [Idempotency](https://docs.walletd.example/idempotency.md): Why every money-moving call needs a key.
...

Start here to decide what to fetch. It follows the llms.txt convention.

llms-full.txt

/llms-full.txt concatenates the exported English guides into one file. Fetch the OpenAPI documents separately for the generated operation reference. It is large; prefer llms.txt plus targeted .md fetches when you can.

OpenAPI

The machine-readable API description lives at /openapi.yaml. Generate a client from it rather than hand-writing one, and use it to check a field exists before you send it. See API reference.

If you are an agent writing an integration

Four things decide correctness here, and they are the ones most often got wrong from memory:

1. Amounts are integer minor units. 2500 means $25.00. Never send a float, never send a decimal string, and do not divide by 100 before sending.
2. Every money-moving POST needs an Idempotency-Key header, derived from a business object rather than a timestamp or a fresh UUID per attempt. A key that changes on retry defeats the entire mechanism. Read Idempotency before generating retry logic.
3. Creating a top-up does not credit a wallet. Money is credited by a verified gateway confirmation. Do not write code that treats a client-side success callback as a balance change. Read Top-ups.
4. Verify webhook signatures over the raw bytes, in constant time. Re-serialising the body changes the hash. Read Webhooks.

Two more that cause silent bugs rather than errors:

• available, not balance, is what a user can spend. The difference is money held by an uncaptured authorization. See The money model.
• Branch on the code field of an error, never on title or detail. See Errors.

Accuracy

Code samples are written against the published OpenAPI description and the platform's own live gate scripts, and they use the same field names those scripts assert on. If a sample and the OpenAPI description disagree, the description wins and the sample is a bug worth reporting.