Quota Switch

Auto-rotate API keys when rate-limited. Quota Switch manages multi-provider API key vaults, injects fresh keys into CLI tool configs (Claude Code, Codex, OpenAI), and automatically switches keys when your proxy provider hits your usage cap.

Features

• Key Vault — store keys from any provider (OpenAI, Anthropic, Google, Groq, DeepSeek, etc.)
• Auto-Rotation — run monitors known tools for 402/429/rate-limit errors, marks the key, and retries with the next available key
• Config Injection — writes the best available key and gateway URL into tool config files (Claude Code, Codex, OpenAI CLI)
• Gateway Probing — check / sync probes live rate-limit headers from your proxy
• Least-Recently-Used Selection — picks the key that was used longest ago
• Shared Key State — duplicate keys across entries stay in sync (cooldown, error count, enabled/disabled)
• JSON Import — bulk import keys from a keys.json file; auto-imported on first run
• Environment Import — pull keys from OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.

Installation

Requires Python 3.11+ (stdlib only — no pip dependencies).

pip (recommended)

git clone https://github.com/yourusername/quota-switch.git
cd quota-switch
pip install .
quotaswitch --help

This installs the quotaswitch command to your PATH via the [project.scripts] entry point.

Editable install (development)

git clone https://github.com/yourusername/quota-switch.git
cd quota-switch
pip install -e .

Without pip (manual PATH)

Use the included quotaswitch.bat launcher (Windows) or add the repo directory to PATH:

# Clone, then add to PATH
set PATH=%PATH%;C:\path\to\quota-switch
quotaswitch --help

Quick Start

# Add keys
quotaswitch add openai sk-xxx --gateway https://my-proxy.com/v1
quotaswitch add anthropic sk-ant-xxx

# List available keys
quotaswitch list

# Inject the best key into Claude Code config
quotaswitch inject claude

# Run a command with auto-rotation on rate-limit
quotaswitch run --monitor -- claude

# Check live rate-limit status for all keys
quotaswitch sync

CLI Reference

Command	Description
add	Add a new API key
list	List all keys with status
status	Detailed key information
select	Print best available key ID or value
run	Run command with key injection and auto-rotation
check	Probe gateway for live rate-limit data
sync	Check all keys (alias for check --all)
ratelimit	Manually mark a key as rate-limited
available / unmark	Clear cooldown, mark key available
inject	Write best key and gateway into tool config
disable / enable	Toggle key state
remove	Remove key from vault
config	View or update vault configuration
import-env	Import keys from environment variables
import	Import keys from a JSON file

run modes

Monitored tool runs (default for known tools): injects the best key into the tool config, streams output, scans for rate-limit patterns, marks the limited key, injects the next key, and restarts the command.

quotaswitch run -- claude
quotaswitch run -- codex

Explicit monitor (--monitor): enables the same output scanner for commands that are not recognized as supported tools.

quotaswitch run --monitor -- codex run 'write tests'
quotaswitch run --monitor -- claude

Passthrough (--passthrough): injects the best key into the tool config, then runs your command without output scanning. If the command exits non-zero, rotates to the next key and retries.

quotaswitch run --passthrough -- claude

inject

Writes the best available key into a tool's config file. Supported tools:

Tool	Key File	URL File
claude	~/.claude/settings.json (env.ANTHROPIC_API_KEY)	same file (env.ANTHROPIC_BASE_URL)
codex	~/.codex/auth.json (OPENAI_API_KEY)	~/.codex/config.toml ([model_providers.*].base_url)
openai	~/.config/openai/config.json (api_key)	same file (base_url)

quotaswitch inject claude
quotaswitch inject codex --provider openai

Vault

Keys are stored in ~/.apikey/vault.json. Override with:

export QUOTASWITCH_VAULT=/path/to/vault.json
quotaswitch --vault /path/to/vault.json ...

Config

Setting	Default	Description
cooldown_seconds	3600	Cooldown duration when rate-limited
max_retries	3	Auto-retry attempts before giving up
max_errors	5	Auto-disable key after this many errors

quotaswitch config --cooldown 7200 --max-retries 5

Import

From keys.json

Place a keys.json in the project directory. Format:

[
  {
    "provider": "openai",
    "key": "sk-...",
    "model": "gpt-4",
    "gateway": "https://my-proxy.com/v1"
  }
]

Auto-imported on first vault creation. Manual import:

quotaswitch import keys.json
quotaswitch import keys.json --update  # update existing keys by ID

From environment variables

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
quotaswitch import-env

How It Works

1. Key selection sorts available keys by last_used (ascending) — LRU policy.
2. Config injection writes the selected key + gateway into the tool's config file(s), preserving all other config fields.
3. Monitor mode pipes output through a rolling scanner that detects 402, 429, 529, and rate-limit error patterns even when terminal UI output is not newline-delimited. On match, the key is marked with a cooldown, the next key is selected + injected, and the wrapped command is restarted so it inherits the new environment.
4. Passthrough mode injects on start, then rotates on non-zero exit.
5. Error parsing handles multiple formats: proxy reset time messages, Retry-After headers, and duration patterns.

License

MIT