Buyer flow

Submit a max_price bid. The gateway matches an ask, dispatches to the winning seller, and returns a standard OpenAI chat.completion object. Consume it the same way you consume OpenAI today.

Discovery for the gateway base URL:

Pass an explicit base_url / baseUrl to the client constructor, or
Call from_config / fromConfig with a config origin (GET {config_url}/config → gatewayApiUrl), or
Error — there is no hardcoded fallback URL.

Set GATEWAY_URL (explicit constructor) or GATEWAY_CONFIG_URL (discovery) in the environment.

See POST /v1/chat/completions for the wire contract.

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. Passed through verbatim — the SDK does not parse or rescale it.
`max_tokens`	number	Optional generation cap
`temperature`	number	Optional sampling
`stream`	bool	SSE when `true`

Response

OpenAI chat.completion object.

field	type	notes
`id`	string	Completion identifier
`object`	string	Typically `"chat.completion"`
`created`	integer	Unix timestamp (seconds)
`model`	string	Model that produced the completion
`choices[]`	array	Generated choices
`usage`	object, optional	Token accounting when the seller reports it

Each choice:

field	type	notes
`index`	integer	Zero-based index among choices
`message`	`{role, content}`	Assistant message for this choice
`finish_reason`	string, optional	Why generation stopped (for example `"stop"`)

Usage, when present: prompt_tokens, completion_tokens, total_tokens.

Errors

code	HTTP	meaning
`no_match` / `bid_timeout`	408	No ask crossed before the bid wait expired
`rate_limited`	429	Buyer key exceeded burst
`insufficient_balance`	402	Ledger rejected the trade
`seller_unreachable`	502	Winning seller timed out or 5xx

Retry patterns live in Error handling.

OpenAI compatibility

The response is the standard OpenAI chat.completion object. The only client change is base URL + max_price.

Python

from openai import OpenAI

openai = OpenAI()
completion = openai.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "hello"}],
)
print(completion.choices[0].message.content)

spot = OpenAI(base_url=f"{GATEWAY_URL}/v1")
completion = spot.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "hello"}],
    extra_body={"max_price": "0.05"},
)
print(completion.choices[0].message.content)

JavaScript

import OpenAI from "openai";

const openai = new OpenAI();
const completion = await openai.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "hello" }],
});
console.log(completion.choices[0].message.content);

const spot = new OpenAI({ baseURL: `${process.env.GATEWAY_URL}/v1` });
const bid = await spot.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "hello" }],
  max_price: "0.05",
});
console.log(bid.choices[0].message.content);

Full-loop example

Submit a bid, receive an OpenAI-shaped completion, consume .choices[0].message.content.

import os

from token_gateway import BuyerAuth, BuyerTokenGateway


def main() -> None:
    gw = BuyerTokenGateway.from_config(
        os.environ["GATEWAY_CONFIG_URL"],
        buyer=BuyerAuth(os.environ["BUYER_API_KEY"]),
    )
    completion = gw.chat_completions(
        model="gpt-4",
        messages=[{"role": "user", "content": "hello from python"}],
        max_price="0.05",
        max_tokens=64,
    )
    print(completion.id)
    print(completion.model)
    print(completion.choices[0].message.role)
    print(completion.choices[0].finish_reason)
    use_completion(completion.choices[0].message.content)


def use_completion(text: str) -> None:
    print(text)

import OpenAI from "openai";

const gatewayUrl = process.env.GATEWAY_URL;
if (!gatewayUrl) {
  throw new Error("GATEWAY_URL must be set");
}
const apiKey = process.env.BUYER_API_KEY;
if (!apiKey) {
  throw new Error("BUYER_API_KEY must be set");
}

const openai = new OpenAI({
  baseURL: `${gatewayUrl}/v1`,
  apiKey,
});

const completion = await openai.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "hello from javascript" }],
  max_price: "0.05",
  max_tokens: 64,
});

const { id, model } = completion;
const { content } = completion.choices[0].message;
const { finish_reason } = completion.choices[0];
console.log(id);
console.log(model);
console.log(finish_reason);
useCompletion(content);

function useCompletion(text) {
  console.log(text);
}

Run it locally

Install

pip install token-gateway
npm install @ai-token-gateway/sdk

Environment

variable	used by
`GATEWAY_CONFIG_URL`	Python discovery (`GET /config`)
`BUYER_API_KEY`	Buyer bearer key for both languages
`GATEWAY_URL`	JavaScript OpenAI client `baseURL`

Run

GATEWAY_CONFIG_URL=http://127.0.0.1:8080 BUYER_API_KEY=sk-buyer python buyer_quickstart.py
GATEWAY_URL=http://127.0.0.1:8080 BUYER_API_KEY=sk-buyer node buyer_quickstart.js

Expected output is the completion text from choices[0].message.content.

Next steps

Wire contract: POST /v1/chat/completions.