# Axis routing

Add a word to the model name to choose how the exchange ranks the offers. The word is `smartest`, `fastest`, `cheapest`, `premium`, `balanced` or `economy`.

```text
deepseek-v4.1-flash:fastest
deepseek:cheapest
liquid.auto:smartest
```

The name before the colon is the **scope**: the models that compete. The word after it is the **axis**: the ranking. An axis changes only the order. Every offer must still pass your cap, limits and key.

| Axis       | The offer that wins                                                                  |
| ---------- | ------------------------------------------------------------------------------------ |
| `smartest` | The highest published score, whatever the charge.                                    |
| `fastest`  | The highest median output speed that the exchange measured. The charge breaks a tie. |
| `cheapest` | The lowest estimated charge plus the cost of the predicted wait.                     |
| `premium`  | [Auto](https://inference.ai.exchange/docs/auto.md): a doubling of the charge must buy 0.5 points.                     |
| `balanced` | Auto: a doubling of the charge must buy 2 points.                                    |
| `economy`  | Auto: a doubling of the charge must buy 5 points.                                    |

## Send a request

```python
from openai import OpenAI

client = OpenAI(base_url="https://router.inference.ai.exchange/v1", api_key="...")

response = client.chat.completions.create(
    model="liquid.auto:smartest",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={"exchange": {"cap_usd": 0.5}},
)
```

`smartest` and the Auto words pay more for a better score, so they need a price bound, such as the `cap_usd` above. With the CLI, write `liquid claude --model liquid/auto:fastest`.

## Choose the scope

| Name before the colon                                              | Models that compete                                                       |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `architect.basket`, a router model such as `liquid.auto`, a preset | The models that the name has without the axis. The axis sets the ranking. |
| A served model name, such as `deepseek-v4.1-flash`                 | That model, across all of its offers.                                     |
| A creator name, such as `deepseek`                                 | Each model of that creator.                                               |

`smartest` and the Auto words need more than one model, because one model has one score.

## Web search

**Beta.** `:web` can change without notice, including its price and search services.

`web` is not an axis. It turns on a web search for the request and combines with any axis. Join the words with `+`, in any order:

```text
deepseek-v4.1-flash:web
liquid.auto:smartest+web
```

Only an exchange with a search service key has web search. `GET /v1/exchange/features` says whether it does. For a request with `web`, the exchange:

- Searches once, for the last user message, before it ranks the offers. It tries TinyFish first, then Exa once.
- Puts the results in a system message before the last user message, marked as untrusted text. The earlier messages do not change, so a prompt cache still reads them.
- Holds the price of the search with the tokens.
- Adds the price of the search to `fee_usd` and `buyer_charge_usd` when the job settles with a charge. A referral discount does not reduce it.
- Reuses the results, free, when the same workspace repeats the query within five minutes. A tool loop, such as Claude Code or Codex, pays for one search.

| Status | Code                     | When                                                     |
| ------ | ------------------------ | -------------------------------------------------------- |
| 400    | `web_search_needs_text`  | The request has no user message with text to search for. |
| 400    | `web_search_exceeds_cap` | The cap is not more than the price of the search.        |
| 402    | `insufficient_balance`   | The balance cannot pay for the search and an answer.     |
| 503    | `web_search_unavailable` | No search service answered. Nothing is charged.          |

## Reference

### Same request, two forms

```json
{ "model": "deepseek-v4.1-flash:fastest" }
```

```json
{
  "model": "deepseek-v4.1-flash",
  "exchange": { "rank": { "strategy": { "kind": "fastest" } } }
}
```

| Axis       | `exchange.rank.strategy`                  |
| ---------- | ----------------------------------------- |
| `smartest` | `{"kind":"smartest"}`                     |
| `fastest`  | `{"kind":"fastest"}`                      |
| `cheapest` | `{"kind":"price"}`                        |
| `premium`  | `{"kind":"auto","preference":"premium"}`  |
| `balanced` | `{"kind":"auto","preference":"balanced"}` |
| `economy`  | `{"kind":"auto","preference":"economy"}`  |

The word counts as an axis only when the text after the last colon is exactly one of the six words, with a name before it. Otherwise the colon belongs to the model name: `llama3:8b` is one model name.

### How each axis ranks

- **`cheapest`** is the default ranking of a model and a basket. A wait value of zero ranks on charge alone. See [Price and wait](https://inference.ai.exchange/docs/price-and-wait.md).
- **`fastest`** uses the median output speed over the last 7 days, counted after 5 timed jobs. A difference under 1 token per second is a tie, and the charge decides. An offer with no counted speed ranks last. See [How the exchange measures performance](https://inference.ai.exchange/docs/performance-measurement.md).
- **`premium`, `balanced`, `economy`** and **`smartest`** rank by [Auto Router](https://inference.ai.exchange/docs/auto.md). `smartest` is mode version 4 and uses the general score when no offer has a coding score.

### Refusals

| Status and code                       | Cause                                                                                                                                                                                        |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 smartest_needs_several_models`   | `smartest` with one model. Use a creator, a router model, a basket or a preset.                                                                                                              |
| `400 strategy_conflicts_with_address` | `premium`, `balanced` or `economy` with one model.                                                                                                                                           |
| `400 auto_requires_price_bound`       | `smartest` or an Auto word with no cap, no cost tier other than `any` and no output-rate ceiling. A router model with a cap of its own does not need one.                                    |
| `400 axis_conflict`                   | Another ranking in the same request: another `exchange.rank.strategy` kind, another Auto version, the `x-liquid-policy` header, or `exchange.candidates.creators.allow` with a creator name. |
| `400 ambiguous_scope`                 | A name that is both a served model and a creator. Send `architect.basket` with a pattern in `exchange.candidates.models.allow`, such as `deepseek-*`.                                        |

See [Errors](https://inference.ai.exchange/docs/errors.md) for every code.