Chat Completions

POST /v1/chat/completions

Send a chat completion request. The endpoint is OpenAI-compatible and supports both JSON and SSE streaming responses. Payment is required via the payment-signature header.

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`payment-signature`	Conditional	Required to get a response. Omit to get a `402` with cost info.
`X-Request-Id`	No	Request correlation ID — logged in usage records
`X-Session-Id`	No	Session correlation ID
`X-Solvela-Debug`	No	Set to `true` to receive routing diagnostics (`X-Solvela-*`) in the response headers. Legacy `X-RCR-Debug` is also accepted.

Request body

Parameter	Type	Required	Description
`model`	string	Yes	Model ID, alias, or routing profile. See Models.
`messages`	array	Yes	Array of message objects. Max 256 messages.
`messages[].role`	string	Yes	`"system"`, `"user"`, `"assistant"`, `"tool"`, or `"developer"`
`messages[].content`	string	Yes	Message text
`messages[].name`	string	No	Participant name
`messages[].tool_calls`	array	No	Tool calls made by the assistant
`messages[].tool_call_id`	string	No	ID of the tool call this message responds to
`stream`	boolean	No	Enable SSE streaming. Default: `false`
`max_tokens`	integer	No	Maximum output tokens. Clamped to the model's own max-output limit when it defines one.
`temperature`	float	No	Sampling temperature 0–2
`top_p`	float	No	Nucleus sampling probability
`tools`	array	No	Tool definitions (function calling)
`tool_choice`	string/object	No	Tool selection strategy (`"auto"`, `"none"`, or a specific function)

Model values

Pass any of the following as model:

Routing profile: auto, eco, premium, free — smart router picks the model
Alias: gpt5, sonnet, opus, gemini, flash, grok, deepseek
Full model ID: openai/gpt-4o, anthropic/claude-opus-4-8, etc.

See Smart Router for how profiles work.

When no payment-signature header is present, the gateway returns 402 with the PaymentRequired object at the top level of the response body (x402-spec compliant — not wrapped in the OpenAI { "error": { ... } } envelope). Parse the body as JSON directly:

{
  "x402_version": 2,
  "resource": { "url": "/v1/chat/completions", "method": "POST" },
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "amount": "2625",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "pay_to": "<gateway-recipient-wallet>",
      "max_timeout_seconds": 300
    },
    {
      "scheme": "escrow",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "amount": "2625",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "pay_to": "<gateway-recipient-wallet>",
      "max_timeout_seconds": 300,
      "escrow_program_id": "9neDHouXgEgHZDde5SpmqqEZ9Uv35hFcjtFEPxomtHLU"
    }
  ],
  "cost_breakdown": {
    "provider_cost": "0.002500",
    "platform_fee": "0.000125",
    "total": "0.002625",
    "currency": "USDC",
    "fee_percent": 5
  },
  "error": "Payment required"
}

The trailing error field is a plain string banner. The second accepts entry (escrow_program_id present) is only included when the gateway has an escrow program configured.

402 Payment Required — invalid payment header

A payment-signature header that fails to decode, replays a previous transaction, or fails on-chain verification returns 402 with the OpenAI error envelope (distinct from the no-payment shape above):

{
  "error": {
    "type": "invalid_payment",
    "message": "transaction has already been used; each payment signature may only be submitted once"
  }
}

error.type for this 402 is always "invalid_payment"; error.message is a plain-text reason string, never a JSON-encoded payload.

200 OK — successful completion

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1712345678,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Solana is a high-throughput blockchain."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  }
}

Response headers on paid requests include:

Header	Description
`x-solvela-session`	Session token for request correlation
`x-solvela-fallback`	Set if the request was served by a fallback provider

Streaming response (SSE)

When stream: true, the gateway returns text/event-stream. Each chunk is an OpenAI-compatible SSE event:

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1712345678,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant","content":"Solana"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1712345678,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":" is"},"finish_reason":null}]}

data: [DONE]

Code examples

Warning

Do not submit the same signed transaction more than once. The gateway tracks transaction signatures and rejects replays with 402 Invalid Payment.