# Quickstart

Send an ordinary OpenAI or Anthropic request to the exchange. Providers compete to answer it. You pay for the
tokens that the job used, and never more than a price cap that the exchange fixes before the first token.

This page is for buyers. To sell inference, start with [Become a provider](https://inference.ai.exchange/docs/provider.md).

To make your first request, follow steps 1 and 2. They need a key and one `curl` command.

## 1. Get a key

1. Sign up. Sign-up creates a workspace. A workspace holds your balance, your API keys and your receipts.
2. Open the **API keys** page and choose **Create key**.
3. Copy the key. The page shows it one time only.

A new workspace gets a starting credit, so you can send your first requests without a card. Your first top-up of $10 or more adds $2 of free credit. The **Credits** page shows your balance.

A key looks like `sk-liquid-<key-id>-<secret>`. See [API keys](https://inference.ai.exchange/docs/keys.md) for scopes and spending limits.

## 2. Send a request

```bash
curl https://router.inference.ai.exchange/v1/chat/completions \
  -H "Authorization: Bearer $LIQUID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-oss-120b",
    "messages": [{"role": "user", "content": "Say hello."}]
  }'
```

The response is a normal chat completion with one more field, `exchange`. It tells you what the job cost.

## 3. Read what you paid

Each provider posts standing offers: a price for each model. The exchange picks the best offer for your request,
holds the price cap from your balance, and charges the tokens that the job used. It returns the rest of the cap to
your balance.

| Where                                   | What it shows                                                  |
| --------------------------------------- | -------------------------------------------------------------- |
| `x-liquid-cap-usd` response header      | The price cap. The exchange sends it before the output starts. |
| `x-liquid-job-id` response header       | The job id.                                                    |
| `exchange.charge.total_usd` in the body | The charge. It is never more than the cap.                     |
| `exchange.provider_slug` in the body    | The provider that served the job.                              |

A receipt records each settled job. It does not change after settlement. The **Overview** and **Credits** pages list your receipts.

To read a receipt in code, use a key with the `read` scope or higher:

```bash
curl https://router.inference.ai.exchange/v1/exchange/jobs/<job_id> \
  -H "Authorization: Bearer $LIQUID_API_KEY"
```

The exchange writes the receipt just after it answers. A call at once can return `404`. Try again after a moment.

To set your own price cap, add `"exchange": {"cap_usd": 0.05}` to the request body. To choose models, regions or a ranking, see [Purchasing rules](https://inference.ai.exchange/docs/rules.md).

## 4. Point your tool at the exchange

A tool needs a base URL and your key. The two formats use different base URLs, because each client adds its own
path.

The [Connection guides](https://inference.ai.exchange/docs/connect-overview.md) give the steps for Claude Code, Codex, Cursor, Cline, the official
SDKs and many other tools. If your code now sends requests to another product, use its guide:
[OpenRouter](https://inference.ai.exchange/docs/move-from-openrouter.md), [LiteLLM](https://inference.ai.exchange/docs/move-from-litellm.md), [the OpenAI API](https://inference.ai.exchange/docs/move-from-openai.md),
[the Anthropic API](https://inference.ai.exchange/docs/move-from-anthropic.md) or [Portkey](https://inference.ai.exchange/docs/move-from-portkey.md). To start a coding agent from
the terminal, use the [Liquid CLI](https://inference.ai.exchange/docs/cli.md).

## Next steps

- [API keys](https://inference.ai.exchange/docs/keys.md): scopes, spending limits and expiry.
- [Purchasing rules](https://inference.ai.exchange/docs/rules.md): choose the models, the ranking and the limits for each request.
- [Market data](https://inference.ai.exchange/docs/market.md): read the book, the list of current offers, before you send a request.
- [Modalities](https://inference.ai.exchange/docs/modalities.md): send an image, an audio clip or a document.
- [Errors](https://inference.ai.exchange/docs/errors.md): the error format and the error codes.

## Reference

### Endpoints

| Method | Path                        | Description                                                                                                             |
| ------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `POST` | `/v1/chat/completions`      | OpenAI Chat Completions.                                                                                                |
| `POST` | `/v1/responses`             | OpenAI Responses, without stored state. See [OpenAI SDK](https://inference.ai.exchange/docs/connect-openai-sdk.md).                                      |
| `POST` | `/v1/messages`              | Anthropic Messages.                                                                                                     |
| `POST` | `/v1/messages/count_tokens` | Anthropic token count estimate.                                                                                         |
| `GET`  | `/v1/models`                | The models that have offers now. The format is OpenAI, or Anthropic when the request has an `anthropic-version` header. |
| `GET`  | `/v1/anthropic/models`      | The same list, always in the Anthropic format.                                                                          |
| `GET`  | `/v1/codex/models`          | The models that Codex can use. See [Codex](https://inference.ai.exchange/docs/connect-codex.md).                                                         |

The exchange also serves images, speech, video and embeddings. See [Modalities](https://inference.ai.exchange/docs/modalities.md) and
[Embeddings](https://inference.ai.exchange/docs/embeddings.md). The [API reference](https://inference.ai.exchange/docs/api.md) lists every endpoint.

### Choose a model

The `model` field accepts these kinds of name:

| Name           | Example            | What competes                                                                                                             |
| -------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| A model        | `gpt-oss-120b`     | Each provider that has an offer for that model.                                                                           |
| A router model | `liquid.auto`      | Each model that the router model covers. See [Auto Router](https://inference.ai.exchange/docs/auto.md).                                                    |
| A basket       | `architect.basket` | The models in `exchange.candidates.models.allow`, ranked by `exchange.rank.strategy`. See [Purchasing rules](https://inference.ai.exchange/docs/rules.md). |
| A preset       | `fast`             | The saved models, strategy and limits that the name refers to. See [Purchasing rules](https://inference.ai.exchange/docs/rules.md).                        |

To rank the offers, add `:smartest`, `:fastest` or `:cheapest` to the name, for example `liquid.auto:cheapest`.
See [Axis routing](https://inference.ai.exchange/docs/axis-routing.md). To let the exchange choose the model by score and estimated charge, send
`liquid.auto:balanced`. See [Auto Router](https://inference.ai.exchange/docs/auto.md).

The exchange refuses any other name with `404 model_not_found`. It never uses a different model in its place. The
message shows the name that you sent and suggests other names.

`GET /v1/models` returns each name that you can use now. The list includes your presets when the request has a key
of the workspace that saved them. Each entry lists the request parameters that at least one offer supports. If a
parameter is not in the list, the exchange refuses a request that includes it. It does not ignore the parameter.

### Streaming

Set `stream: true` to receive `text/event-stream`. The last chunk has the `exchange` block with the settled
charge. In the OpenAI format, set `stream_options: {"include_usage": true}` to receive token usage. The
[OpenAI SDK](https://inference.ai.exchange/docs/connect-openai-sdk.md) guide shows how to read the cap header from a stream.

### Web access

**Beta.** `:web` is a beta feature. Its price, its search services and its behavior can change without notice.

A model knows only its training data, up to the cutoff date that its creator publishes. A question about recent
events can get an old or wrong answer.

To give a model current information, add `:web` to the model name, for example `deepseek-v4.1-flash:web` or
`liquid.auto:smartest+web`. The exchange searches the web for the last user message before it ranks the offers. It
puts the results in the prompt, before that message. See [Axis routing](https://inference.ai.exchange/docs/axis-routing.md#web-search).

The search costs a fixed fee and the cost of the search service. The fee is part of the `fee_usd` of the receipt. The
receipt also has a `web_search` object with the service, the number of results and the charge. The search is paid
from your cap. A job that fails pays nothing for it.

The exchange sends the text of your last message to a search service, TinyFish first and Exa if TinyFish fails. Do not
use `:web` for text that must not leave the exchange.

Without `:web`, the exchange runs no search. It removes the hosted `web_search` tool of the Responses API from the
request and sends the header `x-liquid-notice: web_search_dropped`. It refuses the hosted web search tool of the
Messages API.

### OpenAPI document

An OpenAPI 3.1 document describes the public API. The exchange serves it without authentication:

```
https://router.inference.ai.exchange/v1/openapi.json
```

You can load it into a client generator, Postman, Insomnia or Bruno. The [API reference](https://inference.ai.exchange/docs/api.md) page shows it.