# BlockRun on Solana — API Reference

> Pay-per-call AI gateway on Solana. 73 LLMs, image, video, music, multi-chain blockchain RPC (40+ chains), real-time data, prediction markets, sandbox compute, and phone & voice — all priced in **USDC on Solana** and settled on-chain via the x402 protocol. No API keys, no accounts, no subscriptions.

## Authentication

All paid endpoints follow the **x402 HTTP payment protocol**. There are no API keys.

1. Send the request without payment → BlockRun returns **HTTP 402 Payment Required** with the price and a signed payment requirement in `X-Payment-Required` (also encoded in the JSON body's `accepts[0]`).
2. Sign a USDC transfer on Solana locally (private key never leaves your machine). PayAI is the fee payer — your wallet does **not** need SOL.
3. Retry the same request with the `x-payment` header containing the base64-encoded signed payload.
4. BlockRun verifies, fulfills the request, and settles on-chain. Receipt returned in `X-Payment-Receipt` (Solana tx hash) and `X-Payment-Response` (settlement metadata).

Free models, free `GET /v1/models`, free `GET /v1/crypto|fx|commodity/*`, and `GET /v1/voice/call/{id}` (poll) require no payment.

## Base URL

```
https://sol.blockrun.ai
```

All endpoint paths in this document are relative to this host.

| Network | Base URL | Currency |
|---------|----------|----------|
| **Solana Mainnet** | `https://sol.blockrun.ai` | USDC (you are here) |
| Base Mainnet | `https://blockrun.ai` | USDC |
| Base Sepolia (testnet) | `https://testnet.blockrun.ai` | Test USDC |

## Network

| Field | Value |
|-------|-------|
| Chain | Solana mainnet |
| CAIP-2 | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpLKJaG34Vm1J` |
| Asset | USDC (mint `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`, 6 decimals) |
| Facilitator | `https://facilitator.payai.network` |
| BlockRun treasury | `AQqnMFBwGZEoti85aTVRy8XYpKrho7GaMDx9ZB3CEeKA` |
| Fee payer | PayAI (`2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4`) — absorbs SOL gas + ATA creation |

Each partner endpoint has its own `payTo` — Predexon, for example, receives USDC directly at its own Solana wallet (pass-through, 0% margin).

## Agent Workflow

1. List available models / endpoints — `GET /v1/models` (LLMs) or `GET /api/openapi` (full OpenAPI 3.1 spec).
2. Discover pricing — every paid endpoint returns its price in the 402 `accepts[0].amount` before you commit to paying.
3. Buy any prerequisite resource — e.g. for outbound voice calls, run `POST /v1/phone/numbers/buy` **before** `POST /v1/voice/call`. Receipts in `X-Payment-Receipt`.
4. Send the paid request with `x-payment`. On any non-2xx response that contains `"Payment was NOT charged"`, retry without risk of double-billing.
5. Poll long-running jobs (image, video, voice call) using their free `GET .../{id}` companion endpoint.

If no endpoint matches your task, fall through to one of BlockRun's MCP partners (`mcp__blockrun__*`) — they share the same x402 settlement.

---

# Chat & LLM (85 Models)

OpenAI-compatible. Same body shape as `api.openai.com/v1/chat/completions`. Streaming (`stream: true`), tool use, vision input, and Anthropic prompt caching all supported. Per-call cost = (input_tokens × input_price + output_tokens × output_price), floored at the $0.001/request minimum. Per-token chat carries NO platform margin — the rates below ARE the billed rates. Media, video and Live Search still carry 5%. Free models are completely free — no payment header needed.

## POST /v1/chat/completions
OpenAI-compatible chat completions for every model in the registry.

Example:
```json
{
  "model": "openai/gpt-5.2",
  "messages": [
    { "role": "user", "content": "Hello" }
  ],
  "max_tokens": 1024,
  "stream": false
}
```

## POST /v1/chat/{model}
Convenience alias — model is taken from the URL path, body omits `model`. Useful for hard-coding a model in a route.

## POST /v1/messages
Anthropic-compatible Messages API (system block, content arrays, prompt caching with `cache_control: { type: "ephemeral" }`, extended thinking, native tool use). Free fallback chains in when the primary is rate-limited.

## GET /v1/models
List every available LLM with provider, context window, max output, input/output price ($/M tokens), categories, and free flag. **Free.**

## Notable Free Models (no payment header required)
- `nvidia/muse-glimmer-30b` — Meta's open 30B, Apache 2.0, 131K context
- `nvidia/gemma-4-31b` — Google's open Gemma 4, 131K context
- `nvidia/nemotron-3.5-lightning` — sub-second on typical prompts, 1M context
- `nvidia/nemotron-3-ultra-550b` — the most capable free model here, 1M context; slowest, and its upstream is currently congested (see below)
- `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` — vision + reasoning (image input), 256K context
- `nvidia/llama-3.2-11b-vision` — image input, sub-second on image questions
- `cohere/north-mini-code` — code, under 200ms; give it `max_tokens` of 1200+ (see below)
- `poolside/laguna-xs-2.1` — code, answers directly without a thinking pass

Those eight are what `GET /v1/models` lists today and what `?filter=free`
returns. They are the same ids the Base gateway serves, so a free model chosen
on one chain works on the other.

Live list: `GET /api/v1/models?filter=free` (note the `/api` prefix — bare
`/v1/...` is not the gateway path and returns an HTML 404).

Give reasoning models room. Most of the free tier thinks before it answers, and
that thinking is charged against `max_tokens`. Set it too low and the model is
cut off mid-thought: you get a truncated reply with `finish_reason: "length"`,
or on a stream, nothing at all. `cohere/north-mini-code` is the clearest case —
it reliably writes 2000+ characters of reasoning first, so at `max_tokens: 400`
it produced no answer on 4 of 5 streamed calls, and none at 1200 or above. When
a free reply looks empty or truncated, raise `max_tokens` before assuming an
outage. The model's own reasoning is returned separately in `reasoning_content`,
never mixed into `content`.

`nvidia/nemotron-3-ultra-550b` is the least reliable of the eight right now:
NVIDIA's 550B deployment is congested, and it answered 1 of 3 non-streamed and 1
of 5 streamed calls when last measured. Failures fall through to
`nvidia/nemotron-3.5-lightning`, which carries the same 1M window, so requests
still get answered — but if you need this specific model to answer, retry.

Free models are served through a cascade: if the model you name is saturated or
retired upstream, the gateway answers from a healthy free model rather than
failing. Ids retired by NVIDIA stay callable and are answered this way, so no
pinned caller breaks. The `model` field in the response always names the model
that actually answered, so you can tell when the cascade substituted. Two of the
models it answers from — `nvidia/nemotron-3-super-120b` and
`nvidia/gpt-oss-20b` — are free and callable by exact id, but UNLISTED, so they
will not appear in that response.

Further free models are likewise callable by exact id but UNLISTED —
`nvidia/nemotron-3-nano-30b`, `nvidia/gpt-oss-120b`, `nvidia/gpt-oss-20b`,
`nvidia/deepseek-v4-flash`, `nvidia/nemotron-super-49b` and others. Address them by their full id. Note
`deepseek/deepseek-v4-flash` (the DeepSeek-hosted SKU) is PAID; only the
`nvidia/`-prefixed one is free.

## Notable Paid Vision Models
- `xiaomi/mimo-v2.5` — image input at $0.14/$0.28 per 1M, 1M-token context (the cheapest vision SKU here)
- `zai/glm-5.3-flash` — image input at $0.15/$0.50 per 1M, 1M-token context
- `qwen/qwen3.8-flash` — image input at $0.15/$0.47 per 1M, 1M-token context. Images must be larger than 10px on each side; smaller ones are refused upstream.
- `deepseek/deepseek-v4-flash-vision-exp` — image input at $0.44/$1.32 per 1M, 1M-token context. The only DeepSeek SKU here that takes images.

Free vision: `nvidia/llama-3.2-11b-vision` — 30/30 correct on a
decoder-validated 64x64 PNG, on both `/v1/chat/completions` and
`/v1/messages`. Use it for image input.

`nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` also carries the vision
category and reads images correctly on `/v1/chat/completions` (12/12), where
image turns are served by its direct-NVIDIA twin. On `/v1/messages` the same
request is currently refused with a 400 before payment. Until those two
routes agree, send image turns to `llama-3.2-11b-vision`.

Send images as OpenAI-style `image_url` content parts. Each image adds 1000 tokens to the quote.
Models that cannot take images (the `zai/glm-5*` line except Flash, and the `deepseek/*` text SKUs —
`deepseek-chat`, `deepseek-reasoner` and `deepseek-v4-pro`, but NOT `deepseek-v4-flash-vision-exp`)
reject them with `400 IMAGE_INPUT_UNSUPPORTED` **before** the 402, so a mismatched request is never charged.
Only `text` and `image_url` content parts are carried; anything else (video, audio, file) is refused the
same way rather than silently dropped.

`zai/glm-5.3` and `zai/glm-5.3-flash` always reason and accept `reasoning_effort` of `low`, `high` or
`max` only — `medium` is refused before payment because Z.AI rejects it outright.

## Pricing Highlights (paid models — these ARE the billed per-token rates; chat carries no margin)

Ids below are fully qualified, which is the form to send. A bare id (`gpt-5.4`)
resolves for pricing but is NOT reliably routable — for models we serve through a
wholesale conduit the upstream lookup is keyed on the full id, so the short form
is forwarded verbatim and rejected.

| Model | Provider | Input $/M | Output $/M |
|-------|----------|-----------|------------|
| openai/gpt-6-astra | OpenAI | 10.00 | 50.00 |
| openai/gpt-5.6-sol | OpenAI | 4.00 | 20.00 |
| openai/gpt-5.6-terra | OpenAI | 2.00 | 12.00 |
| openai/gpt-5.6-luna | OpenAI | 0.20 | 1.20 |
| openai/gpt-5.6-sol-pro | OpenAI | 4.00 | 20.00 |
| openai/gpt-5.6-terra-pro | OpenAI | 2.00 | 12.00 |
| openai/gpt-5.6-luna-pro | OpenAI | 0.20 | 1.20 |
| openai/gpt-5.5 | OpenAI | 5.00 | 30.00 |
| openai/gpt-5.4 | OpenAI | 2.50 | 15.00 |
| openai/gpt-5.4-mini | OpenAI | 0.75 | 4.50 |
| openai/gpt-5.1 | OpenAI | 1.25 | 10.00 |
| openai/gpt-4o | OpenAI | 2.50 | 10.00 |
| openai/gpt-4o-mini | OpenAI | 0.15 | 0.60 |
| anthropic/claude-fable-5.1 | Anthropic | 10.00 | 50.00 |
| anthropic/claude-fable-5 | Anthropic | 10.00 | 50.00 |
| anthropic/claude-opus-5 | Anthropic | 5.00 | 25.00 |
| anthropic/claude-opus-4.8 | Anthropic | 5.00 | 25.00 |
| anthropic/claude-sonnet-4.6 | Anthropic | 3.00 | 15.00 |
| anthropic/claude-haiku-4.5 | Anthropic | 1.00 | 5.00 |
| google/gemini-3.1-pro | Google | 2.00 | 12.00 |
| google/gemini-3.8-flash | Google | 0.75 | 3.75 |
| google/gemini-3.6-flash | Google | 0.75 | 3.75 |
| google/gemini-3.5-flash | Google | 1.50 | 9.00 |
| google/gemini-3.5-flash-lite | Google | 0.30 | 2.50 |
| google/gemini-2.5-pro | Google | 1.25 | 10.00 |
| google/gemini-2.5-flash | Google | 0.30 | 2.50 |
| xai/grok-4.6 | xAI | 2.00 | 6.00 |
| xai/grok-4.5 | xAI | 2.00 | 6.00 |
| xai/grok-4.3 | xAI | 1.25 | 2.50 |
| xai/grok-build-0.1 | xAI | 1.00 | 2.00 |
| moonshot/kimi-k3 | Moonshot | 3.00 | 15.00 |
| moonshot/kimi-k2.7 | Moonshot | 0.95 | 4.00 |
| moonshot/kimi-k2.6 | Moonshot | 0.95 | 4.00 |
| qwen/qwen3.8-max | Alibaba | 2.00 | 6.00 |
| qwen/qwen3.7-max | Qwen | 1.475 | 4.425 |
| qwen/qwen3.7-plus | Qwen | 0.32 | 1.28 |
| qwen/qwen3.7-flash | Qwen | 0.03 | 0.13 |
| qwen/qwen3.8-flash | Qwen | 0.15 | 0.47 |
| minimax/minimax-m3 | MiniMax | 0.30 | 1.20 |
| poolside/laguna-s-2.1 | Poolside | 0.090 | 0.180 |
| tencent/hy4-preview | Tencent | 0.834 | 2.501 |
| tencent/hy3 | Tencent | 0.0825 | 0.33 |
| xiaomi/mimo-v2.5 | Xiaomi | 0.14 | 0.28 |
| xiaomi/mimo-v2.5-pro | Xiaomi | 0.435 | 0.87 |
| deepseek/deepseek-v4-pro | DeepSeek | 1.32 | 3.96 |
| deepseek/deepseek-v4-flash-vision-exp | DeepSeek | 0.44 | 1.32 |
| deepseek/deepseek-chat | DeepSeek | 0.14 | 0.28 |
| zai/glm-5.3 | Z.AI | 1.40 | 4.40 |
| zai/glm-5.3-flash | Z.AI | 0.15 | 0.50 |
| zai/glm-5.2 | Z.AI | 1.40 | 4.40 |
| zai/glm-5.1 | Z.AI | 1.40 | 4.40 |
| zai/glm-5 | Z.AI | 1.00 | 3.20 |
| zai/glm-5-turbo | Z.AI | 1.20 | 4.00 |

`GET /api/pricing` returns the full machine-readable list.

Long-context tier: some models reprice the WHOLE request above a prompt-token threshold, mirroring the upstream's official tier. Grok family (grok-4.6, grok-4.5, grok-4.3, grok-4.20, grok-build-0.1) bills at 2x from 200K INCLUSIVE — xAI's own table reads `(>= 200k prompt tokens)` — e.g. grok-4.5 is $4.00 / $12.00 per 1M; Gemini Pro (gemini-3.1-pro, gemini-2.5-pro) at 2x input / 1.5x output above 200K; the GPT family (gpt-6-astra, gpt-5.6, gpt-5.5, gpt-5.4 and variants) at 2x input / 1.5x output above 272K. The OpenAI and Google boundaries are EXCLUSIVE (OpenAI publishes ">272K"), so a prompt of exactly the threshold is still billed at the base tier. `GET /api/pricing` reflects the base tier only.

---

# Image Generation

## POST /v1/images/generations
GPT Image 2.5 Flare / Sunburst, ChatGPT Images 2.0 (`gpt-image-2`), `gpt-image-1`, Google Nano Banana / Nano Banana 2 / Nano Banana Pro, Grok Imagine Image / Pro. Per-image pricing (varies $0.02-$0.15 depending on model + size + quality).

Example:
```json
{
  "model": "google/nano-banana",
  "prompt": "a duck eating ramen, photorealistic",
  "size": "1024x1024",
  "n": 1
}
```

## POST /v1/images/image2image
Image-to-image edits. Same model pool where supported. Pass `image` as a base64 data URI (`data:image/<format>;base64,...`) — URLs are not accepted, and the base64 must be single-line (no newlines). Decoded bytes must be a real PNG, JPEG, or WEBP image (Google models also accept HEIC/HEIF). Undecodable input is rejected BEFORE the 402 and costs nothing. Bytes that pass that header check but are then rejected by the provider return 400 and ARE charged — this route settles optimistically, and a magic-byte check cannot prove a fully valid image. A mislabeled mime type is normalized to the actual byte format. Optional `mask` (OpenAI models only) must decode to a PNG.

## GET /v1/images/models
List available image models with per-image pricing. **Free.**

---

# Video Generation

## POST /v1/videos/generations
Returns a `job_id` immediately; polling is free. Default 5–8s clips.

Example:
```json
{
  "model": "bytedance/seedance-1.5-pro",
  "prompt": "a robot dog skating down a quiet street, slow dolly",
  "duration_seconds": 5
}
```

Available models (Seedance is token-priced like upstream token360; Grok stays per-second):

| Model | Pricing (per 1M tokens) | Default | Default-call price example |
|-------|-------------------------|---------|-----------------------------|
| `xai/grok-imagine-video` | $0.05 / sec @ 480p (default) · $0.07 / sec @ 720p, + $0.001 / generation | 8s 480p | $0.401 (8s 480p) |
| `xai/grok-imagine-video-1.5` | $0.08 / sec @ 480p (default) · $0.14 / sec @ 720p · $0.25 / sec @ 1080p, + $0.001 / generation | 8s 480p, native synced audio | $0.641 (8s 480p) |
| `bytedance/seedance-1.5-pro` | **$3.108** / 1M tokens (text or image input) | 5s 720p, audio on (t2v) / off (i2v), 4–12s | ≈ $0.35 |
| `bytedance/seedance-2.0-mini` | **$3.50** / 1M tokens (text or image input) | 5s 720p, synced audio, 4–15s | ≈ $0.40 |
| `bytedance/seedance-2.0-fast` | **$7.252** / 1M tokens (text or image input) | 5s 720p, audio on (t2v) / off (i2v), 4–15s | ≈ $0.83 |
| `bytedance/seedance-2.0` | **$9.9715** / 1M tokens (text or image input) | 5s 720p, audio on (t2v) / off (i2v), 4–15s | ≈ $1.14 |
| `bytedance/seedance-2.5` | **$13.8565** / 1M tokens (text or image input) | 5s 720p, synced audio, 4–30s | ≈ $1.58 |

Token-priced models charge upfront based on `duration_seconds × 21,690 tokens/sec (calibrated at 720p) × resolution factor × per-1M rate × 1.05 margin`. The resolution factor scales the token count (480p = 0.5, 720p = 1, 1080p = 2.25, 4K = 9) and Seedance defaults to 720p. Image-to-video (`image_url`) bills at the same per-1M rate as text-to-video — there is no image discount. Price scales linearly with duration. Pass `resolution` (e.g. `"1080p"`, `"4K"`) or `generate_audio` to override defaults.

Accepted `resolution` values are per model and checked BEFORE the 402, so a bad one costs nothing: `seedance-2.0` takes 480p/720p/1080p/4K (4K is a real 3840×2160), `seedance-1.5-pro` takes 480p/720p/1080p, and `seedance-2.0-fast` / `seedance-2.5` take 480p/720p — anything else (360p, 540p, 1K and 2K included — no model renders them) returns a 400. `seedance-2.0-mini` renders 480p and 720p.

Seedance 2.5 trades resolution for length: it is text-to-video and image-to-video only — no first/last-frame, no reference media, no RealFace — but takes the longest clips (30s). For 1080p or 4K use Seedance 2.0 Pro.

**Real-person video (RealFace) is supported on Seedance 2.0, 2.0 Fast and 2.0 Mini — no KYC.** (Not on 1.5 Pro or 2.5.) BytePlus RealFace verifies a live face-match (nod + blink via a phone H5 page), not legal identity, so there is no government-ID upload. Enroll a real face once via the `/v1/realface/*` endpoints below to get a reusable `ta_xxxxxxxx` asset id, then pass it as `real_face_asset_id` (mutually exclusive with `image_url` — both seed the first frame). For AI-generated (non-real) characters, pass `image_url` instead.

## GET /v1/videos/generations/{id}
Poll a video job for status, URL, and metadata. **Free.**

## GET /v1/videos/models
List available video models with per-second pricing. **Free.**

---

# RealFace Enrollment (real-person video)

Create a reusable `ta_xxxxxxxx` RealFace asset for Seedance 2.0, 2.0 Fast and 2.0 Mini. No KYC — only a live face-match (nod + blink) on a phone H5 page; no government ID. Three steps: `init` (free) → phone liveness → `enroll` ($0.01). Then pass `real_face_asset_id` on any Seedance 2.0, 2.0 Fast or 2.0 Mini generation.

## POST /v1/realface/init
Create a REAL_FACE group and get the phone link the real person scans. **Free** (rate-limited per IP).

Body: `{ "name": "Display Name" }`. Returns `group_id` and `h5_link` (valid 120s). If the link expires before the scan, re-call with `{ "name", "groupId" }` to refresh.

`group_id` is an OPAQUE handle (`rf1_…`), not the upstream provider's id — store it and pass it back verbatim. It cannot be constructed or guessed, and anything else returns `404`, whether it is malformed, a guess, or a real group that is not yours.

```bash
curl -X POST https://sol.blockrun.ai/api/v1/realface/init \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada"}'
# → { "group_id":"rf1_v1_8Kk2xQ…", "h5_link":"https://...", "expires_in_seconds":120, ... }
```

## GET /v1/realface/status?groupId=…
Poll the group state. **Free** (rate-limited). The real person scans `h5_link` as a QR code and completes the ~1-minute liveness check; status flips `pending_validation` → `active`.

```bash
curl "https://sol.blockrun.ai/api/v1/realface/status?groupId=<groupId>"
# → { "status":"active", "ready_to_finalize":true, ... }
```

## POST /v1/realface/enroll
Upload the face photo and finalize. **$0.01 USDC (x402, Solana).** Requires the group to be `active` (liveness done). Settlement happens only after the asset is confirmed `active` upstream — failed uploads/matches are not charged.

Body: `{ "name", "image_url" (public https, ≤10 MB), "group_id" }`. Returns `asset_id` (`ta_xxxxxxxx`).

```bash
curl -X POST https://sol.blockrun.ai/api/v1/realface/enroll \
  -H "Content-Type: application/json" \
  -H "x-payment: <base64 x402 payment>" \
  -d '{"name":"Ada","image_url":"https://example.com/face.jpg","group_id":"rf1_v1_8Kk2xQ…"}'
# → { "asset_id":"ta_xxxxxxxx", "usage": { "compatible_models":["bytedance/seedance-2.0","bytedance/seedance-2.0-fast"] }, ... }
```

## GET /v1/wallet/{address}/realfaces
List the RealFace assets a wallet has enrolled. **Free** (rate-limited). `{address}` is a Solana base58 address. Returns `{ wallet, realfaces: [...], count }`, each entry carrying `assetId`, `name`, `imageUrl`, `createdAt`. Unauthenticated, so it publishes nothing else — no settlement hash, no upstream ids, no group id.

---

# Audio / Music Generation

## POST /v1/audio/generations
MiniMax Music. Generates a ~3-minute track (the `duration_seconds` hint is forwarded but MiniMax always returns a full track). Generation takes 1–3 minutes — pass `instrumental: true` to skip lyrics or provide your own.

Price: **$0.165 per track** ($0.15 cost + margin).

Example:
```json
{
  "model": "minimax/music-2.5+",
  "prompt": "lo-fi hip hop with a jazzy piano, mellow",
  "instrumental": true,
  "duration_seconds": 90
}
```

## GET /v1/audio/models
List available audio models. **Free.**

---

# Web Search

## POST /v1/search
Grok Live Search via xAI — multi-source live search across web, news, and X/Twitter, summarized by Grok with citations.
**Price: `max_results × $0.025 + 30% margin`** (default 10 results → ~$0.325).

Example:
```json
{
  "query": "latest news about USDC adoption on Solana",
  "sources": ["web", "news", "x"],
  "max_results": 10,
  "from_date": "2026-04-01"
}
```

## POST /v1/exa/{search|find-similar|contents|answer}
Exa neural web search — agent-friendly, fast, structured.

| Endpoint | Price | Description |
|----------|-------|-------------|
| `/v1/exa/search` | $0.01 | Neural/keyword search. Optional `category`: `linkedin profile`, `company`, `research paper`, `news`, `pdf`, `github`, `tweet`, `financial report`. |
| `/v1/exa/find-similar` | $0.01 | Find semantically similar pages for a URL. |
| `/v1/exa/contents` | $0.002 / URL | Extract clean markdown, highlights, and summaries (price scales with `urls.length`). |
| `/v1/exa/answer` | $0.01 | AI-generated answer grounded in live web results. |

LinkedIn profile search example:
```json
{
  "query": "founding engineer USDC payments",
  "category": "linkedin profile",
  "numResults": 10
}
```

---

# Modal Sandbox Compute

Per-tenant isolated containers running on Modal. Any Docker image, optional GPU (T4 → H100). Two-step flow:
1. `POST /v1/modal/sandbox/create` — provision; refunded as a flat charge or hourly bucket.
2. `POST /v1/modal/sandbox/exec` — run a command; returns stdout/stderr/exit code.
3. `POST /v1/modal/sandbox/terminate` — release.

| Endpoint | Price | Description |
|----------|-------|-------------|
| `POST /v1/modal/sandbox/create` | $0.01 (flat) or hourly | Create sandbox. Optional GPU; hourly billing charged upfront for the full duration (no early-terminate refund). |
| `POST /v1/modal/sandbox/exec` | $0.001 | Execute command in a live sandbox. |
| `POST /v1/modal/sandbox/status` | $0.001 | Check status (running/terminated). |
| `POST /v1/modal/sandbox/terminate` | $0.001 | Terminate and release resources. |

Example create:
```json
{
  "image": "python:3.13-slim",
  "gpu": null,
  "timeout_seconds": 300
}
```

---

# Phone & Voice (Twilio + Bland.ai)

Wallet-owned US/CA numbers + outbound AI conversation calls. **Two-step flow**: buy a number, *then* place the call. Numbers are auto-registered with Bland on purchase so they can be used as outbound caller-ID (BYOT). Currently US/CA only; outbound only; no SMS (A2P 10DLC bottleneck).

Ownership is keyed to your **Solana wallet** — buying a number on Base gives you a separate identity, no cross-chain merge.

## POST /v1/voice/call
Outbound AI conversation call via Bland.ai. Default 5 min, hard cap 30 min. Returns `call_id` immediately; poll the `GET` companion for live status, transcript, and recording URL.

Price: **$0.54** per call.

Example:
```json
{
  "to": "+14155552671",
  "task": "Call this restaurant and ask whether they have a table for two at 7pm tonight. If not, ask what time tonight does.",
  "from": "+14152223333",
  "voice": "june",
  "max_duration": 5
}
```

`from` is **required** — must be a number this wallet owns (provisioned via `numbers/buy`). Missing-from returns 400 with a hint pointing to the buy endpoint.

## GET /v1/voice/call/{call_id}
Poll call status, duration, transcript, recording URL. **Free.**

## POST /v1/phone/numbers/buy
Lease a US/CA number for 30 days, wallet-bound.
Price: **$5.00**.

Example:
```json
{ "country": "US", "areaCode": "415" }
```

## POST /v1/phone/numbers/renew
Extend the lease by 30 more days.
Price: **$5.00**.

```json
{ "phoneNumber": "+14152223333" }
```

## POST /v1/phone/numbers/list
List active numbers for the calling wallet (wallet identity comes from x402 payer).
Price: **$0.001**.

## POST /v1/phone/numbers/release
Release a number back to the Twilio pool. **Free** (still goes through x402 so wallet identity is verified).

```json
{ "phoneNumber": "+14152223333" }
```

## POST /v1/phone/lookup
Carrier + line type (landline / mobile / VoIP).
Price: **$0.01**.

```json
{ "phoneNumber": "+14155552671" }
```

## POST /v1/phone/lookup/fraud
Lookup + fraud signals (SIM swap, call forwarding, recent porting).
Price: **$0.05**.

---

# Surf — RETIRED 2026-09-06 (`/api/v1/surf/*`)

The Surf integration has been retired on this gateway. All 82 `/api/v1/surf/*` paths return
**410 Gone** with `code: SERVICE_DISCONTINUED`. The refusal is before the payment gate, so an unpaid
call is refused rather than quoted and a paid call is impossible. They are no longer listed in
`/.well-known/x402` or `/openapi.json` either.

We are looking for a new vendor in this space. No replacement endpoint is live yet — contact
@bc1max on Telegram if you were using it and need a migration path.

# Prediction Markets — Predexon v2 (`/v1/pm/*`)

Unified cross-venue prediction-market data: Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, dFlow, Binance Futures, sports. 100% pass-through to Predexon — they receive USDC directly at `J28Fii2VFnJcavvaeEfsKc628htk3mnrZKubD7WsGStW`.

**Pricing tiers:**
Flat **$0.0075/call** — charged as-is, no service fee added.
Both tiers price identically; they describe endpoint WEIGHT only.
- **Tier 1** — market data, events, trades, orderbooks, positions, leaderboards, UMA oracle status.
- **Tier 2** — wallet analytics (PnL, positions, clustering), smart money signals, cross-venue matching, Binance futures, wallet identity, sports.

Selected endpoints (every URL is `GET /v1/pm/<path>` unless noted):

```
polymarket/markets                      $0.0075  Filter + paginate markets
polymarket/markets/keyset               $0.0075  Cursor-based pagination
polymarket/events                       $0.0075  Events feed
polymarket/market-price/:token_id       $0.0075  Current or historical price
polymarket/candlesticks/:condition_id   $0.0075  OHLCV candles
polymarket/orderbooks                   $0.0075  Historical orderbook snapshots
polymarket/trades                       $0.0075  Historical trades
polymarket/leaderboard                  $0.0075  Smart wallet leaderboard
polymarket/uma/markets                  $0.0075  UMA oracle questions by state

polymarket/wallet/:wallet               $0.0075  Wallet profile + metrics
polymarket/wallet/pnl/:wallet           $0.0075  PnL summary + time series
polymarket/wallet/positions/:wallet     $0.0075  Open + historical positions
polymarket/wallet/identity/:wallet      $0.0075  Identity + profile metadata
POST polymarket/wallet/identities       $0.0075  Bulk identity (≤200 addresses)
polymarket/wallet/:address/cluster      $0.0075  On-chain transfer / identity graph
polymarket/market/:condition_id/smart-money  $0.0075  Smart-money positioning
polymarket/markets/smart-activity       $0.0075  Markets where high performers trade

kalshi/markets                          $0.0075
kalshi/trades                           $0.0075
kalshi/orderbooks                       $0.0075

dflow/trades                            $0.0075
dflow/wallet/positions/:wallet          $0.0075
dflow/wallet/pnl/:wallet                $0.0075

binance/candles/:symbol                 $0.0075  OHLCV
binance/ticks/:symbol                   $0.0075  Microsecond book ticker

matching-markets                        $0.0075  Equivalent markets across venues
matching-markets/pairs                  $0.0075  Active exact-matched pairs
markets/search                          $0.0075  Unified search across 5+ venues

limitless/markets                       $0.0075
limitless/orderbooks                    $0.0075
opinion/markets                         $0.0075
opinion/orderbooks                      $0.0075
predictfun/markets                      $0.0075
predictfun/orderbooks                   $0.0075
```

Full registry (60+ paths including sports + canonical cross-venue markets): `GET /v1/pm/` (returns 404 with available list) or https://blockrun.ai/marketplace/predexon.

Example:
```
GET /v1/pm/polymarket/markets?limit=10&active=true&order_by=volume_24h&order=desc
```

---

# On-chain Price Feeds (Pyth-backed)

Realtime + historical OHLCV for crypto, FX, and commodities. Sessions: `?session=pre|post|on`.

## US Stocks (975+ tickers) — catalog only, quotes NOT served
- `GET /v1/usstock/list` — **Free** symbol list. Works.
- `GET /v1/usstock/price/{SYMBOL}` — **not currently served**, answers `501`.
- `GET /v1/usstock/history/{SYMBOL}` — **not currently served**, answers `501`.

Equity quotes have no data source on this gateway today. The symbol catalog is
real and free; the price and history endpoints exist and return
`501 {"reason":"no_data_source"}`. Realtime and global equity coverage are
available on request — contact care@blockrun.ai. Do not budget for these as a
paid call: nothing is charged, because nothing is served.

## International Stocks (`/v1/stocks/{market}/*`)
Same shape and the same limitation: `/list` works for `us`, `hk`, `jp`, `kr`,
`gb`, `de`, `fr`, `nl`, `ie`, `lu`, `cn`, `ca`; `price` and `history` answer
`501`.

## Crypto (500+ pairs, FREE)
- `GET /v1/crypto/list`
- `GET /v1/crypto/price/BTC-USD`
- `GET /v1/crypto/history/ETH-USD?resolution=D`

## FX (FREE)
- `GET /v1/fx/list`
- `GET /v1/fx/price/EUR-USD`
- `GET /v1/fx/history/EUR-USD`

## Commodities (FREE)
- `GET /v1/commodity/list`
- `GET /v1/commodity/price/XAU-USD` (gold) / `/XAG-USD` (silver)
- `GET /v1/commodity/history/XAU-USD`

---

# Blockchain RPC

## POST /v1/rpc/{network}
Multi-chain JSON-RPC — **one endpoint, 40+ chains**. Swap `{network}` for any chain: `ethereum`, `base`, `solana`, `polygon`, `bsc`, `arbitrum`, `optimism`, `avalanche`, `zksync`, `bitcoin`, `xrp`, `polkadot`, `near`, `sui`, and more (aliases like `eth`, `arb`, `avax` work too). Standard `jsonrpc: "2.0"` body, EVM (`eth_*`) and non-EVM (`getSlot`, …) methods. **$0.002 per call** (a JSON-RPC batch is priced per element); hot reads are cached. No API key — pay-per-call in USDC on Solana.
Example: `curl -X POST https://sol.blockrun.ai/api/v1/rpc/ethereum -d '{"jsonrpc":"2.0","method":"eth_blockNumber","id":1}'`

## POST /v1/solana/rpc
Free public Solana mainnet-beta JSON-RPC proxy, Tatum-backed, with hot-path caching for common reads (getLatestBlockhash, getEpochInfo, getAccountInfo, etc.). Standard `jsonrpc: "2.0"` body — drop in as a replacement for any public RPC URL in your Solana SDK. (Solana is also available via the unified paid `/v1/rpc/solana`.)

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getLatestBlockhash",
  "params": []
}
```

---

# X/Twitter Data

The AttentionVC partner endpoints (`/v1/x/*`) have been removed from the Solana gateway. For X/Twitter data, use `POST /v1/search` with `sources: ["x"]` (Grok Live Search) here, or the Base gateway at blockrun.ai.

---

# Live Streams (Public, Free)

| Endpoint | Description |
|----------|-------------|
| `GET /api/live/transfers` | Server-Sent Events feed of recent on-chain USDC payments to the BlockRun Solana treasury. |
| `GET /api/live/calls` | SSE feed of recent API calls (sanitized, public-safe). |

---

# Health & Discovery

| Endpoint | Description |
|----------|-------------|
| `GET /api/health` | Liveness — returns region echo + service status. |
| `GET /api/openapi` (and `/openapi.json`) | Full OpenAPI 3.1 document with `x-payment-info` on every paid endpoint. |
| `GET /.well-known/x402` | x402scan v1 discovery manifest (resource list). |
| `GET /.well-known/agent.json` | Agent manifest (service description, payment shape, endpoint map). |
| `GET /api/pricing` | Machine-readable model price list. |

---

# Public Traction (across all networks since Feb 2026)

Live, on-chain verifiable at https://blockrun.ai/metrics:
- 6,000,000+ API calls served
- 1,431+ unique paying wallets
- $31,000+ USDC settled on-chain

---

# SDKs & MCP

```bash
# Python
pip install blockrun-llm

# TypeScript / Node
npm install @blockrun/llm

# Go
go get github.com/blockrunai/blockrun-llm-go

# Claude Code / Cursor / any MCP client
claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest
# Prefer Solana settlement: echo solana > ~/.blockrun/.chain
```

Python:
```python
from blockrun_llm import LLMClient
client = LLMClient(base_url="https://sol.blockrun.ai", chain="solana")
response = client.chat("openai/gpt-4o", "Hello!")
```

TypeScript:
```ts
import { LLMClient } from "@blockrun/llm";
const client = new LLMClient({ baseUrl: "https://sol.blockrun.ai", chain: "solana" });
const response = await client.chat("openai/gpt-4o", "Hello!");
```

---

# ClawRouter — Smart LLM Router (Open Source)

MIT-licensed router that sits between your agent and any LLM provider. Saves 67% on average (up to 78%) via 7-layer prompt compression, intelligent model routing, and response caching.

```bash
npm install -g @blockrun/clawrouter
openclaw plugins install @blockrun/clawrouter
```

GitHub: https://github.com/BlockRunAI/ClawRouter

---

# Franklin — AI Agent That Pays Its Own Bills

Reference implementation built on BlockRun: a wallet-owning agent that picks the cheapest capable model per task, buys data, generates media, and searches the web — all paid from its own USDC balance.

Live: https://franklin.run

---

# Error Handling

| Status | Meaning | Settlement |
|--------|---------|------------|
| 200/201 | Success | Charged. `X-Payment-Receipt` returned (Solana tx hash). |
| 400 | Bad request shape — fix params. | Usually not charged (validation runs before the 402). **EXCEPT** when the upstream — not our validator — rejects the request: `images/image2image` "Invalid input image", and non-streaming `/v1/chat/completions` "INVALID_PARAMETER". Those settle optimistically and ARE charged. Trust `X-Payment-Response`. |
| 402 | Payment required (no `x-payment`) or settlement/verification failure. | Not charged. |
| 403 | Forbidden (wrong wallet for the resource, blocked emergency number, expired number, etc.). | Not charged. |
| 404 | Endpoint or resource not found. | Not charged. |
| 429 | Rate limited. | Not charged. |
| 5xx | Upstream / internal error. | **Not reliable — check `X-Payment-Response`.** The media routes and non-streaming chat settle OPTIMISTICALLY (payment fires in parallel with the upstream call), so a failure after that point IS charged and is logged as a paid error for reconciliation. Streaming chat and the async video/audio POSTs are genuinely not charged (settle runs later). |

Always trust the `X-Payment-Response` header — `success=true` means USDC moved on-chain on Solana; `success=false` means no settlement ran.

For irreversible operations (phone-number purchase, voice call), the upstream action runs **before** settlement — if Twilio/Bland fails, payment is not charged and the resource is rolled back automatically.

---

# Pricing Summary

**Every price below is what you actually sign and pay. There is no per-call
service fee on Solana — we keep this rail cheap.** Paid requests are floored at
a **$0.001 minimum charge**, so a very small request pays $0.001 rather than its
linear token price. (Free endpoints stay exactly $0; the floor never applies to
them.) The `amount` in a live 402's payment requirements is always
authoritative; when in doubt, sign what the 402 says, not what this table says.
`GET /v1/models` returns these numbers under `billing`.

| Endpoint | Price (min charge $0.001) |
|----------|-------|
| `POST /v1/chat/completions` (paid models) | input × in$/M + output × out$/M (no margin), min $0.001 |
| `POST /v1/messages` | same as chat completions |
| `POST /v1/images/generations` | $0.02 – $0.15 / image (varies) |
| `POST /v1/videos/generations` | pricePerSecond × duration × 1.05 |
| `POST /v1/audio/generations` (MiniMax music) | $0.165 / track |
| `POST /v1/search` (Grok Live Search) | max_results × $0.025 × 1.05 |
| `POST /v1/exa/search` | $0.01 |
| `POST /v1/exa/find-similar` | $0.01 |
| `POST /v1/exa/contents` | $0.002 / URL |
| `POST /v1/exa/answer` | $0.01 |
| `POST /v1/modal/sandbox/create` | $0.01 flat or hourly |
| `POST /v1/modal/sandbox/exec` | $0.001 |
| `POST /v1/modal/sandbox/status` | $0.001 |
| `POST /v1/modal/sandbox/terminate` | $0.001 |
| `POST /v1/voice/call` | $0.54 |
| `GET /v1/voice/call/{id}` | Free |
| `POST /v1/phone/numbers/buy` | $5.00 (30-day lease) |
| `POST /v1/phone/numbers/renew` | $5.00 (30-day extend) |
| `POST /v1/phone/numbers/list` | $0.001 |
| `POST /v1/phone/numbers/release` | Free |
| `POST /v1/phone/lookup` | $0.01 |
| `POST /v1/phone/lookup/fraud` | $0.05 |
| `GET /v1/pm/*` Tier 1 | $0.0075 |
| `GET/POST /v1/pm/*` Tier 2 | $0.0075 |
| `GET /v1/usstock/list` / `stocks/{market}/list` | Free |
| `GET /v1/usstock/price` / `history`, `stocks/{market}/price` / `history` | **not served — 501** |
| `GET /v1/crypto/*` | Free |
| `GET /v1/fx/*` | Free |
| `GET /v1/commodity/*` | Free |
| `POST /v1/rpc/{network}` | $0.002/call (batch priced per element) |
| `POST /v1/solana/rpc` | Free |
| `GET /v1/models` | Free |
| `GET /api/health`, `/api/openapi`, `/api/pricing` | Free |
| `GET /api/live/*` (SSE) | Free |

---

# Links

- Project: https://blockrun.ai
- OpenAPI: https://sol.blockrun.ai/openapi.json
- x402 discovery: https://sol.blockrun.ai/.well-known/x402
- Agent manifest: https://sol.blockrun.ai/.well-known/agent.json
- Live metrics: https://blockrun.ai/metrics
- GitHub Org: https://github.com/BlockRunAI
- ClawRouter: https://github.com/BlockRunAI/ClawRouter
- Franklin: https://franklin.run
- X/Twitter: https://x.com/BlockRunAI
- MCP Server: `claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest`