Roundhouse

Get started

Quickstart

Discover for free, buy an API key for a cent over x402, and pay half a cent for your first query.

Read as markdown

Three commands, in order of what they cost you. The first needs nothing at all — no key, no wallet, no signup. The second costs one cent and mints your API key; the third pays half a cent per question.

1. Discover something (free)#

Discovery is open without authentication — the capability layer and the service directory. Look for something you might want to buy:

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

Or compare every provider of one job at its going rate:

bash
curl -sL "https://api.roundhouseai.io/v0/unified/web-search" | jq

The settlement index itself — flows, transactions, entity profiles, the graph — takes the API key step 2 mints. SQL (step 3) is pay-per-query.

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 the API key that opens the read endpoints.

bash
curl -iL "https://api.roundhouseai.io/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://api.roundhouseai.io/v0/test/x402').then(
  (r) => r.json(),
);

console.log(api_key, limits); // rh_live_… , { read_requests_per_minute: 2, … }

The key is returned exactly once — only its hash is stored. It opens the read endpoints (2/min, 10/min if your wallet carries registered identity) 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 ($0.005 per query)#

For anything the fixed endpoints do not answer, send read-only SQL. SQL is pay-per-query: an unpaid POST answers 402 with x402 requirements for $0.005 USDC, and any standard x402 client pays it in-line — the same wallet you used in step 2:

javascript
const res = await pay('https://api.roundhouseai.io/v0/sql', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    sql: 'select wallet, inbound_usd, inbound_count from mv_entity_rollups order by inbound_usd desc limit 10',
  }),
}).then((r) => r.json());

One SELECT or WITH, 300 rows maximum, 8-second timeout. A paid-plan organization key runs it QU-metered instead of per-payment — that is the throughput path. 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://roundhouseai.io/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. POST /api/v0/sql answers 402 for $0.005 — pay it with the same wallet and
   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#