Designed for Claude Code, also compatible with Codex and OpenClaw
OpenRouter Cost Controls
Overview
OpenRouter provides per-key credit limits, a credit balance API, and per-generation cost queries. Combined with client-side budget middleware, you can enforce hard spending caps at the key level and soft caps in your application. This skill covers key-level limits, per-request cost tracking, budget enforcement middleware, and alert systems.
Prerequisites
An OpenRouter API key (sk-or-v1-...) exported as OPENROUTER_API_KEY — see the openrouter-install-auth skill for setup
Python 3.8+ with the OpenAI SDK and requests; Node.js 18+ for the TypeScript per-request cost logger in the references
curl, jq, and bc for the balance check and the Budget Alert Script
An OpenRouter management key exported as OPENROUTER_MGMT_KEY if you provision per-key credit limits via POST /api/v1/keys
Instructions
Query GET /api/v1/auth/key per Check Credit Balance to see credits used, the key's limit, remaining balance, free-tier status, and rate limit.
Provision scoped keys per Per-Key Credit Limits — POST /api/v1/keys with a dollar limit (e.g. $50 for backend-prod) using the management key, then list keys to review usage against limits per service.
Deploy the BudgetEnforcer from Budget Enforcement Middleware: check_budget() rejects any request whose pre-flight estimate exceeds the per-request or daily cap, and record_cost() books the exact spend from GET /api/v1/generation?id=.
Cut unit cost with Cost-Saving Model Variants: :floor picks the cheapest provider, :free costs nothing where available, and the task-based ROUTING table sends classification to gpt-4o-mini and simple Q&A to Llama 3.1 8B.
Schedule the Budget Alert Script (cron) so a balance drop below the threshold fires an alert to Slack or PagerDuty.
Set max_tokens on every request and enable auto-topup per Enterprise Considerations to cap completion cost without risking an outage.
Check Credit Balance
# Current balance and limits
curl -s https://openrouter.ai/api/v1/auth/key \
-H "Authorization: Bearer " | jq
# :floor variant -- cheapest provider for a model
response = client.chat.completions.create(
model="anthropic/claude-3.5-sonnet:floor", # Cheapest provider
messages=[{"role": "user", "content": "Summarize this..."}],
max_tokens=500,
)
# :free variant -- free providers (where available)
response = client.chat.completions.create(
model="google/gemma-2-9b-it:free",
messages=[{"role": "user", "content": "Hello"}],
max_tokens=100,
)
# Route simple tasks to cheap models
ROUTING = {
"classification": "openai/gpt-4o-mini", # $0.15/$0.60 per 1M"summarization": "anthropic/claude-3-haiku", # $0.25/$1.25 per 1M"code_generation": "anthropic/claude-3.5-sonnet", # $3/$15 per 1M"simple_qa": "meta-llama/llama-3.1-8b-instruct", # $0.06/$0.06 per 1M
}
Budget Alert Script
#!/bin/bash# Alert when credits drop below threshold
THRESHOLD=5.0
REMAINING=$(curl -s https://openrouter.ai/api/v1/auth/key \
-H "Authorization: Bearer $OPENROUTER_API_KEY" | \
jq '((.data.limit // 0) - .data.usage)')
if (( $(echo "$REMAINING < $THRESHOLD" | bc -l) )); thenecho"ALERT: OpenRouter credits low: \$$REMAINING remaining"# Send to Slack, PagerDuty, etc.fi
Output
A credit-balance JSON summary: credits_used, credit_limit, remaining, is_free_tier, and rate_limit for the active key
Newly provisioned API keys with hard dollar limits, plus a per-key usage / limit listing from the management API
ValueError rejections from the middleware when a request would exceed the per-request or daily budget, and a running daily-spend total booked from actual generation costs
Alert lines such as ALERT: OpenRouter credits low: $4.87 remaining whenever the balance crosses the configured threshold
Examples
Check what's left on a key before turning on traffic:
