# Agent surfaces

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

Section: For agents
Source: https://www.roundhouse.studio/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://www.roundhouse.studio/get-started.md) | The machine quickstart | Cold start. Always current with what is deployed |
| [`/skill.md`](https://www.roundhouse.studio/skill.md) | The full Roundhouse agent skill | Cold start: it sets up its own wallet, then pays, discovers, queries, registers |
| [`/docs.md`](https://www.roundhouse.studio/docs.md) | These docs, as one markdown index | Finding the page that answers a specific question |
| [`/llms.txt`](https://www.roundhouse.studio/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://www.roundhouse.studio/docs/guides/first-x402-payment.md"
curl -sL "https://www.roundhouse.studio/docs/x402/errors.md"
curl -sL "https://www.roundhouse.studio/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

Free, no key, JSON:

```text
https://www.roundhouse.studio/api/v0/...
```

> [!IMPORTANT]
> Use `https://www.roundhouse.studio/api/v0/...`. The bare host redirects to
> `www`, so follow redirects (`curl -L`). The `api.roundhouse.studio` subdomain is
> reserved but **not bound** — do not build against it, and ignore any older
> document that suggests it.

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

If you want a payment to carry a claim you cannot later deny, that is the
[KYA memo](https://www.roundhouse.studio/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://www.roundhouse.studio/docs/x402/errors).

## Rate limits

| Caller | SQL queries / minute |
| --- | --- |
| Anonymous | 30 |
| Trial key (one cent, 30 days) | 240 |
| Organisation key | Query Units |

Buy a trial key with a single call to [`/v0/test/x402`](https://www.roundhouse.studio/docs/guides/first-x402-payment) — no account,
no signup, $0.01. Send it as `authorization: Bearer rh_live_…` or `x-api-key`.

The fixed REST endpoints are free and not metered.

## Per-service skills

Every row in [the directory](https://www.roundhouse.studio/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://www.roundhouse.studio/docs/agents/prompt-library) — prompts that work, ready to copy
- [Set up an agent](https://www.roundhouse.studio/docs/guides/set-up-an-agent) — wallet, policy, skill
- [Vet a counterparty](https://www.roundhouse.studio/docs/guides/vet-a-counterparty) — deciding whether to pay
- [The KYA memo](https://www.roundhouse.studio/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://www.roundhouse.studio/docs.md