Chat completions

POST https://api.spot.market/v1/chat/completions

Fully compatible with the OpenAI request body. Spot adds three optional fields and returns one extra object. Anything not listed here is passed through to the serving venue unchanged.

The live gateway matches the bid against the model book, dispatches to the winning seller, and returns a standard chat-completion body.

Auth: Bearer buyer key.

See also rate limits, errors, and response consumption.

Spot parameters

field	type	notes
`max_price`	float, optional	Maximum blended price. Requests that cannot fill at or below this price return `402`. Defaults to the account ceiling, or the prevailing mid if none is set. On the live gateway this is a decimal string per 1,000 tokens.
`region`	string, optional	One of `us-east`, `us-west`, `eu-west`, `apac`, `global`. Pins execution and data residency.
`venue_pin`	string, optional	Restrict routing to a named venue. Reduces competition and typically raises your fill price — use for compliance, not performance.
`model`	string, required	An instrument string, not a vendor model name. See Instruments.

The `spot` response object

field	notes
`fill_price`	What you paid, $/M blended tokens.
`list_price`	Reference rate for the instrument at fill time.
`vs_list`	Signed fraction; −0.427 means 42.7% under list.
`venue_class`	Anonymized tier of the serving venue.
`fill_id`	Tape identifier. Appears on your statement.

Request

field	type	notes
`model`	string	Instrument / model id
`messages`	`{role, content}[]`	OpenAI chat turns
`max_price`	decimal string	Max price per 1,000 tokens
`max_tokens`	number	Optional generation cap
`temperature`	number	Optional sampling
`stream`	bool	SSE when `true`

Response

OpenAI chat.completion object: id, object, created, model, choices[], optional usage. Each choice has index, message, finish_reason.

Errors

no_match, bid_timeout, rate_limited, seller_unreachable, insufficient_balance, unauthorized. Status codes on Errors.

cURL

curl -s http://127.0.0.1:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-buyer" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"hello"}],"stream":false,"max_price":"0.05","temperature":0.2,"max_tokens":128}'

Rust

use token_gateway_sdk::{BuyerChatMessage, BuyerClient, BuyerKey, ChatCompletionsRequest};
// {"model":"gpt-4","messages":[{"role":"user","content":"hello"}],"stream":false,"max_price":"0.05","temperature":0.2,"max_tokens":128}

let client = BuyerClient::new("http://127.0.0.1:8080", BuyerKey("sk-buyer".into()));
let response = client
    .chat_completions(&ChatCompletionsRequest {
        model: "gpt-4".into(),
        messages: vec![BuyerChatMessage {
            role: "user".into(),
            content: "hello".into(),
        }],
        stream: false,
        max_price: None,
        temperature: None,
        max_tokens: Some(128),
    })
    .await?;
let _ = response.choices[0].message.content.clone();

Python

# {"model":"gpt-4","messages":[{"role":"user","content":"hello"}],"stream":false,"max_price":"0.05","temperature":0.2,"max_tokens":128}
from token_gateway import BuyerAuth, BuyerTokenGateway

gw = BuyerTokenGateway("http://127.0.0.1:8080", buyer=BuyerAuth("sk-buyer"))
print(gw.chat_completions(
    model="gpt-4",
    messages=[{"role": "user", "content": "hello"}],
    max_price="0.05",
    temperature=0.2,
    max_tokens=128,
))

TypeScript

// {"model":"gpt-4","messages":[{"role":"user","content":"hello"}],"stream":false,"max_price":"0.05","temperature":0.2,"max_tokens":128}
import { BuyerClient } from "@ai-token-gateway/sdk";

const buyer = new BuyerClient({ baseUrl: "http://127.0.0.1:8080", apiKey: "sk-buyer" });
const res = await buyer.chatCompletions({
  model: "gpt-4",
  messages: [{ role: "user", content: "hello" }],
  max_price: "0.05",
  temperature: 0.2,
  max_tokens: 128,
});
console.log(res.choices[0].message.content);