Chat Completions
The chat completions endpoint is the core of HPP Router. It is OpenAI-compatible, so request and response shapes match what you already know.
POST https://router.hpp.io/llm/v1/chat/completions
Payment methods
HPP Router supports prepaid quota, keyed x402 wallet, and a keyless Agent path.
| Rail | How to enable | When to use |
|---|---|---|
| Quota (default) | API key, omit X-Payment-Rail | Prepaid credit on the API key |
| Wallet (x402) | API key + X-Payment-Rail: wallet | On-chain settlement per request |
| Agent (keyless) | No API key | Autonomous agents / hpp-x402 — see x402 Agent |
On the wallet or Agent path, paid models typically return 402 until you attach a payment signature. On Agent, free or zero-price models are rejected (keyless_free_model_not_allowed).
See Authentication for key schemes, TypeScript SDK — Wallet for the keyed SDK loop, and x402 Agent (keyless) for no-API-key agents.
Basic request (quota)
- curl
curl -X POST https://router.hpp.io/llm/v1/chat/completions \
-H "apikey: $HPPROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5",
"messages": [
{ "role": "system", "content": "You are a helpful assistant." },
{ "role": "user", "content": "Hello!" }
],
"max_completion_tokens": 100
}'
Basic request (wallet)
Include X-Payment-Rail: wallet and your API key. The first call for a paid model usually returns 402 with a PAYMENT-REQUIRED challenge — then sign and retry with PAYMENT-SIGNATURE (also accepted as X-PAYMENT).
- curl
# 1) First request — expect HTTP 402 for paid models
curl -i -X POST https://router.hpp.io/llm/v1/chat/completions \
-H "apikey: $HPPROUTER_API_KEY" \
-H "X-Payment-Rail: wallet" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5",
"messages": [
{ "role": "system", "content": "You are a helpful assistant." },
{ "role": "user", "content": "Hello!" }
],
"max_completion_tokens": 100
}'
# 2) Sign PAYMENT-REQUIRED / JSON body with @x402/core + @x402/evm (upto / Permit2)
# 3) Retry once with the same body + signature header:
curl -X POST https://router.hpp.io/llm/v1/chat/completions \
-H "apikey: $HPPROUTER_API_KEY" \
-H "X-Payment-Rail: wallet" \
-H "PAYMENT-SIGNATURE: <base64-payload>" \
-H "Content-Type: application/json" \
-d '{ ...same body... }'
For production apps and agents, prefer @hpprouter/sdk with paymentRail: 'wallet' and a paymentSigner so the SDK performs the 402 → sign → retry loop.
Request fields
| Field | Type | Notes |
|---|---|---|
model | string | Required. provider/model (e.g. openai/gpt-5) or hpprouter/auto. |
messages | array | Required. Chat messages with role and content. |
stream | boolean | Stream tokens as Server-Sent Events. See Streaming. |
max_tokens | integer | Maximum tokens to generate. |
max_completion_tokens | integer | Maximum completion tokens (newer OpenAI-style field). |
temperature | number | Sampling temperature. |
top_p | number | Nucleus sampling. |
tools / tool_choice | array / string or object | Tool calls. |
stream_options | object | Forwarded for Anthropic, Moonshot, Ollama, and gpt-image-*. Not sent for OpenAI text models. |
The caller always posts a chat completion to this URL. OpenAI text models (openai/* except gpt-image-*) are translated inside the gateway to OpenAI /v1/responses, then mapped back to a chat completion. On that path the forwarded fields are messages (including image_url parts and tool calls), stream, max_tokens or max_completion_tokens (sent as max_output_tokens), temperature, top_p, tools, and tool_choice. Other fields, including response_format and stream_options, are not sent upstream. gpt-image-* on this endpoint, plus Anthropic, Moonshot, and Ollama, keep the chat body. Image generation as pictures uses Image Generation.
Message roles
role is one of system, user, assistant, or tool. The content is either a string or an array of content parts (used for vision/multimodal).
Response
{
"id": "chatcmpl-...",
"object": "chat.completion",
"created": 1732700000,
"model": "openai/gpt-5",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "Hi there!" },
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 8,
"completion_tokens": 12,
"total_tokens": 20
}
}
The usage block drives billing. When you use hpprouter/auto, check the X-HPP-Router-Resolved-Model header to see which model was billed — see Smart Routing.
Choosing a model
- Pass an explicit
provider/modelfor deterministic routing. - Pass
hpprouter/autoto let the gateway pick a cost-appropriate model per request.
Errors
401— missing or invalid API key; on Agent path, also free-model rejection (keyless_free_model_not_allowed).402— wallet / Agent payment challenge (PAYMENT-REQUIRED). Sign and retry once.429— rate limit or prepaid quota exhaustion (not the normal wallet challenge).
See Errors and x402 Agent for details.