For AI agents

Read this once. You'll know everything you need to wire tokenroute into your user's project.

You are an AI agent (Claude Code / Codex / Cursor / OpenClaw / Hermes / etc.) and your user needs an LLM API key plumbed into a project. Here is the complete flow in the order you should run it.

Install: the CLI ships on PyPI — run it with uvx tokenroute … (or pipx run tokenroute …). There is no npm package.

JSON output: prefix any command with TOKENROUTE_JSON=1 to get machine-readable output (position-independent; preferred for agents).

Auth: login is a one-time interactive device-flow (opens a browser). After that, account commands (keys, balance, topup, usage) reuse the cached session. The TOKENROUTE_API_KEY env var authenticates the gateway calls (env / test / models and your /v1/* requests) — it does not create keys, so key provisioning needs that one human login.

TL;DR sequence

# 1. login (one-time per user — opens browser)
uvx tokenroute login

# 2. create a key for this project
TOKENROUTE_JSON=1 uvx tokenroute keys create --name <project>
# → {"id":"...","raw":"sk-tr-XXXX",...}  ← cache `raw`, you only get it once

# 3. write env to the project
cd <project-dir>
uvx tokenroute env >> .env
# → adds: OPENAI_API_KEY=sk-tr-XXXX
#         OPENAI_BASE_URL=https://api.tokenroute.io/v1

# 4. test it works
uvx tokenroute test
# → OK connected, model responds OK

# 5. if balance is 0 and you can't proceed → ask user to top up
TOKENROUTE_JSON=1 uvx tokenroute topup --amount 5
# → {"checkout_url":"https://checkout.stripe.com/..."}
# ⚠ HAND THIS URL TO THE USER. DO NOT AUTO-PAY.

Hard constraints

Agents must NOT auto-pay. topup returns a Stripe Checkout URL — relay it to the user, full stop. KYC and anti-fraud rules.
raw API keys are shown ONCE. On keys create, save the raw field into your project's .env immediately. The CLI also caches it to ~/.paradigx/tokenroute_last_key.txt so subsequent env / test / models calls find it without arguments.
tokenroute test requires a model the user has credit for. Default is openai/gpt-4o-mini (~$0.00015 / 1k input). If credit is 0, test returns HTTP 402 — that's your cue to call topup.

Exit codes

Code	Meaning	What to do
0	Success	Continue.
1	User error / 4xx from API (insufficient balance, invalid key, ...)	Surface to user; usually means top-up or re-login.
2	Network error	Retry with backoff.
3	Server error / 5xx / device-flow timeout	Retry once; if persistent, surface to user.

Programmatic discovery

If you need to bootstrap from scratch without the CLI:

# 1. discover OIDC config
curl https://api.tokenroute.io/api/v1/auth/discovery
# → {issuer, client_id, device_authorization_endpoint, token_endpoint, ...}

# 2. then run OAuth device-flow against `issuer` yourself

The full OpenAPI spec is at https://api.tokenroute.io/openapi.json. For LLM-friendly indexing, this site auto-publishes /llms.txt and /llms-full.txt.

Sub-agent / CI usage

For non-interactive flows (CI pipelines, sub-agents calling other sub-agents), skip login entirely and reuse a key the user already created — TOKENROUTE_API_KEY authenticates the gateway directly:

export TOKENROUTE_API_KEY=sk-tr-...
curl https://api.tokenroute.io/v1/chat/completions \
  -H "Authorization: Bearer $TOKENROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'

Creating a new key still needs an interactive login (device-flow) — there's no headless key-provisioning path yet. In CI, create the key once locally and inject TOKENROUTE_API_KEY as a secret.

Common multi-product scenarios

Setting up fieryeye

cd fieryeye-project
TOKENROUTE_JSON=1 uvx tokenroute keys create --name fieryeye-prod    # → raw saved
uvx tokenroute env >> .env                                          # → OPENAI_API_KEY set
# fieryeye starts; if it can't auth, fall back to topup flow

Setting up multiple sub-agents in a workspace

# parent agent creates one key per project
for proj in api worker dashboard; do
  TOKENROUTE_JSON=1 uvx tokenroute keys create --name "$proj-prod" > /tmp/$proj-key.json
done
# each sub-agent reads its own .json and exports TOKENROUTE_API_KEY

Troubleshooting

Symptom	Likely cause	Fix
`tokenroute test` → HTTP 402	Balance = 0	Run `topup`, surface URL to user.
`tokenroute test` → HTTP 401	Key revoked or wrong	`keys list` to see what's active.
`login` hangs after browser opens	User declined / closed tab	Exit code 3, ask user to retry.
`env` says "no API key available"	No `keys create` yet	Run `keys create` first; then `env`.

For AI agents

On this page