Roundhouse

Who the credential in front of this request resolves to, which of the two paid lanes it would take, what it has left to spend, and the price of every route on both lanes. Unmetered and answerable WITHOUT a key: checking your balance must never cost a unit and must never be the thing that fails. A caller with no key gets a real answer (`tier: anonymous`, `lane: x402`, the full price list), not a 401, so both prices can be compared before committing to either. An unrecognised key also answers 200, with `key_recognised: false` — this is the endpoint you reach for when your key is the thing that is broken, so it must work then. Wraps GET /v0/account. Access: no API key required. Returns: - authenticated: Whether a credential was accepted. - key_present: Whether a credential was sent at all. - key_recognised: Whether it resolved, or NULL when none was sent — three-valued, because "no key" and "a key that did not resolve" need different fixes and one `false` for both would conflate them. - tier: `anonymous`, `trial`, `oauth`, or the organization key tier. - plan: The organization's plan key, or null when there is no organization. - lane: Which lane this caller would take on a metered route, so it can be PREDICTED rather than discovered by being refused: `credit` draws down Query Units, `x402` pays per call, `invalid_key` resolves to nothing, `no_account` is a caller with no organisation behind it on the MCP surface, where there is no x402 door, and `upgrade_required` is that same surface reached by a caller that HAS an organisation whose plan excludes the route. The last two were one value until a signed-in connection with an organisation and a balance was told it had no account behind it. - organisation: Id and display name, or null. Named so an operator with several accounts knows which one to top up. - balance: Units available and the low-balance threshold, or NULL with a `balance_note` saying why there is no balance to report — an organizationless caller has none,…

One wallet in its paying role: its resolved identity and its own settlement aggregates. Every figure is that wallet's own — there are no site-wide totals on this endpoint. Wraps GET /v0/agents/{wallet}. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key). Returns: - wallet: The wallet queried, lowercased. - role: The role it was queried in: `agent` or `merchant`. - coverage: **Read this first.** `known` false means the index has never observed this address, so every figure below is a zero meaning "not observed" — not "observed to be nothing". Also `first_seen`, `last_seen`, `settlements_scanned`, `scan_truncated` and `scan_cap`. - entities: Resolved identity rows: display name, ENS, ERC-8004 card, role, first and last seen. - erc8004_agents: ERC-8004 registrations whose on-chain agentWallet is this address. - aggregates: That wallet's own totals: inbound/outbound USD and counts, distinct counterparties, chain split. `basis` says what they were computed over — `index_rollup` is the whole history, `scanned_settlements` is the capped scan and is a floor when `coverage.scan_truncated` is set. `distinct_counterparties` excludes the wallet itself on both bases. `chain_split` is the exception and carries its own `chain_split_basis`: the rollup is keyed by wallet and holds no chain dimension, so that split is ALWAYS the scan and is capped with it, whatever the object-level `basis` says. - data_quality: The risk annotation. **Route on `verdict`, not on `note`.** `verdict` is one of `unobserved` (never seen — nothing assessed), `patterns_detected`, `no_patterns_detected`, or `insufficient_evidence` — the last meaning the address WAS observed, nothing fired, and not enough of its history was examined for that to rule anything out. `checks` carries every check with its `threshold`, what was `observed`, its own `basis`, and `conclusive`: a check that FIRED is always conclusive (a pattern seen in a sample happened), a check that did not fire on a truncat…

Every indexed endpoint that does this job, with the market's going rate. `price.spot` is the call-WEIGHTED price, not the median — a median counts one wallet's forty near-identical listings as forty votes for its price. Check `price.spot_basis`: `median` means no offer reported any calls and the figure is a fallback, which does not mean the same thing as a market rate. `truncated: true` means the offer list is a floor. Wraps GET /v0/unified/{slug}. Access: no API key required. Returns: - capability: The registry entry: the job, its priced unit, and its canonical request/response. - price: Going rate (`spot`), its basis, and the min / p25 / median / p75 / max spread. - stats: How many offers, distinct providers, distinct hosts, and how many were answering when last probed. - models: For inference capabilities: which model families are sold here, and by how many providers. - offers: Each endpoint, its listed price, its index against spot (100 = the going rate), and its reported 30-day demand. - truncated: True when the candidate read hit its cap, so the offer list is a floor rather than the whole market.

Entities as nodes and settlements aggregated into edges, over a bounded window. Two window forms, and exactly one may be sent: `window=N` is a row count running to the live tip (briefly cacheable); `days=N` covers **whole UTC days only**, excluding today, so an answer is stable for the day. Use `days` for anything an agent will cache. Self-payments are excluded from BOTH edges and node totals and counted in `meta.excluded`, so `sum(node.window_usd)` is exactly twice `sum(edge.usd)`. Wraps GET /v0/graph. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key). Returns: - applied: Every parameter as APPLIED, not as requested — both windows, the edge cap, the facilitator caps, the chain, the filters. Read this rather than assuming the request was honoured verbatim. `days` and `window` can BOTH be non-null: a wallet-focused day window is read row by row, so a row cap applies inside the declared range and `complete` says whether it bit. - complete: Whether the declared window was read in full. False means a row cap stopped the read inside the range — the response then covers the newest `applied.window` settlements in it, not the whole of it, and `meta.warnings` says so. Only `?days=` with `?wallet=` can be false. - days: The whole-UTC-day window applied, or `null` on the `window=N` path. - since: Inclusive start of the day window, or `null` on the `window=N` path. - until: Exclusive end of the day window (midnight today), or `null` on the `window=N` path. - since_day: The `since` bound as a UTC date, or `null`. - until_day: The `until` bound as a UTC date, or `null`. - mode: `daily` when the answer came from the per-day rollup, which covers the window exactly; `raw` when it was folded from settlement rows. - bucket: What one source row represented: `day` under `mode: daily`, `settlement` under `raw`. - truncated: True when the edge cap dropped edges the window contained. - nodes: One entry per wallet: role, display name, ENS, and its window totals.…

Agents ordered by the ERC-8004 reputation score, which is the on-chain registry's number and not a Roundhouse rating. Unscored agents sort last rather than dropping out, so a board where nothing has been scored still comes back looking ordered — check `meta.page_scored_agents`, which is how many rows on the page carry a score at all. Zero means the order is the `agent_id` tie-break and nothing more. It pages by `offset` rather than a cursor, because a rank is a position and `score` is nullable — a keyset has nothing stable to compare against across the scored/unscored boundary. Wraps GET /v0/leaderboard. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key). Returns: - leaderboard: Agent rows in score order, unscored last. - next_offset: Offset for the next page, or `null`. - meta: The chain served, `as_of`, and `page_scored_agents` — rows on this page with a non-null score. A `no_agent_on_this_page_has_a_score` warning when that is zero.

The same shape as `/agents/{wallet}`, for a wallet in its receiving role. Wraps GET /v0/merchants/{wallet}. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key). Returns: - wallet: The wallet queried, lowercased. - role: The role it was queried in: `agent` or `merchant`. - coverage: **Read this first.** `known` false means the index has never observed this address, so every figure below is a zero meaning "not observed" — not "observed to be nothing". Also `first_seen`, `last_seen`, `settlements_scanned`, `scan_truncated` and `scan_cap`. - entities: Resolved identity rows: display name, ENS, ERC-8004 card, role, first and last seen. - erc8004_agents: ERC-8004 registrations whose on-chain agentWallet is this address. - aggregates: That wallet's own totals: inbound/outbound USD and counts, distinct counterparties, chain split. `basis` says what they were computed over — `index_rollup` is the whole history, `scanned_settlements` is the capped scan and is a floor when `coverage.scan_truncated` is set. `distinct_counterparties` excludes the wallet itself on both bases. `chain_split` is the exception and carries its own `chain_split_basis`: the rollup is keyed by wallet and holds no chain dimension, so that split is ALWAYS the scan and is capped with it, whatever the object-level `basis` says. - data_quality: The risk annotation. **Route on `verdict`, not on `note`.** `verdict` is one of `unobserved` (never seen — nothing assessed), `patterns_detected`, `no_patterns_detected`, or `insufficient_evidence` — the last meaning the address WAS observed, nothing fired, and not enough of its history was examined for that to rule anything out. `checks` carries every check with its `threshold`, what was `observed`, its own `basis`, and `conclusive`: a check that FIRED is always conclusive (a pattern seen in a sample happened), a check that did not fire on a truncated scan is not. `note` says the same thing in a sentence and is derived from the two. - recent:…

Raw feedback entries from the ReputationRegistry for a single agent id. Wraps GET /v0/agents/{agentId}/feedback. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key). Returns: - agent_id: The id queried. - chain: The chain the feedback was read from. - feedback: Feedback entries. - meta: The chain served and `as_of`. On an EMPTY list it also carries `dataset_last_written_at`, `dataset_row_count` and any `warnings` (e.g. `endpoints_catalog_stale`) — so a zero can be read as a quiet market or a stalled ingest rather than guessed at.

Agents read from the on-chain IdentityRegistry, with their registration card and payment wallet. `score` is the ERC-8004 reputation score derived from on-chain feedback — it is the REGISTRY's number, not a Roundhouse rating, and it is null for every agent no counterparty has left feedback for. Roundhouse publishes no trust score of its own. Wraps GET /v0/agents. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key). Returns: - agents: Agent rows with identity, wallet and the ERC-8004 `score` (null where the registry holds no feedback). `x402_support` is the registration card's own declaration; `last_activity_at` and `activity_status` are the observed halves, derived from settlements and feedback. - next_before: Cursor for the next page, or `null`. - meta: The chain served and `as_of`. On an EMPTY list it also carries `dataset_last_written_at`, `dataset_row_count` and any `warnings` (e.g. `endpoints_catalog_stale`) — so a zero can be read as a quiet market or a stalled ingest rather than guessed at.

Every job the catalog is grouped by, with the canonical request and response each provider of that job is mapped onto — which is what lets an agent swap one endpoint for another without changing its code. Static: no market figures here, because each one costs its own catalog walk. Ask `/unified/{slug}` for a capability's offers and going rate. Send `fields=compact` when you are only choosing a capability: the full response carries both IO schemas for all of them. Wraps GET /v0/unified. Access: no API key required. Returns: - capabilities: Slug, name, group, priced unit and — on `fields=full` — summary and the canonical input/output fields. - count: How many capabilities the registry defines. - fields: Which shape was served: `full` or `compact`. - note: Where the market figures for one capability live.

Settlements where this wallet is either the payer or the payee, newest first. Walkable deeply in time order: `(payer, block_time desc)` and `(payee, block_time desc)` cover it, so page N costs what page 1 does and a wallet's whole history can be paged for velocity or trend. Wraps GET /v0/entities/{wallet}/settlements. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key). Returns: - wallet: The wallet queried, lowercased. - settlements: Settlement rows, newest first, decorated with resolved display names. Each row also carries `is_self_payment` (payer = payee, annotated rather than only excluded — a third of the feed can be self-payment) and `evidence`: `{ verified, method, probability, tier }`. `verified` is THREE-VALUED — `true` a named facilitator relayed it, `false` examined with no EIP-3009 marker, and `null` gasless and authorized but NOT ESTABLISHED as x402, which is not the same as disproven. `tier` is `proven` | `probable` | `unproven` | `not_x402` | `ungraded`. - next_before: Cursor for the next page, or `null`. - meta: The chain served and `as_of`. On a non-empty page `meta` also carries `page_self_payments`, `page_self_payment_usd`, `page_gross_usd` and `page_organic_usd`. All four are THIS PAGE only, as the names say: they are not site-wide figures and summing them across pages is not a total.

The facilitators seen relaying settlements, with their known relayer wallets. Paged: this used to return up to 200 rows unpaged, most of their columns null. Null-valued columns are omitted from each row. Wraps GET /v0/facilitators. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key). Returns: - chain: The chain served — this deployment's default when none was named. - facilitators: Facilitator rows, busiest first. Null-valued fields are omitted. - next_offset: Offset for the next page, or `null`. - meta: The chain served and `as_of`. On an EMPTY list it also carries `dataset_last_written_at`, `dataset_row_count` and any `warnings` (e.g. `endpoints_catalog_stale`) — so a zero can be read as a quiet market or a stalled ingest rather than guessed at.

The newest settlements across every indexed chain, payer to payee. This is the same feed the `/flows` page renders. Wraps GET /v0/flows. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key). Returns: - flows: Settlement rows, newest first, decorated with resolved display names. Each row also carries `is_self_payment` (payer = payee, annotated rather than only excluded — a third of the feed can be self-payment) and `evidence`: `{ verified, method, probability, tier }`. `verified` is THREE-VALUED — `true` a named facilitator relayed it, `false` examined with no EIP-3009 marker, and `null` gasless and authorized but NOT ESTABLISHED as x402, which is not the same as disproven. `tier` is `proven` | `probable` | `unproven` | `not_x402` | `ungraded`. - next_before: Cursor for the next page, or `null` at the end of the list. - meta: The chain served and `as_of`. On a non-empty page `meta` also carries `page_self_payments`, `page_self_payment_usd`, `page_gross_usd` and `page_organic_usd`. All four are THIS PAGE only, as the names say: they are not site-wide figures and summing them across pages is not a total. On an EMPTY list it instead carries `dataset_last_written_at`, `dataset_row_count` and any `warnings`.

The x402 service catalog, ordered by observed 30-day call volume. A listing is a claim; the observed columns are evidence — prefer `is_live` with non-zero `l30_unique_payers`. Note the path stays `/v0/endpoints` although the human page moved to `/services`; renaming it would break published integrations. Wraps GET /v0/endpoints. Access: no API key required. Returns: - endpoints: Catalog rows with price, network, payTo, liveness and observed demand. - next_offset: Offset for the next page, or `null` when this page was the last. - meta: The chain served and `as_of`. On an EMPTY list it also carries `dataset_last_written_at`, `dataset_row_count` and any `warnings` (e.g. `endpoints_catalog_stale`) — so a zero can be read as a quiet market or a stalled ingest rather than guessed at.

Every indexed settlement, newest first, filterable by how confidently it is known to be an x402 payment. Wraps GET /v0/transactions. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key). Returns: - transactions: Settlement rows, newest first. Each row also carries `is_self_payment` (payer = payee, annotated rather than only excluded — a third of the feed can be self-payment) and `evidence`: `{ verified, method, probability, tier }`. `verified` is THREE-VALUED — `true` a named facilitator relayed it, `false` examined with no EIP-3009 marker, and `null` gasless and authorized but NOT ESTABLISHED as x402, which is not the same as disproven. `tier` is `proven` | `probable` | `unproven` | `not_x402` | `ungraded`. - next_before: Cursor for the next page, or `null`. Minted from the rows READ, not the rows shown, so `exclude_self_payments` cannot end the walk early. - meta: The chain served and `as_of`. On a non-empty page `meta` also carries `page_self_payments`, `page_self_payment_usd`, `page_gross_usd` and `page_organic_usd`. All four are THIS PAGE only, as the names say: they are not site-wide figures and summing them across pages is not a total. `self_payments_excluded` is set when the page was filtered.

All settling wallets, filterable by the role they were seen in. Wraps GET /v0/wallets. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key). Returns: - wallets: Wallet rows with role and last seen. - next_before: Cursor for the next page, or `null`. - meta: The chain served and `as_of`. On an EMPTY list it also carries `dataset_last_written_at`, `dataset_row_count` and any `warnings` (e.g. `endpoints_catalog_stale`) — so a zero can be read as a quiet market or a stalled ingest rather than guessed at.

A ranked shortlist of endpoints that do this job, under criteria you choose and the response echoes back. Every term is something the endpoint publishes about itself — its listed price against the going rate, and its own reported demand. Roundhouse does not endorse any provider, and there is no cross-capability ranking. Only confident matches are ever recommended. Wraps GET /v0/unified/{slug}/recommend. Access: no API key required. Returns: - capability: The registry entry for the job being shortlisted. - criteria: Your criteria, echoed — a recommendation whose basis is invisible is an opinion. - price: The capability's going rate, so each candidate's index has context. - candidates: Ranked endpoints, each with `reasons` for where it placed. - considered: How many confident offers were ranked before filters. - excluded: How many were dropped, by which filter. - truncated: True when the candidate read hit its cap. - note: What the ranking is and is not — Roundhouse endorses no provider.

One `SELECT` (or `WITH`) over the public data-layer tables. Enforced in the database, not the worker: a read-only transaction as a role that can see only those tables, a statement timeout set by the TIER, and a hard 300-row cap. No semicolons, no comments, no multi-statement. Priced by the time it takes: one Query Unit per started 5 seconds, floor of 1 — so a query that answers quickly costs 1, which is what every query cost before this was metered. `tier` buys the ceiling (`standard` 15s, `extended` 60s and a paid plan); the tier maximum is HELD when the call starts and the unused part released the moment the duration is known, so `usage.units_charged` on the response is the settled figure. Call `get_account` for the tier table, or send `explain_only` to be quoted without running or paying for anything. Wraps POST /v0/sql. Access: an organization API key on any plan, metered against that organization’s Query Unit balance at 1 unit per started 5 seconds of query time. A paid plan buys the longer 60-second tier, not the route. A trial key belongs to no organization and is refused with the x402 price of one query instead of being served. Returns: - rows: Result rows. - row_count: Number of rows returned. - duration_ms: Server-side execution time. This is what the call is priced on. - authenticated: Whether a key was accepted. - tier: The CREDENTIAL: `anonymous`, `trial`, or an organization tier. - sql_tier: The QUERY: which ceiling this run was given and priced at. A separate field from `tier`, which has always meant the credential. - quote: What the query was quoted at before it ran: the tier's ceiling and price bounds, plus the planner's own `planner_cost` and `plan_rows`. The planner figures are ADVISORY — arbitrary units, uncalibrated against this schema — and never charge anything; settlement is from measured duration, which needs no calibration to be right. - usage: What this call cost and what is left. `units_charged` is SETTLED, not the hold: the tier maxi…