{ "openapi": "3.1.0", "info": { "title": "BRRRAIN API", "description": "Sign in with a NEAR account, hold BRRRAIN, spend your daily Power through an OpenAI-compatible API.\n\nAuthenticate with `Authorization: Bearer ` (keys from `/v1/keys`) or a session from `/v1/auth/near`. Errors have the OpenAI shape `{\"error\": {\"message\", \"type\", \"code\", \"param\"}}`; `code` says what happened and the message what to do. Completions carry `x-brrrain-power-remaining` and `x-brrrain-power-reset-at`.", "version": "1" }, "paths": { "/v1/airdrop": { "get": { "tags": [ "airdrop" ], "summary": "The account's airdrop: each published wave it is in, with its amount, rank and what it is in it for.", "operationId": "airdrop", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Airdrop" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "api_key": [] }, { "session": [] }, { "cookie": [] } ] } }, "/v1/airdrop/card": { "post": { "tags": [ "airdrop" ], "summary": "Shares the account's airdrop card: from now on its link shows the\naccount's total and what it is in the airdrop for. Nothing is public before.", "operationId": "share_card", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardShared" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "session": [] }, { "cookie": [] } ] }, "delete": { "tags": [ "airdrop" ], "summary": "Hides the account's airdrop card again: its link stops showing anything.", "operationId": "hide_card", "responses": { "204": { "description": "" }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "session": [] }, { "cookie": [] } ] } }, "/v1/auth/challenge": { "post": { "tags": [ "auth" ], "summary": "Starts a sign-in: returns the message and nonce to sign with NEP-413.", "description": "Pass `referral_code` from a `/r/` link; it binds on the account's first sign-in only.", "operationId": "challenge", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChallengeRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Challenge" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/v1/auth/logout": { "post": { "tags": [ "auth" ], "summary": "Ends the current session.", "operationId": "logout", "responses": { "204": { "description": "" }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "session": [] }, { "cookie": [] } ] } }, "/v1/auth/near": { "post": { "tags": [ "auth" ], "summary": "Finishes a sign-in with the NEP-413 signature of a full-access key of the account.", "description": "`session: \"bearer\"` returns `session_token` for agents; `session: \"cookie\"` sets the site's cookie and returns `csrf_token`.", "operationId": "sign_in", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/v1/chat/completions": { "post": { "tags": [ "openai" ], "summary": "An OpenAI chat completion, streaming or not.", "description": "The request's maximum cost is reserved from today's Power before it runs and the real cost is charged when it ends. Leave out `max_tokens` and the most you can afford (up to a default) is used; a `max_tokens` you cannot afford is refused with `affordable_max_tokens`. Every answer carries `x-brrrain-power-remaining` and `x-brrrain-power-reset-at`.", "operationId": "chat_completions", "requestBody": { "description": "An OpenAI chat completion request. `max_tokens` is set for you when left out.", "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "The completion, or an SSE stream when `stream` is true" }, "402": { "description": "quota_exhausted or max_tokens_too_high", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "no_tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "model_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "api_key": [] }, { "session": [] }, { "cookie": [] } ] } }, "/v1/claims": { "get": { "tags": [ "airdrop" ], "summary": "What the account is owed in each wave and of its referral rewards, what it already claimed, and a signed voucher for the rest of each.", "description": "Send `claim(drop, total, register, signature)` to `contract_id` with `attach_yocto` and `gas` from the voucher, one wave at a time.", "operationId": "claims", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Claims" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "api_key": [] }, { "session": [] }, { "cookie": [] } ] } }, "/v1/keys": { "get": { "tags": [ "keys" ], "summary": "Lists the account's API keys (never the keys themselves).", "operationId": "list_keys", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "session": [] }, { "cookie": [] } ] }, "post": { "tags": [ "keys" ], "summary": "Creates an API key. The key is in `secret`, shown this once; only its hash is kept.", "operationId": "create_key", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewKey" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedKey" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "session": [] }, { "cookie": [] } ] } }, "/v1/keys/{id}": { "delete": { "tags": [ "keys" ], "summary": "Revokes a key at once.", "operationId": "revoke_key", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "" }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "session": [] }, { "cookie": [] } ] }, "patch": { "tags": [ "keys" ], "summary": "Renames a key or changes its daily cap (`null` removes the cap).", "operationId": "change_key", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyChange" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "session": [] }, { "cookie": [] } ] } }, "/v1/me": { "get": { "tags": [ "account" ], "summary": "The account's token balance and Power today: given, spent, held by running requests, left, and when it refreshes.", "operationId": "me", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "api_key": [] }, { "session": [] }, { "cookie": [] } ] } }, "/v1/models": { "get": { "tags": [ "openai" ], "summary": "The models you can use, with prices in Power per million tokens and per typical message.", "operationId": "models", "parameters": [ { "name": "include_unavailable", "in": "query", "description": "Also list the models NEAR AI does not serve right now (`available: false`); they cannot be called.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } } } } }, "/v1/public/card/{code}": { "get": { "tags": [ "public" ], "summary": "A shared airdrop card, by its owner's code (the link `/drop/`).", "operationId": "drop_card", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DropCard" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/v1/public/card/{code}/card.png": { "get": { "tags": [ "public" ], "summary": "A shared airdrop card as an image (PNG, 1200×630), for social previews.", "operationId": "drop_card_png", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The shared airdrop card, 1200×630", "content": { "image/png": {} } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/v1/public/config": { "get": { "tags": [ "public" ], "summary": "The economics constants and contract ids the site shows.", "operationId": "config", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicConfig" } } } } } } }, "/v1/public/days": { "get": { "tags": [ "public" ], "summary": "The day history: budget, spending, holders, Power per million tokens.", "operationId": "days", "parameters": [ { "name": "limit", "in": "query", "description": "Days back from today, at most 366.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DayView" } } } } } } } }, "/v1/public/helper": { "post": { "tags": [ "public" ], "summary": "The site's helper: answers a question about BRRRAIN (no sign-in, no tokens).", "operationId": "ask", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HelperRequest" } } }, "required": true }, "responses": { "200": { "description": "The answer; with `stream: true`, server-sent events (see `HelperRequest.stream`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HelperAnswer" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "helper_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/v1/public/leaderboard": { "get": { "tags": [ "public" ], "summary": "The accounts that invited the most friends. Third-level accounts (`x.wallet.near`) are not\ncounted as friends: a bot or a wallet service makes them by the hundred, and they would buy a\nplace here. They still earn their referrer its bonus (that needs a claim, which a new account\ndoes not have).", "operationId": "leaderboard", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Leaderboard" } } } } } } }, "/v1/public/stats": { "get": { "tags": [ "public" ], "summary": "Today's budget, the latest contract readings (token, pot, market, distributor) and the pot against the token's value.", "operationId": "stats", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stats" } } } } } } }, "/v1/public/usage": { "get": { "tags": [ "public" ], "summary": "AI served: requests, tokens and accounts since launch, today, by model and by day.", "operationId": "public_usage", "parameters": [ { "name": "days", "in": "query", "description": "Days of history, newest first, at most 366.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageView" } } } } } } }, "/v1/public/waves": { "get": { "tags": [ "public" ], "summary": "The published waves, newest first, with what each gave and what was claimed.", "operationId": "waves", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WaveInfo" } } } } } } } }, "/v1/referrals": { "get": { "tags": [ "airdrop" ], "summary": "The account's referral code and link, its invitees and the bonuses they earned it.", "operationId": "referrals", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Referrals" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "api_key": [] }, { "session": [] }, { "cookie": [] } ] } }, "/v1/referrals/check": { "post": { "tags": [ "airdrop" ], "summary": "Checks on chain, now, whether the caller's invitees claimed their airdrop,\nand grants the bonuses due (the worker also does this every few minutes).\nThe site calls it when the browser saw an invitee's claim; nothing is taken\nfrom the caller but the trigger. At most one check per account every 20 s.", "operationId": "check", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardsCheck" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "api_key": [] }, { "session": [] }, { "cookie": [] } ] } }, "/v1/usage": { "get": { "tags": [ "account" ], "summary": "The account's requests, newest first: model, key, tokens, Power charged. No prompts or answers are kept.\nOnly for a session signed in with the account's NEAR key: an API key cannot read the account's history.", "operationId": "usage", "parameters": [ { "name": "before", "in": "query", "description": "Only events before this time (paging: pass the last `created_at`).", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "description": "At most 200.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UsageEvent" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "session": [] }, { "cookie": [] } ] } }, "/v1/usage/days": { "get": { "tags": [ "account" ], "summary": "The account's Power day by day, newest first: what it got and what it used.\nOnly for a session signed in with the account's NEAR key.", "operationId": "usage_days", "parameters": [ { "name": "days", "in": "query", "description": "Days back from today, at most 90 (default 30).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PowerDay" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "session": [] }, { "cookie": [] } ] } } }, "components": { "schemas": { "Airdrop": { "type": "object", "required": [ "account_id", "eligible", "total", "waves" ], "properties": { "account_id": { "type": "string" }, "card_link": { "type": [ "string", "null" ], "description": "The link to the account's public airdrop card, once it shared it with `POST /v1/airdrop/card`; null before." }, "eligible": { "type": "boolean", "description": "In at least one published wave." }, "total": { "type": "string", "description": "Token units, every wave together." }, "waves": { "type": "array", "items": { "$ref": "#/components/schemas/WaveEntry" }, "description": "The published waves the account is in, oldest first." } } }, "ApiKey": { "type": "object", "required": [ "id", "name", "hint", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "daily_cap_power": { "type": [ "number", "null" ], "format": "double" }, "hint": { "type": "string", "description": "The key's first characters." }, "id": { "type": "string", "format": "uuid" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" } } }, "CardShared": { "type": "object", "required": [ "link", "image" ], "properties": { "image": { "type": "string", "description": "The card's image, 1200×630." }, "link": { "type": "string", "description": "`/drop/`: the card's page, which also invites." } } }, "ChainReading": { "type": "object", "required": [ "value", "updated_at" ], "properties": { "updated_at": { "type": "string", "format": "date-time" }, "value": {} } }, "Challenge": { "type": "object", "required": [ "message", "nonce", "recipient", "expires_at" ], "properties": { "expires_at": { "type": "string", "format": "date-time" }, "message": { "type": "string", "description": "Sign exactly this text." }, "nonce": { "type": "string", "description": "32 bytes, base64: the NEP-413 nonce." }, "recipient": { "type": "string", "description": "The NEP-413 recipient." } } }, "ChallengeRequest": { "type": "object", "required": [ "account_id" ], "properties": { "account_id": { "type": "string", "description": "The NEAR account signing in." }, "referral_code": { "type": [ "string", "null" ], "description": "A referral code from a `/r/` link. It binds only on the account's first sign-in." } } }, "Claim": { "type": "object", "description": "The referral rewards, token units.", "required": [ "owed", "claimed", "claimable", "after_first" ], "properties": { "after_first": { "type": "boolean", "description": "Claim a wave first: that claim registers the wallet on the token." }, "claimable": { "type": "string", "description": "`owed − claimed`." }, "claimed": { "type": "string", "description": "What the distributor already paid." }, "owed": { "type": "string" }, "voucher": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Voucher", "description": "`null` when there is nothing to claim, or while it waits for a wave's claim (`after_first`)." } ] } } }, "Claims": { "type": "object", "required": [ "account_id", "waves", "referral" ], "properties": { "account_id": { "type": "string" }, "referral": { "$ref": "#/components/schemas/Claim" }, "waves": { "type": "array", "items": { "$ref": "#/components/schemas/WaveClaim" }, "description": "The published waves the account is in, oldest first; each is claimed on its own." } } }, "CreatedKey": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "description": "The key itself. Shown once; we keep only its hash." } } } ] }, "Credits": { "type": "object", "description": "The project's AI credit at NEAR AI, from the API's own books: what the\nfarm has credited its organisations (their last readings), what their keys\nspent on holders' AI, and what is left. Approximate: NEAR AI's own figures\nare read once a day and reconciled later.", "required": [ "earned_usd", "spent_usd", "left_usd", "read_on" ], "properties": { "earned_usd": { "type": "number", "format": "double", "description": "USD the farm has credited, ever." }, "left_usd": { "type": "number", "format": "double", "description": "`earned − spent`." }, "read_on": { "type": "string", "format": "date", "description": "The day of the latest farm reading." }, "spent_usd": { "type": "number", "format": "double", "description": "USD spent on holders' AI, ever (requests running now included)." } } }, "DayView": { "type": "object", "required": [ "day", "fresh_usd", "carry_usd", "release_usd", "base_budget_usd", "reserve_usd", "promised_usd", "spent_usd", "holders", "closed", "trading" ], "properties": { "base_budget_usd": { "type": "number", "format": "double" }, "cap_per_1m_usd": { "type": [ "number", "null" ], "format": "double", "description": "The day's cap: USD per one million tokens. `null`: no cap." }, "carry_usd": { "type": "number", "format": "double" }, "closed": { "type": "boolean" }, "day": { "type": "string", "format": "date" }, "fresh_usd": { "type": "number", "format": "double", "description": "USD amounts." }, "holders": { "type": "integer", "format": "int32" }, "power_per_1m_tokens": { "type": [ "number", "null" ], "format": "double", "description": "Power per one million tokens held (at most the cap)." }, "promised_usd": { "type": "number", "format": "double" }, "release_usd": { "type": "number", "format": "double" }, "reserve_usd": { "type": "number", "format": "double" }, "spent_usd": { "type": "number", "format": "double" }, "trading": { "type": "boolean", "description": "Trading was open when the day opened; before it, the airdrop rules." }, "unspent_usd": { "type": [ "number", "null" ], "format": "double" } } }, "DropCard": { "type": "object", "description": "An account's airdrop card, public only once its owner shares it: it is\nfound by the owner's referral code, never by the account id, so nobody can\nlook up what another account got.", "required": [ "account_id", "total", "waves", "categories", "referral_link" ], "properties": { "account_id": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "What it is in the airdrop for, every wave together." }, "referral_link": { "type": "string" }, "top_percent": { "type": [ "number", "null" ], "format": "double", "description": "\"Top N %\" by the total over every wave; only within the top 10 %." }, "total": { "type": "string", "description": "Token units, every published wave together." }, "waves": { "type": "array", "items": { "type": "string" }, "description": "The titles of the published waves it is in, oldest first." } } }, "ErrorBody": { "type": "object", "description": "The OpenAPI shape of an error body.", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" } } }, "ErrorCode": { "type": "string", "enum": [ "invalid_request", "invalid_api_key", "session_expired", "csrf_token_missing", "signin_failed", "no_tokens", "quota_exhausted", "max_tokens_too_high", "model_not_found", "rate_limited", "upstream_unavailable", "day_not_open", "key_limit_reached", "not_found", "airdrop_not_eligible", "claims_unavailable", "referral_invalid", "helper_unavailable", "internal_error" ] }, "ErrorDetail": { "type": "object", "required": [ "message", "type", "code" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "type": { "type": "string" } } }, "HelperAnswer": { "type": "object", "required": [ "answer", "refused" ], "properties": { "answer": { "type": "string" }, "refused": { "type": "boolean", "description": "The question was declined (off topic or suspicious); `answer` says so." } } }, "HelperMessage": { "type": "object", "required": [ "role", "content" ], "properties": { "content": { "type": "string" }, "role": { "type": "string", "description": "`user` or `assistant`." } } }, "HelperRequest": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/HelperMessage" }, "description": "The conversation so far, oldest first, ending with the user's question." }, "stream": { "type": "boolean", "description": "Stream the answer as server-sent events, each `data:` a JSON object:\n`{\"delta\": text}` to append, `{\"replace\": text}` to show instead of\neverything so far, then `{\"done\": true, \"refused\": bool}`, or\n`{\"error\": message}` if the answer broke off." } } }, "Invitee": { "type": "object", "required": [ "account_id", "bound_at", "earned" ], "properties": { "account_id": { "type": "string" }, "bound_at": { "type": "string", "format": "date-time" }, "earned": { "type": "boolean", "description": "The friend claimed a wave and earned the referrer a bonus. How much per\nfriend is not shown: it would tell what the friend got." } } }, "KeyChange": { "type": "object", "properties": { "daily_cap_power": { "type": [ "number", "null" ], "format": "double", "description": "A new cap, or `null` to remove it. Leave the field out to keep the cap." }, "name": { "type": [ "string", "null" ] } } }, "KeyPower": { "type": "object", "description": "The calling API key's daily cap and what it can still spend today.", "required": [ "name", "power_spent", "power_left" ], "properties": { "daily_cap_power": { "type": [ "number", "null" ], "format": "double", "description": "`null`: no cap, the key can spend all the account's Power." }, "name": { "type": "string" }, "power_left": { "type": "number", "format": "double", "description": "What this key can still spend today." }, "power_spent": { "type": "number", "format": "double", "description": "Spent today by this key, and held by its running requests." } } }, "LeaderRow": { "type": "object", "required": [ "account_id", "invitees" ], "properties": { "account_id": { "type": "string" }, "invitees": { "type": "integer", "format": "int64", "description": "Friends it invited; sub-accounts of sub-accounts (`x.wallet.near`) are not counted." } } }, "Leaderboard": { "type": "object", "required": [ "referrers" ], "properties": { "referrers": { "type": "array", "items": { "$ref": "#/components/schemas/LeaderRow" }, "description": "By friends invited. No amounts: nobody sees what another account got." } } }, "Me": { "type": "object", "required": [ "account_id", "balance", "holds_enough", "day", "power_today", "power_spent", "power_reserved", "power_left", "resets_at" ], "properties": { "account_id": { "type": "string" }, "ai_use_30d": { "type": [ "number", "null" ], "format": "double", "description": "The share of its quota the account spent over the last 30 closed days\n(0 to 1); `null` without a quota in them. The lock's suggestion of\nwhat AI share to keep starts from it." }, "balance": { "type": "string", "description": "Token units held now." }, "day": { "type": "string", "format": "date" }, "holds_enough": { "type": "boolean" }, "key": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KeyPower", "description": "Only when called with an API key: that key's own limit. What it can\nspend is the smaller of the account's Power left and its cap's." } ] }, "power_left": { "type": "number", "format": "double" }, "power_reserved": { "type": "number", "format": "double" }, "power_spent": { "type": "number", "format": "double" }, "power_today": { "type": "number", "format": "double", "description": "Power for today: given, spent, held by running requests, left." }, "power_tomorrow_estimate": { "type": [ "number", "null" ], "format": "double", "description": "Tomorrow's Power if nothing else changes: today's budget per token and\nthe balance stay; before trading, at most tomorrow's cap." }, "resets_at": { "type": "string", "format": "date-time" } } }, "ModelEntry": { "type": "object", "required": [ "id", "object", "created", "owned_by", "name", "context_length", "private", "available", "reasoning", "price" ], "properties": { "available": { "type": "boolean", "description": "NEAR AI serves it now. Only `?include_unavailable=true` lists models that are not." }, "context_length": { "type": "integer", "format": "int32", "minimum": 0 }, "created": { "type": "integer", "format": "int64" }, "id": { "type": "string" }, "max_output_tokens": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "name": { "type": "string" }, "object": { "type": "string", "description": "Always `model`." }, "owned_by": { "type": "string" }, "price": { "$ref": "#/components/schemas/ModelPrice" }, "private": { "type": "boolean", "description": "Runs in a TEE with attestation (NEAR AI's private models)." }, "reasoning": { "type": "boolean", "description": "It can think before it answers (some such models always do, GLM among\nthem). The thinking is billed as output tokens and counts against\n`max_tokens`: give it room (1 000 or more), or a short `max_tokens` can\nend before any answer text." } } }, "ModelList": { "type": "object", "required": [ "object", "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelEntry" } }, "default_model": { "type": [ "string", "null" ] }, "object": { "type": "string", "description": "Always `list`." } } }, "ModelPrice": { "type": "object", "required": [ "input_per_1m", "output_per_1m", "typical_message" ], "properties": { "cached_input_per_1m": { "type": [ "number", "null" ], "format": "double", "description": "Power per million cached input tokens, when the model prices them." }, "input_per_1m": { "type": "number", "format": "double", "description": "Power per million input tokens." }, "output_per_1m": { "type": "number", "format": "double" }, "typical_message": { "type": "number", "format": "double", "description": "Power for a typical message (1 500 tokens in, 650 out)." } } }, "NewKey": { "type": "object", "required": [ "name" ], "properties": { "daily_cap_power": { "type": [ "number", "null" ], "format": "double", "description": "The most Power this key may spend a day; leave out for the account's whole quota." }, "name": { "type": "string" } } }, "PowerDay": { "type": "object", "description": "One UTC day of the account's Power.", "required": [ "day", "power_given", "power_spent", "requests" ], "properties": { "day": { "type": "string", "format": "date" }, "power_given": { "type": "number", "format": "double", "description": "Power the account got for the day." }, "power_spent": { "type": "number", "format": "double", "description": "Power its requests used that day." }, "requests": { "type": "integer", "format": "int64" } } }, "PublicConfig": { "type": "object", "required": [ "network", "token_contract", "power_usd", "day_boundary_utc", "carry_weights", "long_reserve_share", "reserve_release_days", "max_daily_quota_drop", "max_daily_quota_drop_before_trading", "quota_cap_daily_growth", "snapshot_at_utc", "min_token_balance", "quota_excluded_accounts", "referral_airdrop_bps", "max_concurrent_per_account", "rate_limit_per_key_per_min", "max_keys_per_account", "session_ttl_secs", "helper_enabled" ], "properties": { "carry_weights": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "How unspent budget is carried into the next three days." }, "day_boundary_utc": { "type": "string", "description": "Days refresh at 00:00 UTC." }, "default_model": { "type": [ "string", "null" ] }, "distributor_contract": { "type": [ "string", "null" ] }, "helper_enabled": { "type": "boolean", "description": "The site's helper answers (`POST /v1/public/helper`)." }, "lock_contract": { "type": [ "string", "null" ], "description": "The BRRRAIN lock (`null` before it is deployed)." }, "long_reserve_share": { "type": "number", "format": "double" }, "max_concurrent_per_account": { "type": "integer", "format": "int32", "description": "Requests one account may run at once.", "minimum": 0 }, "max_daily_quota_drop": { "type": "number", "format": "double", "description": "The most a token's quota falls from one day to the next, once trading is open." }, "max_daily_quota_drop_before_trading": { "type": "number", "format": "double", "description": "The same before trading opens." }, "max_keys_per_account": { "type": "integer", "format": "int32", "minimum": 0 }, "min_token_balance": { "type": "string", "description": "Token units an account must hold to use the API." }, "network": { "type": "string" }, "pot_contract": { "type": [ "string", "null" ] }, "power_usd": { "type": "number", "format": "double", "description": "USD per Power." }, "quota_cap_daily_growth": { "type": "number", "format": "double", "description": "How much the cap grows a day." }, "quota_cap_per_1m_usd": { "type": [ "number", "null" ], "format": "double", "description": "Before trading: the first day's cap, USD a day per one million tokens (`null`: no cap)." }, "quota_excluded_accounts": { "type": "array", "items": { "type": "string" }, "description": "Accounts whose tokens earn no quota." }, "rate_limit_per_key_per_min": { "type": "integer", "format": "int32", "description": "Requests per minute per API key (or per session).", "minimum": 0 }, "referral_airdrop_bps": { "type": "integer", "format": "int32", "description": "The referrer's bonus, basis points of each wave an invitee claims; the waves are `/v1/public/waves`.", "minimum": 0 }, "reserve_release_days": { "type": "integer", "format": "int32", "minimum": 0 }, "session_ttl_secs": { "type": "integer", "format": "int64", "description": "How long a sign-in session lasts.", "minimum": 0 }, "snapshot_at_utc": { "type": "string", "description": "Balances are read once a day at this UTC time (\"23:45\")." }, "token_contract": { "type": "string" } } }, "Referrals": { "type": "object", "required": [ "code", "link", "invitees", "bonus_total", "airdrop_bonus_bps" ], "properties": { "airdrop_bonus_bps": { "type": "integer", "format": "int32", "description": "The airdrop bonus, basis points of each invitee's airdrop, paid on top of it.", "minimum": 0 }, "airdrop_bonus_max_invitees": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "bonus_total": { "type": "string", "description": "Token units earned from referrals, in total." }, "code": { "type": "string" }, "invitees": { "type": "array", "items": { "$ref": "#/components/schemas/Invitee" } }, "link": { "type": "string", "description": "`/r/`." }, "referred_by": { "type": [ "string", "null" ] } } }, "RewardsCheck": { "type": "object", "required": [ "granted", "checked" ], "properties": { "checked": { "type": "boolean", "description": "`false` when this account was checked less than 20 seconds ago (nothing was read)." }, "granted": { "type": "integer", "description": "Airdrop referral bonuses this check granted.", "minimum": 0 } } }, "SessionKind": { "type": "string", "enum": [ "cookie", "bearer" ] }, "SignInRequest": { "type": "object", "required": [ "account_id", "public_key", "signature", "nonce", "session" ], "properties": { "account_id": { "type": "string", "description": "The account the challenge was issued to." }, "nonce": { "type": "string", "description": "The nonce from the challenge, base64." }, "public_key": { "type": "string", "description": "`ed25519:`: the full-access key that signed." }, "session": { "$ref": "#/components/schemas/SessionKind", "description": "`bearer` for agents, `cookie` for the site." }, "signature": { "type": "string", "description": "base64 ed25519 signature of the NEP-413 payload." } } }, "SignInResponse": { "type": "object", "required": [ "account_id", "expires_at", "first_sign_in" ], "properties": { "account_id": { "type": "string" }, "csrf_token": { "type": [ "string", "null" ], "description": "Cookie sessions: send in the `x-csrf-token` header on every POST, PATCH and DELETE." }, "expires_at": { "type": "string", "format": "date-time" }, "first_sign_in": { "type": "boolean", "description": "The account signed in for the first time." }, "referred_by": { "type": [ "string", "null" ], "description": "Who referred the account, if a referral bound." }, "session_token": { "type": [ "string", "null" ], "description": "Bearer sessions: send as `Authorization: Bearer `." } } }, "Stats": { "type": "object", "required": [ "resets_at", "chain", "accounts_signed_in", "holders_total" ], "properties": { "accounts_signed_in": { "type": "integer", "format": "int64" }, "chain": { "type": "object", "description": "The latest reading of each contract: `token`, `pot`, `market`, `distributor`, `lock`, and the\nteam's own stake in the farm (`team_stake`: `account_id`, `staked`, yoctoNEAR).", "additionalProperties": { "$ref": "#/components/schemas/ChainReading" }, "propertyNames": { "type": "string" } }, "credits": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Credits", "description": "The project's AI credit at NEAR AI, approximately; `null` before the first farm reading." } ] }, "holders_total": { "type": "integer", "format": "int64", "description": "Accounts that received BRRRAIN from an airdrop wave or referral rewards (their claim landed)." }, "pot_vs_fdv": { "type": [ "number", "null" ], "format": "double", "description": "NEAR in the pot ÷ the token's fully diluted value in NEAR (above 1: the pot is worth more than the token)." }, "resets_at": { "type": "string", "format": "date-time" }, "today": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DayView" } ] } } }, "UsageDay": { "type": "object", "description": "One day, with running totals since launch (they never go down).", "required": [ "day", "requests", "tokens", "accounts", "new_accounts", "cum_requests", "cum_tokens", "cum_accounts" ], "properties": { "accounts": { "type": "integer", "format": "int64" }, "cum_accounts": { "type": "integer", "format": "int64" }, "cum_requests": { "type": "integer", "format": "int64" }, "cum_tokens": { "type": "integer", "format": "int64" }, "day": { "type": "string", "format": "date" }, "new_accounts": { "type": "integer", "format": "int64", "description": "Accounts served that day for the first time." }, "requests": { "type": "integer", "format": "int64" }, "tokens": { "type": "integer", "format": "int64" } } }, "UsageEvent": { "type": "object", "required": [ "id", "created_at", "model", "stream", "status", "power" ], "properties": { "completion_tokens": { "type": [ "integer", "null" ], "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "key_id": { "type": [ "string", "null" ], "format": "uuid" }, "model": { "type": "string" }, "power": { "type": "number", "format": "double" }, "prompt_tokens": { "type": [ "integer", "null" ], "format": "int32" }, "status": { "type": "string" }, "stream": { "type": "boolean" } } }, "UsageModel": { "type": "object", "description": "One model's share of everything served since launch.", "required": [ "model", "name", "requests", "tokens", "share" ], "properties": { "model": { "type": "string" }, "name": { "type": "string" }, "requests": { "type": "integer", "format": "int64" }, "share": { "type": "number", "format": "double", "description": "Its share of all tokens, 0..1." }, "tokens": { "type": "integer", "format": "int64" } } }, "UsageTotals": { "type": "object", "description": "Requests, AI tokens and accounts served over a period.", "required": [ "requests", "requests_with_usage", "prompt_tokens", "completion_tokens", "cached_tokens", "tokens", "accounts", "models" ], "properties": { "accounts": { "type": "integer", "format": "int64", "description": "Distinct accounts served." }, "cached_tokens": { "type": "integer", "format": "int64" }, "completion_tokens": { "type": "integer", "format": "int64" }, "models": { "type": "integer", "format": "int64", "description": "Distinct models served." }, "prompt_tokens": { "type": "integer", "format": "int64" }, "requests": { "type": "integer", "format": "int64" }, "requests_with_usage": { "type": "integer", "format": "int64", "description": "Of `requests`, those with a usage report: the token counts cover only these." }, "tokens": { "type": "integer", "format": "int64", "description": "Prompt plus completion tokens." } } }, "UsageView": { "type": "object", "required": [ "total", "today", "models", "days", "updated_at" ], "properties": { "days": { "type": "array", "items": { "$ref": "#/components/schemas/UsageDay" }, "description": "Newest first, every day since `since` (days with nothing served included)." }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/UsageModel" }, "description": "Since launch, most tokens first." }, "since": { "type": [ "string", "null" ], "format": "date", "description": "The first day anything was served; `null` before that." }, "today": { "$ref": "#/components/schemas/UsageTotals" }, "total": { "$ref": "#/components/schemas/UsageTotals" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Voucher": { "type": "object", "required": [ "contract_id", "drop", "total", "register", "signature", "attach_yocto", "gas" ], "properties": { "attach_yocto": { "type": "string", "description": "yoctoNEAR to attach to `claim`: the distributor's claim fee (0.001 NEAR), plus the token's storage deposit when `register`." }, "contract_id": { "type": "string", "description": "The distributor to call." }, "drop": { "type": "string", "description": "`claim` arguments: `drop`, `total`, `register`, `signature`." }, "gas": { "type": "string", "description": "Gas to attach, in units." }, "register": { "type": "boolean" }, "signature": { "type": "string" }, "total": { "type": "string" } } }, "WaveClaim": { "type": "object", "description": "One wave the account is in, token units.", "required": [ "wave", "title", "owed", "claimed", "claimable", "state", "after_first" ], "properties": { "after_first": { "type": "boolean", "description": "Claim the wave that registers the wallet first (the one with a voucher); then this one opens." }, "claim_until": { "type": [ "string", "null" ], "format": "date-time", "description": "The end of the wave's claim window." }, "claimable": { "type": "string", "description": "`owed − claimed`." }, "claimed": { "type": "string", "description": "What the distributor already paid of this wave." }, "owed": { "type": "string" }, "state": { "$ref": "#/components/schemas/WaveState" }, "title": { "type": "string" }, "voucher": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Voucher", "description": "`null` unless `claimable`, and while the wave waits for the first claim (`after_first`)." } ] }, "wave": { "type": "string" } } }, "WaveEntry": { "type": "object", "description": "The account in one published wave.", "required": [ "wave", "title", "about", "amount", "rank", "of", "percentile_bps", "categories", "snapshot_block" ], "properties": { "about": { "type": "string" }, "amount": { "type": "string", "description": "Token units." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "What the account is in this wave for (`memecoins`, `merit`, …), never\nhow much each counted." }, "of": { "type": "integer", "format": "int64", "description": "Accounts in this wave." }, "percentile_bps": { "type": "integer", "format": "int32", "description": "10000 = the top account of the wave." }, "rank": { "type": "integer", "format": "int32" }, "snapshot_block": { "type": "integer", "format": "int64" }, "title": { "type": "string" }, "wave": { "type": "string", "description": "The wave's id, also its drop on the distributor." } } }, "WaveInfo": { "type": "object", "description": "A published wave, with its drop's state on chain at the last reading.", "required": [ "id", "title", "about", "snapshot_block", "accounts", "total", "published_at" ], "properties": { "about": { "type": "string" }, "accounts": { "type": "integer", "format": "int64" }, "budget": { "type": [ "string", "null" ], "description": "From the distributor (the worker's last reading); `null` before the first." }, "claim_until": { "type": [ "string", "null" ], "format": "date-time" }, "claimed": { "type": [ "string", "null" ] }, "closed": { "type": [ "boolean", "null" ] }, "id": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" }, "snapshot_block": { "type": "integer", "format": "int64" }, "title": { "type": "string" }, "total": { "type": "string", "description": "Token units: what the wave gives in all." } } }, "WaveState": { "type": "string", "description": "Where a wave stands for the account.", "enum": [ "claimable", "claimed", "expired", "closed", "full", "not_open" ] } }, "securitySchemes": { "api_key": { "type": "http", "scheme": "bearer", "description": "An API key (`brrr_…`) from POST /v1/keys" }, "cookie": { "type": "apiKey", "in": "cookie", "name": "brrrain_session", "description": "The site's session cookie; POST, PATCH and DELETE also need the x-csrf-token header" }, "session": { "type": "http", "scheme": "bearer", "description": "A bearer session token from POST /v1/auth/near" } } }, "tags": [ { "name": "auth", "description": "Sign in with a NEAR signature (NEP-413), no transaction." }, { "name": "account", "description": "Your balance, Power and usage." }, { "name": "keys", "description": "API keys for your agents. Managed with a signed-in session." }, { "name": "openai", "description": "OpenAI-compatible inference." }, { "name": "airdrop", "description": "Airdrop waves, referral bonuses and claim vouchers." }, { "name": "public", "description": "Public numbers, no sign-in." } ] }