Claude Code

Claude Code connects to TokenFlux through the Anthropic Messages API. Requests are charged to your TokenFlux balance.

This guide was tested with Claude Code 2.1.302 and claude-fable-5 for streaming replies.

Before you startCopy Anchor Link

1. Start with Claude Code installed. Configuration details are in the official gateway connection guide and model configuration.
2. Create and copy a key on the web app’s API keys page. The full key is shown only once.
3. Check that your balance is above zero on Billing.
4. Copy a model ID from Models and pricing and check its supported protocols.

Set the base URL and credentialCopy Anchor Link

In Bash or Zsh, set these variables. Replace YOUR_MODEL_ID with a model that supports Messages and tool calls. Use a model with native Messages support when you need prompt caching.

export TOKENFLUX_API_KEY="YOUR_TOKENFLUX_KEY"
export ANTHROPIC_BASE_URL="https://tokenflux.ai"
export ANTHROPIC_AUTH_TOKEN="$TOKENFLUX_API_KEY"
export ANTHROPIC_MODEL="YOUR_MODEL_ID"

Replace YOUR_TOKENFLUX_KEY with the key you copied. Keep the key out of Git.

Claude Code adds /v1/messages to this base URL. Do not append /v1/messages yourself. The gateway credential pays from your TokenFlux balance. Check existing Claude Code settings for an env block that overrides these shell variables.

Choose a modelCopy Anchor Link

Change ANTHROPIC_MODEL before the next launch, or use claude --model YOUR_MODEL_ID. Use a full model ID from the TokenFlux catalog rather than a built-in alias.

Verify the connectionCopy Anchor Link

Run these commands in a scratch directory. If the client asks for file access, check the path before you approve it.

printf 'TOKENFLUX_GUIDE_OK\n' > marker.txt
claude -p "Read marker.txt with the Read tool and return its contents" \
  --tools Read --allowedTools Read

The reply should contain TOKENFLUX_GUIDE_OK. Check the model, key, token count and cost on Usage. Delete marker.txt after the test.

TroubleshootingCopy Anchor Link

An HTML response or 404. Set ANTHROPIC_BASE_URL to https://tokenflux.ai. The request must reach /v1/messages.

A login prompt or the wrong account is billed. Export ANTHROPIC_AUTH_TOKEN in the same terminal that starts Claude Code. Run /status to check the credential source and base URL.

Prompt caching or thinking does not work. Use a model with native Messages support. Protocol conversion can lose cache_control and thinking signatures. A cache hit also depends on the model and the prompt; this setup does not guarantee one.

401, 429 or a model error. Check that the key is enabled, the full model ID is correct, and your account has balance and available rate limits. Do not switch models automatically.

API referenceCopy Anchor Link

See Messages, Models and API overview.