Power: where it comes from, how it moves, how to plan

What it is

Power is the unit of the daily AI quota: 1 Power = $0.0001 of NEAR AI inference at NEAR AI's prices (power_usd in https://api.brrrain.fun/v1/public/config). A request costs its input tokens × the model's input price + its output tokens × the output price; /v1/models lists the prices in Power per million tokens.

How a day's Power forms

At 00:00 UTC:

The day budget = the AI credits the pot's stake earned since the last day + unspent budget of the last three days (70 % of yesterday's, 20 % of the day before, 10 % of the third) + a slice of the long reserve.
Your share = your balance at the previous day's reading (balances are read once a day, at 23:45 UTC) ÷ all holders' (team, treasury, pools and contracts excluded) × the budget.
Inertia: a token held yesterday and today keeps at least 95 % of yesterday's Power per token, so a crowd of new holders lowers your Power by at most 5 % a day. Before trading opens it keeps 50 %.
Before trading opens, Power per token is also capped: the cap starts low and rises every day, and what it holds back stays in the budget of later days. It ends for good when trading opens. The current values are in GET /v1/public/config (quota_cap_per_1m_usd, quota_cap_daily_growth, max_daily_quota_drop_before_trading, snapshot_at_utc); each day's cap is in /v1/public/days.

So Power moves when: the pot's stake changes, other holders buy or sell, yesterday's leftovers change, or your own balance changes (tokens bought before today's 23:45 UTC reading count from tomorrow; tokens sold stop counting).

GET /v1/me → power_today, power_spent, power_reserved (running requests), power_left, resets_at, power_tomorrow_estimate (if nothing else changes: today's budget per token, your balance, and before trading tomorrow's cap).

Reservations

Before a request runs, its maximum cost is reserved: input (estimated from the request's size) + max_tokens × the output price, times n choices. When it ends, the real cost is charged and the rest comes back. So:

A small max_tokens lets more requests run in parallel within the same Power.
power_left excludes running requests; the header x-brrrain-power-remaining on an answer is what is left after it.
A stream cut short is charged at its reserved cost until NEAR AI's own figure arrives (minutes later); then the difference comes back.

Planning a long job

Read power_left (GET /v1/me) and the model's prices (GET /v1/models).
Estimate one step: input tokens (≈ 1 token per 4 characters of English) × input_per_1m / 1 000 000 + max_tokens × output_per_1m / 1 000 000.
Steps that fit = power_left / that estimate. Keep a margin of 20 %.
If it does not fit: a cheaper model, shorter context (summaries instead of full history), a smaller max_tokens, or split the job across days and tell your human when it will finish (resets_at).
Watch x-brrrain-power-remaining as you go; stop cleanly before zero rather than failing mid-step.

Limits besides Power

Current values in https://api.brrrain.fun/v1/public/config:

max_concurrent_per_account requests at once per account (4); more wait a few seconds, then rate_limited.
rate_limit_per_key_per_min requests a minute per key (60).
A key's own daily cap, if it has one. A 402 it causes carries limited_by: key_cap and the account's Power left; /v1/me with that key shows key.daily_cap_power and key.power_left.
The whole pot's spending for the day: rarely reached; then everyone gets quota_exhausted until 00:00 UTC.

Spending history

GET /v1/usage (each request: model, key, tokens, Power) and GET /v1/usage/days (Power given and used per day) answer only a session signed in with the account's NEAR key (sign-in.md), never an API key: a key that leaks cannot read the account's history. With a key, use the x-brrrain-power-remaining header and GET /v1/me (its key block shows your key's cap and what it can still spend). The human sees the history on https://brrrain.fun/app/usage/.