Model Routing
A routing service is a seller service that ranks where a buyer should send a request. It does not run the inference. The buyer sends the inference to the chosen seller and pays that seller normally.
Routing is a service category, not one API. Each routing API is its own service API protocol with its own provider plugin, and no protocol or router is a default: buyers choose a router like any other service.
| Protocol | API | Provider plugins |
|---|---|---|
irp-suggest | Inference Routing Protocol (IRP) suggest-only mode | irp-router (any IRP router), free-model-router |
Router settings are sent in the terms of the router's protocol. GET /v1/models?type=router lists each router's protocol and the options it accepts. The rest of this page describes irp-suggest, which uses IRP without Antseed-specific headers or fields. Seller identity stays with the buyer.
A router plugin is local buyer policy. A routing service is a paid service offered by another peer on the network. Buyers use the built-in ModelRoutingClient in @antseed/router-core, which picks an adapter by the router's protocol; no router plugin is required.
Endpoints
| Endpoint | Cost | Purpose |
|---|---|---|
GET /v1/routing/models | Free; the router limits its own list | Models the router can score |
POST /v1/routing/rank | One completed request | Ranks the buyer's allowed candidates for one user turn |
A seller advertises an IRP routing service with the irp-suggest API protocol. IRP paths name no service, so a seller offers at most one irp-suggest service. Buyers ignore peers that advertise more than one.
Models
{
"object": "list",
"data": [
{ "id": "gpt-5.5", "object": "model" },
{ "id": "claude-sonnet-4-6", "object": "model" }
]
}
Buyers cache the list for 60 seconds and only send candidates whose model the router lists. A seller service matches a listed model exactly, or otherwise by canonical model key, so claude-opus-5 can match anthropic/claude-opus-5.
A router that scores any model it is sent lists the wildcard { "id": "*", "object": "model" }. Buyers then send every allowed candidate under its seller's service ID; names that match a model the router also lists keep the router's spelling.
Any entry can carry max_pricing (USD per 1M tokens: input, cache_read, output). Buyers skip candidates priced above it, so a router that only ranks free models lists { "id": "*", "object": "model", "max_pricing": { "input": 0, "cache_read": 0, "output": 0 } }.
Rank request
{
"request": {
"messages": [
{ "role": "system", "content": "You are a coding agent." },
{ "role": "user", "content": "Refactor this function" }
],
"max_tokens": 4096
},
"routing": {
"cost_quality_tradeoff": 3,
"candidates": [
{
"id": "openai:gpt-5.5@aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"model": "gpt-5.5",
"pricing": { "input": 1.25, "cache_read": 0.125, "output": 10 },
"expected_usage": { "cache_read_tokens": 900 }
}
]
}
}
requestis the request as an OpenAI Chat Completions body. Anthropic Messages and OpenAI Responses requests are converted first.model,stream, andstream_optionsare omitted.cost_quality_tradeoffis an integer from0(best quality) to10(cheapest acceptable candidate). If it is omitted, the router uses IRP's default,5.candidatescontains only destinations allowed by the buyer's trust, price, pin, and model filters. The same model from two sellers is two candidates.idisprovider:model@peer, or asha256:hash when that would exceed 128 characters.modeluses the router's model name. The buyer still sends the seller's own service ID with the inference request.pricingis in USD per 1M tokens.expected_usage.cache_read_tokensis present when the buyer has observed cache reads for that destination earlier in the conversation.
Rank response
{
"id": "rank_01J9",
"object": "routing.ranking",
"created": 1790000000,
"router": { "id": "alpha", "version": "2026-10-01" },
"ranked": [
{ "candidate_id": "openai:gpt-5.5@aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "expected_cost_usd": 0.0041 }
]
}
The buyer maps candidate_id values back to the candidates it sent and never parses them. Unknown and duplicate IDs are dropped. If none remain, the ranking is rejected and not charged.
Billing
A well-formed ranking is one completed_requests unit, regardless of how many candidates it ranks. Errors and malformed rankings are zero units, so the buyer and seller both treat them as free. Routing uses the normal payment-channel flow; see Payments.
Errors
Routers use IRP problem details (application/problem+json).
| Status | Type | Buyer action |
|---|---|---|
| 400 | urn:irp:problem:invalid-request | Fail the turn |
| 402 | urn:irp:problem:payment-required | Run normal payment negotiation |
| 422 | urn:irp:problem:no-scorable-candidate | Refresh models and retry once |
| 503 | urn:irp:problem:unavailable | Fail the turn; Retry-After may be set |
Buyer flow
A buyer uses a routing service by sending "model": "<routerPeerId>@<routerServiceId>" to its local /v1 API. See Use a routing service.
- Fetch the routing service's model list.
- Build candidates from eligible sellers whose models the router lists.
- Pay for one ranking and send the inference to the first candidate.
- On retryable inference errors, try later ranked candidates without buying another ranking.
Tool-loop continuations of the same user turn reuse the ranking. Routing charges count toward the conversation's spend.
The routing service receives the full conversation needed to rank the turn. Select only routers you trust with that content.