Requests
Every operation is aPOST with a JSON body and Content-Type: application/json, to a path of the form /api/v1/{domain}/{query|command}/{Action}. IDs such as accountId, hostId and venueId go in the body, never in the path.
Every operation needs a body, even a list with no filters: send {} for the first page. Request bodies are strict: unknown fields, unknown enum values and wrong types return 400 InvalidRequest. Send only the fields the specification defines.
Account operations need both the X-API-KEY and X-API-SECRET headers. Venue operations, List hosts and List host markets are public. See Authentication.
Responses
Successful responses use one of three shapes:
An
Ack is an empty object today; fields may be added later, so do not test it for emptiness.
Every field a response schema declares is present. Optional values are sent as an explicit null rather than left out, so "averagePrice": null means the host did not report it. Errors use the error envelope.
Paging
Open-ended lists are paged, and the server chooses the page size. Omitcursor for the first request, then pass the returned nextCursor as cursor with the same query variant, account and filters. Stop when nextCursor is null. Follow cursors on every paged list, even one that usually fits in a single page.
For example, the next request to List accounts has this body:
400 InvalidRequest.
Pages are read live, not from a snapshot, so items can change while you page. For host lists, the variant’s capability entry gives its defaultOrdering (Chronological or ReverseChronological), which holds within and across pages. Candles are always newest first: they exclude the candle still forming and need the market’s listBefore to page beyond the first page (see Read market data).
Capabilities and variants
Read venues, hosts and their market summaries before choosing operations. Each entry is anOperationSupport: Supported (on every market), PerMarket (check the market’s summary) or NotSupported. Calling an unsupported operation or variant returns 422 NotSupported. See Capabilities.
Unions use a type discriminator. Operations with several access patterns take them as variants in a query or command field, for example GetOrder with ById, ByClientOrderId or ByClientOrderIdForInstrument. SubmitOrder takes an order whose type is Limit, Market, TriggerLimit or TriggerMarket. Each variant has its own required fields and its own capability entry; all variants of one operation return the same shape.
Batches
Batch operations take a list and return one result per item, but they report missing items differently:Sizes and instruments
Instruments are always sent as structured objects, never as symbols:symbol such as BTC-USDT-PERP for display and joining, but it is not accepted as input.
Every size (in orders, fills, positions, order books, trades and size rules) is in the market’s native contracts, not necessarily base-asset units: one contract is contractSize units of contractSizeAsset, from the market’s contractDetails. A notional is an amount of the quote asset. See Instruments.
Decimals and timestamps
Exact decimal values, including prices, sizes, balances, rates and leverage, are JSON strings such as"0.01". Parse them into a decimal type and keep their precision; never round-trip them through binary floating point.
Errors and retries
Every error uses one envelope with a stablecode. Commands document whether they are safe to repeat, and an error alone never proves a command had no effect. See Errors for the code catalogue, the retry rule for each operation and how to reconcile.