Overview

About the API

The Starzip trading API lets a program read markets and order books, place and cancel signed orders, and stream book and order updates. Every endpoint lives under the /v1 path. Paths on these pages omit that prefix, so /book means /v1/book.

Orders are matched off-chain and settled on-chain. You sign each order with your wallet, so the API never holds your keys.

Start Trading

A trading program usually goes through these steps once, then repeats steps 5 to 8.

1. Sign in to your Starzip account and connect the wallet you will trade with. API keys are issued only to a signed-in member, and only for the wallet connected to the account.
2. Create an API key in the Starzip app, or with your account token and a wallet signature. See Create a Key in the App and Create or Derive a Key.
3. Read GET /time and keep your clock within 30 seconds of it. Every signed request carries a timestamp.
4. From your wallet, approve the Exchange contract to spend your collateral token, and to transfer your outcome tokens if you will sell. The addresses are in Network and Contracts.
5. Find a market with GET /markets, then read its tick size, minimum order size, fee rate, and order book. See Market Data.
6. Read your current order nonce with nonces(maker) on the Exchange contract.
7. Sign an order with your wallet and send it with POST /order. See Orders.
8. Follow fills on the user WebSocket channel, and send heartbeats so your orders are canceled if your program stops. See WebSocket and Heartbeats.

Access Levels

Endpoints fall into three access levels.

See Authentication for both signing schemes.

Network and Contracts

During the preview, the API runs on BNB Smart Chain Testnet. Use these values to sign orders, read your nonce, and set approvals.

These values apply to the preview only and will change at general availability. Only the collateral token above counts toward your balance. Another USDT token on the same chain does not.

Responses and Errors

Every REST response, and every error message on the WebSocket, is wrapped in the same envelope. Exactly one of payload and error is null.

// success
{ "payload": 1792565372, "error": null }

// failure
{ "payload": null, "error": { "code": 4004, "message": "market not found for tokenId" } }

The response shapes on these pages describe payload. Branch on error.code or the HTTP status, which always agree. Treat error.message as text for logs and people.

• Error messages are written for people and may change. Do not parse them. The examples above are representative, not a complete list.
• Some errors add an error.data object with the value you need to retry, for example the expected feeRateBps or heartbeatId.
• A batch order request (POST /orders) returns 200 even when items fail. Each failed item reports its reason in errorMsg, with no status of its own. See Place a Batch.
• Retry 503 after a short wait. Do not retry 400, 401, 403, or 409 unchanged; fix the request first.
• WebSocket errors use the same envelope. Fatal ones close the connection with code 1008. See Errors and Closing.
• Unknown fields in a request body are ignored.

Data Formats

• JSON keys are camelCase in every request, response, and WebSocket message.
• Amounts, sizes, prices, and token IDs are decimal strings, for example "1.5" or "0.55". Sizes and prices are in whole tokens with trailing zeros removed.
• Addresses, transaction hashes, order IDs, and signatures are 0x hex strings.
• API key IDs, trade IDs, and heartbeat IDs are 26-character ULID strings, not UUIDs.

A few fields differ from these defaults:

Pagination

List endpoints (/markets, /data/orders, /data/trades, /activity) return pages of up to 100 items, newest first, inside payload. The page size is fixed.

{
  "limit": 100,
  "nextCursor": "MDFKOVo...",
  "count": 100,
  "data": [ ... ]
}

• Request the first page without a cursor, or with nextCursor=MA==.
• Pass the returned nextCursor as a query parameter to get the next page.
• A nextCursor of LTE= means there are no more pages.
• Only send cursors that the API returned. Any other value is rejected with 400.

Request Limits

• Request bodies are limited to 64 KiB. Larger bodies are rejected with 400.
• Each request must complete within 12 seconds.
• Batch endpoints have their own item limits, listed with each endpoint.
• Request-rate limits are not published during the preview. Responses carry no rate-limit headers.
• The WebSocket refuses new connections with 503 when it is at capacity. Retry with backoff.

Compatibility

The API follows the shape of the Polymarket CLOB API: the same POLY_* authentication headers, the same two-level key scheme, and a similar endpoint layout. It is not a drop-in replacement. Clients built for Polymarket need these changes:

• All keys are camelCase, including WebSocket messages, so stock Polymarket SDKs do not work without modification.
• Every response is wrapped in the {"payload":...,"error":...} envelope. Unwrap payload before reading the shapes Polymarket clients expect.
• Orders use the original CTF Exchange order layout, which includes taker, nonce, and feeRateBps. They are signed against the Starzip Exchange domain.
• Only externally owned account (EOA) signatures are accepted. Proxy wallet and Safe signatures are not supported.
• Fees are a per-market taker rate. Each order's feeRateBps must equal the market's current rate from GET /fee-rate.
• Post-only orders, deferred execution, and negative-risk markets are not supported.