Capacity tickets

POST https://aispotmarket.com/buy/api/v1/tickets

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.

Choose IOC (the SDK default), FOK, or GTC. IOC and FOK fill once and mint a ticket over a fixed set of seller lots. GTC rests the unfilled remainder on the book and keeps adding lots to the same ticket as later asks cross it — the credential you were given never changes, and its remaining grows.

Body

Response

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

The raw credential is a bearer secret. Copy it when the ticket is minted. Historical ticket lists return a non-secret fingerprint instead of recovering the raw key.

Search orders and tickets

GET /buy/api/v1/orders and GET /buy/api/v1/tickets return all objects owned by the authenticated buyer, newest first. Both support cursor pagination plus q, model_id, region, status, from, and to filters.

curl -s 'http://127.0.0.1:8080/v1/orders?status=open&region=us-east&limit=50' \
  -H "Authorization: Bearer sk-buyer"

curl -s 'http://127.0.0.1:8080/v1/tickets?q=gpt-4' \
  -H "Authorization: Bearer sk-buyer"

Cancel the unfilled remainder of an open or partial order with DELETE /v1/orders/{order_id}.

Read one order with GET /v1/orders/{id} and one ticket with GET /v1/contracts/{id}. Both endpoints enforce buyer ownership and return 403 when the authenticated buyer does not own the requested object.

A GTC order that crosses nothing returns 200 with status: open and no contract: there are no lots yet, so there is no ticket to sign. Poll GET /buy/api/v1/orders/{order_id} for the credential once it fills, and DELETE the same path to cancel the unfilled remainder.

Errors

no_fill_at_limit (402) on IOC/FOK with no cross. GTC never returns it — it rests instead. Status codes on Errors.

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

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",
    time_in_force="ioc",
)
print(order.contract.credential if order.contract else order.order_id)

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",
  time_in_force: "ioc",
});
console.log(order.contract?.credential ?? order.order_id);

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

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: Some(token_gateway_sdk::Decimal::new(20, 2)),
        split: None,
        order: ContractOrderType::Take,
        time_in_force: TimeInForce::Ioc,
        ttl_seconds: None,
        delivery: None,
    })
    .await?;
let _ = order.order_id;