Market data and order-book stream

Market-data routes are public and require no API key. Prices are decimal strings per 1,000 tokens unless a field says otherwise.

Market catalog

GET /v1/markets

Returns model families, instruments, configured regions, and live regional quotes. Each quote includes best_bid, best_ask, last_price, and volume_24h. A missing side is null, not zero.

Candles

GET /v1/markets/{model_id}/candles

Returns ascending OHLCV buckets derived from executed trades.

query	required	meaning
`interval`	no	`1m`, `5m`, `1h`, or `1d`
`region`	no	Restrict executions to one seller region
`from`	no	Inclusive RFC 3339 timestamp
`to`	no	Exclusive RFC 3339 timestamp
`limit`	no	Maximum 2,000 candles

The response contains model_id, optional region, interval, and candles[]. Each candle has time, open, high, low, close, and token volume.

Fill estimate

GET /v1/markets/{model_id}/estimate

Returns non-guaranteed guidance from current compatible depth and recent executions.

query	required	meaning
`quantity`	yes	Requested tokens
`region`	no	Eligibility filter over the global book
`limit_price`	no	Proposed ceiling per 1,000 tokens; omitted means market
`horizon_hours`	no	Horizon for the suggested limit price

The response separates immediately fillable quantity from an estimated wait for any remainder and includes its sample size, lookback window, confidence, and disclaimer. Estimates never reserve capacity.

Order-book WebSocket

Connect to wss://aispotmarket.com/market/api/v1/orderbook?model_id=MODEL_ID. model_id is required. Optional region filters the view of the one global book; region=any and an omitted region both sweep all regions.

The server sends a complete orderbook_snapshot immediately after the upgrade. Later book changes are also sent as complete snapshots, so clients can replace local depth without applying a sequence of deltas. Matching trades are interleaved as trade messages. If an internal subscriber lags, the server recovers by sending another complete snapshot.

`orderbook_snapshot`

{
  "type": "orderbook_snapshot",
  "model_id": "gpt-4",
  "bids": [{"price": "9.5", "quantity": "1000"}],
  "asks": [{"price": "10", "quantity": "500"}]
}

Bids are highest price first; asks are lowest price first. price and quantity are strings to avoid floating-point drift.

`trade`

{
  "type": "trade",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model_id": "gpt-4",
  "price": "10",
  "quantity": "25",
  "taker_side": "bid",
  "region": "us-east",
  "timestamp": 1710000000000
}

timestamp is Unix epoch milliseconds. The server answers WebSocket pings with pongs and ignores application text or binary frames. A disconnected client should reconnect with exponential backoff; the first snapshot after reconnection replaces all prior local state. Browser connections from an unapproved Origin receive 403, and a request without model_id receives 400 before upgrade.