Prices and the price feed#

Lockpin caps a call by its worst-case price, so the prices it holds decide every cap. This page explains where those prices come from, what happens to a model with no price, and how to add, change and update prices. It is for developers and admins who use models Lockpin does not know yet, or whose prices differ from the list.

Where prices come from#

Prices ship in Lockpin’s catalog, inside the binary, and change with a release. They are as of the date each provider’s pricing page was checked. To see them:

lockpin providers -models

lockpin doctor checks that the catalog is valid and says how old its prices are.

On top of the catalog, you can add catalog files of your own with -prices, and fetch updated catalogs with lockpin providers update. Both are described below.

What the catalog holds#

Rates are in USD per 1M tokens. For each model the catalog can hold:

Field	What it is
`input`, `cached_input`, `output`	The base rates. A cached price the provider does not list is the input price.
Cache-write rates	What writing the prompt cache costs, where the provider bills it (Anthropic, OpenAI’s gpt-6 models).
Long-context tier	Higher rates for the whole call above an input size.
`max_output`	The model’s largest output, which caps what a worst case reserves.
`schedule`	A new price from an instant on, such as a known price rise.
`windows`	A multiplier inside UTC hours of the week, such as off-peak hours.
Tiers and tool fees	Multipliers for a requested tier, and fees for tools Lockpin can price.

Prices that change by date or time#

A call reserves the highest price in force at any moment before it can finish (10 minutes ahead, the HTTP timeout), so a call started just before a rise cannot overshoot the cap. It is charged the price in force when it ran: the dearer of its start and its end, because the providers do not say which counts.

Tiers#

A request can ask for a tier in service_tier, speed or inference_geo. Lockpin reserves the tier’s price and charges the tier the response says it got:

Provider	Request	Price
OpenAI	`service_tier: "priority"` or `"fast"` / `"ultrafast"` / `"flex"`	2x / 6x / 0.5x
Anthropic	`speed: "fast"` (Opus 5.5 and Opus 5) / `inference_geo: "us"`	2x / 1.1x, stacking
xAI	`service_tier: "priority"` (billed only when the reply says priority)	2x
Mistral	`service_tier: "auto"` (Priority Tier)	1.75x, or 1x if the reply says `standard`
Gemini	`service_tier: "priority"` on Gemini 4 Argon	1.8x
xAI US, Fireworks Kimi K3 Fast and US	the `/xai-us/v1` endpoint, or the model id	1.1x, 1.5x

A discount (Flex) is only taken when the response confirms the tier. A tier with no price in the catalog gets a 400.

Tool fees#

Anthropic’s web search costs $10 per 1,000. With max_uses on the tool, Lockpin reserves that many searches and charges the number the reply reports. A tool whose fee Lockpin cannot bound or does not know (web search on xAI, OpenAI and Gemini; code execution; file search; image generation) gets 400 unpriced_tool while the task has a budget, because the cap would not hold for it.

-allow-unpriced sends such calls anyway at the standard price and logs a warning. The reply says X-Lockpin-Unpriced. A task with no cap at all has nothing to break, so its calls go through, unless the solo-mode -day-limit is on.

Models with no price#

A model with no price is refused with 400 unknown_model, so the cap can never be skipped by accident. You have three ways forward:

Add the model to a catalog file of your own. See Add or change prices.
Find what is missing. lockpin providers missing lists a provider’s models with that provider’s key and prints the text models the catalog cannot price. Listing models is free.
```
lockpin providers missing -provider openai
```
-provider is required and names the provider as lockpin providers does. -base sets the provider’s API base URL (default: the catalog’s). The key goes only over HTTPS, or HTTP to localhost, and a redirect is not followed.
Set a fallback price for every unknown model with -unknown-model-price, in USD per 1M tokens, as input,output[,cached]:
```
lockpin -unknown-model-price 15,75
```
The reply says X-Lockpin-Price: fallback, the charge counts as estimated, and the meter alerts once a day per model so you add it to the catalog.

Add or change prices#

Add models, change prices, or add an OpenAI-compatible server of your own with a catalog file passed as -prices FILE.

Write the file. It has a providers object and a models object, with models named provider/model:

{"providers": {"local": {"api": "openai", "base_url": "http://127.0.0.1:11434/v1", "auth": "bearer"}},
 "models": {"local/qwen3:8b": {"input": 0, "cached_input": 0, "output": 0.01}}}

Start Lockpin with it. Several files, comma-separated, are merged in order:
```
lockpin -prices lockpin-prices.json,mine.json
```
The first file in -prices is where fetched catalogs are stored (default lockpin-prices.json), and an update replaces it. Keep your own models in a second file.

A running Lockpin picks up a changed file within seconds, with no restart. A call in flight keeps the price it started with. A broken file is logged once and ignored.

Overrides for cloud providers#

Provider	Override key	When
Azure OpenAI	`"azure/<model>"`	Azure’s price in your region differs from OpenAI’s list.
Bedrock (InvokeModel)	`"bedrock-invoke/<id>"`	A model before Claude 4.5, priced by AWS per region.
Bedrock (Converse)	`"bedrock-converse/<id as sent>"`	Another vendor’s model outside us-east-1.
Vertex AI	`"vertex/<id>"`	An Anthropic model before Sonnet 4.5.

An explicit entry wins over the price Lockpin derives. See Amazon Bedrock, Google Vertex AI and Azure OpenAI.

Update prices from a catalog#

lockpin providers update fetches a catalog, checks it, and stores it in the -prices file (default lockpin-prices.json). Run lockpin with -prices on that file to use it.

lockpin providers update -url https://example.com/catalog.json -dry-run
lockpin providers update -url https://example.com/catalog.json
lockpin -prices lockpin-prices.json

To fetch an unsigned catalog on a schedule instead, start Lockpin with -prices-url. It is fetched into the first -prices file every -prices-refresh (default 1h) and reloaded with no restart:

lockpin -prices-url https://example.com/catalog.json

Lockpin has no catalog URL of its own: you give it. The URL is never logged (only its host), and it must be HTTPS, or HTTP to localhost.

Flag	Default	What it does
`-dry-run`	off	Check and show what would change; write nothing.
`-url`	none	HTTPS URL of an unsigned catalog JSON.
`-feed`	the machine policy’s feed	HTTPS URL of a signed price feed (its signature is the URL with `.sig` added).
`-from`	none	Read the catalog from this file instead of a URL, with the same checks.
`-sig`	none	With `-from`: the feed’s `.sig` file, so the file is checked as a signed feed.
`-max-drop`	`50`	Refuse a catalog that lowers a model’s price by more than this percent, unless `-force`.
`-force`	off	Accept price drops above `-max-drop`.
`-allow-providers`	off	Accept a catalog that adds a provider or changes where calls go. A key follows them: review it first.
`-max-age`	`720h`	Refuse a signed feed issued longer ago than this.
`-timeout`	`20s`	Give up fetching after this long.

To check any file the same way without writing anything:

lockpin providers update -from catalog.json -dry-run

What an update checks#

A catalog is refused if it has a field Lockpin does not know, a negative, infinite or absurd price, a malformed schedule or window, or a model with no provider.
A price that falls by more than 50 percent (-max-drop) needs -force. The check prices every model id as the proxy bills it, including derived Bedrock, Vertex and Azure ids, at every long-context edge, tier and schedule or window edge, and compares max_output too.
A new provider, or any change to a provider entry other than its source note (address, key, count endpoint, tiers, tool fees and the rest), needs -allow-providers, because a key or a price would follow it.
The scheduled refresh (-prices-url) never forces or allows either. It logs the refusal and keeps the old prices.
-prices-max-drop sets the same drop limit for the running proxy’s fetches.

Signed price feed#

A company can keep prices current across its machines without trusting the server they are downloaded from. A signed feed is a catalog plus an Ed25519 signature, a sequence number that may only go up, and an age limit. A machine applies it only when a key it trusts signed it.

The feed is off by default. A company turns it on with price_feed in its signed machine policy, which names the feed’s URL, the keys it must be signed by, and whether to fetch it automatically. Only the machine policy can choose the feed or its keys. See Signed policy.

By hand, lockpin providers update fetches the feed the machine policy names, and -feed URL fetches another signed feed with the same checks. A machine with no network can take a copy with -from and -sig:

lockpin providers update -dry-run
lockpin providers update -feed https://prices.example.com/lockpin/catalog.json
lockpin providers update -from catalog.json -sig catalog.json.sig

While the machine policy names a feed, nothing unsigned is fetched: -prices-url is ignored with a warning, and -url, or -from without -sig, is refused. Your own -prices files are local files and still merge over the feed.
Cap enforcement never waits for the feed. When the feed host is down, slow or serves something refused, Lockpin logs one line and keeps the last good prices.
A feed cannot raise a cap, change a budget, or carry code. It holds prices and provider entries only.
Fetching the feed uploads nothing: it is two HTTPS GETs.

Limits#

A model id that is new and has no undated form is not compared with anything when a catalog is updated.
Whoever can write a machine’s -prices files can change its prices: those files are not signed.
DeepSeek’s peak hours do not apply on Chinese public holidays, and Lockpin has no holiday list, so on those days DeepSeek spend can read up to 2x high.
Gemini’s price rises are known by date, not by hour or time zone. The new price starts at the earliest moment the date can begin anywhere, so Gemini can read high for up to 38 hours.
Not priced, so refused on a capped call: Anthropic’s Priority Tier and Batch, Fireworks’ Priority, and Gemini priority on models other than 4 Argon.