# Roundhouse — agent reference > Roundhouse is the neutral data layer for the autonomous-agent economy. It > indexes x402 settlements and ERC-8004 agent identity into one canonical, > queryable store, and exposes it read-only over HTTP and SQL — no account, no > key, no SDK required to start. It also runs the market half: an HTTP 402 > paywall that prices a publisher's API or files in USDC and settles payment > straight to their wallet on Base. Roundhouse never custodies funds. > Aggregate figures are per-entity; site-wide totals live only on /stats. ## Base URL Two origins: the API host, which is what you call, and the site, where the human pages and the bulk files live. https://api.roundhouseai.io/v0 the read API https://roundhouseai.io pages, docs, /skill.md, the .json files - Read API: https://api.roundhouseai.io/v0/... - Control plane: https://roundhouseai.io/api/v1/... - This reference: https://roundhouseai.io/llms.txt - API docs (human): https://roundhouseai.io/docs/api Do not use ioi.md, api.ioi.md, or docs.ioi.md — they are legacy names from the project's previous identity and do not resolve. Call the read API on the API host above: your reads then do not transit the dashboard. The older base, https://roundhouseai.io/api/v0/..., reaches the same service and keeps working, so an integration built against it needs no change. docs.roundhouseai.io is still not bound; the human docs are the https://roundhouseai.io/docs path above. Payment is USDC over x402 on Base mainnet (production) and Base Sepolia (staging). The first-party Roundhouse facilitator settles it and pays the gas. ## Read API (public, no key, no payment) - GET /v0/flows?limit=50 live settlement feed, newest first - GET /v0/transactions?limit=50 settlement ledger (?min_probability=0.5) - GET /v0/agents?q=&x402=true indexed ERC-8004 agents - GET /v0/agents/ per-agent aggregates + identity - GET /v0/merchants/ per-merchant aggregates - GET /v0/agents//feedback itemised ERC-8004 feedback - GET /v0/leaderboard agents ranked by score - GET /v0/entities//settlements raw per-entity settlements - GET /v0/graph?window=500&wallet= reputation graph: entity nodes + payer→payee edges - GET /v0/endpoints?q= indexed x402 service directory - GET /v0/unified capability catalogue (also /unified/, /recommend) - GET /v0/kya/... Know Your Agent attestations - POST /v0/sql read-only SQL — $0.005/query over x402, or a paid-plan org key - GET /v0/topup?usd=10 top up Query Units over x402 (org keys) - GET /v0/test/x402 pay $0.01, get a higher-limit API key Cursor pagination: list responses carry next_before; pass it back as ?before=. /leaderboard is the exception - it is a ranked list, so it pages by ?offset= and returns next_offset (a rank is a position, and score is nullable, which a cursor cannot walk). The token is opaque - it encodes the whole sort key, including a tiebreaker, so a page boundary that lands inside a group of rows sharing a timestamp does not skip the rest of them. Do not parse it or construct one by hand. A null next_before is the end of the list. curl -s 'https://api.roundhouseai.io/v0/flows?limit=3' ## Bulk files (generated, cached) - GET /flows.json recent settlement feed as a static file - GET /explore.json the reputation graph (nodes + edges) behind /explore - GET /services.json the indexed x402 service catalog, enriched (?q= &category= &live= &price= &provider= &paid=1 &network= &page= &per=) - GET /discovery.json Roundhouse-hosted paywalled listings (machine-readable) - GET /discovery.md the same, as Markdown discovery.* covers only listings published on Roundhouse itself and is empty until publishers exist — an empty listings array is a valid, current answer, not an error. For third-party x402 services that Roundhouse has indexed, read services.json or GET /v0/endpoints instead. services.json carries the Roundhouse-only columns as well: category, verified on-chain volume, the payee's ERC-8004 provider, and a daily activity series. (/bazaar.json was the older, Base-only, unpaged form of the same catalog; it now redirects to services.json.) ## Read-only SQL (POST /v0/sql) For questions the fixed endpoints don't cover, send a single SELECT. Body: {"sql": "select …", "limit": 100}. Response: {"rows": [...], "row_count": N, "duration_ms": M, "authenticated": bool, "tier": "…"}. curl -s https://api.roundhouseai.io/v0/sql \ -H 'content-type: application/json' \ -d '{"sql":"select wallet, inbound_usd, inbound_count from mv_entity_rollups order by inbound_usd desc limit 10"}' Queryable tables — this is the whole list: chains chain_tokens settlements entities agents agent_feedback facilitators fee_proxies external_resources settlement_corrections settlement_sync_state mv_entity_rollups mv_entity_daily mv_global_daily Column notes: settlements(payer, payee, amount_usd, block_time, chain_id, tx_hash, scheme, source, x402_probability, via_facilitator, resource_url); entities(wallet, display_name, ens_name, role, first_seen, last_seen); mv_entity_rollups(wallet, inbound_usd, outbound_usd, inbound_count, outbound_count, distinct_counterparties) — no display_name here, read it from entities; mv_global_daily(day, volume_usd, settlement_count). Sandbox (enforced in the database, not advisory): one statement only; SELECT/WITH only; no semicolons or comments; 8-second timeout; hard 300-row cap; runs as a role that can read ONLY the tables listed above. Platform internals — pg_catalog, information_schema, session and config functions — are rejected. An unbounded aggregate or a wide join over the full settlements / entities tables can exceed the 8s timeout (a bare "select count(*) from settlements" does) — filter on block_time, or read the pre-computed mv_entity_rollups / mv_entity_daily / mv_global_daily views instead. These all return in well under a second: select wallet, inbound_usd, inbound_count from mv_entity_rollups order by inbound_usd desc limit 10 select day, volume_usd, settlement_count from mv_global_daily order by day desc limit 30 select payer, payee, amount_usd, block_time from settlements order by block_time desc limit 20 select name, score, feedback_count from agents where feedback_count > 0 order by score desc limit 10 Rate limits: 30 queries/min per IP anonymous, 240/min with a trial key, 120/min per organization with a dashboard key. ## MCP server (POST /v0/mcp) The endpoints above, as Model Context Protocol tools, over stateless Streamable HTTP. One JSON-RPC 2.0 message per POST; no session id, no SSE stream (GET and DELETE answer 405). Protocol revision 2025-06-18. The tool surface is VERSIONED with the endpoints above: MCP negotiates the wire protocol, not whether a tool still takes the arguments it takes today. Both bases named above serve it. https://roundhouseai.io/mcp is not the endpoint — it answers 404 naming the real one. { "type": "http", "url": "https://api.roundhouseai.io/v0/mcp", "headers": { "Authorization": "Bearer rh_live_..." } } initialize, ping and tools/list need no credential, so a client can connect and read what each tool wants. A tools/call is forwarded to the endpoint the tool wraps and answered by that endpoint's own gate: the same requirement, the same per-minute limit, the same Query Unit charge on run_sql. There is no separate MCP quota. Two ways to authenticate, one gate. An API key is the header above. A client that can only authorise by opening a login window uses OAuth 2.1 instead: a refused call answers a real HTTP 401 with a WWW-Authenticate header naming /.well-known/oauth-protected-resource/v0/mcp, discovery follows RFC 9728, and the token resolves to the same organisation limits and Query Unit balance an API key for that organisation would. Which organisation, and whether the connection may run SQL, are chosen by a person on a Roundhouse consent screen — the OAuth request cannot carry either. Tool names are the endpoints: get_account, list_flows, list_transactions, list_entity_settlements, get_agent, get_merchant, list_agents, list_wallets, get_leaderboard, list_agent_feedback, list_facilitators, get_graph, list_services (= /v0/endpoints), list_capabilities, get_capability, recommend_capability_offers, run_sql. The five capability/directory/account tools work with no key. run_sql needs a paid-plan org key. Call get_account FIRST if you are unsure what you are entitled to: it is unmetered, answers without a key, and reports which lane you are on, what balance is left and what every route costs in both Query Units and USDC — so you never have to learn your entitlement from a refusal. tools/list carries each tool's arguments, defaults and caps, generated from the same registry as the OpenAPI spec, so it cannot describe a parameter the endpoint does not take. An argument a tool does not declare is REFUSED, not ignored — a dropped filter would return a list you believe is narrower than it is. A read that fails comes back as a tool result with isError set and the reason intact, never as an empty list. A caller who cannot proceed gets a JSON-RPC error instead: -32001 no or bad credential (HTTP 401, with WWW-Authenticate), -32002 paid plan needed or the organisation is out of Query Units, -32003 rate limited (data.retry_after seconds), -32004 this connection lacks the scope the tool needs (HTTP 403 — re-authorise, do not retry), -32005 no account behind this connection at all (the MCP surface issues no x402 challenge and cannot pay one, so sign in or configure an org key — retrying refuses identically), -32602 unknown tool or argument. Every one of those states what to do in the error MESSAGE: data carries the route's full body, but some clients drop it, so never rely on data alone being what the model reads. Docs: https://roundhouseai.io/docs/api/mcp ## Higher limits: buy a key with x402 (GET /v0/test/x402) A paywalled test resource that doubles as self-serve signup, and the quickest way to prove an x402 client works end to end. Unpaid it returns 402 with standard x402 payment requirements ($0.01 USDC on Base, atomic maxAmountRequired "10000", the token's EIP-712 domain in "extra"). Sign an EIP-3009 authorization over accepts[0], resend it base64 in X-PAYMENT, and the response carries a success message plus a key: {"paid": true, "message": "Payment settled …", "api_key": "rh_live_…", "tier": "trial", "expires_at": "…", "limits": {"sql_queries_per_minute": 240}} The key is shown exactly once (only its hash is stored) and raises the POST /v0/sql limit to 240/min for 30 days, unmetered — the settlement is the payment. Send it as "authorization: Bearer rh_live_…" or "x-api-key". Your payment settles on-chain for real and is indexed like any other, so it appears in GET /v0/flows. The paying wallet needs USDC but no ETH: the facilitator pays gas. One key per settlement; pay again for another. Standard x402 clients (x402-fetch, x402-axios) work against it unmodified. ## Paying for a resource (the x402 flow) 1. Request a priced resource. The first response is 402 carrying the payment requirements (amount, asset, network, payTo). 2. Sign them with your wallet and resend with the payment header. 3. Roundhouse verifies + settles via the facilitator, then returns 200 with the settlement receipt (including the on-chain tx hash) in a response header. Free paths on a paywalled listing (always 200, no payment): /.well-known/x402-manifest.json, /.well-known/openapi.json, and any path matching the listing's preview globs. ## x402 headers - X-PAYMENT client → server base64 signed payment (standard x402) - X-PAYMENT-RESPONSE server → client base64 settlement receipt (standard x402) - PAYMENT-REQUIRED server → client JSON requirement on the 402 (Roundhouse legacy) - PAYMENT-SIGNATURE client → server base64 signed payment (Roundhouse legacy) - PAYMENT-RESPONSE server → client settlement receipt incl. tx_hash (legacy) - X-Wallet-Session client → server SIWx session token (skips x402 when valid) Both envelopes are accepted on the way in. New clients should use the standard X-PAYMENT pair. ## Using the Roundhouse facilitator for your own paywall A facilitator verifies a payment payload and submits the settlement on-chain. Ours pays the gas (your payers need USDC only), records failed attempts a chain indexer can never see, and indexes settlements through it at full confidence with the paid resource attached. Standard endpoints: GET / (service descriptor), GET /supported, POST /verify, POST /settle, GET /test/x402. Request bodies are {x402Version, paymentPayload, paymentRequirements}, where paymentPayload is the base64 X-PAYMENT value your client sent and paymentRequirements is exactly what you published. See /docs/api for the current facilitator host. ## Control plane (publishers, SIWx-authenticated) POST /api/v1/sessions exchanges a CAIP-122 (SIWx) signature for a 24h session token; send it as X-Wallet-Session. Listing create/publish/upload endpoints live under /api/v1/* and are charged a flat platform fee via x402 for unauthenticated agent callers. ## Errors - 402 payment required expected on the first hit of a priced resource; sign + resend. - 401 invalid_api_key key not found, revoked, or expired. - 429 rate_limited per-minute window; back off and retry, nothing is banned. - 400 invalid_query POST /v0/sql: failed a sandbox check (detail says which). - 400 query_failed the query ran but errored (timeout, unknown column). - 402 insufficient_qu organization key with no Query Units left. - 4xx from upstream proxied through for wrapped APIs after settlement. ## Keys and safety Paid resources need no API key — authority is a wallet signature. Keys exist only to raise read limits on POST /v0/sql: buy one for $0.01 at GET /v0/test/x402, or create a non-expiring organization key in the dashboard. Never put a private key or seed phrase in an agent's prompt or context. For autonomous agents, fund a dedicated low-balance wallet so a runaway loop can't spend more than you staked. ## Human pages (context, not APIs) - https://roundhouseai.io/docs what is indexed, and how - https://roundhouseai.io/docs/api full API reference incl. limits - https://roundhouseai.io/docs/api/openapi.yaml OpenAPI 3.1 spec for /v0 (also .json) - https://roundhouseai.io/docs/api/playground call any endpoint from the browser - https://roundhouseai.io/docs/x402 how x402 works, end to end - https://roundhouseai.io/docs/identity/erc-8004 portable agent identity - https://roundhouseai.io/flows the live flow of funds - https://roundhouseai.io/explore the reputation graph as a bubble map - https://roundhouseai.io/stats index coverage + site-wide volume Contact: team@roundhouseai.io