# Quickstart

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

Section: Get started
Source: https://roundhouseai.io/docs/get-started/quickstart

---

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

## 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](https://roundhouseai.io/dashboard/team) 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](https://roundhouseai.io/docs/data/sql).

## Give this to an agent instead

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

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

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

---

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