This guide gets you from zero to a working Tokonomics integration with your first budget alert — in under 5 minutes. Works for any language that can make HTTP requests.

Before you start: Create your free account at tokonomics.ca/register. You'll get your proxy URL and API key from the dashboard.

Step 1: Get Your Credentials (1 minute)

From your Tokonomics dashboard:

Copy your Proxy URL: https://api.tokonomics.ca/proxy
Copy your API key: mk_xxxxxxxxxxxxxxxx...

Your proxy URL is the only URL you'll change in your app.

Step 2: Update Your Base URL (2 minutes)

Replace your LLM provider's base URL with your Tokonomics proxy URL. That's it.

PHP:

// Before
$baseUrl = 'https://api.openai.com/v1';

// After — add your Tokonomics key in the Authorization header
$response = Http::withHeaders([
    'Authorization' => 'Bearer mk_your_tokonomics_key',
    'X-Feature-Name' => 'your-feature-name',    // optional but recommended
    'X-Tenant-ID'   => auth()->user()->tenant_id, // optional but recommended
])->post('https://api.tokonomics.ca/proxy/openai/chat/completions', $payload);

Python:

from openai import OpenAI
client = OpenAI(
    api_key="mk_your_tokonomics_key",
    base_url="https://api.tokonomics.ca/proxy/openai"
)
# All your existing calls work unchanged
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}]
)

Node.js:

import OpenAI from 'openai';
const client = new OpenAI({
    apiKey: process.env.TOKONOMICS_KEY,
    baseURL: 'https://api.tokonomics.ca/proxy/openai'
});

Anthropic (any language — HTTP directly):

POST https://api.tokonomics.ca/proxy/anthropic/messages
Authorization: Bearer mk_your_tokonomics_key
X-Feature-Name: your-feature
Content-Type: application/json

{ ...your normal Anthropic request body... }

DeepSeek:

POST https://api.tokonomics.ca/proxy/deepseek/chat/completions
Authorization: Bearer mk_your_tokonomics_key

Step 3: Add Feature Tags (1 minute, optional but valuable)

Add two headers to every LLM call to enable per-feature and per-tenant cost attribution:

X-Feature-Name: support-bot     # What feature is making this call?
X-Tenant-ID: tenant_abc123      # Which of your customers?

Without these, you'll see total costs. With them, you'll see costs broken down by feature and customer. For most teams, this is where 80% of the value is.

Step 4: Set Your First Budget Alert (1 minute)

In your Tokonomics dashboard:

Go to Alerts → New Alert
Set Monthly budget: your expected monthly LLM spend × 1.5
Set 70% threshold: Notify me (email or webhook URL)
Set 90% threshold: Notify me + downgrade to cheaper model
Click Save

That's it. You now have:

Real-time cost tracking for every LLM call
Per-feature and per-tenant attribution (if you added tags)
An alert that fires before you overspend

Verifying It Works

Make one test LLM call through the proxy. In your Tokonomics dashboard → Usage, you should see the call appear within 30 seconds with:

Model name
Token counts (input and output)
Cost in USD
Feature name (if you tagged it)
Latency

If you don't see it:

Verify the base URL is correct (check for trailing slashes)
Verify your API key is in the Authorization: Bearer mk_... header
Check the response for an error message — common issues: wrong provider in URL (/proxy/openai vs /proxy/anthropic)

Next Steps

Once you're seeing calls in the dashboard:

Add tags to all your features — Per-Feature Cost Tracking guide
Set up per-tenant budgets — Multi-Tenant LLM Cost Isolation guide
Configure hard caps — Hard Spending Caps guide
Optimize your highest-cost feature — LLM Cost Optimization guide

Frequently Asked Questions

Does changing the base URL affect my existing code?

No. The proxy is a transparent pass-through. Your existing requests, response handling, error handling, and retry logic all work identically. The only change is the URL and auth header.

What if I'm using multiple LLM providers?

Configure a separate proxy path for each: /proxy/openai, /proxy/anthropic, /proxy/deepseek. Your existing provider API keys stay in your .env — Tokonomics uses them to authenticate with each provider.

How do I handle my existing provider API keys?

Keep them in your environment as usual. When you route through Tokonomics, pass your Tokonomics API key in the Authorization header. The proxy substitutes your actual provider keys on the outbound request. This means you don't expose your OpenAI/Anthropic keys in client-side code.

Can I use Tokonomics in local development?

Yes. Configure your local app to use the proxy URL with a development environment tag (X-Environment: development). You can filter out development costs in the dashboard to see only production spend.

Questions? Contact us → | Documentation →

Getting Started with Tokonomics: 5-Minute Setup