TokenomixAI API

The TokenomixAI endpoint follows the OpenAI format. Code and tools that already support OpenAI work right away once you change the base URL and API key.

Quickstart

1. Buy a package on the pricing page. Once your payment comes through, you receive an API key sk-tkx-… and an account hashtag #TKX-XXXXXX.
2. Set the base URL to https://api.tokenomixai.com/v1.
3. Send requests just as you would to OpenAI.

curl https://api.tokenomixai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "stream": true,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

No tool yet? Install with one command

If you do not have a coding agent yet, the command below installs OpenCode or Claude Code and fills in the base URL and API key at the same time. The script checks the key first, then backs up your old config before filling in the TokenomixAI part. Your other settings (MCP servers, plugins, other providers) are kept; a config with comments in it is rewritten (the backup stays). To go back to the original config, run the same command with --restore added (Linux/macOS) or $env:RESTORE="1" (Windows), then run /logout and /login inside the tool. You can read the scripts before running them: opencode.sh, opencode.ps1, claude.sh, claude.ps1.

Using a desktop app

There is no separate command. Run the command above once in Terminal or PowerShell. Desktop apps read the same config:

• OpenCode Desktop: use the OpenCode command. Close and reopen the app, and the TokenomixAI provider and default model are selected right away.
• Claude Code in VS Code: use the Claude Code command. Close and reopen VS Code, open the Claude Code panel, and start chatting. No Claude account login is needed.

The Claude Desktop app does not work yet, in either the Chat or the Code tab. Its Code tab always uses the Claude account you are signed in with, so the settings from the command above are not picked up. Use Claude Code in Terminal or VS Code instead.

Authentication

Send the key in the header Authorization: Bearer sk-tkx-…. The key is shown only once, when it is issued. TokenomixAI stores keys as hashes, so a lost key cannot be shown again, only rotated.

Endpoints

Any other endpoint outside this list returns 404.

Tool use (function calling)

Tool use works on both endpoints, each in its standard format. Tool definitions, the model's tool calls, and tool results are passed through as they are, including with stream: true. Claude Code, OpenCode, and the agents in Tool setup rely on it under the hood.

Pick a model that supports tool calling. If a model replies with plain text and no tool call, try another model from the catalog.

Chat Completions (OpenAI format)

Send your tools in the tools field. tool_choice is optional ("auto", "none", "required", or a specific function).

curl https://api.tokenomixai.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tkx-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [{ "role": "user", "content": "What is the weather in Jakarta right now?" }],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

When the model calls a tool, the response has choices[0].message.tool_calls with finish_reason: "tool_calls". arguments is a JSON string. Run the tool on your side, then send the conversation again: the assistant message as it was, plus one role: "tool" message per tool call.

"messages": [
  { "role": "user", "content": "What is the weather in Jakarta right now?" },
  { "role": "assistant", "content": null, "tool_calls": [{
      "id": "call_1", "type": "function",
      "function": { "name": "get_weather", "arguments": "{\"city\":\"Jakarta\"}" }
  }] },
  { "role": "tool", "tool_call_id": "call_1", "content": "{\"temp_c\":31,\"condition\":\"sunny\"}" }
]

Messages (Anthropic format)

Each entry in tools has a name, description, and input_schema. max_tokens is required in this format.

curl https://api.tokenomixai.com/v1/messages \
  -H "Authorization: Bearer sk-tkx-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "What is the weather in Jakarta right now?" }],
    "tools": [{
      "name": "get_weather",
      "description": "Get the current weather for a city",
      "input_schema": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      }
    }]
  }'

The model replies with a tool_use block in content and stop_reason: "tool_use". Send the result back as a tool_result block in the next user message, with the same tool_use_id.

"messages": [
  { "role": "user", "content": "What is the weather in Jakarta right now?" },
  { "role": "assistant", "content": [
      { "type": "tool_use", "id": "toolu_1", "name": "get_weather", "input": { "city": "Jakarta" } }
  ] },
  { "role": "user", "content": [
      { "type": "tool_result", "tool_use_id": "toolu_1", "content": "{\"temp_c\":31,\"condition\":\"sunny\"}" }
  ] }
]

Tool setup

Cursor

1. Open Settings → Models.
2. Put your sk-tkx-… key in OpenAI API Key, turn on Override OpenAI Base URL and enter https://api.tokenomixai.com/v1.
3. Add a model name from the catalog (for example MODEL_ID) as a custom model.

Cline / Roo Code

Choose the API Provider OpenAI Compatible, then enter the Base URL https://api.tokenomixai.com/v1, your API Key, and a Model ID from the catalog.

Zed

// ~/.config/zed/settings.json
{
  "language_models": {
    "openai": {
      "api_url": "https://api.tokenomixai.com/v1",
      "available_models": [
        // max_tokens: match the model's context window
        { "name": "MODEL_ID", "display_name": "MODEL_ID (TokenomixAI)", "max_tokens": 128000 }
      ]
    }
  }
}
// Enter the API key in Agent Panel → Settings → OpenAI.

OpenCode

The fastest way: one-command install. Manually:

1. Install: curl -fsSL https://opencode.ai/install | bash (Windows: npm install -g opencode-ai).
2. Create the config at ~/.config/opencode/opencode.json:

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tokenomixai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "TokenomixAI",
      "options": {
        "baseURL": "https://api.tokenomixai.com/v1",
        "apiKey": "{env:TOKENOMIXAI_API_KEY}"
      },
      "models": {
        "MODEL_ID": { "name": "MODEL_ID" },
        "MODEL_ALT": { "name": "MODEL_ALT" }
      }
    }
  }
}

3. Set TOKENOMIXAI_API_KEY in your environment, then run opencode.

Seeing upstream request failed: invalid credential or a 401? The key is missing or wrong: check that it was copied in full (starts with sk-tkx-, no spaces), that TOKENOMIXAI_API_KEY is set in the terminal that runs OpenCode, or run the one-command install again to fill the key in. A rotated key no longer works.

Claude Code

The fastest way: one-command install. A full guide per operating system is in How to install Claude Code. Manually:

1. Install (needs Node.js): npm install -g @anthropic-ai/claude-code.
2. Fill in ~/.claude/settings.json. The base URL has no /v1, because Claude Code appends /v1/messages itself:

// ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.tokenomixai.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-tkx-…",
    "ANTHROPIC_MODEL": "MODEL_ID",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "MODEL_FAST",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "MODEL_ID",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "MODEL_ID",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "200000"
  }
}

3. Run claude. Switch models with /model haiku, sonnet or opus (mapped to the models above, not to actual Claude models). Pick any other model from the catalog, Claude included, with /model <model-id>.
4. The warning Model "…" isn't recognized · context assumed … is normal: Claude Code does not know the catalog model names yet, and the model still works. The CLAUDE_CODE_AUTO_COMPACT_WINDOW line makes Claude Code summarize the conversation automatically at 200K tokens, so models with a smaller context do not fail and long chats do not spend quota on the whole context with every message.

9router

1. Install and run: npm install -g 9router then 9router. The dashboard is at http://localhost:20128/dashboard.
2. Open Providers, then Add OpenAI Compatible.
3. Set Prefix to tknx (any value, used as the model ID prefix) and API Type to Chat Completions.
4. Set Base URL to https://api.tokenomixai.com/v1 and API Key to sk-tkx-….
5. Set Model ID to a model from the catalog (for example MODEL_ID), click Check until it shows Valid, then Create.

The model is called with the ID tknx/<model-id>, and can be added to 9router combos or routing like any other provider.

Hermes

Hermes can connect straight to TokenomixAI as a custom provider, with no intermediary. Install: curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash, then fill in the two files below and run hermes.

# ~/.hermes/config.yaml
model:
  provider: custom
  base_url: https://api.tokenomixai.com/v1
  default: MODEL_ID    # a model ID from the catalog, not auto
  key_env: ROUTER_API_KEY

# ~/.hermes/.env
ROUTER_API_KEY=sk-tkx-…

The variable name in key_env can be anything, as long as it matches what you put in .env. If you already use 9router, Hermes can also be pointed at the 9router that has the TokenomixAI provider above.

n8n

Use the AI Agent node version 3 or newer, then pick one chat model:

• Anthropic Chat Model (easiest): create an Anthropic credential with API Key sk-tkx-… and Base URL https://api.tokenomixai.com (without /v1).
• OpenAI Chat Model: create an OpenAI credential with API Key sk-tkx-… and Base URL https://api.tokenomixai.com/v1, with no trailing slash. This node uses the Responses API by default; if your workflow gets a 404, open Options and turn off Use Responses API.

Type a model ID from the catalog directly (for example a GLM model), not auto: auto adds a lot of input tokens to every request. Chat nodes, AI Agent and tool calling work. Embeddings are not available yet, so the Embeddings node and vector stores cannot use this key.

OpenClaw & other agents

Choose the custom / OpenAI-compatible provider (chat/completions API), then enter the Base URL https://api.tokenomixai.com/v1, the API Key sk-tkx-…, and a Model ID from the catalog. Agents rely on tool calling, so pick a model that supports it.

Stuck during setup? Ask in the Telegram group, open to everyone (mostly in Indonesian).

New models

As soon as a new model appears in the catalog, you can use it with the same key. Call it by its exact catalog ID. Only tools that keep their own model list need a change:

The OpenCode update command reuses the key already in your config, backs the config up first, then replaces only the TokenomixAI model list. Your default model, other providers and other settings stay as they are. It needs python3 (Linux/macOS) or Node.js (Windows).

Linux / macOS:

bash <(curl -fsSL https://tokenomixai.com/install/opencode.sh) --update-models

Windows (PowerShell):

$env:UPDATE_MODELS="1"; irm https://tokenomixai.com/install/opencode.ps1 | iex

Models & multiplier

The tokens deducted are calculated as:

tokens_used = (prompt_tokens + completion_tokens) × multiplier

Example: a model with a 2× multiplier deducts 2,000 tokens for a 1,000-token task. The model and multiplier list below is live from the server and has the same content as the model catalog on the homepage.

Rate limit

The limit is 600 requests per minute per account (shared by all your keys, extra keys included), enforced with a token bucket algorithm (bursts of up to 600 requests). It covers all models combined, not each model separately. The gateway does not cap concurrent requests. When the limit is exceeded, the gateway returns 429 with a Retry-After header (in seconds).

When a model is under heavy load, requests to it can occasionally get a 429 even while your key is below the limit. For agents or async traffic, retry with backoff. Having trouble with the limit? Contact us.

Error codes

Errors follow the OpenAI format: {"error": {"message", "type", "code"}}.

Check remaining quota

Your remaining quota is always shown in the Portal. To skip the trip to the Portal, it can also appear right inside your tool:

The line in VS Code needs a recent Claude Code version. If the installer says yours does not support it yet, update Claude Code and run the install command again. Installed before this feature existed? Run the install command again to add it. Without the installer: type /plugin install tokenomixai --marketplace sagarasea/tokenomixai-claude inside Claude Code.

curl https://api.tokenomixai.com/v1/quota -H "Authorization: Bearer sk-tkx-…"

{
  "object": "quota",
  "hashtag": "#TKX-XXXXXX",
  "status": "active",
  "remainingTokens": 3800000000,
  "maxTokens": 5000000000,
  "usagePercent": 24,
  "expiresAt": "2026-12-12T00:00:00.000Z",
  "low": false,
  "checkedAt": "2026-11-08T07:00:00.000Z",
  "stale": false
}

low is true at 10% or less left. status is exhausted when the quota is used up or the key has expired. Values are cached for 60 seconds (stale: true = the last stored value, because fresh data could not be fetched). The limit is 60 requests per minute per IP, and this endpoint does not use any quota.

Save quota on small requests

Every request uses at least about 1,000 tokens (before the multiplier), however small it is. For many small tasks, such as one n8n item, one spreadsheet cell or one bot message, combine several items into one request instead of sending them one by one.

Type a model ID from the catalog directly, not auto. The auto model adds about 17K input tokens to every request, so it is the most wasteful choice for small requests.

Portal & top-up

Sign in to the Portal with your API key to see remaining quota, validity, request history, to rotate your key, and to create or revoke extra keys (one per tool or device, up to 5, same quota). To add quota, buy a package with the Top-up option and enter your account hashtag (format #TKX-XXXXXX). Your key does not change on top-up.

Data we log

For every request, the gateway logs: time, endpoint, model, HTTP status, latency, and prompt/completion token counts. Prompt and response content is not stored by the TokenomixAI gateway. Requests are still processed by the upstream model provider to produce the answer. Details in the Privacy Policy (Bahasa Indonesia).