Market routing for buyers

Native routes are served by the cheapest healthy market offer, with the in-house catalog as fallback. Nothing about your request changes; the response tells you what served it.

Which routes use the market

Only native routes are market-eligible. Catalog tool execution (POST /v1/tools/…/execute) always uses in-house supply.

Route	Served by offers for	Fallback
`POST /v1/rpc/solana`	Helius, Quicknode plans	In-house Quicknode route
`POST /v1/chat/completions`	OpenAI, OpenRouter plans	In-house Locus route
`POST /v1/messages`	Anthropic plans	In-house Locus route
`ANY /v1/market/{provider}/{path…}`	Allow-listed REST paths (Birdeye, Helius REST)	No fallback unless a catalog tool is mapped

The live list of providers with offers is on /market and from GET /v1/market (no auth).

Routing policy

Set per workspace on Settings → Routing (GET/PATCH /dashboard/routing) or per key via routing in PATCH /dashboard/keys/{id}.

mode	Behaviour
`market_first` (default)	Try the cheapest healthy market offer. If no offer can serve the request, fall back to the in-house catalog route.
`market_only`	Only use market offers. When none can serve the request it fails with tool_unavailable (details.routing = market_only) instead of using in-house supply. Nothing is charged.
`in_house_only`	Never use market offers. Every request goes to the in-house catalog route at catalog pricing.

json

PATCH /dashboard/routing
{ "mode": "market_first", "max_unit_price_usd": "0.000005", "exclude_offers": [] }

max_unit_price_usd skips offers whose buyer price per unit (fee included) is above it. exclude_offers skips specific offer ids you saw in X-Local-Offer.

How an offer is chosen

Candidates: active offers for the provider (and route or model scope) with health ok, remaining capacity ≥ estimated units, and a seller that is not you.
Lowest buyer price wins; ties go to the oldest offer.
The gateway reserves estimated units × price + fee (bounded by your per-request ceiling), dispatches through the seller proxy, meters the actual units, settles, and releases the unused remainder.
Pre-execution upstream rejections (401/403/429/402) fail over to the next offer or the fallback inside the same reservation. Timeouts and 5xx never fail over; they become reconciling like any other uncertain outcome. Non-idempotent writes such as sendTransaction are never retried.

Response headers

Header	Meaning
`X-Local-Route`	`market` when an offer served the request, `fallback` when the in-house route did.
`X-Local-Offer`	Opaque id of the serving offer (market only). It never identifies the seller.
`X-Local-Units`	Units metered for the request (credits, compute units, tokens).
`X-Local-Charged-Usd`, `X-Local-Billing-State`, `X-Local-Request-Id`	The usual receipt headers.

The same values appear on each request’s receipt in Usage (Route column) and in the playground receipt tab.

Fees

A market request costs units × the offer’s price per unit plus a 5% platform fee on the fill, itemised separately. The seller receives exactly their ask. Fallback requests are priced like any catalog request: supplier cost plus the platform markup, shown as a price or ceiling before you run. See Pricing for a worked example.

Discounts are computed, not promised

Each provider shows a dated reference list price with its source. “x% below list” is arithmetic against that reference at the time you look; it is not a guarantee about what you would otherwise pay.

Examples

A Solana RPC call (Helius or Quicknode offers, Quicknode direct as fallback):

bash

curl https://api.uselocal.sh/v1/rpc/solana \
  -H "Authorization: Bearer $LOCAL_API_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot","params":[]}'

An OpenAI-compatible chat completion (OpenAI or OpenRouter offers, Locus as fallback):

bash

curl https://api.uselocal.sh/v1/chat/completions \
  -H "Authorization: Bearer $LOCAL_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model":"gpt-5-mini","messages":[{"role":"user","content":"Say hi"}]}'

REST passthrough for allow-listed paths (no fallback unless a catalog tool is mapped):

bash

curl "https://api.uselocal.sh/v1/market/birdeye/{path}" \
  -H "Authorization: Bearer $LOCAL_API_KEY"

Market-specific errors

tool_unavailable with details.routing = "market_only" — the policy is market_only and no healthy offer can serve the request. Not charged.
ceiling_too_low — the estimated units × price + fee exceeds your per-request ceiling. Raise the ceiling or lower max_unit_price_usd.

Units

Credit / compute-unit providers (Helius, Quicknode, Birdeye): one unit is one provider credit or CU, weighted per method or path (for example Helius DAS and getProgramAccounts count 10 credits).
Token providers (OpenAI, Anthropic, OpenRouter): one unit is one micro-USD (0.000001) of the model’s list price, so a seller discount applies uniformly to whichever model is called and prices are comparable across models. A chat model is only market-routed when the provider has a dated reference price for it.

Prices on /market and in GET /v1/market* are buyer prices per unit with the platform fee included; discount tiers measure the seller’s ask against the dated reference price.

Public market data

text

GET /v1/market                      → { providers: [{ slug, name, unit, unit_label, reference_unit_price_usd, reference_source,
                                        reference_captured_at, best_price_per_unit_usd, best_discount_bps, available_units,
                                        available_usd, active_offers, fills_24h, units_24h, serves[] }], computed_at }
GET /v1/market/{provider}           → { provider, book: [{ discount_bps, price_per_unit_usd, available_units, available_usd, offers }],
                                        reference: { prices, source_url, captured_at }, recent_fills[], fallback: { available, label } }
GET /v1/market/{provider}/prices    → dated reference prices per item/model