Claude Code API Key Setup Without a Subscription: ANTHROPIC_BASE_URL, Env Vars and Fixes (2026)
Run Claude Code on a metered API key instead of a subscription: the two env vars, settings.json and apiKeyHelper options, model codes, a degradation check and the errors you will hit.
1. Subscription or API key: pick by how you work
Claude Code authenticates two ways. A subscription gives a flat monthly fee with a usage window that resets every few hours; heavy agent sessions run into the window. An API key is metered: you pay for tokens consumed, there is no window, and a session keeps running while balance remains. Light, occasional use usually favours the subscription. Long sessions with many tool calls, large repos and several hours a day usually favour metered billing, because cost tracks real usage and nothing throttles you mid-task. The two are not exclusive: many developers keep a subscription for casual use and a metered key for the heavy projects. If you cannot pay the official vendor at all, because the card is declined or the region is not billed, the key route through a compatible endpoint is the path that does not depend on that payment.
2. The two variables that matter
Claude Code officially supports `ANTHROPIC_BASE_URL`, which redirects its requests to a different Anthropic-compatible endpoint; that is a documented mechanism, not a hack. Set that together with `ANTHROPIC_AUTH_TOKEN`, and the rest of the tool is untouched. Create a key in the cocodot console (it starts with cocodot-), then export the two variables in the shell where you run claude. Put them in ~/.zshrc or ~/.bashrc to persist them. On Windows PowerShell use `$env:ANTHROPIC_BASE_URL = "..."` for the session or add them under system environment variables. The base URL must be exactly https://cocodot.co/api/ai with no /v1: Claude Code appends its own path, and doubling it up is a common misconfiguration.
export ANTHROPIC_BASE_URL="https://cocodot.co/api/ai"
export ANTHROPIC_AUTH_TOKEN="cocodot-xxxxxxxx"
export ANTHROPIC_MODEL="mco-7"
export ANTHROPIC_SMALL_FAST_MODEL="mch-1"
claude3. Persist it properly: settings.json and apiKeyHelper
Shell exports are fine for a laptop, but projects and teams want something more durable. Claude Code reads an env block from its settings.json, per user or per project, so the same variables can live there instead of your shell profile. Keep the key out of any file you commit: put the base URL and model codes in the project file and the key in your user-level settings or a secret manager. If your key rotates, the apiKeyHelper setting lets Claude Code call a script that prints a fresh key, which suits secret managers and short-lived credentials. To see which credential and endpoint are actually active, open the status view inside Claude Code; if you previously logged in with a subscription, log out first or the old login may still win over your variables.
4. Choose a main model and a fast model
Claude Code runs two models at once. The main model reads code, plans and edits; the fast model handles chores like summarising files or quick yes-no decisions. Point the main variable at the strongest tier you need, drop to a mid tier when budget matters, and keep the fast variable on the smallest tier, since chores are high-volume and low-difficulty. You can change either by editing the variable and restarting claude; the same key works for all of them. The endpoint accepts both its short codes (such as mco-8) and versioned official names (such as claude-opus-5-5); copy the exact names from the model list in the console. A bare name such as opus routes to an older model. Opus 5.5 uses mco-8 or claude-opus-5-5, and Sonnet 5.5 uses mcs-7 or claude-sonnet-5-5.
5. How billing behaves in long agent sessions
Billing is per token, with listed prices for the Claude, GPT and Gemini lines not above the maker's official list; check the pricing page for each model's current number. Top-ups are in CNY by Alipay or WeChat and land as a USD balance, and API usage has no extra fee. Agent sessions have a particular shape: every turn re-sends a long, mostly unchanged context, which is why caching matters. Here, cache hits bill at half the standard input price, and cache writes at 1.25x the input price (2x for the portion written to the 1-hour cache), the same structure as the official pricing. Official direct billing charges far less for cache hits, so for sessions dominated by cache reads, going direct is cheaper on that line. The advantages of a metered relay are on output, on uncached input, and on being payable at all. The console lists tokens and charges per call, so one real task is enough to measure your actual cost per session.
6. Check the model is real
The classic worry with any third-party endpoint is substitution: you are billed for a flagship and served something cheaper. Do not judge by tone. A model's own claim about its identity is weak evidence, and one good answer proves nothing. Use repeatable checks: compare the model list and the reported model field, look at usage numbers against your own token estimate, probe context-window behaviour with a long input, and repeat the same prompts over time to get a baseline. The open-source checker at probe.cocodot.co does a set of these against any Anthropic- or OpenAI-compatible endpoint, vendor-neutral. Use a temporary, low-balance key for any third-party checker, never paste a real key into a URL or screenshot, and delete the temporary key afterwards.
7. Errors and what they mean
401 or authentication failure: the token is not the full key, has a stray space, or the balance is zero; remember the variable is AUTH_TOKEN. 404 or connection errors that look like routing problems: the base URL has /v1 on the end or a typo; it should end at /api/ai. Model errors: a typo in the model name, or a code that has been retired. Streaming or tool-call oddities: the Anthropic-compatible endpoint is in beta; chat, file reads and writes, command execution and streaming are covered, edge cases are fixed when reported. Unexpected cost: you left the fast model unset, so chores run at flagship rates. If a login screen appears at start, an old subscription login is overriding the environment variables.
8. Two other routes from the same key
The same balance works elsewhere. Inside editors such as Cursor, Cline or Cherry Studio, use the OpenAI-compatible endpoint https://cocodot.co/api/ai/v1 as a custom provider and type a model code by hand. If you specifically want the official subscription, a US-BIN virtual card from cocodot can pay for it, with the account and quota being the vendor's own; fees for the card are on the pricing page, including 0% on spending, a $0.60 fee on purchases under $20 and a monthly fee while the card is active. We have not verified every merchant, so start with a small charge. All of these draw on one wallet, which makes it easy to try the metered route first and keep the subscription as a fallback.
Claude Code environment variables for a compatible endpoint
| Variable | Value | What it does | Common mistake |
|---|---|---|---|
| ANTHROPIC_BASE_URL | https://cocodot.co/api/ai | Where requests are sent | Adding /v1 on the end, which produces 404s |
| ANTHROPIC_AUTH_TOKEN | your key | Sent as a bearer token | Using ANTHROPIC_API_KEY semantics, or a key with a stray space |
| ANTHROPIC_MODEL | versioned official name or model code | Main reasoning and coding model | A name without a version (such as a bare opus), which routes to an older model |
| ANTHROPIC_SMALL_FAST_MODEL | fast model code | Summaries and quick chores | Leaving it unset and paying flagship rates for chores |
| settings.json env block | same keys as JSON | Persists the above per user or per project | Committing the file with the key inside |