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#

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#

curl https://www.roundhouse.studio/api/v0/unified/web-search

{
  "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#

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:

{
  "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:

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#

I need to call a paid service that does <job>. 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/<slug> — 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/<slug>/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 — the checks to run on whoever you picked, before money moves.
• Make your first x402 payment — actually calling the endpoint.
• API reference — every parameter on the three endpoints above.