# Price and pick a service Find the going rate for a job, then choose an endpoint that does it — in two requests. Section: Guides Source: https://www.roundhouse.studio/docs/guides/price-and-pick-a-service --- An agent that needs web search does not need a list of 41,000 endpoints. It needs to know what web search costs, who sells it, and which one to call. That is three questions, and the capability layer answers them in two requests. ## The problem with a directory The service catalog lists endpoints. Endpoints do not describe themselves consistently: two that do the identical job publish different paths, different field names and prices six orders of magnitude apart. So a directory answers "what exists" and leaves "what should this cost" and "which one" to the caller. Unified Services groups endpoints by the **job they do** — 34 capabilities, each with a canonical request and response that every provider is mapped onto. Once endpoints are grouped that way, a price becomes comparable, and comparing prices is the whole point. ## Step 1 — find the capability ```bash curl https://www.roundhouse.studio/api/v0/unified ``` Each entry carries the job, the unit it is priced in, and the canonical `input` / `output` fields. The unit matters more than it looks: two prices are only comparable if they buy the same thing, which is why the registry names it once per capability rather than leaving it to each provider. This endpoint does no market lookup, so it is fast and safe to cache. Figures come from step 2. ## Step 2 — get the going rate ```bash curl https://www.roundhouse.studio/api/v0/unified/web-search ``` ```json { "capability": { "slug": "web-search", "name": "Web search", "unit": "per query" }, "price": { "spot": 0.0162, "spot_basis": "calls", "min": 0.001, "p25": 0.01, "median": 0.02, "p75": 0.03, "max": 0.5, "priced_offers": 118 } } ``` **`spot` is the going rate, and it is call-weighted, not a median.** That distinction is the number's whole value. A median treats one wallet publishing forty near-identical endpoints at $0.50 as forty votes for $0.50 — a listing strategy becomes a market price. Weighting by demand asks the different question: of the calls that were actually made, what did they cost. **Always read `spot_basis`.** `calls` means demand data carried the figure. `median` means no offer in the capability reported any calls and it fell back — that is not a market rate, and treating it as one is a claim the data does not support. Use `p25` and `p75` rather than `min` and `max` to judge a quote. The extremes on this catalog are usually one misconfigured listing at each end; the middle half is where the offers actually are. If `truncated` is `true`, the offer list is a floor, not the whole market. ## Step 3 — pick one ```bash curl "https://www.roundhouse.studio/api/v0/unified/web-search/recommend?prefer=balanced&live=1&limit=3" ``` Each candidate comes back with `reasons` — why it placed where it did: ```json { "criteria": { "prefer": "balanced", "live_only": true, "max_price_usdc": null }, "candidates": [ { "resource": "https://example.dev/api/search", "price_usdc": 0.01, "price_index": 62, "l30_unique_payers": 48, "is_live": true, "reasons": ["38% below the going rate", "48 buyers in the last 30 days", "answering when last probed"] } ], "excluded": { "not_live": 11 } } ``` `price_index` is the endpoint's price against spot, where **100 is the going rate** — so 62 is 38% below it and 180 is 80% above. Pick `prefer` for what you are optimising: | `prefer` | Weights | Use when | | --- | --- | --- | | `price` | Listed price against spot | The job is routine and cheap wins | | `demand` | Reported 30-day calls, log-scaled | You would rather be the hundredth caller than the first | | `balanced` | An even split (default) | You have no strong reason to prefer either | Narrow with `live=1`, `max_price=0.02`, and — for inference capabilities — `model=llama` to require an endpoint that names that model family. **What this is not.** It ranks endpoints *within* one capability, by criteria you chose and the response echoes back, using only what each endpoint publishes about itself. Roundhouse does not endorse providers, does not rank them across capabilities, and does not order anything by settled volume. The `reasons` array is there so you can disagree with the ranking. ## Two things worth knowing before you trust a price **A listed price is a claim.** It is what the endpoint says it charges, from the catalog. The evidence that anyone pays it is `l30_unique_payers` and `l30_total_calls`, which are the upstream catalog's own counters. A listing with no buyers is a price nobody has tested. **A price of `null` is not a price of zero.** Unpriced offers are in every count and in no sum — `unpriced_offers` says how many. Free is a real listing state and reads as `0`. ## Hand it to an agent ```prompt I need to call a paid service that does . Price it, then pick one. 1. GET https://www.roundhouse.studio/api/v0/unified — find the capability slug whose summary matches the job. Note its `unit`, and its canonical input and output fields. 2. GET https://www.roundhouse.studio/api/v0/unified/ — read price.spot as the going rate. Check price.spot_basis: if it is "median", say so and treat the figure as weak. Note price.p25 and price.p75 as the normal band. 3. GET https://www.roundhouse.studio/api/v0/unified//recommend?prefer=balanced&live=1&limit=3 — take the candidates with their reasons. Then tell me: the going rate and its basis, the three candidates with price, price_index and 30-day buyers, and which you would call and why. Flag any candidate whose price_index is above 150, and say if `truncated` was true so I know the list was a floor. Do not pay anything yet. ``` ## Next steps - [Vet a counterparty](https://www.roundhouse.studio/docs/guides/vet-a-counterparty) — the checks to run on whoever you picked, before money moves. - [Make your first x402 payment](https://www.roundhouse.studio/docs/guides/first-x402-payment) — actually calling the endpoint. - [API reference](https://www.roundhouse.studio/docs/api) — every parameter on the three endpoints above. --- Every page in these docs is available as markdown at its own URL plus `.md`. Full index: https://www.roundhouse.studio/docs.md