Query the index

Everything Roundhouse knows is readable. There is no private tier of the dataset; the paid tiers buy you rate limit and convenience, not access.

Pick a read path by how specific your question is.

Fixed endpoints#

Free, no key, JSON. The full list with every parameter is the API reference; these are the ones you will reach for first.

GET /api/v0/flows?limit=50                    live flow of funds, newest first
GET /api/v0/transactions?limit=50             the global settlement feed
GET /api/v0/agents?q=<search>                 indexed ERC-8004 agents
GET /api/v0/agents/<wallet>                   one agent: identity + settlement stats
GET /api/v0/merchants/<wallet>                one merchant: inbound volume, customers
GET /api/v0/entities/<wallet>/settlements     raw settlements for one wallet
GET /api/v0/endpoints?q=<search>              the priced service directory
GET /api/v0/leaderboard?limit=25              agents ranked by trust
GET /api/v0/facilitators                      who relays payments, and how much
GET /api/v0/graph?days=7                      nodes and payer→payee edges

Two paging conventions, and they are not interchangeable:

• Feeds use a cursor. next_before is an opaque token encoding the whole sort key including its tiebreaker. Pass it back as ?before=. Do not parse it, and do not construct one — a naive block_time cursor silently drops every row sharing the last row's timestamp, and on a 2-second chain most timestamps are shared.
• The leaderboard uses an offset. A rank is a position, and score is nullable, so there is nothing stable for a cursor to compare against. ?offset= in, next_offset out.

An empty array is a real answer. A failed read is not: a rejected query returns 503 upstream_unavailable naming the resource, never 200 {"flows": []}. On a settlement index "no rows" reads as "nothing ever happened", which is the one lie the read path is built to prevent.

Read-only SQL#

For everything else. One statement, SELECT or WITH only, over the public data-layer tables.

curl -sL -X POST "https://www.roundhouse.studio/api/v0/sql" \
  -H "authorization: Bearer $ROUNDHOUSE_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "sql": "select date_trunc('day', block_time) as day, count(*) as settlements, sum(amount_usd) as usd from settlements where block_time > now() - interval '14 days' group by 1 order by 1 desc"
  }' | jq

The sandbox is enforced in the database, not in the request handler: a role that can read only the public tables, a read-only transaction, an 8-second statement timeout, and a hard 300-row cap. Write for those limits rather than discovering them — SQL over the index has the readable tables, the useful shapes, and the traps.

Use the rollups, not the raw table#

settlements has tens of millions of rows. An unbounded aggregate over it will hit the timeout. The pre-computed views exist so you do not have to:

They refresh on a schedule, so they trail the tip of the chain by up to an hour. Read surfaces fold in the newer settlements at read time, which is why a profile page and a raw mv_entity_rollups query can differ by a few rows — the page is more current, not wrong.

Rate limits and keys#

Send a key as authorization: Bearer rh_live_… or x-api-key. Organisation keys are created in the dashboard; the trial key costs one cent and needs no account at all.

Next steps#

• SQL over the index — the tables, and queries to copy
• The data model — what a settlement row actually contains
• Coverage and confidence — when to trust a number