Docs TokenomiCo

Referencia completa del proxy de LLM que ahorra tokens.

Introducción

TokenomiCo es un proxy entre tu aplicación y la API de tu proveedor de LLM. Cada petición pasa por tres etapas: autenticación (tu clave tk_live) → compresión (opcional, por petición) → reenvío al proveedor con tu propia clave (BYOK). La respuesta vuelve intacta, más los headers de ahorro.

El precio es pay as you gain: el 40% del ahorro de tokens medido, nada más. Sin ahorro, sin factura.

Quickstart (~5 minutos)

Cuatro pasos desde cero hasta tu primer token ahorrado:

1. Crea tu cuenta en tokenomico.com/app (la primera factura llega solo el mes siguiente al registro).
2. En Claves de API, crea una clave tk_live_... — se muestra una vez, guárdala bien.
3. En Proveedores, registra la clave de tu proveedor (BYOK, cifrada en reposo).
4. Apunta la base URL de tu SDK al proxy y llámalo exactamente como llamabas al proveedor:

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

Autenticación

Toda llamada requiere el header authorization: Bearer tk_live_.... La clave identifica tu cuenta, aplica tu preferencia de compresión y mide el uso. Las claves se pueden revocar al instante en el panel; una clave revocada recibe 401.

Tu clave del proveedor se resuelve en el servidor desde tu bóveda cifrada. También puedes enviarla por petición con x-provider-key — se usa en tránsito, nunca se guarda.

Endpoint y proveedores

Endpoint canónico: POST /v1/{provider}/proxy. El cuerpo pasa en el formato nativo del proveedor — mismos modelos, mismos parámetros, misma respuesta.

Aliases compatibles con SDK (los SDK oficiales funcionan cambiando solo la base URL): POST /v1/{provider}/chat/completions (familia OpenAI) y POST /v1/anthropic/v1/messages (SDK de Anthropic).

Headers

Petición

Respuesta

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

Compresión (Telegraph English)

Un motor determinista (sin GPU, ~1,7 ms) reescribe el texto en un dialecto compacto que los modelos entienden. Cubre los tres bloques que dominan el costo agéntico: el historial de la conversación (turnos anteriores — user, assistant y resultados textuales de herramientas), las descripciones de herramientas (solo el texto de la descripción; nombres, tipos y schemas quedan byte-exactos) y las instrucciones de sistema. El mensaje más reciente del usuario nunca se comprime — el modelo lee tu tarea actual literal. Imágenes, argumentos de function-call y payloads estructurados pasan intactos. Un reescritor en segundo plano mejora los textos recurrentes entre turnos (nunca en el camino de la petición).

Es lossy por diseño — cambia la forma, preserva el sentido (los números siempre se mantienen intactos). Actívala en cargas tolerantes (agentes, RAG, contexto multi-turno) y desactívala en extracción / salida estructurada (JSON, datos) y tareas críticas de forma. Si la ganancia neta de una petición sería cero o negativa, el cuerpo original se envía sin cambios — nunca quedas peor.

Control por petición con x-toke-compress; el default de la clave se define al crearla. Gate integrado: textos cortos (< ~240 chars, configurable) y contenido estructurado (code fences, "json", denso en datos) pasan sin comprimir automáticamente — en prompts cortos el output extra costaría más que el input ahorrado.

Dónde gana (y dónde no)

TokenomiCo está hecho para cargas agénticas y multi-turno: loops de agentes (LangChain, CrewAI, orquestadores propios), chats RAG con historial creciente y cualquier integración que reenvíe un prefijo estable grande (system + tools) más una conversación que crece en cada llamada. Ahí las tres palancas se componen: el prefijo estable se comprime una vez y sigue cacheable, el historial deja de crecer cuadráticamente en costo, y el prefix cache del proveedor sigue acertando porque la forma comprimida es determinista y estable.

Honestidad: en un prompt único y corto no hay ahorro — el overhead del decodificador superaría la ganancia, así que el proxy envía tu texto original y no cobra nada. Los números medidos de punta a punta por longitud de sesión están publicados en el documento de benchmark; solo anunciamos cifras medidas.

Streaming

Envía "stream": true como siempre. Los bytes se reenvían intactos según llegan (SSE); el ahorro se mide del propio stream. En la familia OpenAI el proxy inyecta stream_options.include_usage para capturar el usage real — tu SDK ya entiende el 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": "..."}]}'

Los headers x-toke-* también están presentes en respuestas con streaming.

Ejemplos de SDK

REST puro (cualquier lenguaje)

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 de 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 de OpenAI (sirve para toda la familia compatible)

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

Facturación

Cada petición registra: tokens originales, tokens enviados y tokens netos ahorrados (ahorro bruto menos el overhead del decodificador, inyectado una vez y amortizado por el prefix cache del proveedor). Ahorro en USD = tokens netos × un factor de calibración medido contra el tokenizador real del proveedor × precio de referencia de entrada; tu factura = 40% de eso. El otro 60% es tu ganancia neta. Sin ahorro, sin cobro. El comprobante mensual (PoC) desglosa el ahorro por palanca (historial / tools / system / cache) en el panel y vía GET /v1/poc (autenticado con tu clave tk_live).

Ciclo: la factura cierra el día 15 (e-mail con comprobante + link de pago Stripe), tolerancia hasta el 18, 23:59 hora de São Paulo (UTC−3). Las cuentas vencidas se suspenden automáticamente — el proxy devuelve 402 hasta el pago; la reactivación es instantánea.

Cuentas nuevas: la primera factura llega solo el mes siguiente al registro; el uso del mes de alta se acumula en ella.

Rate limits

120 peticiones/minuto por clave con burst de 40. Al exceder: 429 con header retry-after (segundos). Límite de cuerpo: 8 MB.

Errores

Seguridad

Prompts y respuestas se procesan en tránsito — los originales nunca se almacenan (solo métricas numéricas de tokens). Un matiz por transparencia: para mejorar textos recurrentes entre turnos, el proxy puede retener la reescritura comprimida de un bloque de texto (nunca el original), indexada por hash, hasta por 7 días. Claves BYOK y secretos 2FA cifrados en reposo (AES-256-GCM); contraseñas con scrypt; todo sobre TLS; el panel soporta 2FA TOTP. Detalles en la Política de Privacidad.

← Volver al panel