--- name: blockrun-api description: | HTTP reference for calling BlockRun directly over REST — endpoints, request bodies, model tables, and the x402 payment flow. Use this when you are writing code against the API rather than driving it through the MCP server; for install and wallet setup read https://blockrun.ai/skill.md instead. One endpoint serving 92 AI models, real-time data, media generation, and 40-chain blockchain RPC. Pay-per-request in USDC on Base or Solana via x402. No API keys. TRIGGERS: blockrun api, x402 request, chat completions endpoint, /v1/chat/completions, 402 payment required, x-payment header, EIP-3009 authorization, blockrun curl, blockrun sdk homepage: https://blockrun.ai metadata: version: 1 --- # BlockRun Agent API The routing & payment layer for AI. One endpoint routes to 92 AI models, real-time data, and multi-chain blockchain RPC — payment built in, pay-per-request in USDC via x402. No API keys. ## Overview BlockRun provides AI agents with: - **Multi-model access** - GPT-5, Claude, Gemini, Grok, DeepSeek, Kimi - **No API keys** - Pay with USDC via x402 protocol - **Web search** - Neural semantic search via Exa ($0.011/search), find similar pages, extract page contents, AI-grounded answers. Endpoint: `/api/v1/exa/search` - **Image generation** - ChatGPT Images 2.0 (gpt-image-2), GPT Image 1, Nano Banana / Nano Banana Pro, Grok Imagine / Pro, CogView-4, Seedream 5.0 Pro - **Video generation** - Grok Imagine Video, Seedance (1.5 Pro / 2.0 Fast / 2.0 Pro), Sora 2 — up to 15s (Seedance 2.0), token-metered - **Music generation** - MiniMax Music — full-length tracks up to ~4 min ($0.1575/track) - **Phone & Voice** - Outbound AI conversation calls via Bland.ai ($0.541/call) + wallet-owned US/CA phone numbers via Twilio ($5.001/30 days). Carrier + fraud lookups ($0.011/$0.051). Endpoints: `/api/v1/voice/call`, `/api/v1/phone/*`. - **Text-to-Speech** - ElevenLabs voice synthesis. Flash v2.5 (~75ms, real-time) and Turbo v2.5 at $0.05/1k chars; Multilingual v2 / Eleven v3 at $0.10/1k chars. Plus ByteDance Seed Audio 1.0 (bytedance/seed-audio-1.0) — prompt-directed audio creation, up to 120s, $0.003/second. Plus sound effects ($0.0535/clip). Endpoints: `/api/v1/audio/speech`, `/api/v1/audio/sound-effects`, free `/api/v1/audio/voices`. - **Multi-chain RPC** - One endpoint, 40 chains. JSON-RPC 2.0 passthrough for Ethereum, Base, Solana, Polygon, BSC, Arbitrum, Optimism, Avalanche, Bitcoin, Sui, and more. $0.003/call, no API key. Endpoint: `POST /api/v1/rpc/{network}` (e.g. `/api/v1/rpc/ethereum`). ## API Endpoints Base URL: `https://blockrun.ai/api` ### Chat Completions ``` POST /v1/chat/completions ``` OpenAI-compatible endpoint. Requires x402 payment header. **Request:** ```json { "model": "openai/gpt-4o", "messages": [ {"role": "user", "content": "Hello"} ], "max_tokens": 1024 } ``` ### List Models ``` GET /v1/models ``` Returns available models with pricing. ### Image Generation ``` POST /v1/images/generations POST /v1/images/image2image ``` Generate or edit images with gpt-image-2 (ChatGPT Images 2.0), gpt-image-1, Nano Banana / Pro, Grok Imagine / Pro, CogView-4, or Seedream 5.0 Pro (bytedance/seedream-5-pro). ### Video Generation ``` POST /v1/videos/generations ``` Generate videos with Grok Imagine Video, Seedance 1.5 Pro / 2.0 Fast / 2.0 Pro, or Sora 2. Default 5s @ 720p; max duration 15s (Seedance 2.0 / 2.0 Fast), 12s (Seedance 1.5 Pro, Sora 2), 15s (Grok). Payment is settled on the first completed poll. ### Phone & Voice **2-step flow: buy a number first, then call.** `voice/call` requires `from` (a wallet-owned number). ``` POST /v1/phone/numbers/buy $5.001 Lease a US/CA number for 30 days (wallet-bound). DO THIS FIRST. POST /v1/voice/call $0.541 Outbound AI call via Bland.ai. REQUIRES `from` = wallet-owned number. Default max_duration=5min, hard cap 30min. GET /v1/voice/call/{call_id} free Poll call status, transcript, recording URL POST /v1/phone/numbers/renew $5.001 Extend lease by 30 days POST /v1/phone/numbers/list $0.002 List numbers owned by the calling wallet POST /v1/phone/numbers/release free Release a number back to the pool POST /v1/phone/lookup $0.011 Carrier + line type POST /v1/phone/lookup/fraud $0.051 Lookup + SIM swap / call forwarding signals ``` Numbers purchased via `numbers/buy` are auto-registered with Bland so they can be passed as the `from` field on `voice/call` (BYOT outbound caller-ID). ### Multi-chain RPC One JSON-RPC endpoint for 40 chains (powered by Tatum). No API key — $0.003/call. ``` POST /v1/rpc/{network} $0.003/call Standard JSON-RPC 2.0; {network} = ethereum, base, solana, polygon, bsc, arbitrum, optimism, avalanche, bitcoin, xrp, sui, near… (40+, aliases like eth/arb/avax). ``` EVM (`eth_*`) and non-EVM (`getSlot`…) methods both work. A JSON-RPC batch (array body) is priced per element. Unsupported `{network}` → 400 with the supported list. ```bash curl -X POST https://blockrun.ai/api/v1/rpc/ethereum \ -d '{"jsonrpc":"2.0","method":"eth_blockNumber","id":1}' ``` ## x402 Payment Flow 1. Send request to endpoint 2. Receive `402 Payment Required` with price in `x-payment-required` header 3. Sign USDC payment locally (key never leaves your machine) 4. Retry request with `x-payment` header containing signed payment 5. Receive response ## Available Models ### Chat Models | Model | Input $/M | Output $/M | |-------|-----------|------------| | openai/gpt-5.6-sol | 5.00 | 30.00 | | openai/gpt-5.6-sol-pro | 5.00 | 30.00 | | openai/gpt-5.6-terra | 2.00 | 12.00 | | openai/gpt-5.6-terra-pro | 1.00 | 6.00 | | openai/gpt-5.6-luna | 0.20 | 1.20 | | openai/gpt-5.6-luna-pro | 0.10 | 0.60 | | openai/gpt-5.5 | 5.00 | 30.00 | | openai/gpt-5.4 | 2.50 | 15.00 | | openai/gpt-4o | 2.50 | 10.00 | | openai/gpt-4o-mini | 0.15 | 0.60 | | anthropic/claude-fable-5 | 10.00 | 50.00 | | anthropic/claude-opus-5 | 5.00 | 25.00 | | anthropic/claude-opus-4.8 | 5.00 | 25.00 | | anthropic/claude-sonnet-5 | 3.00 | 15.00 | | anthropic/claude-sonnet-4.6 | 3.00 | 15.00 | | anthropic/claude-haiku-4.5 | 1.00 | 5.00 | | google/gemini-3.1-pro | 2.00 | 12.00 | | google/gemini-3.6-flash | 1.50 | 7.50 | | google/gemini-3.5-flash | 1.50 | 9.00 | | google/gemini-3.5-flash-lite | 0.30 | 2.50 | | google/gemini-2.5-pro | 1.25 | 10.00 | | deepseek/deepseek-v4-pro | 0.435 | 0.87 | | deepseek/deepseek-chat | 0.20 | 0.40 | | xai/grok-4.5 | 2.50 | 9.00 | | xai/grok-4.3 | 1.50 | 4.00 | | xai/grok-build-0.1 | 1.50 | 3.00 | | moonshot/kimi-k3 | 3.00 | 15.00 | | minimax/minimax-m3 | 0.30 | 1.20 | | qwen/qwen3.7-max | 1.48 | 4.43 | | qwen/qwen3.7-plus | 0.32 | 1.28 | | qwen/qwen3.7-flash | 0.03 | 0.13 | | tencent/hy3 | 0.13 | 0.53 | | xiaomi/mimo-v2.5-pro | 0.44 | 0.87 | | zai/glm-5.2 | 1.40 | 4.40 | | zai/glm-5.1 | 1.40 | 4.40 | | zai/glm-5 | 0.60 | 1.92 | Long-context tier: some models reprice the whole request above 200K prompt tokens, mirroring the provider's official pricing. Grok (grok-4.5, grok-4.3, grok-4.20, grok-build-0.1) charges 2x (e.g. grok-4.5 is 5.00 / 18.00 per 1M); Google Gemini Pro (gemini-2.5-pro, gemini-3.1-pro) charges 2x input / 1.5x output (e.g. gemini-2.5-pro is 2.50 / 15.00 per 1M). ### E2E Verified (Feb 2026) All models tested end-to-end via TypeScript and Python SDKs: | Provider | Model | Status | |----------|-------|--------| | OpenAI | gpt-4o-mini | Passed | | Anthropic | claude-sonnet-4 | Passed | | Google | gemini-2.5-flash | Passed | | DeepSeek | deepseek-chat | Passed | | xAI | grok-4.3 | Passed | | Moonshot | kimi-k3 | Passed | | Moonshot | kimi-k2.7 | Passed | ### Image Models | Model | Price | |-------|-------| | openai/gpt-image-1 | $0.02-0.04/image | | openai/gpt-image-2 | $0.06-0.12/image | | google/nano-banana | $0.05/image | | google/nano-banana-2 | $0.09/image | | google/nano-banana-pro | $0.10-0.15/image | | xai/grok-imagine-image | $0.02/image | | xai/grok-imagine-image-pro | $0.07/image | | zai/cogview-4 | $0.015-0.02/image | | bytedance/seedream-5-pro | $0.045-0.09/image | ### Video Models | Model | Price | Default | Max duration | RealFace | |-------|-------|---------|--------------|----------| | xai/grok-imagine-video | $0.05/sec | 8s | 15s | — | | bytedance/seedance-1.5-pro | token-metered $4.32/1M (~$0.098/sec @720p) | 5s 720p | 12s | ❌ | | bytedance/seedance-2.0-fast | token-metered $11.2/1M (~$0.255/sec @720p) | 5s 720p | 15s | ✅ | | bytedance/seedance-2.0 | token-metered $14/1M (~$0.319/sec @720p) | 5s 720p | 15s | ✅ | | azure/sora-2 | $0.10/sec | 4s | 12s (4/8/12s) | — | Seedance is token-metered: `duration × 21,690 tokens/sec (@720p) × resolution-factor × per-1M rate × 1.05`. Image-to-video uses the same rate as text-to-video (no discount). Price scales linearly with duration. **RealFace** (consistent real-person character video, Seedance 2.0 / 2.0 Fast only — NOT 1.5 Pro): pass `real_face_asset_id` (format `ta_xxxx`) on those models. Get the asset id from BlockRun's RealFace enrollment flow (`POST /v1/realface/enroll`, $0.011). Mutually exclusive with `image_url`. Sora rejects human faces upstream. ## SDKs ### TypeScript ```bash npm install @blockrun/llm ``` ```typescript import { LLMClient } from '@blockrun/llm'; const client = new LLMClient(); const response = await client.chat('openai/gpt-4o', 'Hello!'); ``` ### Python ```bash pip install blockrun-llm ``` ```python from blockrun_llm import LLMClient client = LLMClient() response = client.chat('openai/gpt-4o', 'Hello!') ``` ### MCP Server ```bash claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest ``` ## Networks - **Base Mainnet** (Chain ID 8453) - Production with real USDC - **Base Sepolia** (Chain ID 84532) - Testnet with test USDC - **Solana Mainnet** - Production with real USDC ## Links - Website: https://blockrun.ai - Docs: https://github.com/BlockRunAI/awesome-blockrun/tree/main/docs - GitHub: https://github.com/BlockRunAI - X/Twitter: https://x.com/BlockRunAI