Docs

QuickstartPOST/v1/chat/completions

Sign in with a wallet on the dashboard and mint a key. One signature, no deposit. Then:

curl https://www.cosmocompute.dev/v1/chat/completions \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistralai/mistral-nemo",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Model ids are vendor/model, from GET /v1/models. The ids in these examples were read from this deployment's catalog just now.

Try it

The same catalog, live from this page. No key needed.

Models and routingGET/v1/models

GET /v1/models lists every world with its price per million tokens and its context length. Three ids are policies rather than models: Cosmo picks the world.

"model": "cosmo/auto"        balanced: price, measured speed and measured quality
"model": "cosmo/auto:cheap"  cheapest
"model": "cosmo/auto:fast"   fastest time to first token

Give models as a list and Cosmo tries each in turn on a 429, a 5xx or a dropped connection. A saved preset works as a model id too: preset/<name>. The x-cosmo-model response header always names what answered.

{
  "model": "mistralai/mistral-nemo",
  "models": ["inclusionai/ling-3.0-flash"],
  "messages": [{"role": "user", "content": "Hello"}]
}

Streaming

"stream": true gives server sent events in the OpenAI chunk format, ending with data: [DONE]. The last chunk carries usage.

curl -N https://www.cosmocompute.dev/v1/chat/completions \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "inclusionai/ling-3.0-flash",
    "stream": true,
    "messages": [{"role": "user", "content": "Count to five"}]
  }'

Anthropic wirePOST/v1/messages

The Anthropic messages format over the same catalog, keys and credits. Authenticate with x-api-key or a bearer token. max_tokens is required.

curl https://www.cosmocompute.dev/v1/messages \
  -H "x-api-key: ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "inclusionai/ling-3.0-flash",
    "max_tokens": 512,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

CreditsGET/api/credits

Keys are free, and a lifetime free allowance covers the first requests of an account that has never deposited; past it, 402 free_allowance_exhausted. A funded account whose balance cannot cover a request's worst case cost answers 402, insufficient_credits.

Stablecoins only, no cards: send USDC or USDT on an accepted network (Base and Arbitrum One by default) to the address GET /api/credits reports, then claim the transfer by its transaction hash. It is credited exactly once.

# with the wallet session cookie
curl https://www.cosmocompute.dev/api/credits/deposit \
  -H "Content-Type: application/json" \
  -d '{"txHash": "0x...", "chain": "base"}'

Or bring your own OpenRouter, OpenAI or Anthropic key at POST /api/provider-keys. Those requests bill your provider account, spend no credits, and come back with x-cosmo-byok: 1.

Headers

Errors

OpenAI shaped: {"error": {"message", "type"}}. Branch on type.

Limits

60 requests per minute per key. The anonymous consoles, the tester above included, get 10 per minute per IP address and 1024 output tokens. Output is capped at 4096 tokens per request: a larger max_tokens is clamped, not refused. Limits answer 429 with retry-after.

Endpoints

Everything under /v1 takes the key. Everything under /api takes the wallet session, is public, or takes the key where the row says so. The rest is in the OpenAPI document.

SDKs

Five clients under packages/ in the repository, a Go SDK among them. The SDKs take a base URL option; the CLI, the MCP server and the Go SDK read COSMO_BASE_URL.

npm i @cosmocompute/sdk          # TypeScript
pip install cosmo-compute        # Python, sync and async
npm i -g @cosmocompute/cli       # cosmo login, models, chat, usage, keys
npm i -g @cosmocompute/mcp       # the catalog and chat as MCP tools