Field manual

Docs

Cosmo speaks the OpenAI chat wire format. If your client already talks to an OpenAI-compatible API, you are a base URL and a key away from every world in the catalog.

The cosmos in one minute

Every model is a planet. Browse them on the galaxy map, where each world links to its own page with live facts and a prompt console, or race two of them in orbit view. When a route earns your trust, ship it through the API below.

Quickstart

Mint a key in the dashboard (one wallet signature, no deposit), pick a model id from the catalog, and call completions:

curl http://localhost:3000/v1/models

curl http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Model ids are namespaced as vendor/model and come from the live catalog at GET /v1/models, which also carries each model's price card (USD per million tokens) and context length. The response includes an x-cosmo-upstream header naming the provider that served the request.

Streaming

Set "stream": true for server-sent events in the OpenAI chunk format, ending with data: [DONE]. The final chunk carries a usage object with token counts, whichever provider served the request.

curl -N http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-haiku-4-5",
    "stream": true,
    "messages": [{"role": "user", "content": "Count to five"}]
  }'

Wallet sign-in

Sign-in is three steps against this origin, usable from any wallet that can personal_sign:

1. GET  /api/auth/nonce?address=0xYourAddress
   -> { "nonce": "...", "message": "..." }

2. personal_sign the exact message text with your wallet

3. POST /api/auth/verify
   { "address": "0x...", "nonce": "...", "signature": "0x..." }
   -> a session cookie; manage keys at /api/keys

The signature proves control of the wallet. It authorizes no transaction and costs nothing. Keys are stored as hashes and shown once at mint; revoke any key at any time and it stops working immediately.

Errors and limits

Errors are OpenAI-shaped: {"error": {"message", "type"}}. Rate limits return 429 with a retry-after header. Keyed API traffic is limited per key; the anonymous compare and planet consoles are limited per IP address and cap responses at 1024 output tokens. Requests above the deployment's output-token cap are clamped, not refused.

What works today

A live catalog, the galaxy map, side by side comparison, wallet sign-in, revocable API keys, an OpenAI-compatible streaming endpoint, and per-request metering. Routing is explicit: you pick the planet.

What is not built yet

Honest list, kept current. There are no balances and no billing yet: keys are free to mint and usage is metered and shown, not charged. Routing is explicit today: you pick the planet, and requests go to the provider serving it (native adapters first, aggregator otherwise). Measured automatic routing is planned but not shipped, so we do not sell it.

Cosmo