OrdersService

Get Order History

Retrieve terminal order history for an account. Supports optional subaccount, trigger, symbol, side, status, and time-range filters with cursor pagination. While the current state of an order on the page is temporarily unavailable, the call fails with a retryable 503 UNAVAILABLE rather than returning a stale state; retry the same request.

Method

GET

Path

/v1/orders/history

Visibility

Authentication required

Authentication

Session token or API key

MFA Requirement

Not required

GET

/v1/orders/history

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/orders/history?endTime=2025-01-01T00%3A00%3A00Z&includeAttachedRisk=false&includeAttachedRiskState=false&limit=100&side=BUY&startTime=2025-01-01T00%3A00%3A00Z&status=PENDING&subaccountId=45LUmqjT&symbol=BTC-USDT&triggerId=59VD7Lar' \
  --header 'Accept: */*' \
  --header 'X-API-KEY-ID: YOUR_API_KEY_ID' \
  --header 'X-API-TIMESTAMP: YOUR_API_TIMESTAMP' \
  --header 'X-API-SIGNATURE: YOUR_API_SIGNATURE'

Responses

{
  "nextPageToken": "eyJvZmZzZXQiOjIwMH0",
  "orders": [
    {
      "attachedRisk": {
        "oco": false,
        "stopLoss": {
          "policy": {
            "child": {},
            "triggerPrice": "61000.25",
            "triggerPriceSource": "LAST_PRICE"
          },
          "state": {
            "armedAt": "2025-01-01T00:00:00Z",
            "childOrderId": "5USXJZmk",
            "status": "NOT_CONFIGURED",
            "terminalAt": "2025-01-01T00:00:00Z",
            "triggerId": "59VD7Lar"
          }
        },
        "takeProfit": {
          "policy": {
            "child": {},
            "triggerPrice": "61000.25",
            "triggerPriceSource": "LAST_PRICE"
          },
          "state": {
            "armedAt": "2025-01-01T00:00:00Z",
            "childOrderId": "5USXJZmk",
            "status": "NOT_CONFIGURED",
            "terminalAt": "2025-01-01T00:00:00Z",
            "triggerId": "59VD7Lar"
          }
        },
        "trailingStop": {
          "policy": {
            "activationPrice": "61000.25",
            "limitPrice": "61000.25",
            "maxSlippageTicks": 1,
            "trailingDistance": "0.000000001",
            "triggerPriceSource": "LAST_PRICE"
          },
          "state": {
            "armedAt": "2025-01-01T00:00:00Z",
            "childOrderId": "5USXJZmk",
            "status": "NOT_CONFIGURED",
            "terminalAt": "2025-01-01T00:00:00Z",
            "triggerId": "59VD7Lar"
          }
        }
      },
      "avgPx": "18.446744073709551617",
      "batchRequestId": "2",
      "cancelReason": "USER_REQUEST",
      "clientOrderId": "cli-ord-20250101-001",
      "createdAt": "2025-01-01T00:00:00Z",
      "cumQty": "0.001",
      "cumQuote": "184.46744073709551617",
      "expireAt": "2025-01-01T00:00:00Z",
      "feeAsset": "QUOTE",
      "feeTotal": {
        "amount": "18.446744073709551617",
        "isRebate": false,
        "qty": "0.001"
      },
      "inheritedCumQty": "0.001",
      "leavesQty": "0.001",
      "lineage": {
        "generation": 1,
        "id": "2"
      },
      "marketClientRefPrice": "61000.25",
      "marketMaxSlippageBps": 1,
      "marketMaxSlippageTicks": 1,
      "orderId": "5USXJZmk",
      "orderType": "LIMIT",
      "origQty": "0.001",
      "origin": {
        "childSeq": 1,
        "parentOrderId": "5USXJZmk",
        "scope": "DIRECT",
        "triggerId": "59VD7Lar",
        "triggerType": "STOP_LOSS"
      },
      "postOnly": false,
      "price": "61000.25",
      "rejectReason": "BAD_REQUEST",
      "side": "BUY",
      "status": "PENDING",
      "stpMode": "EXPIRE_MAKER",
      "submittedMaxQuoteDebit": "100",
      "symbol": "BTC-USDT",
      "terminalAt": "2025-01-01T00:00:00Z",
      "tif": "GTC",
      "version": 0
    }
  ]
}

endTime string (date-time)

RFC3339 timestamp (nanosecond precision supported)

includeAttachedRisk boolean

Include attached-risk policy fields in each order. Defaults to false when omitted.

includeAttachedRiskState boolean

Include attached-risk state fields in each order. Defaults to false when omitted.

limit integer 1–1000

pageToken string max 512 chars

side enum must be defined value

startTime string (date-time)

RFC3339 timestamp (nanosecond precision supported)

status enum must be defined value

OrderStatus enum name (e.g. FILLED, CANCELED)

subaccountId string > 0

symbol array

Filter by symbol(s): use repeated params (?symbol=BTC-USDT&symbol=ETH-USDT) or comma-separated values.

triggerId string > 0

Filter by trigger public ID (base58).

nextPageToken string

Opaque cursor for the next page. A page may hold fewer orders than requested, or none; continue while this token is non-empty. Empty when no more results exist.

Example eyJvZmZzZXQiOjIwMH0

32 fields

4 fields

oco boolean

True while the parent's legs were placed with oco and both the take-profit and a stop leg (stop-loss or trailing stop) are present. False once either leg is removed. A leg that ended, including one canceled with TRIGGER_CANCEL_REASON_OCO, stays present.

Example false

2 fields

7 fields

5 fields

avgPx string /^[0-9]…9]+)?$/

Average execution price across the lineage through this generation, as a decimal string in quote asset units per base asset unit, for example '0.000002908714285714': the exact executed quote amount divided by cumQty, rounded half to even at 18 decimal places, trailing zeros trimmed. '0' if no fills.

Example 18.446744073709551617

batchRequestId string /^[1-9A…m-z]+$/

Batch-replace identity that admitted this order. Zero for other origins.

Example 2

cancelReason enum

For a CANCELED order, why it ended. Not set for every other status; JSON and REST responses then omit it.

USER_REQUEST IOC_REMAINDER MARKET_REMAINDER STP_EXPIRE_MAKER STP_EXPIRE_TAKER STP_EXPIRE_BOTH REPLACED GTD_EXPIRED QTY_AT_OR_BELOW_FILLED PAIR_DRAIN ATTACHED_RISK_REFUSED CANCEL_ALL_AFTER ACCOUNT_REPAIR TWAP_ROLLOVER STRATEGY_CANCEL SYSTEM MARKET_HALTED ATTACHED_EXIT_FIRED

Example USER_REQUEST

clientOrderId string

Client-provided, account-scoped identifier for correlation, lookup, and cancellation. Empty when none was supplied.

Example cli-ord-20250101-001

createdAt string (date-time)

Creation timestamp in nanoseconds since epoch (UTC).

Example 2025-01-01T00:00:00Z

cumQty string /^[0-9]…9]+)?$/

Cumulative filled quantity across the lineage through this generation, as a decimal string in base asset units, for example '0.0005'.

Example 0.001

cumQuote string /^[0-9]…9]+)?$/

Exact quote amount of the fills across the lineage through this generation, before fees, as a decimal string in quote asset units, for example '3215.5809531728'. For a BUY sized by submittedMaxQuoteDebit, the quote it used is cumQuote plus feeTotal.amount when feeAsset is QUOTE, or minus it when feeTotal.isRebate is true, since a rebate is credited, and cumQuote alone when feeAsset is BASE; submittedMaxQuoteDebit less the quote it used is what it left unspent. '0' if no fills. Each fill settles its quote rounded down to 18 decimal places, so cumQuote is exactly the quote the fills settled when the base asset's quantity scale is at most 9; above that, cumQuote can exceed it by less than 1e-18 per fill.

Example 184.46744073709551617

expireAt string (date-time)

Exact UTC expiry time for GTD orders, within the supported signed Unix-nanosecond range from 1677-09-21T00:12:43.145224193Z through 2262-04-11T23:47:16.854775807Z. Omitted for all other time-in-force policies. The order cannot execute when the current time equals this value.

Example 2025-01-01T00:00:00Z

feeAsset enum

Fee asset selected for fills.

QUOTE BASE

Example QUOTE

3 fields

inheritedCumQty string /^[0-9]…9]+)?$/

Cumulative filled base quantity inherited from predecessors when this replacement was accepted, as a decimal string in base asset units, for example '0.0005'. '0' for the original order and immutable within a generation. cumQty minus this value is the quantity executed by this generation, not the quantity new to a client session.

Example 0.001

leavesQty string /^[0-9]…9]+)?$/

Remaining working quantity as a decimal string in base asset units, for example '0.001'. '0' for terminal orders.

Example 0.001

2 fields

marketClientRefPrice string /^[0-9]…9]+)?$/

Optional client-side reference price used for MARKET slippage protection, as a decimal string in quote asset units per base asset unit, for example '61000.25'.

Example 61000.25

marketMaxSlippageBps integer (int32)

Optional MARKET max slippage in basis points (1 bp = 0.01%).

Example 1

marketMaxSlippageTicks integer (int64)

Non-negative MARKET maximum absolute price delta in Q9 execution-price ticks (1 tick = 1e-9 quote units). Zero means no absolute cap is configured.

Example 1

orderId string /^[1-9A…m-z]+$/

Public order identifier as fixed64.

Example 5USXJZmk

orderType enum

Order type.

LIMIT MARKET

Example LIMIT

origQty string /^[0-9]…9]+)?$/

Current accepted total order quantity, updated by successful modifies, as a decimal string in base asset units, for example '0.001'.

Example 0.001

5 fields

postOnly boolean

True if the order was submitted as post-only (maker-only).

Example false

price string /^[0-9]…9]+)?$/

Limit price as a decimal string in quote asset units per base asset unit, for example '61000.25'. '0' for MARKET orders.

Example 61000.25

rejectReason enum

For a REJECTED order, why it was refused: the same error code the Orders API returns for the same refusal. Not set for every other status; JSON and REST responses then omit it.

BAD_REQUEST INVALID_ARGUMENT INSUFFICIENT_FUNDS UNKNOWN_SYMBOL BAD_PRICE BAD_QTY MIN_NOTIONAL QTY_STEP_SIZE CONFLICT_DUPLICATE_CLIENT_ORDER_ID UNAVAILABLE UNAUTHENTICATED PERMISSION_DENIED NOT_FOUND UPSTREAM_ERROR FEE_ASSET_NOT_ALLOWED PAIR_DISABLED ORDER_UNKNOWN INTERNAL_ERROR SUBACCOUNT_INACTIVE POLICY_MARKET_DENY POLICY_MAX_NOTIONAL POLICY_TRADING_HALTED POLICY_SPOT_TRADE_DENY API_KEY_ROOT_SCOPE_ONLY API_KEY_SUB_SCOPE_ONLY API_KEY_SUBACCOUNT_MISMATCH API_KEY_POLICY_REQUIRED API_KEY_UNKNOWN API_KEY_MARKET_DENY PRICE_TICK_SIZE MIN_QTY POST_ONLY_LIMIT_ONLY BATCH_TOO_LARGE POLICY_MAX_OPEN_ORDERS MODIFICATION_REQUIRES_REPLACE CONFLICT_IDEMPOTENCY_KEY_REUSE MARKET_PRICE_UNAVAILABLE PAIR_NOT_LISTED_YET PAIR_DELISTED PAIR_CANCEL_ONLY PAIR_POST_ONLY PAIR_REDUCE_ONLY RISK_LIMIT MARKET_HALTED ACCOUNT_UNKNOWN POST_ONLY_CROSS REDUCE_ONLY_BLOCKED PRICE_BAND_VIOLATION MARKET_CAP_VIOLATION EMPTY_BOOK FOK_INSUFFICIENT_LIQUIDITY ORDER_ALREADY_TERMINAL TRIGGER_PRICE_INVALID TRIGGER_PRICE_SOURCE_UNSUPPORTED TRAILING_DISTANCE_INVALID TRIGGER_NOT_FOUND TRIGGER_STATUS_INVALID TRIGGER_NOT_MODIFIABLE CONFLICT_DUPLICATE_CLIENT_TRIGGER_ID MAX_SLIPPAGE_INVALID STALE_QUOTE VALIDATION_ERROR OVERLOADED MAX_QUOTE_DEBIT_TOO_SMALL RATE_LIMIT_EXCEEDED SUBACCOUNT_READ_FORBIDDEN POLICY_SPOT_READ_DENY API_KEY_SPOT_READ_DENY CANCEL_REQUEST_EXPIRED MAX_QTY MAX_NOTIONAL QTY_AT_OR_BELOW_FILLED GATEWAY_MISCONFIGURED INVALID_ORDER_ID CHILD_QTY_RAISE_NOT_ALLOWED ATTACHED_RISK_NOT_SUPPORTED SETTLEMENT_BACKLOGGED PRICE_LEVEL_QUANTITY_LIMIT MARKET_QUOTE_STALE MARKET_QUOTE_UNHEALTHY INVALID_TIME_IN_FORCE QUICKSWAP_NOT_PERMITTED DUPLICATE_ORDER_ID MAX_OPEN_ORDERS_TOTAL STP_MODE_NOT_ALLOWED PAIR_BACKLOGGED PRICE_LEVELS_EXHAUSTED CLIENT_ORDER_IDS_EXHAUSTED ORDER_ID_CONFLICT INVALID_SIDE INVALID_ORDER_TYPE INVALID_STP_MODE INVALID_ORDER_FLAGS BATCH_OTHER_ITEM_INVALID REPLACE_ONTO_OWN_ID INVALID_CLIENT_ORDER_ID ORDER_SEQUENCE_EXHAUSTED INVALID_HANDLING_MODE FEE_SCHEDULE_UNAVAILABLE POLICY_UNAVAILABLE CANCEL_ALL_AFTER_TIMEOUT_INVALID CANCEL_SCOPE_TOO_LARGE RATE_LIMIT_POLICY_UNAVAILABLE SYSTEM_RATE_LIMITED ORDER_MODIFY_IN_PROGRESS ORDER_PLACEMENT_PENDING INVALID_MODIFY_BEHAVIOR BATCH_REPLACE_ONLY_REQUIRED BATCH_SINGLE_SYMBOL_REQUIRED REQUEST_RECEIPTS_EXHAUSTED INTENT_ID_INVALID DRY_RUN_INVALID CANCEL_ALL_AFTER_SCOPE_CONFLICT NEW_ACCOUNT_CAPACITY_REACHED TRIGGER_CHILD_PRICE_NOT_MODIFIABLE TRIGGER_GENERATIONS_EXHAUSTED TRIGGER_CONTROL_SHARE_EXHAUSTED TRIGGER_CONTROLS_BUSY TRIGGER_TYPE_NOT_SUPPORTED INVALID_TRIGGER_TYPE TRIGGER_DIRECTION_INVALID TRIGGER_QTY_INVALID TRIGGER_BUY_REQUIRES_LIMIT ACCOUNT_ROUTING_INVALID TRIGGER_LIMIT_EXCEEDED TRIGGER_CONTROL_IN_PROGRESS TRIGGER_PATCH_EMPTY CLIENT_TRIGGER_ID_INVALID TRIGGER_ACTIVATION_PRICE_INVALID SLIPPAGE_TICKS_INVALID SLIPPAGE_BPS_INVALID TRIGGER_CONTROL_OUTCOME_UNKNOWN TRIGGER_CAPACITY_REACHED RESERVATION_CAPACITY_REACHED CLIENT_ORDER_ID_CAPACITY_REACHED ACCOUNT_RESERVATION_LIMIT_REACHED INVALID_TRIGGER_CONTROL TRIGGER_PATCH_NOT_ALLOWED TRIGGER_PATCH_FIELD_UNKNOWN TRIGGER_PATCH_VALUE_UNMASKED TRIGGER_PATCH_PRICE_MODE_INVALID ACCOUNT_ORDERS_SUSPENDED TRAILING_SIDE_NOT_SUPPORTED TRAILING_CHILD_NOT_MARKET TWAP_DURATION_INVALID LIMIT_CHILD_SLIPPAGE_SET SLIPPAGE_BOUNDS_CONFLICT TWAP_INTERVAL_INVALID LADDER_LEVEL_REJECTED LADDER_RANGE_TOO_NARROW LADDER_LEVELS_INVALID ORDER_LIMITS_UNAVAILABLE ORDER_TYPE_NOT_ALLOWED_IN_AUCTION POST_ONLY_NOT_ALLOWED_IN_AUCTION QUICKSWAP_FEE_DETAILS_INCOMPLETE QUICKSWAP_MARKET_NOT_PRICED QUICKSWAP_BROKER_FEE_TERMS_MISMATCH QUICKSWAP_FEE_RECIPIENT_IS_PAYER QUICKSWAP_BROKER_FEE_TERMS_UNAVAILABLE QUICKSWAP_BROKER_ACCOUNT_UNAVAILABLE QUICKSWAP_ACCOUNT_OWNER_UNKNOWN QUICKSWAP_DISABLED QUICKSWAP_ATTACHED_RISK_NOT_ALLOWED QUICKSWAP_ORDER_NOT_MODIFIABLE QUICKSWAP_FEE_TOTAL_TOO_HIGH QUICKSWAP_BROKER_FEE_TERMS_INVALID QUICKSWAP_BROKER_INVALID QUICKSWAP_FEE_SCHEDULE_INVALID QUICKSWAP_MARKET_FEE_INVALID QUICKSWAP_SETUP_INVALID QUICKSWAP_CAPACITY_REACHED ATTACHED_EXIT_WORKING MARKET_TRIGGER_LIMIT_EXCEEDED MARKET_TWAP_LIMIT_EXCEEDED MARKET_LADDER_LIMIT_EXCEEDED CHILD_QTY_EXCEEDS_REMAINING ORDER_CANCEL_OUTCOME_UNKNOWN ORDER_MODIFY_OUTCOME_UNKNOWN ORDER_REPAIRING ACCOUNT_REPAIRING TRIGGER_WOULD_TRIGGER_IMMEDIATELY ORDER_CREATE_OUTCOME_UNKNOWN TRIGGER_CREATE_OUTCOME_UNKNOWN TRIGGER_SYMBOL_MISMATCH MAX_OPEN_ORDERS_PER_PAIR SELF_TRADE_PREVENTED ATTACHED_LEGS_EXCEEDED FEE_ASSET_INVALID FEE_CEILING_INVALID UNSUPPORTED_FIELD_SET TRIGGER_FIRE_LIMIT_REACHED CONDITION_FLAGS_INVALID CONDITION_PARAMETER_SET TWAP_CAPACITY_REACHED CHILD_ORDER_INCONSISTENT

Example BAD_REQUEST

side enum

Order side.

BUY SELL

Example BUY

status enum

Current order lifecycle status.

PENDING PENDING_CANCEL WORKING FILLED CANCELED REJECTED

Example PENDING

stpMode enum

Self-trade prevention mode.

EXPIRE_MAKER EXPIRE_TAKER EXPIRE_BOTH

Example EXPIRE_MAKER

submittedMaxQuoteDebit string /^[0-9]…9]+)?$/

Submitted hard all-in quote debit limit as a decimal string in quote asset units, for example '100'. Present only when that sizing method was submitted.

Example 100

symbol string

Trading symbol numeric identifier.

Example BTC-USDT

terminalAt string (date-time)

Terminal timestamp in nanoseconds since epoch (UTC). Zero for open orders.

Example 2025-01-01T00:00:00Z

tif enum

Time-in-force policy.

GTC IOC FOK GTD

Example GTC

version integer (int32)

Per-order state version: 0 while the order is accepted but not yet on the book (status PENDING), then 1 from its first book state and higher for every later published execution-state change. Higher values identify newer execution state. Fee totals and requested enrichments are not covered by this version and may differ between responses with the same version.

Example 0

Possible errors: 5

Key	HTTP status	Connect code	Error	When
unauthenticated	401	unauthenticated	Unauthenticated	Authentication required.
permission-denied	403	permission_denied	Permission Denied	Permission denied.
invalid-argument	400	invalid_argument	Invalid Argument	Invalid argument.
not-found	404	not_found	Not Found	Not found.
unavailable	503	unavailable	Unavailable	Service unavailable.

GET

/v1/orders/history

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/orders/history?endTime=2025-01-01T00%3A00%3A00Z&includeAttachedRisk=false&includeAttachedRiskState=false&limit=100&side=BUY&startTime=2025-01-01T00%3A00%3A00Z&status=PENDING&subaccountId=45LUmqjT&symbol=BTC-USDT&triggerId=59VD7Lar' \
  --header 'Accept: */*' \
  --header 'X-API-KEY-ID: YOUR_API_KEY_ID' \
  --header 'X-API-TIMESTAMP: YOUR_API_TIMESTAMP' \
  --header 'X-API-SIGNATURE: YOUR_API_SIGNATURE'

Responses

{
  "nextPageToken": "eyJvZmZzZXQiOjIwMH0",
  "orders": [
    {
      "attachedRisk": {
        "oco": false,
        "stopLoss": {
          "policy": {
            "child": {},
            "triggerPrice": "61000.25",
            "triggerPriceSource": "LAST_PRICE"
          },
          "state": {
            "armedAt": "2025-01-01T00:00:00Z",
            "childOrderId": "5USXJZmk",
            "status": "NOT_CONFIGURED",
            "terminalAt": "2025-01-01T00:00:00Z",
            "triggerId": "59VD7Lar"
          }
        },
        "takeProfit": {
          "policy": {
            "child": {},
            "triggerPrice": "61000.25",
            "triggerPriceSource": "LAST_PRICE"
          },
          "state": {
            "armedAt": "2025-01-01T00:00:00Z",
            "childOrderId": "5USXJZmk",
            "status": "NOT_CONFIGURED",
            "terminalAt": "2025-01-01T00:00:00Z",
            "triggerId": "59VD7Lar"
          }
        },
        "trailingStop": {
          "policy": {
            "activationPrice": "61000.25",
            "limitPrice": "61000.25",
            "maxSlippageTicks": 1,
            "trailingDistance": "0.000000001",
            "triggerPriceSource": "LAST_PRICE"
          },
          "state": {
            "armedAt": "2025-01-01T00:00:00Z",
            "childOrderId": "5USXJZmk",
            "status": "NOT_CONFIGURED",
            "terminalAt": "2025-01-01T00:00:00Z",
            "triggerId": "59VD7Lar"
          }
        }
      },
      "avgPx": "18.446744073709551617",
      "batchRequestId": "2",
      "cancelReason": "USER_REQUEST",
      "clientOrderId": "cli-ord-20250101-001",
      "createdAt": "2025-01-01T00:00:00Z",
      "cumQty": "0.001",
      "cumQuote": "184.46744073709551617",
      "expireAt": "2025-01-01T00:00:00Z",
      "feeAsset": "QUOTE",
      "feeTotal": {
        "amount": "18.446744073709551617",
        "isRebate": false,
        "qty": "0.001"
      },
      "inheritedCumQty": "0.001",
      "leavesQty": "0.001",
      "lineage": {
        "generation": 1,
        "id": "2"
      },
      "marketClientRefPrice": "61000.25",
      "marketMaxSlippageBps": 1,
      "marketMaxSlippageTicks": 1,
      "orderId": "5USXJZmk",
      "orderType": "LIMIT",
      "origQty": "0.001",
      "origin": {
        "childSeq": 1,
        "parentOrderId": "5USXJZmk",
        "scope": "DIRECT",
        "triggerId": "59VD7Lar",
        "triggerType": "STOP_LOSS"
      },
      "postOnly": false,
      "price": "61000.25",
      "rejectReason": "BAD_REQUEST",
      "side": "BUY",
      "status": "PENDING",
      "stpMode": "EXPIRE_MAKER",
      "submittedMaxQuoteDebit": "100",
      "symbol": "BTC-USDT",
      "terminalAt": "2025-01-01T00:00:00Z",
      "tif": "GTC",
      "version": 0
    }
  ]
}