API conventions
Machine-readable specs: Buyer, Seller, and Market. The legacy /openapi.json and /api/openapi.yaml files remain aliases for the Buyer spec. Versioning and sunset: Versioning and deprecation.
Surfaces
Spot exposes three public APIs. Which one you use depends on what you are doing, not on who you are.
| Surface | Base URL | Authentication | Prices are quoted in |
|---|---|---|---|
| Buyer — inference and capacity tickets | https://aispotmarket.com/buy/api | Authorization: Bearer <buyer_key> | decimal strings per 1,000 tokens |
| Seller — offers, trades, deliveries | https://aispotmarket.com/sell/api | X-Seller-API-Key: <seller_key>, except POST /sell/api/v1/register, which is public | decimal strings per 1,000,000 tokens |
| Market — market data and order book | https://aispotmarket.com/market/api | public for market data; Authorization: Bearer <buyer_key> for contracts and orders | decimal strings per 1,000 tokens |
The Seller API is the one surface quoted per million tokens; it converts at its boundary, so you never do that arithmetic yourself.
Everywhere
| Request and response bodies | JSON, with Content-Type: application/json |
| Error shape | { "code": "seller_unreachable", "error": "..." } — see Errors |
| Versioning | /v1 in the path; see Versioning and deprecation |
| Internal amounts | Settlement is recorded in scale-8 integers. API prices are always decimal strings. |
Error codes
Abbreviated. The canonical table is Errors.
| code | HTTP | meaning |
|---|---|---|
no_fill_at_limit | 402 | nothing crossed at or under the ceiling |
no_match | 404 | no seller matched the bid |
rate_limited | 429 | per-key rate limit exceeded |
insufficient_balance | 402 | account has insufficient pre-funded balance |
seller_unreachable | 502 | winning seller could not be reached |
contract_exhausted | 402 | ticket remaining is below the requested burn |
seller_default | 409 | bound seller failed to deliver |
contract_expired | 410 | ticket TTL or window has ended |
not_found | 404 | resource does not exist |
Endpoints
| Surface | Method | Path | Auth |
|---|---|---|---|
| Buyer | POST | /buy/api/v1/chat/completions | Buyer or ticket credential |
| Buyer | POST | /buy/api/v1/tickets | Buyer |
| Buyer | GET | /buy/api/v1/tickets/{id} | Buyer |
| Seller | POST | /sell/api/v1/register | Public |
| Seller | GET | /sell/api/v1/profile | Seller |
| Seller | GET, POST | /sell/api/v1/offers | Seller |
| Seller | DELETE | /sell/api/v1/offers/{id} | Seller |
| Seller | GET | /sell/api/v1/trades | Seller |
| Seller | GET | /sell/api/v1/deliveries | Seller |
| Seller | GET | /sell/api/v1/reputation | Seller |
| Seller | POST | /sell/api/v1/decisions | Seller |
| Market | GET | /market/api/v1/markets | Public |
| Market | GET | /market/api/v1/orderbook | Public/WebSocket |
| Market | POST | /market/api/v1/contracts | Buyer |
See Buyer account, Market data, Deliveries, Reputation, and Decisions for the detailed response contracts. Health, runtime configuration, administrative, and internal routes are excluded from the public OpenAPI documents.
Advanced Market operation paths
The /market/api façade forwards these versioned operation paths unchanged.
They remain in the aggregate OpenAPI document for backward-compatible contract
checking; callers prepend https://aispotmarket.com/market/api.
| Method | Operation path |
|---|---|
| GET, POST | /v1/contracts |
| GET | /v1/contracts/{id} |
| GET | /v1/orders |
| GET, DELETE | /v1/orders/{id} |
| GET | /v1/account |
| GET | /v1/markets, /v1/markets/{model_id}/candles, /v1/markets/{model_id}/estimate |
| POST | /v1/sellers/register |
| GET, POST | /v1/sellers/{id}/asks |
| DELETE | /v1/sellers/{id}/asks/{ask_id} |
| POST | /v1/sellers/{id}/capacity, /v1/sellers/{id}/decisions |
| GET | /v1/sellers/{id}/trades, /v1/sellers/{id}/deliveries, /v1/sellers/{id}/reputation |
| WebSocket | /v1/orderbook |