Skip to main content
skill CX Codex

openrouter-pricing-basics — Claude Code skill: how to install

openrouter-pricing-basics calculates OpenRouter token costs, tracks credit balances, and compares model rates. Helpful when estimating LLM spend or picking cheaper providers.

MIT 2 installs ★ 2,935 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add jeremylongshore/tons-of-skills-marketplace --skill openrouter-pricing-basics -a claude-code
Open on GitHub

What openrouter-pricing-basics does

This skill provides direct instructions for managing spend on OpenRouter. The platform bills prompt and completion tokens at separate rates, deducting them from a prepaid credit pool. Credits incur a 5.5% processing fee with an $0.80 minimum. Reasoning tokens are billed at the completion rate.

Inside are Python scripts and shell commands for querying platform endpoints. Public rates can be retrieved without authentication via GET /api/v1/models. In contrast, checking account balances via /api/v1/auth/key or retrieving exact request charges requires an active OPENROUTER_API_KEY, curl, jq, and Python 3.8+ with requests and the OpenAI SDK.

To trim expenses, the guide demonstrates special model suffixes. Adding :floor automatically routes requests to the lowest-priced provider for that model. The :free variant accesses zero-cost endpoints, which limit volume between 50 and 1000 daily requests depending on credit tier.

What it helps with

  • calculate request costs from prompt and completion token counts
  • check remaining credit balance using the auth key endpoint
  • route completions to the lowest-priced provider using :floor
  • fetch the exact dollar charge for a completed generation ID

Example prompts for the agent

  • Estimate the cost for 1000 prompt tokens and 500 completion tokens on anthropic/claude-3.5-sonnet.
  • Check my current OpenRouter credit balance using curl and my API key.
  • Show how to structure a request with the :floor variant to reduce costs.

How to install openrouter-pricing-basics

1Skills CLI (Vercel)

npx skills add jeremylongshore/tons-of-skills-marketplace --skill openrouter-pricing-basics -a claude-code

2Manually: put the files in place

~/.claude/skills/openrouter-pricing-basics/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/openrouter-pricing-basics/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about openrouter-pricing-basics

How to install openrouter-pricing-basics in Claude Code?

Run npx skills add jeremylongshore/tons-of-skills-marketplace --skill openrouter-pricing-basics -a claude-code.

What does openrouter-pricing-basics do?

It teaches the agent how to calculate OpenRouter token expenses, check prepaid credit balances, and route traffic to cheaper providers.

What tools are needed to use this skill?

You need an OPENROUTER_API_KEY, curl, jq, and Python 3.8+ with both requests and the OpenAI SDK installed.

Source text

SKILL.md · MIT
---
name: openrouter-pricing-basics
description: 'Understand OpenRouter pricing, calculate costs, and optimize spend.
  Use when budgeting, comparing model costs, or tracking spend. Triggers: ''openrouter
  pricing'', ''openrouter cost'', ''model pricing'', ''openrouter budget'', ''how
  much does openrouter cost''.

  '
allowed-tools: Read, Write, Edit, Grep, Bash(python3:*), Bash(curl:*), Bash(jq:*)
version: 1.20.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- openrouter
- pricing
- cost-optimization
compatibility: Designed for Claude Code
---
# OpenRouter Pricing Basics

## Overview

OpenRouter charges per token with separate rates for prompt (input) and completion (output) tokens. Prices are listed per token in the models API (multiply by 1M for per-million rates). Credits are prepaid with a 5.5% processing fee ($0.80 minimum). Free models are available for testing and low-volume use.

## Prerequisites

- An OpenRouter API key (`sk-or-v1-...`) exported as `OPENROUTER_API_KEY` — see the `openrouter-install-auth` skill for setup
- `curl` and `jq` for the model-pricing and credit-balance queries
- Python 3.8+ with the OpenAI SDK plus the `requests` package for the cost-calculation and generation-endpoint snippets
- Prepaid credits for paid models — the public models/pricing endpoint needs no auth, but real completions require credits or a `:free` model

## Instructions

1. Read How Pricing Works: prepaid credits (5.5% fee, $0.80 minimum) are drawn down per request as `(prompt_tokens * prompt_rate) + (completion_tokens * completion_rate)`.
2. Query per-token rates via `GET /api/v1/models` per Query Model Pricing, and place candidate models in the Cost Tiers table (free → premium).
3. Estimate spend before committing: run `estimate_cost()` from Calculate Request Cost with your expected prompt/completion token counts.
4. After sending real traffic, fetch the exact charge with `GET /api/v1/generation?id=` per Track Actual Cost Per Request.
5. Watch the balance via `GET /api/v1/auth/key` per Check Credit Balance, and enable auto-topup for production keys.
6. Cut costs with the `:floor` and `:free` variants per Save Money with Variants, and check Special Pricing for reasoning tokens, image inputs, per-request fees, and BYOK.

## How Pricing Works

1. **Buy credits** at [openrouter.ai/credits](https://openrouter.ai/credits) (5.5% fee, $0.80 minimum)
2. **Each request** deducts `(prompt_tokens * prompt_rate) + (completion_tokens * completion_rate)`
3. **Check balance** via `GET /api/v1/auth/key` or the dashboard
4. **Auto-topup** is available to prevent service interruption

## Query Model Pricing

```bash
# Get pricing for all models
curl -s https://openrouter.ai/api/v1/models | jq '.data[] | select(.id == "anthropic/claude-3.5-sonnet") | {
  id: .id,
  prompt_per_M: ((.pricing.prompt | tonumber) * 1000000),
  completion_per_M: ((.pricing.completion | tonumber) * 1000000),
  context: .context_length
}'
# → { "id": "anthropic/claude-3.5-sonnet", "prompt_per_M": 3, "completion_per_M": 15, "context": 200000 }
```

## Cost Tiers (Representative)

| Tier | Example Model | Prompt/1M | Completion/1M | Use Case |
|------|--------------|-----------|---------------|----------|
| Free | `google/gemma-2-9b-it:free` | $0.00 | $0.00 | Testing, prototyping |
| Budget | `meta-llama/llama-3.1-8b-instruct` | $0.06 | $0.06 | Simple Q&A, classification |
| Mid | `openai/gpt-4o-mini` | $0.15 | $0.60 | General purpose |
| Standard | `anthropic/claude-3.5-sonnet` | $3.00 | $15.00 | Complex reasoning, code |
| Premium | `openai/o1` | $15.00 | $60.00 | Deep reasoning |

## Calculate Request Cost

```python
def estimate_cost(model_id: str, prompt_tokens: int, completion_tokens: int) -> float:
    """Calculate cost for a single request."""
    import requests
    models = requests.get("https://openrouter.ai/api/v1/models").json()["data"]
    model = next((m for m in models if m["id"] == model_id), None)
    if not model:
        raise ValueError(f"Model {model_id} not found")

    prompt_rate = float(model["pricing"]["prompt"])       # Cost per token
    completion_rate = float(model["pricing"]["completion"])
    return (prompt_tokens * prompt_rate) + (completion_tokens * completion_rate)

# Example: Claude 3.5 Sonnet, 1000 prompt + 500 completion tokens
cost = estimate_cost("anthropic/claude-3.5-sonnet", 1000, 500)
print(f"Estimated cost: ${cost:.6f}")  # ~$0.0105
```

## Track Actual Cost Per Request

```python
import requests

# Method 1: From response usage (estimate)
response = client.chat.completions.create(
    model="anthropic/claude-3.5-sonnet",
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=100,
)
# response.usage.prompt_tokens, response.usage.completion_tokens

# Method 2: Query generation endpoint (exact cost from OpenRouter)
gen = requests.get(
    f"https://openrouter.ai/api/v1/generation?id={response.id}",
    headers={"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}"},
).json()
print(f"Exact cost: ${gen['data']['total_cost']}")
print(f"Tokens: {gen['data']['tokens_prompt']} prompt + {gen['data']['tokens_completion']} completion")
```

## Check Credit Balance

```bash
curl -s https://openrouter.ai/api/v1/auth/key \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" | jq '{
    credits_used: .data.usage,
    credit_limit: .data.limit,
    remaining: ((.data.limit // 0) - .data.usage),
    is_free_tier: .data.is_free_tier
  }'
```

## Save Money with Variants

```python
# :floor variant picks the cheapest provider for a model
response = client.chat.completions.create(
    model="anthropic/claude-3.5-sonnet:floor",  # Cheapest provider
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=100,
)

# :free variant uses free providers (where available)
response = client.chat.completions.create(
    model="google/gemma-2-9b-it:free",
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=100,
)
```

## Special Pricing

| Item | Pricing |
|------|---------|
| **Reasoning tokens** | Charged as output tokens at completion rate |
| **Image inputs** | Per-image charge listed in `pricing.image` |
| **Per-request fee** | Some models charge a flat fee per request (`pricing.request`) |
| **BYOK** | First 1M requests/month free; then 5% of normal provider cost |
| **Free model limits** | 50 req/day (free users), 1000 req/day (with $10+ credits) |

## Output

- A per-model pricing record from the models API: `prompt_per_M`, `completion_per_M`, `context` (e.g. $3 / $15 per 1M tokens for `anthropic/claude-3.5-sonnet`)
- A pre-request dollar estimate from `estimate_cost()` and the exact post-request figures from the generation endpoint: `total_cost`, `tokens_prompt`, `tokens_completion`
- A credit-balance snapshot from `/api/v1/auth/key`: `credits_used`, `credit_limit`, `remaining`, `is_free_tier`

## Examples

Check remaining credits before a batch job:

```bash
curl -s https://openrouter.ai/api/v1/auth/key \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" | jq '{
    credits_used: .data.usage,
    remaining: ((.data.limit // 0) - .data.usage)
  }'
# {"credits_used": 2.34, "remaining": 47.66}
```

Estimating first keeps surprises out: 1,000 prompt + 500 completion tokens on `anthropic/claude-3.5-sonnet` comes to roughly $0.0105 via `estimate_cost()`, and the generation endpoint then confirms the exact charge. More worked examples: `references/examples.md`.

## Error Handling

| HTTP | Cause | Fix |
|------|-------|-----|
| 402 | Insufficient credits | Top up at [openrouter.ai/credits](https://openrouter.ai/credits) or use `:free` model |
| 402 | Key credit limit reached | Increase key limit or use a different key |

## Enterprise Considerations

- Set per-key credit limits via the dashboard or provisioning API to isolate blast radius
- Query `/api/v1/generation?id=` after each request for exact cost auditing
- Use `:floor` variant to automatically pick the cheapest provider
- Route simple tasks to budget models and complex tasks to premium models (see openrouter-model-routing)
- Set `max_tokens` on every request to cap completion cost
- Enable auto-topup to prevent service interruptions in production

## References

- Examples | Errors
- [Pricing](https://openrouter.ai/pricing) | [Credits](https://openrouter.ai/credits) | [Models API](https://openrouter.ai/docs/api/api-reference/models/get-models)

© Jeremy Longshore · MIT · jeremylongshore/tons-of-skills-marketplace

Similar skills

All skills for AI and ML →

From the same set139

The whole set →
excel-variance-analyzer excel-variance-analyzer is a Claude Code skill that compares budget and actual figures in Excel, flags variances, builds waterfall charts, and identifies root causes. CX Codex +1 3installs helm-chart-generator The helm-chart-generator skill guides Helm chart generation, creates configuration drafts and checks the result. It fits requests about Helm generators and related DevOps work. CX Codex +1 3installs brand-strategy Build or review a seven-part brand strategy with an AI coding assistant. Use it for a brand brief, positioning work, or messaging revisions. CX Codex +1 2installs seo-meta-generator An auto-activating skill for frontend work. It kicks in when a prompt mentions seo, seo generator, or seo meta generator, and walks through SEO metadata generation. CX Codex +1 2installs scanning-for-xss-vulnerabilities scanning-for-xss-vulnerabilities scans application code for reflected, stored, and DOM-based XSS. Use it when reviewing input handling or checking a web app before release. CX Codex +1 2installs excel-lbo-modeler excel-lbo-modeler — a skill that builds leveraged buyout models in Excel: deal structure, debt schedules, IRR and MOIC. Use it when you need a quick read on PE returns for a transaction. CX Codex +1 2installs excel-formula-generator excel-formula-generator generates spreadsheet formulas and configurations for business automation tasks. Activates on requests mentioning Excel operations and formula design. CX Codex +1 2installs juicebox-cost-tuning The juicebox-cost-tuning skill helps control Juicebox spending by cutting redundant searches and profile enrichment, then checking changes against a quota baseline. CX Codex +1 1installs

Project sponsors

Companies that keep this analytics open