Chat Completions

The Chat Completions API is OpenAI-compatible, making it easy to migrate existing code. Point your client at BlockRun, pick a model, and pay per request in USDC over x402.

Endpoint

POST https://blockrun.ai/api/v1/chat/completions

/api/v1/... is the canonical namespace and the one /api/openapi and /.well-known/x402 publish. /v1/... is served as an alias for every route — POST https://blockrun.ai/v1/chat/completions reaches the same handler with the same body, headers and payment flow — because a great deal of published material named that path first. Prefer the canonical form in new code.

Request

Headers

Body Parameters

Unknown parameters (seed, n, logprobs, top_k, …) are kept and forwarded verbatim to OpenAI-compatible upstreams. stream_options is the one exception: it is never forwarded — the gateway sets its own stream_options.include_usage because billing needs the usage frame.

Message Object

A messages array with only system entries is rejected with 400 / EMPTY_CONVERSATION — at least one user, assistant, or tool message is required.

Response

Success (200)

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1703123456,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  }
}

Usage Fields

Reasoning in its own field

Reasoning models (DeepSeek, Z.AI GLM, MiniMax, Moonshot Kimi, Claude with thinking enabled, open-weight reasoning models) return their chain of thought on message.reasoning_content, separate from content. The field is optional and absent when the model produced no reasoning.

• Non-streaming (since 2026-08-27): choices[0].message.reasoning_content carries the reasoning; content carries the answer.
• Streaming: reasoning arrives as delta.reasoning_content chunks alongside delta.content.
• Tool-call turns: an assistant message that carries tool_calls has content: "" — that is the OpenAI shape for "answered by calling a tool". The gateway no longer promotes reasoning into content on those turns; it lives on reasoning_content only. If you echo assistant turns back into history, echo reasoning_content too — some thinking models require it on prior tool-call turns.
• A reply whose content would otherwise be empty on a non-tool turn still receives the reasoning text as content, so a paying caller never gets a blank string.

{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "",
      "reasoning_content": "The user wants the weather, so I should call get_weather…",
      "tool_calls": [{"id": "call_abc", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\":\"SF\"}"}}]
    },
    "finish_reason": "tool_calls"
  }]
}

Response headers

Protocol naming convention:

• Claude native /v1/messages: usage.input_tokens, usage.output_tokens, usage.cache_creation_input_tokens, usage.cache_read_input_tokens
• OpenAI-compat /v1/chat/completions: usage.prompt_tokens_details.cached_tokens (reads), usage.prompt_tokens_details.cached_creation_tokens (writes), usage.completion_tokens_details.reasoning_tokens (reasoning)

Enabling prompt caching on Anthropic models: Pass "prompt_cache": true in the request body, or embed cache_control blocks in your message content directly — both are honored.

Payment Required (402)

When you first make a request without payment, you'll receive:

HTTP/1.1 402 Payment Required
Content-Type: application/json
Cache-Control: no-store, no-cache, must-revalidate, max-age=0
X-Payment-Required: <base64 payment requirements>
PAYMENT-REQUIRED: <same value>
WWW-Authenticate: X402 requirements="<same value>"

{
  "x402Version": 2,
  "accepts": [{"scheme": "exact", "network": "eip155:8453", "amount": "25685", "asset": "0x8335…", "payTo": "0x…", "maxTimeoutSeconds": 300}],
  "error": "Payment Required",
  "message": "This endpoint requires x402 payment",
  "price": {"amount": "0.025685", "currency": "USD"},
  "paymentInfo": {"network": "base", "asset": "USDC", "x402Version": 2}
}

price.amount is the exact amount the header signs, transaction fee included. x402Version/accepts at the top level mirror the header's challenge in the body, for clients that only parse the body. Decoded, the header is:

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "25685",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x…",
    "maxTimeoutSeconds": 300,
    "extra": {"name": "USD Coin", "version": "2"}
  }],
  "resource": {
    "url": "https://blockrun.ai/api/v1/chat/completions",
    "description": "GPT-5.5 API call (~17 input, 8192 max output tokens)",
    "mimeType": "application/json"
  },
  "extensions": {"bazaar": {…}}
}

How the quote is computed. Estimated input tokens at the model's input rate, plus 10% of max_tokens at the output rate — most calls use a small fraction of their ceiling. Per-token chat carries no platform margin (list price, since 2026-08-07); the quote is floored at $0.001 and then the flat $0.001 per-request transaction fee is added. amount is in micro-USDC (6 decimals). The settled amount is the signed amount — there is no post-hoc refund when the model uses fewer tokens, so set max_tokens to what you need. Prompts at or above a model's long-context threshold re-price the whole request at that model's long-context rates.

Payment rejected (402 with a code)

If you send a PAYMENT-SIGNATURE that does not verify, the response is still 402 but carries a machine-readable code so a client can branch instead of parsing prose:

{
  "error": "Payment verification failed",
  "code": "PAYMENT_UNFUNDED",
  "message": "The payment authorization could not be executed on-chain. The usual cause is an insufficient USDC balance on Base for the quoted amount — …",
  "debug": "<facilitator reason>",
  "payer": "0x…"
}

Verification runs strictly before settlement, so a 402 with any of these codes means nothing was charged. The Solana gateway (sol.blockrun.ai) uses the same envelope with PAYMENT_INVALID, PAYMENT_REPLAY, and PAYMENT_VERIFICATION_UNAVAILABLE (the facilitator itself was unreachable — retry the same signed payment). The Anthropic-compatible /v1/messages and /v1/responses endpoints keep their vendor error envelopes and do not carry these codes.

Other status codes

Errors use the OpenAI envelope — error.message, error.type, error.code, error.param — with message and code mirrored at the top level for older clients. Full details in Error Handling.

Timeouts

• Each upstream call has a 120s timeout (non-streaming, and time-to-first-byte / stall between chunks when streaming).
• A streaming response has an overall deadline of 500s; a stream that hits it is terminated.
• Payment authorizations are valid for 300s (maxTimeoutSeconds); settlement happens after the response (non-streaming) or after the last chunk (streaming), so the whole call has to finish inside that window.

Example

What's next?