# 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 Everything is on one origin: https://www.roundhouse.studio - Read API: https://www.roundhouse.studio/api/v0/... - Control plane: https://www.roundhouse.studio/api/v1/... - This reference: https://www.roundhouse.studio/llms.txt - API docs (human): https://www.roundhouse.studio/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. The api.roundhouse.studio and docs.roundhouse.studio subdomains are not bound yet; until they are, the paths above on www.roundhouse.studio are the API. They are stable — when the subdomains land, these keep working. 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 /api/v0/flows?limit=50 live settlement feed, newest first - GET /api/v0/transactions?limit=50 settlement ledger (?min_probability=0.5) - GET /api/v0/agents?q=&x402=true indexed ERC-8004 agents - GET /api/v0/agents/ per-agent aggregates + identity - GET /api/v0/merchants/ per-merchant aggregates - GET /api/v0/agents//feedback itemised ERC-8004 feedback - GET /api/v0/leaderboard agents ranked by score - GET /api/v0/entities//settlements raw per-entity settlements - GET /api/v0/graph?window=500&wallet= reputation graph: entity nodes + payer→payee edges - GET /api/v0/endpoints?q= indexed x402 service directory - POST /api/v0/sql read-only SQL over the dataset - GET /api/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://www.roundhouse.studio/api/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 /api/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 /api/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://www.roundhouse.studio/api/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. ## Higher limits: buy a key with x402 (GET /api/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 /api/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 /api/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 /api/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 /api/v0/sql: buy one for $0.01 at GET /api/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://www.roundhouse.studio/docs what is indexed, and how - https://www.roundhouse.studio/docs/api full API reference incl. limits - https://www.roundhouse.studio/docs/api/openapi.yaml OpenAPI 3.1 spec for /v0 (also .json) - https://www.roundhouse.studio/docs/api/playground call any endpoint from the browser - https://www.roundhouse.studio/docs/x402 how x402 works, end to end - https://www.roundhouse.studio/docs/identity/erc-8004 portable agent identity - https://www.roundhouse.studio/flows the live flow of funds - https://www.roundhouse.studio/explore the reputation graph as a bubble map - https://www.roundhouse.studio/stats index coverage + site-wide volume Contact: team@roundhouse.studio