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-Debug-Payment`	No	Set to `true` to receive cost and routing info in response headers

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 model limit (max 128,000).
`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-20250514, etc.

See Smart Router for how profiles work.

Responses

402 Payment Required — no payment header

When no payment-signature header is present, the gateway returns 402. Parse error.message as JSON to get cost and payment instructions.

{
  "error": {
    "message": "{\"x402_version\":2,\"resource\":{\"url\":\"/v1/chat/completions\",\"method\":\"POST\"},\"accepts\":[{\"scheme\":\"exact\",\"network\":\"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp\",\"amount\":\"2625\",\"asset\":\"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\",\"pay_to\":\"<gateway-wallet>\",\"max_timeout_seconds\":300},{\"scheme\":\"escrow\",\"network\":\"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp\",\"amount\":\"2625\",\"asset\":\"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\",\"pay_to\":\"<gateway-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 decoded PaymentRequired object has this structure:

{
  "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
    }
  ],
  "cost_breakdown": {
    "provider_cost": "0.002500",
    "platform_fee": "0.000125",
    "total": "0.002625",
    "currency": "USDC",
    "fee_percent": 5
  },
  "error": "Payment required"
}

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.