Docs TokenomiCo

Referência completa do proxy de LLM que economiza tokens.

Introdução

O TokenomiCo é um proxy entre a sua aplicação e a API do seu provedor de LLM. Cada requisição passa por três etapas: autenticação (sua chave tk_live) → compressão (opcional, por requisição) → repasse ao provedor com a sua própria chave (BYOK). A resposta volta intacta, mais os headers de economia.

O preço é pay as you gain: 40% da economia de tokens medida, e nada além. Sem economia, sem fatura.

Quickstart (~5 minutos)

Quatro passos do zero ao primeiro token economizado:

1. Crie sua conta em tokenomico.com/app (a primeira fatura só vem no mês seguinte ao cadastro).
2. Em Chaves de API, crie uma chave tk_live_... — exibida uma única vez, guarde bem.
3. Em Provedores, registre a chave do seu provedor (BYOK, cifrada em repouso).
4. Aponte a base URL do seu SDK para o proxy e chame exatamente como chamava o provedor:

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": "..."}]
  }'

Autenticação

Toda chamada exige o header authorization: Bearer tk_live_.... A chave identifica sua conta, aplica sua preferência de compressão e mede o uso. Chaves podem ser revogadas na hora pelo painel; chave revogada recebe 401.

A chave do provedor é resolvida no servidor a partir do seu cofre cifrado. Alternativa: envie-a por requisição via x-provider-key — usada em trânsito, nunca armazenada.

Endpoint e provedores

Endpoint canônico: POST /v1/{provider}/proxy. O corpo passa no formato nativo do provedor — mesmos modelos, mesmos parâmetros, mesma resposta.

Aliases compatíveis com SDK (os SDKs oficiais funcionam trocando só a base URL): POST /v1/{provider}/chat/completions (família OpenAI) e POST /v1/anthropic/v1/messages (SDK da Anthropic).

Headers

Requisição

Resposta

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

Compressão (Telegraph English)

Um motor determinístico (sem GPU, ~1,7 ms) reescreve texto num dialeto compacto que os modelos entendem. Cobre os três blocos que dominam o custo agêntico: o histórico da conversa (turnos anteriores — user, assistant e resultados textuais de ferramentas), as descrições de ferramentas (só o texto da description; nomes, tipos e schemas ficam byte-exatos) e as instruções de sistema. A mensagem mais recente do usuário nunca é comprimida — o modelo lê a sua tarefa atual literalmente. Imagens, argumentos de function-call e payloads estruturados passam intactos. Um reescritor em segundo plano melhora textos recorrentes entre turnos (nunca no caminho da requisição).

É lossy por design — muda a forma, preserva o sentido (números são sempre mantidos intactos). Ligue nas cargas tolerantes (agentes, RAG, contexto multi-turno) e desligue em extração / saída estruturada (JSON, dados) e tarefas críticas quanto à forma. Quando o ganho líquido de uma requisição seria zero ou negativo, o corpo original é enviado sem alteração — você nunca fica pior.

Controle por requisição com x-toke-compress; o default da chave é definido na criação. Gate embutido: textos curtos (< ~240 chars, configurável) e conteúdo estruturado (code fences, "json", denso em dados) passam sem comprimir automaticamente — em prompt curto o output extra custaria mais que o input poupado.

Onde ganha (e onde não)

O TokenomiCo foi feito para cargas agênticas e multi-turno: loops de agentes (LangChain, CrewAI, orquestradores próprios), chats RAG com histórico crescente e qualquer integração que reenvia um prefixo estável grande (system + tools) mais uma conversa que cresce a cada chamada. Ali as três alavancas se compõem: o prefixo estável é comprimido uma vez e continua cacheável, o histórico deixa de crescer quadraticamente em custo, e o prefix cache do provedor continua acertando porque a forma comprimida é determinística e estável.

Honestidade: em prompt único e curto não há economia — o overhead do decodificador superaria o ganho, então o proxy envia o seu texto original e não cobra nada. Os números medidos de ponta a ponta por tamanho de sessão estão publicados no documento de benchmark; só anunciamos números medidos.

Streaming

Envie "stream": true como sempre. Os bytes são repassados intactos conforme chegam (SSE); a economia é medida do próprio stream. Na família OpenAI o proxy injeta stream_options.include_usage para capturar o usage real — seu SDK já entende o chunk final extra.

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": "..."}]}'

Os headers x-toke-* também vêm nas respostas com streaming.

Exemplos de SDK

REST puro (qualquer linguagem)

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 — SDK oficial da Anthropic

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 — SDK oficial da OpenAI (serve para toda a família compatível)

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: "..." }],
});

Cobrança

Cada requisição registra: tokens originais, tokens enviados e tokens líquidos poupados (economia bruta menos o overhead do decodificador, injetado uma vez e amortizado pelo prefix cache do provedor). Economia em USD = tokens líquidos × um fator de calibração medido contra o tokenizador real do provedor × preço de referência de entrada; sua fatura = 40% disso. Os outros 60% são seu ganho líquido. Sem economia, sem cobrança. O comprovante mensal (PoC) abre a economia por alavanca (histórico / tools / system / cache) no painel e em GET /v1/poc (autenticado com sua chave tk_live).

Ciclo: a fatura fecha no dia 15 (e-mail com comprovante + link de pagamento Stripe), tolerância até o dia 18, 23:59 no horário de São Paulo (UTC−3). Conta vencida é suspensa automaticamente — o proxy responde 402 até quitar; a reativação é imediata.

Contas novas: a primeira fatura vem só no mês seguinte ao cadastro; o uso do mês de entrada acumula nela.

Rate limits

120 requisições/minuto por chave, com pico (burst) de 40. Excedeu: 429 com header retry-after (segundos). Limite de corpo: 8 MB.

Erros

Segurança

Prompts e respostas são processados em trânsito — os originais nunca são armazenados (ficam só métricas numéricas de tokens). Uma nuance, por transparência: para melhorar textos recorrentes entre turnos, o proxy pode reter a reescrita comprimida de um trecho (nunca o original), indexada por hash, por até 7 dias. Chaves BYOK e segredos 2FA cifrados em repouso (AES-256-GCM); senhas em scrypt; tudo sob TLS; o painel suporta 2FA TOTP. Detalhes na Política de Privacidade.

← Voltar ao painel