Tokonomics API Documentation

Tokonomics is a drop-in LLM cost metering proxy that tracks token usage and costs across 60+ models from 9 providers. It adds ~31ms overhead per request (3.6%), supports streaming, and works with any HTTP client in any language. Over 37 models have sub-cent per-thousand-token pricing synced weekly from official provider pages.

Last updated: July 2026

Quick Start

Tokonomics requires exactly one code change to start tracking costs: replace your provider's base URL with the Tokonomics proxy URL. Setup takes under 5 minutes and works with cURL, Python, JavaScript, Go, and any HTTP client.

# Before: direct to OpenAI
# curl https://api.openai.com/v1/chat/completions

# After: through Tokonomics (one URL change)
curl https://tokonomics.ca/proxy/openai/chat/completions \
  -H "Authorization: Bearer mk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

from openai import OpenAI

client = OpenAI(
    api_key="mk_your_key_here",
    base_url="https://tokonomics.ca/proxy/openai"  # only change
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'mk_your_key_here',
  baseURL: 'https://tokonomics.ca/proxy/openai', // only change
});

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
});
console.log(response.choices[0].message.content);

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]any{
        "model": "gpt-4o",
        "messages": []map[string]string{{"role": "user", "content": "Hello!"}},
    })
    req, _ := http.NewRequest("POST",
        "https://tokonomics.ca/proxy/openai/chat/completions",
        bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer mk_your_key_here")
    req.Header.Set("Content-Type", "application/json")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    fmt.Println("Status:", resp.Status)
}

Authentication

Tokonomics authenticates every request using SHA-256 hashed API keys with the mk_ prefix format. Keys are never stored in plaintext. Pass your key as a Bearer token in the Authorization header.

Authorization: Bearer mk_your_key_here

Base URL

https://tokonomics.ca

All endpoints are relative to this base URL. The proxy path follows the pattern:

https://tokonomics.ca/proxy/{provider}/{upstream-path}

Proxy Endpoint

POST /proxy/{provider}/{path}

Tokonomics forwards your request to the upstream LLM provider with ~31ms median overhead, records token usage with DECIMAL(12,8) precision, calculates cost using rates synced from 9 providers, and checks budget alerts. Responses are streamed back in real-time without buffering.

Path Parameters

Headers

Request Body

Pass the exact same body you would send directly to the provider. Tokonomics forwards it unchanged.

Response

The response is streamed back transparently. Tokonomics does not buffer or modify the response body.

Supported Providers

Use the provider slug in the proxy path. The upstream path mirrors the provider's own API.

Tagging Calls

Add the X-Metering-Tags header to attribute costs to specific teams, features, users, or environments. Tags are stored with every usage event and queryable via analytics.

curl https://tokonomics.ca/proxy/openai/chat/completions \
  -H "Authorization: Bearer mk_your_key_here" \
  -H "Content-Type: application/json" \
  -H 'X-Metering-Tags: {"team":"growth","feature":"chatbot","env":"production"}' \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello!"}]}'

Common Tag Patterns

Bring Your Own Key (BYOK)

Tokonomics never calls providers on your behalf. You supply your own API keys.

Option 1: Store in dashboard (recommended)

Go to Provider Keys and save your provider API key once. It is stored encrypted with AES-256.

Option 2: Per-request header

curl https://tokonomics.ca/proxy/openai/chat/completions \
  -H "Authorization: Bearer mk_your_key_here" \
  -H "X-Provider-Key: sk-your-openai-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello!"}]}'

Key resolution priority

Analytics: Summary

GET /analytics/summary

Returns current month spend, budget utilization percentage, and a per-model cost breakdown.

curl https://tokonomics.ca/analytics/summary \
  -H "Authorization: Bearer mk_your_key_here"

{
  "current_spend_usd": 12.4831,
  "monthly_budget_usd": 100.00,
  "budget_used_pct": 12.48,
  "by_model": [
    { "model": "gpt-4o", "cost_usd": 9.21, "calls": 142 },
    { "model": "deepseek-chat", "cost_usd": 3.27, "calls": 891 }
  ]
}

Analytics: Daily Spend

GET /analytics/daily?days=30

Returns daily spend for the last N days. Maximum 90 days.

{
  "daily": [
    { "date": "2026-06-01", "cost_usd": 1.2340, "calls": 48 },
    { "date": "2026-06-02", "cost_usd": 0.8821, "calls": 31 }
  ]
}

Analytics: By Tag

GET /analytics/by-tag?key=team&period=month

Returns spend grouped by a custom tag key.

{
  "tag_key": "team",
  "period": "month",
  "breakdown": [
    { "value": "growth", "cost_usd": 8.44, "calls": 312 },
    { "value": "support", "cost_usd": 4.00, "calls": 189 }
  ]
}

Analytics: Events

GET /analytics/events?limit=50&offset=0

Returns paginated raw usage events. Maximum limit of 200 per request.

{
  "events": [
    {
      "id": "uuid",
      "model": "gpt-4o",
      "provider": "openai",
      "input_tokens": 512,
      "output_tokens": 128,
      "cost_usd": 0.00384,
      "latency_ms": 342,
      "tags": { "team": "growth", "feature": "chatbot" },
      "created_at": "2026-06-05T14:32:00Z"
    }
  ],
  "total": 1042,
  "limit": 50,
  "offset": 0
}

Errors

All errors return a JSON body with an error field and an appropriate HTTP status code.

{ "error": "Invalid or inactive API key" }

Rate Limits

Tokonomics enforces sliding-window rate limits via Redis. The Free plan allows 10 requests per minute; Pro allows 60. Rate limiting uses fail-open design.

Per-minute rate limits

Response headers

When limits are exceeded

Requests return 429 Too Many Requests with a Retry-After header.

{
  "error": "Rate limit exceeded",
  "detail": "You have exceeded 10 requests/minute. Free plan limit.",
  "retry_after": 12
}

Health Check

GET /health — No authentication required.

{ "status": "ok", "ts": 1749139200 }