Documentation

Everything, step by step

No jargon, no prior experience needed. Pick your tool below, follow the numbered steps exactly, and you'll be coding with AI in a few minutes — paid for with attention, not a credit card.

Getting started

What is Tokenly?

Tokenly gives you one API key that works with every major AI coding tool. Instead of paying per token with a credit card, you spend credits — and when they run out, you earn more by completing a quick survey or watching a sponsored post.

Step 1

You start with 50.00 free credits.

Step 2

Create a key

One click in your dashboard.

Step 3

Plug it in

Codex, Claude Code, Python — anything OpenAI-compatible.

Step 4

Earn to refill

Credits run out? A survey tops you back up.

Getting started

1 · Create your API key

An API key is like a password that lets a tool use your Tokenly credits. Creating one takes three clicks.

Open the API keys page

Go to Dashboard → API keys (sign in first if you haven't).

Click “Create key”

Give it any name that helps you remember where you'll use it — for example my-laptop or codex. Leave “Model access” on All models unless you want to lock this key to a single model.

Copy the key immediately

A green box appears showing your full key — it starts with sk-. Click Copy and paste it somewhere safe right now.

The full key is shown only this once. We store a fingerprint of it, not the key itself, so we can't show it again. Lost it? No problem — just create a new key and revoke the old one.

Getting started

2 · Keep it safe

Treat your key like a password. Anyone who has it can spend your credits.

Paste it into a password manager, or a private note — not a public document.
Never post it in screenshots, GitHub, or chat groups.
If you think a key leaked, go to API keys and click Revoke — it stops working instantly, and your other keys are unaffected.

Use it in your tools

Codex CLI (Recommended)

Codex is OpenAI's AI coding agent that lives in your terminal. Here's the complete setup — copy, paste, done. You only do this once.

Open your terminal

macOS: press ⌘ + Space, type Terminal, press Enter. Windows: press the Windows key, type PowerShell, press Enter. A window with a text prompt appears — that's where you'll paste the commands below.

Install Node.js (skip if you have it)

Codex is installed through npm, which ships with Node.js. Not sure you have it? Run node --version — if it prints a version number, skip this step. On a Mac without brew, download the installer from nodejs.org instead.

macOS

brew install node
node --version

Windows

winget install OpenJS.NodeJS.LTS
node --version

Paste the block for your system, then press Enter

It installs Codex (if needed), registers Tokenly as a provider, and saves your key. Two edits first: replace sk-YOUR-KEY with the key you copied earlier, and YOUR-MODEL with a model id (the comment next to it shows the live one). Safe to re-paste any time — it replaces any old key automatically.

macOS

npm install -g @openai/codex

mkdir -p ~/.codex
curl -fsSL -o ~/.codex/tokenly-models.json https://www.tokenly.us/codex-model-catalog.json

grep -qs "model_providers.tokenly" ~/.codex/config.toml || cat >> ~/.codex/config.toml << 'EOF'

[model_providers.tokenly]
name = "Tokenly"
base_url = "https://www.tokenly.us/api/v1"
env_key = "TOKENLY_API_KEY"
wire_api = "responses"
EOF

cat > ~/.codex/tokenly.config.toml << EOF
model_provider = "tokenly"
model = "YOUR-MODEL" # e.g. gpt-5.6-terra, claude-sonnet-5, deepseek-v4-flash
model_context_window = 128000
model_max_output_tokens = 8192
model_catalog_json = "$HOME/.codex/tokenly-models.json"
EOF

touch ~/.zshrc
sed -i '' '/export TOKENLY_API_KEY=/d' ~/.zshrc
echo 'export TOKENLY_API_KEY=sk-YOUR-KEY' >> ~/.zshrc
source ~/.zshrc

Windows (PowerShell)

# 1) Install Codex CLI (skip if you already use Codex)
npm install -g @openai/codex

# 2) Register Tokenly as a provider (run once — safe to re-run)
$codex = "$env:USERPROFILE\.codex"
New-Item -ItemType Directory -Force $codex | Out-Null
curl.exe -fsSL -o "$codex\tokenly-models.json" https://www.tokenly.us/codex-model-catalog.json

if (!(Test-Path "$codex\config.toml") -or !(Select-String -Quiet -Path "$codex\config.toml" -Pattern "model_providers.tokenly")) {
Add-Content "$codex\config.toml" @"

[model_providers.tokenly]
name = "Tokenly"
base_url = "https://www.tokenly.us/api/v1"
env_key = "TOKENLY_API_KEY"
wire_api = "responses"
"@
}

Set-Content "$codex\tokenly.config.toml" @"
model_provider = "tokenly"
model = "YOUR-MODEL" # e.g. gpt-5.6-terra, claude-sonnet-5, deepseek-v4-flash
model_context_window = 128000
model_max_output_tokens = 8192
model_catalog_json = "$($codex -replace '\\','/')/tokenly-models.json"
"@

# 3) Save your key — replace sk-YOUR-KEY with the key you copied
$KEY = "sk-YOUR-KEY"
setx TOKENLY_API_KEY $KEY | Out-Null
$env:TOKENLY_API_KEY = $KEY

Start Codex on Tokenly

Works right away — run this every time you want Codex on your Tokenly credits:

codex --profile tokenly

How to tell it worked: the status bar at the top of Codex shows the model you picked (e.g. model: gpt-5.6-terra). If it shows a GPT model instead, you forgot --profile tokenly.

Don't look for Tokenly models inside Codex's /model menu — that menu only lists OpenAI's own models. The profile is what switches you to Tokenly. Plain codex (no profile) still uses your regular OpenAI account, so nothing breaks.

Use it in your tools

Claude Code

Anthropic's AI coding agent also runs on your Tokenly key. We set it up as a separate command — your regular Claude subscription keeps working untouched.

Install Node.js (skip if you have it)

Claude Code is installed through npm, which ships with Node.js. Run node --version — if it prints a version number, skip this step. On a Mac without brew, download the installer from nodejs.org instead.

macOS

brew install node
node --version

Windows

winget install OpenJS.NodeJS.LTS
node --version

Install Claude Code (skip if you have it)

Same command on macOS and Windows:

npm install -g @anthropic-ai/claude-code

Paste the block for your system into your terminal

It creates a tokenly-claude command that runs Claude Code on your Tokenly credits. Replace sk-YOUR-KEY with your key (the same key as the Codex guide is fine) and YOUR-MODEL with a model id — the comment next to it shows the live one. Safe to re-paste any time; it replaces any old key automatically.

macOS

mkdir -p ~/.tokenly
cat > ~/.tokenly/claude.zsh << 'EOF'
tokenly-claude() {
  local model="YOUR-MODEL" # e.g. claude-sonnet-5, claude-opus-5, deepseek-v4-flash
  # Claude Code asks once whether to use a custom API key and remembers the
  # answer in ~/.claude.json — a mis-click on "No" is sticky and silently
  # takes billing off Tokenly. Pre-approve this key on every launch instead.
  node -e 'const fs=require("fs");const os=require("os");const p=os.homedir()+"/.claude.json";const k=process.env.TOKENLY_API_KEY||"";if(k.length>=20){const s=k.slice(-20);let d={};try{const t=JSON.parse(fs.readFileSync(p,"utf8"));if(t&&typeof t==="object"&&!Array.isArray(t))d=t}catch(e){}let r=d.customApiKeyResponses;if(!r||typeof r!=="object"||Array.isArray(r)){r={};d.customApiKeyResponses=r}r.approved=Array.isArray(r.approved)?r.approved:[];r.rejected=(Array.isArray(r.rejected)?r.rejected:[]).filter(function(x){return x!==s});if(r.approved.indexOf(s)<0)r.approved.push(s);fs.writeFileSync(p,JSON.stringify(d,null,2))}' 2>/dev/null
  ANTHROPIC_BASE_URL="https://www.tokenly.us/api" \
  ANTHROPIC_API_KEY="$TOKENLY_API_KEY" \
  ANTHROPIC_MODEL="$model" \
  ANTHROPIC_SMALL_FAST_MODEL="$model" \
  claude "$@"
}
EOF

grep -qs "tokenly/claude.zsh" ~/.zshrc || echo 'source ~/.tokenly/claude.zsh' >> ~/.zshrc
sed -i '' '/export TOKENLY_API_KEY=/d' ~/.zshrc
echo 'export TOKENLY_API_KEY=sk-YOUR-KEY' >> ~/.zshrc
source ~/.zshrc

Windows (PowerShell)

# Create the tokenly-claude command (run once — safe to re-run)
New-Item -ItemType Directory -Force "$env:USERPROFILE.tokenly" | Out-Null
Set-Content "$env:USERPROFILE.tokenlyclaude.ps1" @'
function tokenly-claude {
  $model = "YOUR-MODEL"  # e.g. claude-sonnet-5, claude-opus-5, deepseek-v4-flash
  # Claude Code asks once whether to use a custom API key and remembers the
  # answer in ~/.claude.json — a mis-click on "No" is sticky and silently
  # takes billing off Tokenly. Pre-approve this key on every launch instead.
  node -e 'const fs=require("fs");const os=require("os");const p=os.homedir()+"/.claude.json";const k=process.env.TOKENLY_API_KEY||"";if(k.length>=20){const s=k.slice(-20);let d={};try{const t=JSON.parse(fs.readFileSync(p,"utf8"));if(t&&typeof t==="object"&&!Array.isArray(t))d=t}catch(e){}let r=d.customApiKeyResponses;if(!r||typeof r!=="object"||Array.isArray(r)){r={};d.customApiKeyResponses=r}r.approved=Array.isArray(r.approved)?r.approved:[];r.rejected=(Array.isArray(r.rejected)?r.rejected:[]).filter(function(x){return x!==s});if(r.approved.indexOf(s)<0)r.approved.push(s);fs.writeFileSync(p,JSON.stringify(d,null,2))}' 2>$null
  $env:ANTHROPIC_BASE_URL = "https://www.tokenly.us/api"
  $env:ANTHROPIC_API_KEY = $env:TOKENLY_API_KEY
  $env:ANTHROPIC_MODEL = $model
  $env:ANTHROPIC_SMALL_FAST_MODEL = $model
  claude @args
}
'@

if (!(Test-Path $PROFILE)) { New-Item -ItemType File -Force $PROFILE | Out-Null }
if (!(Select-String -Quiet -Path $PROFILE -Pattern "tokenly.claude.ps1")) {
Add-Content $PROFILE '. "$env:USERPROFILE.tokenlyclaude.ps1"'
}

# Save your key — replace sk-YOUR-KEY with the key you copied
$KEY = "sk-YOUR-KEY"
setx TOKENLY_API_KEY $KEY | Out-Null
$env:TOKENLY_API_KEY = $KEY
. $PROFILE

Run it — works right away in this window:

tokenly-claude

Plain claude still uses your normal Claude account; tokenly-claude is the one that spends Tokenly credits, on whichever catalog model you picked. Everything else — files, commands, tools — works the same.

Windows note: if PowerShell says tokenly-claude is not recognized, run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser once, then open a new window — Windows blocks profile scripts by default. Also note that in the window where you ran tokenly-claude, a plain claude keeps pointing at Tokenly until you open a new window.

Use it in your tools

VS Code

VS Code can talk to any OpenAI-compatible endpoint, so Tokenly plugs straight into its chat and agent mode — no GitHub Copilot subscription required.

Open the language model manager

Press Ctrl/Cmd + Shift + P and run Chat: Manage Language Models. (Same thing as the gear icon inside the chat model picker.)

Add Models → Custom Endpoint

Pick Custom Endpoint from the provider list — not OpenAI or Anthropic. Those talk to those companies directly; the custom option is the one that lets you point at us.

Answer the four prompts

Group name Tokenly, any display name, then paste your Tokenly key, and choose Chat Completions as the API type. VS Code then opens a file called chatLanguageModels.json.

Replace that file's contents with this, then save

Swap sk-YOUR-KEY for your key. Every model in our catalog is listed — delete any lines you don't want cluttering the picker.

[
  {
    "name": "Tokenly",
    "vendor": "customendpoint",
    "apiKey": "sk-YOUR-KEY",
    "apiType": "chat-completions",
    "models": [
      {
        "id": "claude-opus-5",
        "name": "Claude Opus 5",
        "url": "https://www.tokenly.us/api/v1/chat/completions",
        "toolCalling": true,
        "maxInputTokens": 200000,
        "maxOutputTokens": 4096
      },
      {
        "id": "gpt-5.6-sol",
        "name": "GPT-5.6 Sol",
        "url": "https://www.tokenly.us/api/v1/chat/completions",
        "toolCalling": true,
        "maxInputTokens": 200000,
        "maxOutputTokens": 4096
      },
      {
        "id": "glm-5.2",
        "name": "GLM-5.2",
        "url": "https://www.tokenly.us/api/v1/chat/completions",
        "toolCalling": true,
        "maxInputTokens": 200000,
        "maxOutputTokens": 4096
      },
      {
        "id": "claude-sonnet-5",
        "name": "Claude Sonnet 5",
        "url": "https://www.tokenly.us/api/v1/chat/completions",
        "toolCalling": true,
        "maxInputTokens": 200000,
        "maxOutputTokens": 4096
      },
      {
        "id": "gpt-5.6-terra",
        "name": "GPT-5.6 Terra",
        "url": "https://www.tokenly.us/api/v1/chat/completions",
        "toolCalling": true,
        "maxInputTokens": 200000,
        "maxOutputTokens": 4096
      },
      {
        "id": "gpt-5.6-luna",
        "name": "GPT-5.6 Luna",
        "url": "https://www.tokenly.us/api/v1/chat/completions",
        "toolCalling": true,
        "maxInputTokens": 200000,
        "maxOutputTokens": 4096
      },
      {
        "id": "deepseek-v4-flash",
        "name": "DeepSeek V4 Flash",
        "url": "https://www.tokenly.us/api/v1/chat/completions",
        "toolCalling": true,
        "maxInputTokens": 200000,
        "maxOutputTokens": 4096
      }
    ]
  }
]

Pick a Tokenly model in chat

Open the chat view, click the model picker, and choose one from the Tokenly group. Ask it something — that request is already running on your credits.

Agent mode works. VS Code only offers a model for agent tasks when it can call tools, which is why every entry above sets "toolCalling": true. Leave it in or the model shows up for chat but disappears the moment you switch to agent.

Want longer answers? maxOutputTokens is set to 4,096 because that is what this endpoint allows per reply. If you need more, change a model's url to https://www.tokenly.us/api/v1/messages, set "apiType": "messages" on that entry, and raise the number to 8,192.

Inline code completions are not part of this. The grey ghost-text suggestions as you type still come from GitHub Copilot and still need a Copilot plan — bringing your own key covers chat and agent mode only. That is a VS Code rule, not ours.

Type tokenly-remaining as a chat message any time to see your balance. It costs nothing and works even at zero credits.

Use it in code

Python

The official OpenAI SDK works as-is — you only change two values.

# 1) install the SDK:   pip install openai
from openai import OpenAI

client = OpenAI(
    base_url="https://www.tokenly.us/api/v1",
    api_key="sk-YOUR-KEY",  # your Tokenly key
)

reply = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Say hello!"}],
)
print(reply.choices[0].message.content)

Save as hello.py, run with python hello.py.

Use it in code

JavaScript / Node

Same idea: the official SDK plus a custom base URL.

// 1) install the SDK:   npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://www.tokenly.us/api/v1",
  apiKey: "sk-YOUR-KEY", // your Tokenly key
});

const reply = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [{ role: "user", content: "Say hello!" }],
});
console.log(reply.choices[0].message.content);

Use it in code

curl

The rawest way to test your key — paste into any terminal.

curl https://www.tokenly.us/api/v1/chat/completions \
  -H "Authorization: Bearer sk-YOUR-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "Say hello!"}]
  }'

Every response includes x-tokenly-credits-charged and x-tokenly-credits-remaining headers, so you can watch your spend per call.

Credits

How credits work

Credits are the only currency here — no dollars, no invoices. Every model charges per token at its own rate.

Model	Credits / 1M in	Credits / 1M out
Claude Opus 5claude-opus-5	208	1,038
GPT-5.6 Solgpt-5.6-sol	30	178
GLM-5.2glm-5.2	143	498
Claude Sonnet 5claude-sonnet-5	83	415
GPT-5.6 Terragpt-5.6-terra	11.9	71.2
GPT-5.6 Lunagpt-5.6-luna	1.2	7.2
DeepSeek V4 Flashdeepseek-v4-flash	28	56

Exact billing: charges are precise to 0.01 credits — a tiny call costs 0.01, not a rounded-up whole credit.
DeepSeek's cache discount passes through: cached input tokens on DeepSeek bill at 2% of the input price. Claude, GPT and GLM bill cached input at the full input rate — our upstream reports no cache discount on them, and we don't advertise savings we can't verify.
One pool per account: all your keys and the Chat share the same balance.
Cap: your balance can hold at most 3,000 credits. At the cap, earning pauses (you'll see a “Maxxed out” badge) until you spend some.
Expiry: each batch of credits expires 3 months after you receive it. Your dashboard lists exactly what expires when.

Credits

Check your balance in-chat

No dashboard needed — ask for your balance right inside whatever tool you connected.

Send this as a message — in Codex, Claude Code, Chat, or any app using your key:

tokenly-remaining

Tokenly answers instantly with your live balance instead of calling the model:

[Tokenly] Balance: 202.16 credits (cap 3,000)
Expiring: 152.16 credits on Oct 18, 2026 · 50.00 credits on Sep 30, 2026
Earn more: https://www.tokenly.us/earn

Always free: the check never costs credits — and it still works when your balance is at zero.
Automatic reminders: when your balance drops below 50 credits, replies start carrying a short [Tokenly] note with your balance and the earn link, so you're never surprised when your credits run out.

Models

Switch models in-chat

One all-models key runs every model — swap between them from inside your tool, no config edits.

Send this as a message to see the model this key is using and the full menu:

tokenly-model

Tokenly replies with the list — reply with a number to switch:

[Tokenly] Current model: DeepSeek V4 Flash (deepseek-v4-flash)
Reply with a number to switch this key:
  1. Claude Opus 5 · Anthropic
  2. GPT-5.6 Sol · OpenAI
  3. GLM-5.2 · Zhipu
  4. Claude Sonnet 5 · Anthropic
  5. GPT-5.6 Terra · OpenAI
  6. GPT-5.6 Luna · OpenAI
  7. DeepSeek V4 Flash · DeepSeek  ← current
Or reply "tokenly-model reset" to use the model your app sends.

Sticks to the key: your choice applies to every request on that key — across Codex, Claude Code, and any SDK — until you change it. Your tool's own model setting is ignored while an override is active.
One-shot forms too: tokenly-model 3 or tokenly-model gpt-5.6-sol switch in a single message.
Undo anytime: send tokenly-model reset to clear the override and go back to the model your app is configured to send.
Free & billed per model: the command itself never costs credits; each request is billed at the price of whichever model is active.

Credits

When you run out

Nothing breaks and nothing needs reinstalling — your tools just start returning this error:

{
  "error": {
    "message": "You're out of credits. Earn free credits in ~60s: https://www.tokenly.us/earn",
    "type": "insufficient_credits",
    "code": "insufficient_credits",
    "portal": "https://www.tokenly.us/earn",
    "portal_url": "https://www.tokenly.us/earn",
    "balance": 0
  }
}

The fix takes about a minute: open the Earn page, complete a survey or watch a sponsored post, and your credits land instantly. The same key starts working again on the very next call — nothing to restart. The feed resets daily.

Help

Troubleshooting

“Invalid or revoked API key” (401)

The key was mistyped, or it was revoked. Check for extra spaces when pasting; if in doubt, create a fresh key and use that.

“You're out of credits” (402)

That's the credits-empty signal working as designed — earn more at /earn and retry. Nothing is broken.

Codex says the profile can't be used / mentions a legacy profile

Codex changed its config format in a recent update. Delete the [profiles.tokenly] block from ~/.codex/config.toml if you added one long ago, and make sure ~/.codex/tokenly.config.toml exists (step 3 of the Codex guide writes it).

Codex warns “Model metadata for your model not found”

Your setup predates our model catalog. Re-run step 3 of the Codex guide — it now downloads a small catalog file that removes the warning. (Ignoring it is also fine; Codex falls back to safe defaults.)

PowerShell says “tokenly-claude is not recognized” (Windows)

Windows blocks profile scripts by default. Run once: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser — then open a new PowerShell window.

“Model … does not exist on Tokenly” (404)

The tool is sending a model name we don't serve (often gpt-4o). Set the model to one from our catalog (e.g. deepseek-v4-flash) in the tool's settings, and untick other models if the tool lets you.

Requests suddenly slow or failing with 429

Each key allows 30 requests per minute. Agents that fire rapid calls can brush against it — wait a few seconds, or split work across two keys.

API Error: 401 Invalid or revoked API key

Your tool is sending an old, revoked, or placeholder key. Fastest fix: copy a fresh key from the dashboard and re-paste the setup block with it — it replaces any old or duplicate key lines automatically.

My terminal says TOKENLY_API_KEY is empty

You're in a window opened before you saved the key. On macOS, open a brand-new terminal window or run: source ~/.zshrc. On Windows, setx only affects new windows — close the terminal and open a fresh one.

Ready?

Create a key, paste one block into your tool, and you're coding on credits.

Create your key