For agents
Agent surfaces
Everything on this origin written for a machine to read, and the rules for consuming it.
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 | The machine quickstart | Cold start. Always current with what is deployed |
/skill.md | The full Roundhouse agent skill | Cold start: it sets up its own wallet, then pays, discovers, queries, registers |
/docs.md | These docs, as one markdown index | Finding the page that answers a specific question |
/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:
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 themThe 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:
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. Query shapes: SQL over the index.
If you want a payment to carry a claim you cannot later deny, that is the
KYA memo: 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 returns503 upstream_unavailablenaming the resource, never200with 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. Averifyfailure is deterministic and will never succeed on an unchanged retry. See payment 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 — 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 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
402naming 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 — prompts that work, ready to copy
- Set up an agent — wallet, policy, skill
- Vet a counterparty — deciding whether to pay
- The KYA memo — signing a statement your payment commits to