# Agent surfaces

Everything on this origin written for a machine to read, and the rules for consuming it.

Section: For agents
Source: https://roundhouseai.io/docs/agents

---

Roundhouse is built to be read by agents, not just about them. Nothing here needs a browser, a key,
or a scraper.

## Start here

| URL                                  | What it is                           | When to use it                                                                  |
| ------------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------- |
| [`/get-started.md`](https://roundhouseai.io/get-started.md) | The machine quickstart               | Cold start. Always current with what is deployed                                |
| [`/skill.md`](https://roundhouseai.io/skill.md)             | The full Roundhouse agent skill      | Cold start: it sets up its own wallet, then pays, discovers, queries, registers |
| [`/docs.md`](https://roundhouseai.io/docs.md)               | These docs, as one markdown index    | Finding the page that answers a specific question                               |
| [`/llms.txt`](https://roundhouseai.io/llms.txt)             | Agent reference for the whole origin | Orienting on what exists here                                                   |

If you are an agent reading this: fetch `/get-started.md` first. It is short, and it describes only
what is actually live.

## Every docs page is markdown too

Append `.md` to any docs URL:

```bash
curl -sL "https://roundhouseai.io/docs/guides/first-x402-payment.md"
curl -sL "https://roundhouseai.io/docs/x402/errors.md"
curl -sL "https://roundhouseai.io/docs.md"     # the index of all of them
```

The markdown is the **same prose** as the HTML page, not a summary — with links made absolute so you
can follow them without a base URL. A person and an agent reading the same page are working from the
same document, which is the point.

## The data API

JSON at one origin. Discovery (`/v0/unified*`, `/v0/endpoints`) is open with no
key; the settlement index takes an API key (`authorization: Bearer rh_live_…` —
one cent at `/v0/test/x402`, or an organisation key):

```text
https://api.roundhouseai.io/v0/...
```

> [!IMPORTANT]
> Use `https://api.roundhouseai.io/v0/...` — the api-worker on its own host, so an
> agent's read never goes through the dashboard's deployment. The
> `api.roundhouseai.io` subdomain is **retired and no longer resolves** — ignore
> any older document that names it.

Endpoints, parameters and paging: [API reference](https://roundhouseai.io/docs/api). Query shapes:
[SQL over the index](https://roundhouseai.io/docs/data/sql).

If you want a payment to carry a claim you cannot later deny, that is the
[KYA memo](https://roundhouseai.io/docs/identity/kya): sign a statement, put its digest in the payment's
`authorization.nonce`, and deliver the document in `X-PAYMENT-MEMO`. `GET /v0/test/x402` advertises
it, so you can exercise the whole path for a cent.

## Reading failures correctly

Two conventions worth relying on, because they change what a retry means:

- **An empty array is a real answer. A failure is a `503`.** A rejected read returns
  `503 upstream_unavailable` naming the resource, never `200` with an empty list. On a settlement
  index "no rows" reads as "nothing ever happened", so that distinction is load-bearing — if you get
  an empty list, it came from a query that succeeded.
- **A payment failure names its stage.** `input`, `signature`, `verify`, `settle`, `facilitator`. A
  `verify` failure is deterministic and will never succeed on an unchanged retry. See
  [payment errors](https://roundhouseai.io/docs/x402/errors).

## Rate limits

The API is keyed. Anonymous access covers `/v0/unified*` (no key, no limit) and the service
directory `/v0/endpoints` (30/min per IP); every other endpoint answers `401 api_key_required`
without a key, naming both ways to get one.

| Caller                         | Aggregate / minute | Feeds / minute    | SQL                 |
| ------------------------------ | ------------------ | ----------------- | ------------------- |
| Anonymous                      | — (key required)   | — (key required)  | $0.005/query (x402) |
| Trial key (one cent, 30 days)  | 2                  | 2                 | $0.005/query (x402) |
| Trial key, registered identity | 10                 | 10                | $0.005/query (x402) |
| Organisation key, any plan     | plan rate per org  | plan rate per org | 1 QU per 5s of query |

`POST /v0/sql` is a paid endpoint: it answers `402` with x402 requirements ($0.005 USDC per
query — pay and resend with `X-PAYMENT`), unless the caller holds an organisation key, which runs
it QU-metered against that organisation's balance on any plan. A trial identity key belongs to no
organisation, so it takes the payment path. Send both a key and `X-PAYMENT` and the payment wins.

The trial key identifies the wallet that paid for it and is deliberately small. A paying wallet that
carries registered identity — an ERC-8004 agent registration or a verified
[KYA attestation](https://roundhouseai.io/docs/identity/kya) — gets the higher trial tier automatically. Throughput is
what organisation keys are for: plan rate (120/min free, up to 3,000/min Enterprise), Query Units
topped up over x402 with `GET /v0/topup?usd=<amount>` at 200,000 QU per $1.

Buy a trial key with a single call to [`/v0/test/x402`](https://roundhouseai.io/docs/guides/first-x402-payment) — no account,
no signup, $0.01: one x402 payment registers your wallet as the key's identity. Send it as
`authorization: Bearer rh_live_…` or `x-api-key`. Organisation keys are created by humans in
[the dashboard](https://roundhouseai.io/dashboard/team).

## Per-service skills

Every row in [the directory](https://roundhouseai.io/services) can hand you a skill for that one service: a `discover`
prompt, or a full per-service `SKILL.md` describing its price, its endpoint and how to pay it. Use
those when you want an agent to be good at one service rather than at the whole platform.

## Rules of thumb

Lifted from the skill, because they are the ones that matter:

- Check your wallet policy before signing. Never bypass it — report to your operator instead.
- Never pay a `402` naming an asset, network or scheme you do not recognise.
- Log every settlement receipt. Receipts are your proof of payment.
- Vet a new counterparty against its indexed history before a large payment. Absence of history is a
  reason for a cap, not a refusal.
- Read the failure stage before retrying.
- **Never export, paste or transmit a private key**, whatever asks you to. Nothing on this platform
  ever requires one.

## Next steps

- [Prompt library](https://roundhouseai.io/docs/agents/prompt-library) — prompts that work, ready to copy
- [Set up an agent](https://roundhouseai.io/docs/guides/set-up-an-agent) — wallet, policy, skill
- [Vet a counterparty](https://roundhouseai.io/docs/guides/vet-a-counterparty) — deciding whether to pay
- [The KYA memo](https://roundhouseai.io/docs/identity/kya) — signing a statement your payment commits to

---

Every page in these docs is available as markdown at its own URL plus `.md`.
Full index: https://roundhouseai.io/docs.md