On this page

Capacity tickets

POST https://api.spot.market/v1/contracts

Buy reserved seller lots. A fill is title transfer: you are debited immediately, leftover tokens perish at expiry (take-or-pay). The response includes a credential you can drop into any OpenAI-compatible client.

Auth: Bearer buyer key. Spend with Authorization: Bearer sk-contract-… on chat completions.

GTC does not hold the HTTP request. Poll GET /v1/orders/{order_id} (or use SDK wait) until status is filled.

Body

field	type	notes
`instrument`	string	Model / instrument id
`quantity`	integer	Tokens to buy
`max_price`	decimal string	Ceiling per 1,000 tokens. Required except `order=market`
`order`	`take` / `set` / `limit` / `market`	take and market are IOC
`time_in_force`	`ioc` / `fok` / `gtc`	GTC rests the unfilled remainder
`ttl_seconds`	integer	Spot ticket lifetime after fill (default 86400)
`split`	object	Optional `region`, `privacy`, `venue_pin`
`delivery`	`1d` / `1m` / `{start,end}`	Buy ahead. Omitted = spot

Response

order_id, status (open / partial / filled / rejected), filled, optional contract with id, credential, remaining, expires_at, lots[].

Errors

no_fill_at_limit (402) on IOC/FOK with no cross. Status codes on Errors.

cURL

curl -s http://127.0.0.1:8080/v1/contracts \
  -H "Authorization: Bearer sk-buyer" \
  -H "Content-Type: application/json" \
  -d '{"instrument":"gpt-4","quantity":2000,"max_price":"0.20","order":"take","time_in_force":"ioc"}'

Python

from token_gateway import BuyerAuth, BuyerTokenGateway

gw = BuyerTokenGateway("http://127.0.0.1:8080", buyer=BuyerAuth("sk-buyer"))
order = gw.buy(instrument="gpt-4", tokens=2000, max_price="0.20", order="take")
print(order.contract.credential if order.contract else order.order_id)

TypeScript

import { BuyerClient } from "@ai-token-gateway/sdk";

const buyer = new BuyerClient({ baseUrl: "http://127.0.0.1:8080", apiKey: "sk-buyer" });
const order = await buyer.buy({
  instrument: "gpt-4",
  tokens: 2000,
  max_price: "0.20",
  order: "take",
});
console.log(order.contract?.credential ?? order.order_id);

Rust

use token_gateway_sdk::{BuyerClient, BuyerKey, CreateContractRequest};

let client = BuyerClient::new("http://127.0.0.1:8080", BuyerKey("sk-buyer".into()));
let order = client
    .buy(&CreateContractRequest {
        instrument: "gpt-4".into(),
        quantity: 2000,
        max_price: None,
        split: None,
        order: Default::default(),
        time_in_force: Default::default(),
        ttl_seconds: None,
        delivery: None,
    })
    .await?;
let _ = order.order_id;