Clients
Spot has three persona APIs and four official clients. Inference and tickets use https://aispotmarket.com/buy/api; simple seller capacity uses https://aispotmarket.com/sell/api; advanced market operations use https://aispotmarket.com/market/api.
Available today
| You have… | Use |
|---|---|
| An existing OpenAI Chat Completions client | Change base_url / baseURL to https://aispotmarket.com/buy/api/v1, keep your SDK, add max_price. Nothing to install. |
| A script, health check, or one-shot call | The aispot CLI — curl -fsSL https://aispotmarket.com/install.sh | sh |
| Any other language, or you want the wire contract | POST https://aispotmarket.com/buy/api/v1/chat/completions, against the Buyer OpenAPI |
For most buyers the first row is the whole integration. Spot implements the OpenAI Chat Completions API, so an existing client keeps working — you change where it points and add a price ceiling.
Do not install an unrelated package named spot. Homebrew, npm, and PyPI
already ship other projects under that name; none of them are this.
Official SDKs — not yet released
Typed SDKs for TypeScript, Python, and Rust exist and are documented here, but they are not published to npm, PyPI, or crates.io, so there is currently no way to install them from outside. Until they ship, use an OpenAI-compatible client, the CLI, or plain HTTP.
| Language | Package name (reserved) | Entry points | Reference |
|---|---|---|---|
| TypeScript | @ai-token-gateway/sdk | BuyerClient, SellerClient | TypeScript SDK |
| Python | token-gateway | BuyerTokenGateway, SellerTokenGateway | Python SDK |
| Rust | token-gateway-sdk | BuyerClient, SellerClient | Rust SDK |
The SDK pages describe the API those packages present, so you can see what an
integration will look like and tell whether it fits. The aispot CLI is a thin
front end over the same Rust client and is available now.
Shared rules
Every client, including a raw curl, follows the same contract.
| Topic | Rule |
|---|---|
| Buyer auth | Authorization: Bearer <key> — SPOT_API_KEY or BUYER_API_KEY |
| Seller auth | X-Seller-API-Key — SPOT_SELLER_KEY (register is public) |
| Host | Buyer default https://aispotmarket.com/buy/api. Seller default https://aispotmarket.com/sell/api. Override with the client-specific environment variable or --base-url. |
| Discovery | from_config / fromConfig / --from-config calls GET {url}/v1/config and uses gatewayApiUrl. There is no hardcoded fallback. Local: GATEWAY_CONFIG_URL or GATEWAY_URL. |
| Prices | Decimal strings, per 1,000 tokens ("0.05"). The SDK does not parse or rescale max_price. |
| Version | Path /v1. See versioning. |
| Limits | Honor RateLimit, RateLimit-Policy, and Retry-After. See rate limits. |
| Not on v1 | Embeddings, images, audio, fine-tuning, webhooks, MCP |
Buyer surface
Same job on every official client. Streaming and capacity tickets are extras — chat completions is the path that fills.
| Job | TypeScript | Python | Rust | CLI |
|---|---|---|---|---|
| Construct | new BuyerClient({ baseUrl, apiKey }) | BuyerTokenGateway(url, buyer=BuyerAuth(key)) | BuyerClient::new(url, BuyerKey(key)) | --base-url / SPOT_API_URL |
| Discover | BuyerClient.fromConfig(configUrl, key) | BuyerTokenGateway.from_config(url, buyer=…) | BuyerClient::from_config(url, key).await | --from-config |
| Chat | chatCompletions({ model, messages, max_price }) | chat_completions(model=, messages=, max_price=) | chat_completions(&ChatCompletionsRequest { … }) | aispot chat --message … --max-price … |
| Stream | chatCompletionsStream | chat_completions_stream | chat_completions_stream | — |
| Tickets | buy / wait / spend / replenish | helpers in token_gateway.tickets | buy / wait / spend / replenish | — |
Seller surface
| Job | TypeScript | Python | Rust | CLI |
|---|---|---|---|---|
| Construct | new SellerClient({ baseUrl }) | SellerTokenGateway(url) | SellerClient::new(url, None) | --base-url |
| Register | register({ name, endpoint_url, supported_models, regions, api_key }) | register_seller(name=, endpoint_url=, regions=, …) | register(&RegisterSellerRequest { … }) | aispot seller register |
| Set key | setApiKey(key) | pass SellerAuth / key on later calls | set_key(SellerKey(key)) | --seller-key / SPOT_SELLER_KEY |
| List capacity | createOffer({ model, price_per_million_tokens, quantity_tokens }) | create_offer(model=, price_per_million_tokens=, quantity_tokens=) | create_offer(&CreateSellerOfferRequest { … }) | aispot seller ask |
| Stop selling | cancelOffer(offerId) | cancel_offer(offer_id) | cancel_offer(offer_id) | aispot seller cancel |
| Capacity | reportCapacity({ … }) | report_capacity(…) | report_capacity(&…) | aispot seller capacity |
| Trades | listTrades() | list_trades() | list_trades() | aispot seller trades |
Language pages have install commands and a first-fill example: TypeScript, Python, Rust. CLI mapping: aispot CLI. Wire shapes: chat completions, submit ask.
Prompt an agent
Paste the block on What Spot is for → Prompt your agent. It tells the agent to read this page, pick one row from the table above, and implement against the named package.
Also here
- Telemetry and privacy — off by default; what is sent if you enable it