Roundhouse

Get started

Quickstart

Make a free read, buy an API key for a cent over x402, and run your first query.

Read as markdown

Three commands, in order of what they cost you. The first two need nothing at all — no key, no wallet, no signup. The third needs one cent.

Note

The data API is live at https://www.roundhouse.studio/api/v0. The bare roundhouse.studio host redirects to www, so pass -L to curl. The api.roundhouse.studio subdomain is reserved but not yet bound — do not build against it.

1. Read something (free)#

The whole index is readable without authentication. Start with the live flow of funds:

bash
curl -sL "https://www.roundhouse.studio/api/v0/flows?limit=5" | jq

Then look for something you might want to buy:

bash
curl -sL "https://www.roundhouse.studio/api/v0/endpoints?q=weather&limit=5" | jq \
  '.endpoints[] | {service_name, resource, price_usdc, is_live, l30_unique_payers}'

price_usdc is what the listing claims. l30_unique_payers is how many distinct wallets actually paid it in the last 30 days. Those are different facts, and the second one is the useful one — see vetting a counterparty.

2. Make a paid call ($0.01)#

GET /v0/test/x402 is a real x402-gated endpoint whose only job is to prove your payment path works end to end: client, wallet, signing, facilitator, settlement. It costs one cent in USDC on Base, and it hands back an API key that raises your SQL rate limit.

bash
curl -iL "https://www.roundhouse.studio/api/v0/test/x402"

Unpaid, that returns 402 with the payment requirements in the body. Any standard x402 client can take it from there:

javascript
import { wrapFetchWithPayment } from 'x402-fetch';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.AGENT_KEY);
const pay = wrapFetchWithPayment(fetch, account);

const { api_key, expires_at, limits } = await pay(
  'https://www.roundhouse.studio/api/v0/test/x402',
).then((r) => r.json());

console.log(api_key, limits); // rh_live_… , { sql_per_minute: 240 }

The key is returned exactly once — only its hash is stored. It is good for 240 SQL queries a minute for 30 days.

If you want to understand what just happened header by header, that is your first x402 payment. If it failed, the failure is almost always one of five things.

3. Ask the data a question#

For anything the fixed endpoints do not answer, send read-only SQL:

bash
curl -sL -X POST "https://www.roundhouse.studio/api/v0/sql" \
  -H "authorization: Bearer $ROUNDHOUSE_KEY" \
  -H 'content-type: application/json' \
  -d '{"sql":"select wallet, inbound_usd, inbound_count from mv_entity_rollups order by inbound_usd desc limit 10"}' | jq

One SELECT or WITH, 300 rows maximum, 8-second timeout. Anonymous callers get 30 queries a minute; the trial key above gets 240. The full contract, the readable tables and the shapes worth knowing are in SQL over the index.

Give this to an agent instead#

Everything above, written for a machine rather than a person:

Agent prompt
Fetch https://www.roundhouse.studio/get-started.md and follow it.

Goal: prove you can pay for an x402 resource, then answer a question from the
Roundhouse index.

1. Read the free endpoints first and tell me what you found.
2. Pay the $0.01 test drive at GET /api/v0/test/x402 and keep the API key it
   returns in an environment variable, not in your notes.
3. Using that key, tell me the ten wallets with the highest inbound settled
   volume, and what each one appears to sell.

Do not proceed past step 2 if the payment fails — report the failure stage
instead.

Next steps#