Quickstart · Bot

Drive the venue from your own process

Bots are first-class. The REST surface is stateless, the matcher is fast (~79ms p50 place-to-ack), and every order accepts an attribution string you can use as an identity. Auth and idempotency keys are Phase B.

1. Get credentials

Heads up

API keys are PLANNED. Today there is no auth — anyone can post orders with any attribution. The shape of the eventual flow is documented at /clob/docs/api/authentication; until then, use a stable attribution string and treat it as your handle.

2. Place your first order

POST/book/v1/orders

REAL

Submits a single limit or market order. Returns the matcher-assigned order_id synchronously.

Request body

Field	Type	Required	Description
market	string	yes	e.g. "BTC-PERP", "ETH-PERP", "SOL-PERP".
side	string	yes	"buy" \| "sell".
qty	string	yes	Decimal string. Wire format is always a string to avoid float drift.
price	string	yes	Decimal string. Required for limit orders. For market orders, omit or send "0".
tif	string	no	"gtc" (default) \| "ioc" \| "fok".
attribution	string	yes	Stable identity string. Required to cancel-by-attribution later.
session	string	no	Warp-session id when replaying historical state.

Response

Field	Type	Required	Description
order_id	string	no	UUID assigned by the matcher.
t_placed	integer	no	Unix seconds at which the matcher accepted the order.
speed_x	number	no	1.0 in live mode; equals the session speed during a warp.

Code

curl -s -X POST https://api.taifoon.dev/book/v1/orders \
  -H 'Content-Type: application/json' \
  -d '{
    "market":"BTC-PERP","side":"buy",
    "qty":"0.01","price":"75000",
    "tif":"gtc","attribution":"bot-demo"
  }'

Errors

400BadRequestMissing field, malformed decimal, unknown market.
429RateLimitPhase B — placeholder. Today no rate-limit is enforced.

3. Stream fills via WebSocket

Heads up

WebSocket streams are PLANNED for Phase B. Today, poll /book/v1/fills at 500ms–2s. The WS contract is sketched at /clob/docs/api/websocket.

4. Idempotency

On Phase B the order-place endpoint will accept an idempotency_key field (and anIdempotency-Key HTTP header). Resubmitting a key within a 5-minute window will return the original response without placing a duplicate order. Today there is no de-duplication — retry with care.

5. Rate limits + retry

No rate limit is enforced today. The Phase B contract: 10 orders/sec/attribution,100 reads/sec/IP. On 429, back off exponentially starting at 200ms with jitter, capped at 5s. Cancellation is always free (never rate-limited).