---
name: brrrain
description: Use BRRRAIN AI from an agent - an OpenAI-compatible API paid by holding the BRRRAIN token on NEAR, with a daily quota called Power. Use when the human gives you a BRRRAIN API key (brrr_...), asks you to call models through BRRRAIN, to sign a NEAR account in to BRRRAIN, to check how much Power is left, or when a BRRRAIN request fails with quota_exhausted, max_tokens_too_high, no_tokens or another BRRRAIN error code.
---

# BRRRAIN AI for agents

BRRRAIN holders get a daily AI quota, **Power**, paid by NEAR staked in the
NEAR AI farm. The API speaks OpenAI's chat completions: the same SDKs and
tools, a different base URL and key.

- API: `https://api.brrrain.fun/v1` (OpenAPI document: `https://api.brrrain.fun/openapi.json`)
- Site: `https://brrrain.fun` (keys at `https://brrrain.fun/app/keys`)
- This skill: `https://brrrain.fun/skill/brrrain/SKILL.md`; the files it links are next to it.

## Before you start

The NEAR account behind the key must hold at least 1 BRRRAIN. Power for a day
is given at 00:00 UTC to the tokens held during the day before, so tokens
bought today give Power from tomorrow. No BRRRAIN → no access: tell your
human. Never buy tokens, sign transactions or move funds on your own unless
your human told you to.

## Get a key

Either way you end with an API key `brrr_…`. It is shown once.

1. **Your human makes one** at `https://brrrain.fun/app/keys` and gives it to you.
   Simplest; ask for a key with a daily cap if you share the account's Power
   with other agents.
2. **You have your own NEAR account** and a full-access key of it: run the
   sign-in script. It signs a message (NEP-413, no transaction, costs
   nothing) and creates a key:

   ```bash
   NEAR_ACCOUNT_ID=agent.near NEAR_PRIVATE_KEY=ed25519:... node scripts/sign-in.mjs > key.txt
   # or: python3 scripts/sign_in.py  (needs pip install pynacl)
   ```

   Pass the private key in the environment, never as an argument. Details and
   every failure: `references/sign-in.md`.

Store the key as a secret (an environment variable or your harness's secret
store). Never print it, log it, commit it or put it in a prompt.

## Call it

```bash
curl https://api.brrrain.fun/v1/chat/completions \
  -H "Authorization: Bearer $BRRRAIN_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "z-ai/glm-5.3-flash", "max_tokens": 400,
       "messages": [{"role": "user", "content": "Say hi in five words."}]}' -i
```

```python
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.brrrain.fun/v1", api_key=os.environ["BRRRAIN_API_KEY"])
r = client.chat.completions.with_raw_response.create(
    model="z-ai/glm-5.3-flash", max_tokens=400,
    messages=[{"role": "user", "content": "Say hi in five words."}])
print(r.headers["x-brrrain-power-remaining"], r.parse().choices[0].message.content)
```

`stream: true` works as in OpenAI; the last chunk carries `usage`. Models and
their prices: `GET https://api.brrrain.fun/v1/models` (no key needed).

**Chat only.** Images, speech-to-text and embeddings are not served here:
use NEAR AI Cloud directly, with your own account and key
(`references/beyond-chat.md`).

## Power rules

Follow these on every request.

1. **Read the headers.** Every answer carries `x-brrrain-power-remaining`
   (Power left today) and `x-brrrain-power-reset-at` (the next 00:00 UTC).
   `GET /v1/me` gives the same at any time.
2. **Set `max_tokens` yourself** for what the task needs. The request's
   maximum cost (input + `max_tokens` of output) is reserved before it runs;
   the unused part comes back when it ends. Leave it out and the API picks
   the most you can afford, up to a default. A model with `reasoning: true`
   in `/v1/models` can think first, and its thinking uses `max_tokens` too:
   give it 1 000 or more (`references/models.md`).
3. **`max_tokens_too_high`:** resend with `max_tokens` at most the
   `affordable_max_tokens` in the error, or less.
4. **`quota_exhausted`: stop.** Power refills at `resets_at`. Tell your human
   or wait until then. Never retry in a loop: it cannot succeed before the
   reset. A cheaper model may still fit what is left.
5. **Read `limited_by` in a 402** to know what ran short:
   - `account`: the account's Power for today;
   - `key_cap`: your key's own daily cap, while the account may still have
     Power (`account_power_left`). Ask your human to raise or remove the cap
     at `https://brrrain.fun/app/keys`, or for a key without one. You cannot change it
     yourself: keys are managed only from a signed-in session;
   - `pot`: everyone's Power for the day; wait for `resets_at`.

   `GET /v1/me` with your key also shows `key.daily_cap_power` and
   `key.power_left`: what your key can still spend.
6. **Pick the model by the job.** The default private model (runs in a TEE)
   is the cheap one; other models cost several times to a hundred times more
   Power per message (`price.typical_message` in `/v1/models`). Use the
   expensive ones when the task needs them. `references/models.md`.
7. **`rate_limited`, `upstream_unavailable`, `day_not_open`:** temporary; wait
   the `Retry-After` seconds, retry a few times with growing pauses.

Every error has the OpenAI shape `{"error": {"message", "type", "code",
"param"}}`; branch on `code`, show the human `message`. All codes and what to
do: `references/api.md#errors`.

## Privacy

The API keeps metadata of each request (time, model, tokens, cost), never
the prompt or the answer. Still: no secrets in prompts.

## Where to read next

| The task in front of you | Read |
|---|---|
| Sign your own NEAR account in, create or cap a key | `references/sign-in.md` |
| An endpoint's fields, an error code | `references/api.md` |
| Plan a long job within today's Power; why Power changed | `references/power.md` |
| Which model to use, what a message costs | `references/models.md` |
| Plug the key into an SDK, LangChain, Vercel AI SDK, Cursor, Continue, Cline, Aider | `references/frameworks.md` |
| Generate an image, transcribe audio, embed text | `references/beyond-chat.md` |

## Never

- Print, log or commit the key, or pass it on a command line.
- Hand the key to another agent unless your human says so; ask for a
  separate key with a daily cap instead.
- Call BRRRAIN endpoints that `references/api.md` does not list.
- Retry `quota_exhausted` before `resets_at`.
- Buy, sell or stake tokens, or sign any transaction, without your human's
  instruction.