llms.txt
+45 −13
− > Drop-in BYOK gateway that cuts OpenAI, Anthropic and Gemini API bills. Change one line (base_url) and keep your own API key; TokenZero formats prompts for provider caching, serves deterministic repeats from an edge cache, optionally routes simple requests to cheaper models, and signs a savings receipt for every request. Free up to $500/month routed spend, then 15% of verified savings.− ## Tools, comparisons, guides, reports (every page also as Markdown: append .md or send Accept: text/markdown)− - Other gateways and routers (30 pages): https://tokenzero.sh/compare (…/<product>-alternative, …/tokenzero-vs-<product>)− - Model lifecycle: 17 ids with provider-announced retirement dates (OpenAI and Anthropic deprecation pages); audits flag them, the gateway warns in X-TokenZero-Warning, /models/<id> shows the date and replacement.− - Plans (self-serve, POST /v1/workspaces/me/plan {plan, billing}): free ($0, up to $500/mo routed spend) | performance (15% of verified savings, 3x-ROI-or-$0 guarantee) | pro_cap (15% capped at $199/mo, $1,790/yr prepaid) | scale_cap (15% capped at $999/mo, $8,990/yr prepaid). Annual prepay takes 25% off the rate and the cap. Nothing is billed until billing goes live; GET /v1/usage shows the fee preview under the workspace's plan.− - X-TokenZero-Semantic-Cache: true (near-duplicate matching, opt-in)− - X-TokenZero-Prompt-Cache-TTL: auto (or workspace setting prompt_cache_ttl_mode / cacheTtl: auto): OpenAI Responses on GPT-5.6+ pick the 12h lifetime per static prefix only when its observed revival rate (reuses after a gap over 30 min, inside 12h) clears 2 per 12-hour window over a rolling 48h (break-even 1.087); otherwise 30m, and it drops back on its own. Advise mode reports the decision and the predicted saving in X-TokenZero-Cache-Format; apply mode sets prompt_cache_options.ttl. Receipt e− - X-TokenZero-Reasoning-Stepdown: off | advise | auto (default advise; workspace setting reasoning_stepdown): on multi-turn GPT-6 Responses requests the classifier scores simple, the gateway lowers reasoning effort by appending {"type":"configuration_update","reasoning":{"effort":"low"}} to input and leaves reasoning.effort untouched, so the cached prefix survives (per the OpenAI prompt-caching guide). Never stacked on a caller-sent configuration_update; a model that rejects the item is retried − X-TokenZero-Request-Id, X-TokenZero-Workspace, X-TokenZero-Plan, X-TokenZero-Free-Tier-Used-USD, X-TokenZero-Free-Tier-Limit-USD, X-TokenZero-Notice, X-TokenZero-Baseline-Cost-USD, X-TokenZero-Actual-Cost-USD, X-TokenZero-Savings-USD, X-TokenZero-Savings-Pct, X-TokenZero-Engines, X-TokenZero-Cache (hit-exact | hit-semantic | miss | bypass;reason=…), X-TokenZero-Cascade-Recommendation, X-TokenZero-Receipt-URL, X-TokenZero-Receipt-Signature (Ed25519, key at /.well-known/tokenzero.json).− - GET /v1/pricing — the versioned list-price table (2026-10-26)− - GET/POST https://tokenzero.sh/v1/doctor (optional X-TokenZero-Key / Authorization: Bearer / {key}): six checks (gateway, signer with a sample receipt + signature, pricing, workspace key, quota and billing, settings and ZDR) plus copy-paste base URLs. CLI: npx -y @tokenzero/cli doctor.− - GET /v1/workspaces/me/metrics?window=24h|7d|30d|all (X-TokenZero-Key; alias /v1/workspaces/metrics; ?demo=1 returns a labelled sample without a key): the value scorecard — cost_and_roi per window, by_engine (prompt cache + CAPC, edge cache, cascade + reasoning, signed ledger), speed_and_latency, quality_and_safety, reliability_and_privacy, by_provider, by_model, daily_series, actionable_recommendations with setting_patch for POST /v1/workspaces/settings, system_improvements. CLI: tokenzero met− - Error playbooks: https://tokenzero.sh/errors (/errors/openai-429-rate-limit, /errors/anthropic-529-overloaded, /errors/prompt-cache-miss-debugging, /errors/deepseek-r1-reasoning-token-bloat, /errors/gpt-5-tool-schema-token-bloat)+ > TokenZero is the independent ledger of record for AI spend: metering, attribution, budget control, audit. Each model call becomes an Ed25519-signed, hash-chained receipt (metadata only) anyone can check at /verify. Two ingestion paths: the gateway sensor (set base_url, BYOK) or record-only (POST /v1/records). Per-agent budgets, signed audit bundles, optional savings engines.+ ## Quickstart (curl)+ No key yet (free model, signed receipt; any api_key value works with OpenAI SDKs at base_url https://tokenzero.sh/sandbox/v1):+ curl https://tokenzero.sh/sandbox/v1/chat/completions -H "Content-Type: application/json" -d '{"messages":[{"role":"user","content":"hi"}]}'+ Savings estimate from your usage export (OpenAI, Anthropic, OpenRouter or any CSV with model and token columns; no key, nothing stored):+ curl https://tokenzero.sh/v1/estimate -H "Content-Type: text/csv" --data-binary @usage.csv+ With your own provider key:+ curl https://tokenzero.sh/v1/chat/completions -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" -d '{"model":"gpt-6-luna","messages":[{"role":"user","content":"hi"}]}'+ - The Authorization header carries YOUR provider key (OpenAI sk-…, Anthropic sk-ant-… or x-api-key, Gemini AIza… or x-goog-api-key). TokenZero forwards it unchanged and never stores it.+ - A TokenZero key (tz_live_…) never goes in Authorization: send it as X-TokenZero-Key, or use the base URL https://tokenzero.sh/w/<tz_live_…>/v1.+ - A 401 whose body has "tokenzero": {"source": "upstream"} means the provider rejected your key; X-TokenZero-Hint says which provider.+ ## MCP Events (experimental; poll mode, SEP-3415 draft)+ An agent can wake on a cost spike or an upstream auth failure. https://tokenzero.sh/mcp and @tokenzero/mcp advertise io.modelcontextprotocol/events; poll only (events/poll, opaque cursor, nextPollMs). Types: spend.threshold_crossed {usd, window}, upstream.auth_failed {provider?}, savings.daily_report, pricing.changed {models?}. Without MCP: GET https://tokenzero.sh/v1/events, POST /v1/events/poll with X-TokenZero-Key.+ ## Cache breaks+ X-TokenZero-Cache-Break: tools|system;tokens=N;est_lost_usd=… : this session's tools or system prompt changed since its last accepted turn, so the cached prefix was re-billed. Keep both fixed per session. Signed into the receipt; counted on the scorecard.+ ## Check a provider key first+ POST https://tokenzero.sh/v1/keys/check with Authorization: Bearer <provider key> (?provider=deepseek|mistral when the prefix says nothing): one read-only listing call to the provider; returns verdict valid|invalid|no_access|rate_limited|unreachable plus fix and keyless_sandbox. Not stored. The CLI init and @tokenzero/mcp run it locally against the provider.+ The gateway checks each key once before the first forward. A first call with no key or a rejected key (no success yet) gets a labelled 200 from a free sandbox model in your SDK's shape, with the fix and a signed receipt.+ ## Try free (provider free tiers, your own key)+ Base URL for every row: https://tokenzero.sh/v1 (OpenAI SDKs: base_url=https://tokenzero.sh/v1, api_key=<that provider's key>). TokenZero routes by key prefix; add X-TokenZero-Provider only where noted.+ - Google Gemini (AI Studio free tier): key AIza… · model e.g. gemini-3-flash+ - Groq: key gsk_… · model e.g. llama-3.3-70b-versatile+ - OpenRouter free models: key sk-or-… · model openrouter/free or any id ending in :free (priced at $0 on receipts)+ - Cerebras: key csk-… · model e.g. llama-3.3-70b+ - Mistral: keys have no prefix, so send X-TokenZero-Provider: mistral (or use a mistral-* model id) · model e.g. mistral-small-latest+ - GitHub Models: a GitHub token with models:read (ghp_… / github_pat_…) · model e.g. openai/gpt-4.1-mini+ - No key at all: https://tokenzero.sh/sandbox/v1/chat/completions (free model, 10 calls an hour)+ Example: curl https://tokenzero.sh/v1/chat/completions -H "Authorization: Bearer $GROQ_API_KEY" -H "Content-Type: application/json" -d '{"model":"llama-3.3-70b-versatile","messages":[{"role":"user","content":"hi"}]}'+ ## Tools, comparisons, guides, reports (each page in this section is also Markdown: append .md or send Accept: text/markdown; so are /audits and /docs/receipt-spec)+ - Other gateways and routers (54 pages, incl. MLflow AI Gateway, Baseten Grid and Fireworks Nexus): https://tokenzero.sh/compare (…/<product>-alternative, …/tokenzero-vs-<product>)+ - Model lifecycle: 19 ids with provider-announced retirement dates (OpenAI and Anthropic deprecation pages); audits flag them, the gateway warns in X-TokenZero-Warning, /models/<id> shows the date and replacement.+ - GitHub App (LLM cost diff comment on every pull request, no workflow file): https://tokenzero.sh/github-app+ - Plans (POST /v1/workspaces/me/plan {plan}): free ($0, up to $500/mo routed) | performance (15% of verified savings TokenZero caused; provider_native savings never billed). Monthly only, no prepay. GET /v1/usage shows the fee preview.+ - X-TokenZero-Semantic-Cache: true (near-duplicate and paraphrase matching, opt-in; negations and numbers must match; word order is not compared)+ - X-TokenZero-Semantic-Threshold: 0.5-0.99 (cosine similarity a paraphrase must reach; default 0.9)+ - Virtual model aliases: define once, PATCH /v1/workspaces/me {"settings":{"aliases":{"tz/coding-agent":{"model":"gpt-6.1-sol","cascade":"auto"}}}} (X-TokenZero-Key), then call model "tz/coding-agent". Response header X-TokenZero-Alias; savings per alias in /v1/workspaces/me/metrics (by_alias). Change the mapped model without redeploying clients; null removes an alias.+ - X-TokenZero-Prompt-Cache-TTL: auto (or workspace setting prompt_cache_ttl_mode / cacheTtl: auto): OpenAI Responses on GPT-5.6+ pick the 12h lifetime per static prefix only when its revival rate over a rolling 48h clears break-even; otherwise 30m. Advise mode reports it in X-TokenZero-Cache-Format; apply mode sets prompt_cache_options.ttl. Receipt engine tags ttl-auto / ttl-advice.+ - X-TokenZero-Reasoning-Stepdown: off | advise | auto (default advise; workspace setting reasoning_stepdown): on multi-turn GPT-6 Responses requests the classifier scores simple, the gateway lowers reasoning effort by appending {"type":"configuration_update","reasoning":{"effort":"low"}} to input and leaves reasoning.effort untouched, so the cached prefix survives. Never stacked on a caller-sent configuration_update; a rejecting model is retried without it. Covered by the shadow-eval parity floo+ X-TokenZero-Request-Id, -Baseline-Cost-USD, -Actual-Cost-USD, -Savings-USD, -Engines, -Cache (hit-exact | hit-semantic | miss | bypass;reason=…), -Cascade-Affinity, -Receipt-URL, -Receipt-Signature (Ed25519, key at /.well-known/tokenzero.json); the full list is in /openapi.json.+ - POST /v1/demo/sandbox {model?} — 1-click live demo: the four engines on a canned request, no provider call, $0; returns the engine trace, the response headers and a real Ed25519-signed receipt (workspace ws_demo_sandbox) that verifies at /v1/ledger/verify