Skip to main content
GET
List orders

Authorizations

​
X-API-Key
string
header
required

Send the API key in X-API-Key.

Request signing. A key with signing enabled (enabled for the key in its workspace's credential settings, which return the signing secret once; see Sign requests) must also sign every request:

  • X-Timestamp: the current Unix time in seconds, within 300 seconds of the server clock (at most 10 seconds ahead of it on a request that sends X-Nonce).
  • X-Nonce: a fresh random value for each request, 16 to 128 characters of A-Z, a-z, 0-9, - and _ (a UUID fits). Required on a write (POST, PUT, PATCH, DELETE); optional on a read (GET, HEAD).
  • X-Signature: lower-case hex HMAC-SHA256 of the canonical string, keyed with the signing secret's 32 bytes (the secret is 64 hex characters; decode it first).

The canonical string is joined by \n, with no trailing newline: the X-Timestamp value, the X-Nonce value, the upper-case method, the path with its query exactly as sent (/api/v1/orders?limit=1), and the lower-case hex SHA-256 of the exact body bytes (the SHA-256 of an empty body when there is none). A request without X-Nonce (a read) omits the nonce line and signs four lines.

A nonce is accepted once per key: the same nonce again inside the window is refused, whatever the body, so two identical writes in one second each carry their own nonce and both succeed, and a retry signs again with a new nonce. Every API server shares one nonce record, so a nonce accepted by one server is refused by all of them. Rate admission runs first: a rate-limited write (429) does not consume its nonce, and a replay sent while the key is rate limited is answered 429; otherwise a replay spends a rate token and is refused. A read without a nonce changes nothing, so an identical signed read inside the window is admitted again. A write whose window has already passed on the nonce record's clock when its nonce is recorded is refused as TIMESTAMP_OUT_OF_RANGE. If the nonce record cannot be read or written the request is refused with 503 API_KEY_UNAVAILABLE; the nonce may have been consumed, so sign again with a new X-Timestamp and X-Nonce before retrying.

A signing refusal is a 401 AUTH_REQUIRED whose details.reason names the cause: SIGNATURE_REQUIRED (a header is missing), SIGNATURE_INVALID (a malformed header or a wrong signature), TIMESTAMP_OUT_OF_RANGE, NONCE_REQUIRED (a write without X-Nonce), NONCE_INVALID (a malformed or repeated X-Nonce header), SIGNATURE_REPLAYED (the nonce was already accepted). SIGNATURE_PREDATES_RESTART and 429 REPLAY_WINDOW_FULL are reserved and not answered today.

Scopes

​
orders_read
api_key
​
orders_read
bearer_auth

Headers

​
X-Workspace-Id
string<uuid>

The workspace the request acts in. An API key bound to a workspace implies it: omit the header, or send that same id (another id answers 403 WORKSPACE_SCOPE_MISMATCH). A member session must send it (400 MISSING_WORKSPACE without it).

Query Parameters

​
limit
integer<int32>

Number of matching items requested, 1–20; default 20.

Required range: x >= 0
​
cursor
string

Opaque nextCursor from this caller, workspace and the identical filter set.

​
status
enum<string>

Public lifecycle status, shared by Basic and Advanced orders. Open public lifecycle vocabulary shared by both order kinds. States may be skipped; act on terminal, not on a particular sequence.

New values may be added; treat unknown values as other.

Available options:
pending,
working,
filled,
settled,
unfilled,
cancelled,
failed,
refunded,
reviewRequired,
outcomeUnknown,
refused
​
kind
enum<string>

Which native owner holds an order.

Available options:
basicTrade,
advancedTrade
​
from
string<date-time>

Created at or after this RFC 3339 instant, inclusive.

​
to
string<date-time>

Created at or before this RFC 3339 instant, inclusive.

​
sellAsset
string
​
buyAsset
string
​
clientOrderId
string

Exact caller reference, including terminal orders with a reused reference.

Response

A page of the workspace's orders, newest first. A status filter keeps reading until the page has limit items or the orders end, within a bounded scan: a page shorter than limit with a nextCursor means that scan reached its limit (scanLimitReached), never that the orders ended.

​
items
object[]
required

The Basic venue trade created by POST /orders and read from its saved venue-trade operation. Common order identity and progress fields remain stable; undocumented response fields must be ignored.

New values may be added; treat unknown values as other.

​
scanLimitReached
boolean
required

True when a status-filtered page stopped at its scan limit before filling limit: more orders remain to examine, so follow nextCursor. False on every other page.

​
nextCursor
string | null