# BlockRun API (api.blockrun.ai) — API-key entry point to the routing and payment layer for AI

> BlockRun is the routing and payment layer for AI. One OpenAI-compatible endpoint routes to 100+ LLMs plus image, video, music and speech generation, web search, prediction-market and on-chain data, and multi-chain RPC. This host is the account-balance entry point: authenticate with an API key and pay from a BlockRun account funded by card or wire — no wallet signature per call. The same services are also sold per call in USDC over x402 at https://blockrun.ai (Base), https://sol.blockrun.ai (Solana) and https://arc.blockrun.ai (Arc).

## Base URL
- API: https://api.blockrun.ai/v1
- Auth: `Authorization: Bearer $BLOCKRUN_API_KEY`
- Get a key: register at https://user.blockrun.ai, create a key at https://user.blockrun.ai/dashboard/keys, add credit at https://user.blockrun.ai/dashboard/credits
- This document: https://api.blockrun.ai/llms.txt · OpenAPI 3.1: https://api.blockrun.ai/openapi.json · Discovery (JSON): https://api.blockrun.ai/discovery · Agent card: https://api.blockrun.ai/.well-known/agent-card.json

## First call

```
curl https://api.blockrun.ai/v1/chat/completions \
  -H "Authorization: Bearer $BLOCKRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4.1-mini","messages":[{"role":"user","content":"hello"}]}'
```

Point any OpenAI SDK at `base_url="https://api.blockrun.ai/v1"`; point the Anthropic SDK at the same base URL for `/v1/messages`.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | /v1/models | Live model catalog with per-token prices. Free. |
| GET | /v1/images/models | Image/video model catalog with per-call prices. Free. |
| POST | /v1/chat/completions | OpenAI Chat Completions for every model, streaming and tools supported. Billed per token. |
| POST | /v1/messages | Anthropic Messages, native envelopes. Billed per token. |
| POST | /v1/responses | OpenAI Responses API. Billed per token. |
| POST | /v1/images/generations | Image generation. Billed per image. |
| POST | /v1/videos/generations | Video generation; returns a `poll_url` — use it verbatim with the same key. Billed per second; reference video/audio clips add a per-clip surcharge, and the 202 body's `price.amount` is the exact quote. |
| POST | /v1/audio/speech | Text to speech. Billed per character. |
| POST | /v1/search | Live web / news / X search. Flat fee per call. |
| POST | /v1/decide | Yes/no, choice and score decisions for agents over text or JSON state; typed answers with probabilities. Free for any registered key, 1000 calls per key per hour. |
| GET | /v1/usage | One row per request; `window=today|24h|7d|30d` or `from`/`to`. Free. |
| GET | /v1/usage.csv | The same rows as a CSV file, whole window, one download. Free. |
| GET | /v1/usage/summary | Totals over a window: per day, model, endpoint, key. Free. |
| GET | /v1/balance | Available balance, recorded spend and open reservations. Free. |

The data and tool services published at https://blockrun.ai/llms.txt (Exa, prediction markets, DefiLlama, multi-chain RPC, phone) are reachable here under the same `/v1/...` paths with Bearer auth; the price sheet is the one `GET /v1/models` and `GET /api/pricing` on the gateway publish.

## Decisions

`POST /v1/decide` answers typed questions about a piece of state — a message, a tool call, a document, a JSON object — instead of generating text. Three question types: `noul` (yes/no with a probability), `choice` (one of your labels, with probabilities and a confidence), `score` (a position on your ordered scale). Ask several questions in one call. The request is System One's wire format; the response names the backend that served it in `x-blockrun-backend` (currently `openjev`, an open NLI cross-encoder on BlockRun's own GPU).

```
curl https://api.blockrun.ai/v1/decide \
  -H "Authorization: Bearer $BLOCKRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state":"Help! My payouts have been failing for 3 days.","questions":{"is_urgent":{"type":"noul","instructions":"Does this convey urgency?","criteria":{"true":"Explicitly time-sensitive","false":"No urgency"}},"department":{"type":"choice","instructions":"Which team should handle this?","criteria":{"billing":"Payments, refunds","technical":"Bugs, outages"}}}}'
```

Free for any registered key — no balance, no card, no wallet: register at https://user.blockrun.ai, create a key at https://user.blockrun.ai/dashboard/keys, and call. 1000 calls per key per hour, `x-ratelimit-remaining` on every response. Decisions are only served here, on api.blockrun.ai.

## Billing
- Metered at exact upstream usage × the published price sheet; chat tokens carry no platform margin on self-service accounts (see your contract for provisioned accounts).
- No per-call transaction fee and no minimum charge on key-metered accounts: you pay usage × rate and nothing is added to it.
- Long context: some models reprice the WHOLE request above a prompt-token threshold (OpenAI: above 272K, at 2x input and 1.5x output). Thresholds and rates are per model in `GET https://blockrun.ai/api/pricing` (`longContextThreshold`, `longContextThresholdInclusive`, `longContext*Price`); `GET /v1/models` does not repeat them.
- Flex: send `service_tier: "flex"` for half the rate on every token class, including the long-context rate. Billed from the tier the response reports, not the tier asked for. A Flex ask with no capacity returns 429 `resource_unavailable`, carries no usage and is not charged — retry with backoff or drop the field for standard processing. A successful upstream answer that does not report `service_tier: "flex"` is refused with 502 `FLEX_TIER_UNCONFIRMED` and not charged; it is never served at the standard rate in Flex's name (streams are checked on their first chunk). Availability is the provider's limited beta. A Flex ask is refused with 400 `FLEX_TIER_UNSUPPORTED` before any charge, never answered by a different model, when the model offers no Flex (`openai/gpt-4.1*`, `openai/gpt-4o*`, `openai/o1`, `openai/o3-mini`, `openai/chat-latest`, `openai/gpt-5.3-codex`) or cannot report the served tier (`openai/gpt-5.6-*-pro`, partner pool; `openai/gpt-oss-*`, NVIDIA) — drop the field to run them at standard rates.
- `service_tier` on each `/v1/usage` row states the tier that line was billed at; absent means standard.
- A request that fails on our side is not charged. Truncated or malformed streams produce an error event and are not recorded as a charge.
- `/v1/usage` is the authoritative record; HTTP status alone does not establish a successful stream.

## Links
- Website: https://blockrun.ai · Docs: https://blockrun.ai/docs/getting-started/enterprise-api · Terms: https://blockrun.ai/terms (plain-text pointer for agents: https://api.blockrun.ai/terms.txt) · Contact: hello@blockrun.ai