[API reference]

Chat completions

Generate a response from a list of messages. Works with every chat and reasoning model on the network, including tool calls and structured outputs.

POST/v1/chat/completions

Create a chat completion

Send the conversation so far as messages. Topo routes the request to the fastest eligible node for the model, verifies the output and settles the cost from your wallet.

curl https://api.topolabs.ai/v1/chat/completions \  -H "Authorization: Bearer $TOPO_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "claude-sonnet-5.5",    "messages": [{ "role": "user", "content": "Explain zk proofs in 3 lines" }],    "pay_with": "usdt"  }'

import osfrom openai import OpenAI client = OpenAI(    base_url="https://api.topolabs.ai/v1",    api_key=os.environ["TOPO_API_KEY"],) response = client.chat.completions.create(    model="claude-sonnet-5.5",    messages=[{"role": "user", "content": "Explain zk proofs in 3 lines"}],) print(response.choices[0].message.content)

import OpenAI from "openai"; const client = new OpenAI({  baseURL: "https://api.topolabs.ai/v1",  apiKey: process.env.TOPO_API_KEY,}); const response = await client.chat.completions.create({  model: "claude-sonnet-5.5",  messages: [{ role: "user", content: "Explain zk proofs in 3 lines" }],}); console.log(response.choices[0].message.content);

Request body

modelstringRequired
ID of the model to use, such as claude-sonnet-5.5. See Models.
messagesobject[]Required
The conversation. Each message has a role (system, user, assistant or tool) and content.
max_tokensinteger
Upper bound on generated tokens, including reasoning tokens.
Default: model maximum
temperaturenumber
Sampling temperature between 0 and 2. Lower is more deterministic.
Default: 1
streamboolean
Stream tokens as server-sent events. See Streaming.
Default: false
toolsobject[]
Functions the model may call, in the OpenAI tool schema.
response_formatobject
Set { "type": "json_schema" } with a schema to force structured output.
pay_withstring
Settlement currency: usdt, eth, sol or topo. Defaults to your wallet's default currency.
topoobject
Routing, verification and spend controls. See The topo object.

Response

response.json

json

{  "id": "chatcmpl_7Hq2kf91",  "object": "chat.completion",  "created": 1792142596,  "model": "claude-sonnet-5.5",  "choices": [    {      "index": 0,      "message": {        "role": "assistant",        "content": "A zk proof shows a statement is true without revealing why. ..."      },      "finish_reason": "stop"    }  ],  "usage": { "prompt_tokens": 18, "completion_tokens": 406, "total_tokens": 424 },  "topo": {    "request_id": "req_7Hq2kf91",    "node": "eu-west-2",    "gpu": "B200",    "ttft_ms": 182,    "attestors": "3/3",    "receipt": {      "amount": "0.0041",      "currency": "USDT",      "chain": "base",      "tx": "0x51c4…9ab2"    }  }}

topo.request_idstring
Stable ID for the request. Use it to fetch the receipt.
topo.nodestring
Region of the node that served the response.
topo.ttft_msinteger
Time to first token measured at the router, in milliseconds.
topo.attestorsstring
Attestors that agreed with the output, such as 3/3. 0/0 when not sampled.
topo.receiptobject
Amount, currency, chain and transaction of the settlement.

Tool calls

Tool calling uses the OpenAI schema unchanged. When the model calls a tool, finish_reason is tool_calls and the arguments arrive as a JSON string.

request.json

json

{  "model": "claude-sonnet-5.5",  "messages": [{ "role": "user", "content": "What is my wallet balance?" }],  "tools": [    {      "type": "function",      "function": {        "name": "get_balance",        "description": "Read the team wallet balance in USDT",        "parameters": { "type": "object", "properties": {} }      }    }  ]}