# What is Cairva

> Cairva is a private market for AI inference. Buyers negotiate capacity with authorized suppliers and call the agreement through an OpenAI-compatible API.

Source: https://cairva.xyz/docs

You describe the inference capacity you need, verified suppliers quote you privately, and the version you accept becomes an **allocation**: a fixed token allowance, delivery window and set of rate limits that your code calls through an OpenAI-compatible API.

You don't buy credits from a price list. You negotiate an agreement for one model, a token allowance, a window and limits, and the gateway enforces exactly those terms on every request.

> [!NOTE]
> Cairva is in its Genesis phase. The only route open today is a **sandbox** route serving the open-weight model `gemma4:e2b` through Ollama on Cairva's development infrastructure. The full deal flow runs on it, but no money moves and no live commercial supply is listed yet. See [Sandbox](https://cairva.xyz/docs/sandbox).

## What you can do here

- **Buy capacity.** Send a [private request](https://cairva.xyz/docs/requests-and-quotes) to the verified suppliers you choose, [negotiate](https://cairva.xyz/docs/negotiation) versioned terms, and accept one exact version.
- **Run it.** Create an [API key](https://cairva.xyz/docs/api-keys) for the allocation, point an OpenAI SDK at Cairva, and call [chat completions](https://cairva.xyz/docs/chat-completions).
- **Track it.** Read the [current allocation](https://cairva.xyz/docs/allocation-status) and per-request [usage events](https://cairva.xyz/docs/usage), the same numbers the supplier sees.
- **Supply it.** [Become a supplier](https://cairva.xyz/docs/become-a-supplier), list [inventory lots](https://cairva.xyz/docs/inventory) on a route Cairva can reach, and quote buyers from them.

## The API in one minute

The gateway lives under one base URL and speaks the OpenAI chat completions format. A key is bound to one allocation, so it can only call that allocation's model and spend that allocation's allowance.

| Method | Path | Scope | What it does |
| --- | --- | --- | --- |
| `POST` | `/v1/chat/completions` | `inference` | Runs a chat completion, streamed or not, and meters it |
| `GET` | `/v1/models` | `inference` | Lists the one model your key can call |
| `GET` | `/v1/allocations/current` | `usage:read` | Quota, usage, holds, remaining allowance and limits |
| `GET` | `/v1/usage` | `usage:read` | Metered usage events, newest first |

```bash
curl https://cairva.xyz/v1/chat/completions \
  -H "Authorization: Bearer $CAIRVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemma4:e2b", "max_tokens": 200,
       "messages": [{"role": "user", "content": "Say hello in five words."}]}'
```

Every response carries a `cairva` object with the request id, the allocation id and the allowance left after the request. Read [Chat completions](https://cairva.xyz/docs/chat-completions) for the full shape.

## Where to go next

- New here: follow the [Quickstart](https://cairva.xyz/docs/quickstart).
- Want the model of the market first: read [How Cairva works](https://cairva.xyz/docs/how-cairva-works).
- Migrating OpenAI code: check [OpenAI compatibility](https://cairva.xyz/docs/compatibility) before you switch the base URL.