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:

   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: 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

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

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 (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. 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: api.md.

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

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 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.