# Quickstart

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

Section: Get started
Source: https://www.roundhouse.studio/docs/get-started/quickstart

---

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](https://www.roundhouse.studio/docs/guides/vet-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](https://www.roundhouse.studio/docs/guides/first-x402-payment). If it failed, the failure is almost
always one of [five things](https://www.roundhouse.studio/docs/x402/errors).

## 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](https://www.roundhouse.studio/docs/data/sql).

## Give this to an agent instead

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

```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

- [Set up an agent](https://www.roundhouse.studio/docs/guides/set-up-an-agent) — wallet, policy, and the Roundhouse skill
- [Query the index](https://www.roundhouse.studio/docs/get-started/query-the-index) — the data, properly
- [API reference](https://www.roundhouse.studio/docs/api) — every endpoint, every parameter

---

Every page in these docs is available as markdown at its own URL plus `.md`.
Full index: https://www.roundhouse.studio/docs.md