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.

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=1735689600000000000&includeAttachedRisk=false&includeAttachedRiskState=false&limit=100&pageToken=eyJvZmZzZXQiOjEwMH0&side=BUY&startTime=1735689600000000000&status=PENDING&subaccountId=6789012345678&symbol=BTC-USDT&triggerId=9155001234567' \
  --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": "0.005"
          },
          "state": {
            "armedAt": "2025-01-01T00:00:00Z",
            "childOrderId": "5USXJZmk",
            "status": "NOT_CONFIGURED",
            "terminalAt": "2025-01-01T00:00:00Z",
            "triggerId": "59VD7Lar"
          }
        },
        "takeProfit": {
          "policy": {
            "child": {},
            "triggerPrice": "0.005"
          },
          "state": {
            "armedAt": "2025-01-01T00:00:00Z",
            "childOrderId": "5USXJZmk",
            "status": "NOT_CONFIGURED",
            "terminalAt": "2025-01-01T00:00:00Z",
            "triggerId": "59VD7Lar"
          }
        },
        "trailingStop": {
          "policy": {
            "activationPrice": "0.005",
            "maxSlippageTicks": 1,
            "trailingDistanceTicks": "0.000000001"
          },
          "state": {
            "armedAt": "2025-01-01T00:00:00Z",
            "childOrderId": "5USXJZmk",
            "status": "NOT_CONFIGURED",
            "terminalAt": "2025-01-01T00:00:00Z",
            "triggerId": "59VD7Lar"
          }
        }
      },
      "avgPx": "0.005",
      "batchRequestId": "2",
      "clientOrderId": "cli-ord-20250101-001",
      "createdAt": "2025-01-01T00:00:00Z",
      "cumQty": "100000",
      "expireAt": "2025-01-01T00:00:00Z",
      "feeAsset": "QUOTE",
      "inheritedCumQty": "100000",
      "leavesQty": "100000",
      "lineage": {
        "generation": 1,
        "id": "2"
      },
      "marketClientRefPrice": "0.005",
      "marketMaxSlippageBps": 1,
      "marketMaxSlippageTicks": 1,
      "orderId": "5USXJZmk",
      "orderType": "LIMIT",
      "origQty": "100000",
      "origin": {
        "childSeq": 1,
        "parentOrderId": "5USXJZmk",
        "scope": "DIRECT",
        "triggerId": "59VD7Lar",
        "triggerType": "STOP_LOSS"
      },
      "postOnly": false,
      "price": "0.005",
      "side": "BUY",
      "status": "PENDING",
      "stpMode": "EXPIRE_MAKER",
      "submittedMaxQuoteDebit": "1",
      "symbol": "BTC-USDT",
      "terminalAt": "2025-01-01T00:00:00Z",
      "terminalReason": "USER_REQUEST",
      "terminalReasonCode": 1,
      "tif": "GTC",
      "version": 1
    }
  ]
}

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. Empty when no more results exist.

Example eyJvZmZzZXQiOjIwMH0

30 fields

4 fields

oco boolean

True when the take-profit and stop leg are linked as one-cancels-the-other.

Example false

2 fields

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

Average execution price across the lineage through this generation, in quote units scaled by 1e9. Zero if no fills.

Example 0.005

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

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

Example 2

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, scaled by the pair's base_quantity_scale from GetSpotConfig for symbol_id.

Example 100000

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

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

Cumulative filled base quantity inherited from predecessors when this replacement was accepted, scaled by the pair's base_quantity_scale from GetSpotConfig for symbol_id. Zero for the original order and immutable within a generation. cum_qty_scaled minus this value is the quantity executed by this generation, not the quantity new to a client session.

Example 100000

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

Remaining working quantity scaled by the pair's base_quantity_scale from GetSpotConfig for symbol_id. Zero for terminal orders.

Example 100000

2 fields

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

Optional client-side reference price used for MARKET slippage protection, in quote units scaled by 1e9.

Example 0.005

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, scaled by the pair's base_quantity_scale from GetSpotConfig for symbol_id.

Example 100000

5 fields

postOnly boolean

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

Example false

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

Limit price in quote units scaled by 1e9. Zero for MARKET orders.

Example 0.005

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, scaled by the pair's quote_quantity_scale from GetSpotConfig. Present only when that sizing method was submitted.

Example 1

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

terminalReason string

Stable string for terminal_reason_code (e.g. "POST_ONLY_CROSS", "USER_REQUEST"). Empty for non-terminal orders.

Example USER_REQUEST

terminalReasonCode integer (int32)

Terminal reason code for canceled/rejected orders. Zero for non-terminal orders.

Example 1

tif enum

Time-in-force policy.

GTC IOC FOK GTD

Example GTC

version integer (int32)

Per-order state version. Starts at 1 and increases for every published state change. Use this field to reconcile API and realtime updates.

Example 1

Possible errors: 5

Key	Status	Error	When
unauthenticated	401	Unauthenticated	Authentication required.
permission-denied	403	Permission Denied	Permission denied.
invalid-argument	400	Invalid Argument	Invalid argument.
not-found	404	Not Found	Not found.
unavailable	503	Unavailable	Service unavailable.

GET

/v1/orders/history

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/orders/history?endTime=1735689600000000000&includeAttachedRisk=false&includeAttachedRiskState=false&limit=100&pageToken=eyJvZmZzZXQiOjEwMH0&side=BUY&startTime=1735689600000000000&status=PENDING&subaccountId=6789012345678&symbol=BTC-USDT&triggerId=9155001234567' \
  --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": "0.005"
          },
          "state": {
            "armedAt": "2025-01-01T00:00:00Z",
            "childOrderId": "5USXJZmk",
            "status": "NOT_CONFIGURED",
            "terminalAt": "2025-01-01T00:00:00Z",
            "triggerId": "59VD7Lar"
          }
        },
        "takeProfit": {
          "policy": {
            "child": {},
            "triggerPrice": "0.005"
          },
          "state": {
            "armedAt": "2025-01-01T00:00:00Z",
            "childOrderId": "5USXJZmk",
            "status": "NOT_CONFIGURED",
            "terminalAt": "2025-01-01T00:00:00Z",
            "triggerId": "59VD7Lar"
          }
        },
        "trailingStop": {
          "policy": {
            "activationPrice": "0.005",
            "maxSlippageTicks": 1,
            "trailingDistanceTicks": "0.000000001"
          },
          "state": {
            "armedAt": "2025-01-01T00:00:00Z",
            "childOrderId": "5USXJZmk",
            "status": "NOT_CONFIGURED",
            "terminalAt": "2025-01-01T00:00:00Z",
            "triggerId": "59VD7Lar"
          }
        }
      },
      "avgPx": "0.005",
      "batchRequestId": "2",
      "clientOrderId": "cli-ord-20250101-001",
      "createdAt": "2025-01-01T00:00:00Z",
      "cumQty": "100000",
      "expireAt": "2025-01-01T00:00:00Z",
      "feeAsset": "QUOTE",
      "inheritedCumQty": "100000",
      "leavesQty": "100000",
      "lineage": {
        "generation": 1,
        "id": "2"
      },
      "marketClientRefPrice": "0.005",
      "marketMaxSlippageBps": 1,
      "marketMaxSlippageTicks": 1,
      "orderId": "5USXJZmk",
      "orderType": "LIMIT",
      "origQty": "100000",
      "origin": {
        "childSeq": 1,
        "parentOrderId": "5USXJZmk",
        "scope": "DIRECT",
        "triggerId": "59VD7Lar",
        "triggerType": "STOP_LOSS"
      },
      "postOnly": false,
      "price": "0.005",
      "side": "BUY",
      "status": "PENDING",
      "stpMode": "EXPIRE_MAKER",
      "submittedMaxQuoteDebit": "1",
      "symbol": "BTC-USDT",
      "terminalAt": "2025-01-01T00:00:00Z",
      "terminalReason": "USER_REQUEST",
      "terminalReasonCode": 1,
      "tif": "GTC",
      "version": 1
    }
  ]
}

Polyester is best experienced on desktop.

Request

Responses