TokenomiCo Docs

Complete reference for the token-saving LLM proxy.

Introduction

TokenomiCo is a proxy that sits between your application and your LLM provider's API. Every request goes through three stages: authentication (your tk_live key) → compression (optional, per request) → forwarding to the provider with your own key (BYOK). The response comes back untouched, plus savings headers.

Pricing is pay as you gain: 40% of the measured token savings, nothing else. No savings, no invoice.

Quickstart (~5 minutes)

Four steps from zero to your first saved token:

1. Create your account at tokenomico.com/app (first invoice only in the month after sign-up).
2. In API keys, create a tk_live_... key — shown once, store it safely.
3. In Providers, register your provider API key (BYOK, encrypted at rest).
4. Point your SDK's base URL at the proxy and call it exactly as you called the provider:

curl https://tokenomico.com/v1/anthropic/proxy \
  -H "authorization: Bearer tk_live_..." \
  -H "content-type: application/json" \
  -H "x-toke-compress: on" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 300,
    "messages": [{"role": "user", "content": "..."}]
  }'

Authentication

Every call requires the header authorization: Bearer tk_live_.... The key identifies your account, applies your default compression preference and meters usage. Keys can be revoked instantly in the dashboard; revoked keys get 401.

Your provider key is resolved server-side from your encrypted vault. Alternatively, send it per request via x-provider-key — it is used in transit only, never stored.

Endpoint & providers

Canonical endpoint: POST /v1/{provider}/proxy. The body is passed through in the provider's native format — same models, same parameters, same response shape.

SDK-compatible aliases (so official SDKs work by only changing the base URL): POST /v1/{provider}/chat/completions (OpenAI-family SDKs) and POST /v1/anthropic/v1/messages (Anthropic SDK).

Headers

Request

Response

HTTP/2 200
x-toke-compressed: true
x-toke-tokens-saved-est: 1284

Compression (Telegraph English)

A deterministic engine (no GPU, ~1.7 ms) rewrites text into a compact dialect the models understand. It covers the three blocks that dominate agentic cost: conversation history (earlier turns — user, assistant and textual tool results), tool descriptions (only the description strings; names, types and schemas stay byte-exact) and system instructions. The most recent user message is never compressed — the model reads your current task verbatim. Images, function-call arguments and structured payloads pass through untouched. A background rewriter improves recurring texts between turns (never in the request path).

It is lossy by design — wording changes, meaning is preserved (numbers are always kept intact). Turn it on for tolerant workloads (agents, RAG, long multi-turn context) and off for extraction / structured output (JSON, data) and wording-critical tasks. When the net gain of a request would be zero or negative, the original body is sent unchanged — you are never worse off.

Control per request with x-toke-compress; the key's default is configurable at creation. Built-in gate: short texts (< ~240 chars, configurable) and structured-looking content (code fences, "json", data-dense) are passed through uncompressed automatically — on short prompts the extra output would cost more than the input saved.

Where it wins (and where it does not)

TokenomiCo is built for agentic and multi-turn workloads: agent loops (LangChain, CrewAI, custom orchestrators), RAG chats with growing history, and any integration that resends a large stable prefix (system + tools) plus an ever-growing conversation on every call. There the three levers compound: the stable prefix is compressed once and stays cacheable, history stops growing quadratically in cost, and the provider's prefix cache keeps being hit because the compressed form is deterministic and stable.

Honest flip side: on a single short prompt there are no savings — the decoder overhead would exceed the gain, so the proxy sends your original text and charges nothing. Measured end-to-end numbers per session length are published in the benchmark document; we only advertise measured figures.

Streaming

Send "stream": true as usual. Bytes are forwarded untouched as they arrive (SSE); savings are metered from the stream itself. For OpenAI-family providers the proxy injects stream_options.include_usage so real usage is captured — your SDK already understands the extra final chunk.

curl -N https://tokenomico.com/v1/openai/proxy \
  -H "authorization: Bearer tk_live_..." \
  -H "content-type: application/json" \
  -d '{"model": "gpt-4.1", "stream": true,
       "messages": [{"role": "user", "content": "..."}]}'

Response headers x-toke-* are present on streamed responses too.

SDK examples

Raw REST (any language)

curl https://tokenomico.com/v1/anthropic/proxy \
  -H "authorization: Bearer tk_live_..." \
  -H "content-type: application/json" \
  -H "x-toke-compress: on" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 300,
    "messages": [{"role": "user", "content": "..."}]
  }'

Python — official Anthropic SDK

from anthropic import Anthropic

client = Anthropic(
    api_key="tk_live_...",                            # TokenomiCo key
    base_url="https://tokenomico.com/v1/anthropic",
    default_headers={"x-toke-compress": "on"},
)
msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=300,
    messages=[{"role": "user", "content": "..."}],
)

Node — official OpenAI SDK (works for the whole OpenAI-compatible family)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "tk_live_...",
  baseURL: "https://tokenomico.com/v1/openai",  // /v1/grok, /v1/deepseek, ...
  defaultHeaders: { "x-toke-compress": "on" },
});
const r = await client.chat.completions.create({
  model: "gpt-4.1",
  messages: [{ role: "user", content: "..." }],
});

Billing

Each request records: original tokens, tokens actually sent, and net tokens saved (gross savings minus the decoder overhead, which is injected once and amortized by the provider's prefix cache). Savings in USD = net tokens saved × a calibration factor measured against the provider's real tokenizer × reference input price; your invoice = 40% of that. The other 60% is your net gain. No savings, no charge. The monthly statement (PoC) breaks savings down by lever (history / tools / system / cache) in the dashboard and via GET /v1/poc (authenticated with your tk_live key).

Cycle: the invoice closes on the 15th (e-mail with statement + Stripe payment link), grace until the 18th, 11:59 PM São Paulo time (UTC−3). Overdue accounts are suspended automatically — the proxy returns 402 until settled; reactivation is instant after payment.

New accounts: the first invoice comes only in the month after sign-up; usage from the sign-up month accrues into it.

Rate limits

120 requests/minute per key with a burst of 40. Exceeding returns 429 with a retry-after header (seconds). Request body limit: 8 MB.

Errors

Security

Prompts and responses are processed in transit — original prompts and responses are never stored (only numeric token metrics are kept). One nuance for transparency: to improve recurring texts between turns, the proxy may retain the compressed rewrite of a text block (never the original), keyed by hash, for up to 7 days. BYOK keys and 2FA secrets are encrypted at rest (AES-256-GCM); passwords use scrypt; everything runs over TLS; the dashboard supports TOTP 2FA. Details in the Privacy Policy.

← Back to dashboard