# Connect an app

Any tool that uses the OpenAI or Anthropic API can use the exchange. Change two settings: the base URL and the API key. For each request, the exchange picks the best standing offer for the model that you named. It sets a price cap before the first token and charges for the tokens used.

Each guide gives the steps for one tool, a check, and fixes for common errors.

## Connect in three steps

1. **Issue a key.** Create a `spend` key in your workspace. The format is `sk-liquid-<key-id>-<secret>`. The console shows it one time only. See [API keys](https://inference.ai.exchange/docs/keys.md).
2. **Keep the key out of config files.** Each guide reads it from `LIQUID_API_KEY`.

   ```bash
   export LIQUID_API_KEY=sk-liquid-...
   ```

3. **Set the base URL and pick a guide.** If your tool is not listed, follow the [OpenAI SDK](https://inference.ai.exchange/docs/connect-openai-sdk.md) or [Anthropic SDK](https://inference.ai.exchange/docs/connect-anthropic-sdk.md) guide for its format.

A new workspace has a starting balance, shown on the **Credits** page. If the balance is less than the price cap of a job, the exchange refuses the request.

## Start with the Liquid CLI

The [Liquid CLI](https://inference.ai.exchange/docs/cli.md) starts the coding agent that you already use with the exchange as its provider. It sets the base URL, key and model for that process only, and writes none of your files.

```bash
curl -fsSL https://inference.ai.exchange/cli/install.sh | bash
liquid login
liquid claude
```

`liquid tools` lists every tool. `liquid connect <tool>` prints the setup for a tool that the CLI cannot start, such as an app or an SDK. The guides show the same setup by hand.

## Which guide to use

The full list is under [All guides](#all-guides).

## Test a request

To test a key and a base URL, send one request with `curl`. The exchange accepts the key as a bearer token, or as `x-api-key`.

**curl**

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

**curl (images)**

```bash
curl https://router.inference.ai.exchange/v1/images/generations \
  -H "Authorization: Bearer $LIQUID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "liquid.auto",
    "prompt": "A red bicycle leaning on a brick wall",
    "n": 1
  }'
```

The `x-liquid-cap-usd` response header is the maximum charge for the job. The actual charge is usually less.

## Name a model

Each guide uses `liquid.auto`. The `model` field accepts these names:

| Name           | Example                | Behaviour                                                                                     |
| -------------- | ---------------------- | --------------------------------------------------------------------------------------------- |
| A model        | `gpt-oss-120b`         | Every provider that quotes that model competes.                                               |
| A router model | `liquid.auto`          | Every listed model competes, ranked by price or by Auto.                                      |
| Auto           | `liquid.auto:balanced` | The exchange chooses by published score and estimated charge. See [Auto Router](https://inference.ai.exchange/docs/auto.md).   |
| A basket       | `architect.basket`     | The models in `exchange.candidates.models.allow` compete. See [Purchasing rules](https://inference.ai.exchange/docs/rules.md). |
| A preset       | `fast`                 | Saved models, strategy and limits. See [Purchasing rules](https://inference.ai.exchange/docs/rules.md).                        |

A client that sets only `model` can add a suffix:

- `:smartest`, `:fastest` or `:cheapest` picks how the exchange ranks the offers, as in `deepseek:fastest`.
- `+web` or `:web` searches the web for each message (beta), as in `deepseek:fastest+web`.

A creator name, such as `deepseek`, is valid with a suffix. See [Axis routing](https://inference.ai.exchange/docs/axis-routing.md). The exchange refuses any other name and never uses a different model. `GET /v1/models` lists the names you can use. See [Market data](https://inference.ai.exchange/docs/market.md).

## Read the result

Each response has an `exchange` block with `job_id`, `provider_slug`, `charge.cap_usd` (the maximum cost) and `charge.total_usd` (the actual cost). Two headers arrive before the first token, so a streaming client has them from the start:

| Header             | Meaning                                 |
| ------------------ | --------------------------------------- |
| `x-liquid-job-id`  | The job id. Use it to read the receipt. |
| `x-liquid-cap-usd` | The most this job can be charged.       |

To choose the models, strategy or limits, send an `exchange` block in the body. A client that can send only headers can send the cap and the first-token limit as `x-liquid-*` headers, or name a preset. See [Purchasing rules](https://inference.ai.exchange/docs/rules.md).

## Reference

### Base URL and format

One origin and one key serve both formats. Both formats accept both auth headers.

| Format    | Base URL                                  | Auth header                         |
| --------- | ----------------------------------------- | ----------------------------------- |
| OpenAI    | `https://router.inference.ai.exchange/v1` | `Authorization: Bearer sk-liquid-…` |
| Anthropic | `https://router.inference.ai.exchange`    | `x-api-key: sk-liquid-…`            |

An OpenAI client adds a path such as `/chat/completions`. An Anthropic client adds `/v1/messages`, so a base URL that ends in `/v1` gets a 404.

### All guides

| Tool               | Format    | Configured through          | Guide                                               |
| ------------------ | --------- | --------------------------- | --------------------------------------------------- |
| Claude Code        | Anthropic | Environment                 | [Claude Code](https://inference.ai.exchange/docs/connect-claude-code.md)             |
| Codex              | OpenAI    | Config file                 | [Codex](https://inference.ai.exchange/docs/connect-codex.md)                         |
| GitHub Copilot CLI | OpenAI    | Environment                 | [GitHub Copilot CLI](https://inference.ai.exchange/docs/connect-copilot-cli.md)      |
| DeepSeek Harness   | Anthropic | Environment                 | [DeepSeek Harness](https://inference.ai.exchange/docs/connect-deepseek-harness.md)   |
| Grok Build         | OpenAI    | Config file                 | [Grok Build](https://inference.ai.exchange/docs/connect-grok-build.md)               |
| Pi                 | OpenAI    | Config file                 | [Pi](https://inference.ai.exchange/docs/connect-pi.md)                               |
| Factory Droid      | OpenAI    | Config file                 | [Factory Droid](https://inference.ai.exchange/docs/connect-factory-droid.md)         |
| Oh My Pi           | OpenAI    | Liquid Inference profile    | [Oh My Pi](https://inference.ai.exchange/docs/connect-omp.md)                        |
| Reason             | OpenAI    | In the app                  | [Reason](https://inference.ai.exchange/docs/connect-reason.md)                       |
| Goose              | OpenAI    | Custom provider file        | [Goose](https://inference.ai.exchange/docs/connect-goose.md)                         |
| Crush              | OpenAI    | `crushrc` provider          | [Crush](https://inference.ai.exchange/docs/connect-crush.md)                         |
| Hermes Agent       | OpenAI    | Provider plugin             | [Hermes Agent](https://inference.ai.exchange/docs/connect-hermes-agent.md)           |
| OpenClaw           | OpenAI    | Config file                 | [OpenClaw](https://inference.ai.exchange/docs/connect-openclaw.md)                   |
| OpenCode           | OpenAI    | Config file                 | [OpenCode](https://inference.ai.exchange/docs/connect-opencode.md)                   |
| Paperclip          | OpenAI    | Adapter environment         | [Paperclip](https://inference.ai.exchange/docs/connect-paperclip.md)                 |
| Cursor             | OpenAI    | In the app                  | [Cursor](https://inference.ai.exchange/docs/connect-cursor.md)                       |
| Cline              | OpenAI    | In the app                  | [Cline](https://inference.ai.exchange/docs/connect-cline.md)                         |
| Z Code             | OpenAI    | Provider file or in the app | [Z Code](https://inference.ai.exchange/docs/connect-zcode.md)                        |
| RikkaHub           | OpenAI    | In the app                  | [RikkaHub](https://inference.ai.exchange/docs/connect-rikkahub.md)                   |
| Roo Code           | OpenAI    | In the app                  | [Roo Code](https://inference.ai.exchange/docs/connect-roo-code.md)                   |
| Kilo Code          | OpenAI    | In the app                  | [Kilo Code](https://inference.ai.exchange/docs/connect-kilo-code.md)                 |
| Open WebUI         | OpenAI    | In the app                  | [Open WebUI](https://inference.ai.exchange/docs/connect-open-webui.md)               |
| Cherry Studio      | OpenAI    | In the app                  | [Cherry Studio](https://inference.ai.exchange/docs/connect-cherry-studio.md)         |
| n8n                | OpenAI    | In the app                  | [n8n](https://inference.ai.exchange/docs/connect-n8n.md)                             |
| Dify               | OpenAI    | In the app                  | [Dify](https://inference.ai.exchange/docs/connect-dify.md)                           |
| LobeHub            | OpenAI    | In the app                  | [LobeHub](https://inference.ai.exchange/docs/connect-lobehub.md)                     |
| OpenAI SDK         | OpenAI    | In code                     | [OpenAI SDK](https://inference.ai.exchange/docs/connect-openai-sdk.md)               |
| Anthropic SDK      | Anthropic | In code                     | [Anthropic SDK](https://inference.ai.exchange/docs/connect-anthropic-sdk.md)         |
| Claude Agent SDK   | Anthropic | In code                     | [Claude Agent SDK](https://inference.ai.exchange/docs/connect-claude-agent-sdk.md)   |
| OpenAI Agents SDK  | OpenAI    | In code                     | [OpenAI Agents SDK](https://inference.ai.exchange/docs/connect-openai-agents-sdk.md) |
| Vercel AI SDK      | OpenAI    | In code                     | [Vercel AI SDK](https://inference.ai.exchange/docs/connect-vercel-ai-sdk.md)         |
| LiteLLM            | OpenAI    | In code                     | [LiteLLM](https://inference.ai.exchange/docs/connect-litellm.md)                     |
| LangChain          | OpenAI    | In code                     | [LangChain](https://inference.ai.exchange/docs/connect-langchain.md)                 |
| LlamaIndex         | OpenAI    | In code                     | [LlamaIndex](https://inference.ai.exchange/docs/connect-llamaindex.md)               |
| pgvector           | OpenAI    | In code                     | [pgvector](https://inference.ai.exchange/docs/connect-pgvector.md)                   |
| Qdrant             | OpenAI    | In code                     | [Qdrant](https://inference.ai.exchange/docs/connect-qdrant.md)                       |
| Pinecone           | OpenAI    | In code                     | [Pinecone](https://inference.ai.exchange/docs/connect-pinecone.md)                   |
| RAGFlow            | OpenAI    | In the app                  | [RAGFlow](https://inference.ai.exchange/docs/connect-ragflow.md)                     |
| OpenHands SDK      | OpenAI    | In code                     | [OpenHands SDK](https://inference.ai.exchange/docs/connect-openhands.md#sdk)         |
| OpenHands CLI      | OpenAI    | Config file and environment | [OpenHands CLI](https://inference.ai.exchange/docs/connect-openhands.md#cli)         |

A **Verified** label with a release number, such as "Verified 2.1.287", means the setup passed a test run with that release in the last 14 days. Hold the pointer over it to see the date.