orders.v1.OrdersService

GetOrderHistory

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 UNAVAILABLE rather than returning a stale state; retry the same request.

Method

POST

Path

orders.v1.OrdersReadService/GetOrderHistory

Service

orders.v1.OrdersReadService

Visibility

Authentication required

Authentication

Session token or API key

MFA Requirement

Not required

POST

orders.v1.OrdersReadService/GetOrderHistory

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/orders.v1.OrdersReadService/GetOrderHistory' \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{
  "endTsNs": "1735689600000000000",
  "includeAttachedRisk": false,
  "includeAttachedRiskState": false,
  "limit": 100,
  "pageToken": "eyJvZmZzZXQiOjEwMH0",
  "side": "BUY",
  "startTsNs": "1735689600000000000",
  "status": "PENDING",
  "subaccountId": "6789012345678",
  "symbolId": [
    1
  ],
  "triggerId": "9155001234567"
}'

Responses

{
  "nextPageToken": "eyJvZmZzZXQiOjIwMH0",
  "orders": [
    {
      "attachedRisk": {
        "oco": false,
        "stopLoss": {
          "policy": {
            "child": {},
            "triggerPriceSource": "LAST_PRICE",
            "triggerPriceTicks": "61000250000000"
          },
          "state": {
            "armedTsNs": "1735689600000000000",
            "childOrderId": "9876543210123",
            "status": "NOT_CONFIGURED",
            "terminalTsNs": "1735689600000000000",
            "triggerId": "9155001234567"
          }
        },
        "takeProfit": {
          "policy": {
            "child": {},
            "triggerPriceSource": "LAST_PRICE",
            "triggerPriceTicks": "61000250000000"
          },
          "state": {
            "armedTsNs": "1735689600000000000",
            "childOrderId": "9876543210123",
            "status": "NOT_CONFIGURED",
            "terminalTsNs": "1735689600000000000",
            "triggerId": "9155001234567"
          }
        },
        "trailingStop": {
          "policy": {
            "activationPriceTicks": "61000250000000",
            "limitPriceTicks": "61000250000000",
            "maxSlippageTicks": "1",
            "trailingDistanceTicks": "1",
            "triggerPriceSource": "LAST_PRICE"
          },
          "state": {
            "armedTsNs": "1735689600000000000",
            "childOrderId": "9876543210123",
            "status": "NOT_CONFIGURED",
            "terminalTsNs": "1735689600000000000",
            "triggerId": "9155001234567"
          }
        }
      },
      "avgPriceE18": {
        "hi": "1",
        "lo": "1"
      },
      "avgPriceTicks": "61000250000000",
      "batchRequestId": "1",
      "cancelReason": "CANCEL_REASON_USER_REQUEST",
      "clientOrderId": "cli-ord-20250101-001",
      "createdTsNs": "1735689600000000000",
      "cumNotional": {
        "hi": "1",
        "lo": "1"
      },
      "cumQtyScaled": "100000",
      "expireAt": "2025-01-01T00:00:00Z",
      "feeAsset": "QUOTE",
      "feeTotal": {
        "amountE18": {
          "hi": "1",
          "lo": "1"
        },
        "isRebate": false,
        "qtyScaled": "100000"
      },
      "inheritedCumQtyScaled": "100000",
      "leavesQtyScaled": "100000",
      "lineage": {
        "generation": 1,
        "id": "1"
      },
      "marketClientRefPriceTicks": "61000250000000",
      "marketMaxSlippageBps": 1,
      "marketMaxSlippageTicks": "1",
      "orderId": "9876543210123",
      "orderType": "LIMIT",
      "origQtyScaled": "100000",
      "origin": {
        "childSeq": 1,
        "parentOrderId": "9876543210123",
        "scope": "DIRECT",
        "triggerId": "9155001234567",
        "triggerType": "STOP_LOSS"
      },
      "postOnly": false,
      "priceTicks": "61000250000000",
      "rejectReason": "ERROR_CODE_BAD_REQUEST",
      "selfTradePreventionMode": "EXPIRE_MAKER",
      "side": "BUY",
      "status": "PENDING",
      "submittedMaxQuoteDebitScaled": "100000000",
      "symbolId": 1,
      "terminalTsNs": "1735689600000000000",
      "timeInForce": "GTC",
      "version": 0
    }
  ]
}

Request

orders.v1.GetOrderHistoryRequest

Response

orders.v1.GetOrderHistoryResponse

subaccountId string (fixed64) > 0

Optional public subaccount ID. When omitted, subaccount-scoped API keys use their bound subaccount; other callers use their authenticated root account.

symbolId integer[] (int32) max 100 items, unique

Optional filter by symbol_id values. Empty means all symbols.

side enum must be defined value

Optional side filter.

status enum must be defined value

Optional status filter.

startTsNs string (uint64)

Inclusive start of the time range, in nanoseconds since epoch (UTC).

endTsNs string (uint64)

Inclusive end of the time range, in nanoseconds since epoch (UTC).

limit integer (int32) 1–1000

Max number of orders to return (1-1000, default 100).

pageToken string max 512 chars

Opaque keyset cursor from a previous response. The cursor is exclusive and bound to the authenticated account, sub-account scope, filters, time range, and sort order.

includeAttachedRisk boolean

Include attached-risk policy details in each order (defaults to false when unset).

includeAttachedRiskState boolean

Include attached-risk state details in each order (defaults to false when unset).

triggerId string (fixed64) > 0

Optional trigger identifier. When set, returns only child orders created by that trigger.

33 fields

orderId string (fixed64)

Public order identifier as fixed64.

symbolId integer (int32)

Trading symbol numeric identifier.

clientOrderId string max 36 chars /^[A-Za…:/-]*$/

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

side enum must be defined value

Order side.

BUY SELL

status enum

Current order lifecycle status.

PENDING PENDING_CANCEL WORKING FILLED CANCELED REJECTED

orderType enum

Order type.

LIMIT MARKET

timeInForce enum

Time-in-force policy.

GTC IOC FOK GTD

selfTradePreventionMode enum

Self-trade prevention mode.

EXPIRE_MAKER EXPIRE_TAKER EXPIRE_BOTH

feeAsset enum

Fee asset selected for fills.

QUOTE BASE

postOnly boolean

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

origQtyScaled string (int64)

Current accepted total order quantity, updated by successful modifies, scaled by the pair's base_quantity_scale from GetSpotConfig for symbol_id.

cumQtyScaled string (int64)

Cumulative filled quantity across the lineage through this generation, scaled by the pair's base_quantity_scale from GetSpotConfig for symbol_id.

inheritedCumQtyScaled string (int64)

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.

leavesQtyScaled string (int64)

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

avgPriceTicks string (int64)

Average execution price across the lineage through this generation, in quote units scaled by 1e9, rounded down. Zero if no fills. avg_price_e18 carries the exact average.

2 fields

3 fields

priceTicks string (int64)

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

createdTsNs string (uint64)

Creation timestamp in nanoseconds since epoch (UTC).

terminalTsNs string (uint64)

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

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.

ERROR_CODE_BAD_REQUEST ERROR_CODE_INVALID_ARGUMENT ERROR_CODE_INSUFFICIENT_FUNDS ERROR_CODE_UNKNOWN_SYMBOL ERROR_CODE_BAD_PRICE ERROR_CODE_BAD_QTY ERROR_CODE_MIN_NOTIONAL ERROR_CODE_QTY_STEP_SIZE ERROR_CODE_CONFLICT_DUPLICATE_CLIENT_ORDER_ID ERROR_CODE_UNAVAILABLE ERROR_CODE_UNAUTHENTICATED ERROR_CODE_PERMISSION_DENIED ERROR_CODE_NOT_FOUND ERROR_CODE_UPSTREAM_ERROR ERROR_CODE_FEE_ASSET_NOT_ALLOWED ERROR_CODE_PAIR_DISABLED ERROR_CODE_ORDER_UNKNOWN ERROR_CODE_INTERNAL_ERROR ERROR_CODE_SUBACCOUNT_INACTIVE ERROR_CODE_POLICY_MARKET_DENY ERROR_CODE_POLICY_MAX_NOTIONAL ERROR_CODE_POLICY_TRADING_HALTED ERROR_CODE_POLICY_SPOT_TRADE_DENY ERROR_CODE_API_KEY_ROOT_SCOPE_ONLY ERROR_CODE_API_KEY_SUB_SCOPE_ONLY ERROR_CODE_API_KEY_SUBACCOUNT_MISMATCH ERROR_CODE_API_KEY_POLICY_REQUIRED ERROR_CODE_API_KEY_UNKNOWN ERROR_CODE_API_KEY_MARKET_DENY ERROR_CODE_PRICE_TICK_SIZE ERROR_CODE_MIN_QTY ERROR_CODE_POST_ONLY_LIMIT_ONLY ERROR_CODE_BATCH_TOO_LARGE ERROR_CODE_POLICY_MAX_OPEN_ORDERS ERROR_CODE_MODIFICATION_REQUIRES_REPLACE ERROR_CODE_CONFLICT_IDEMPOTENCY_KEY_REUSE ERROR_CODE_MARKET_PRICE_UNAVAILABLE ERROR_CODE_PAIR_NOT_LISTED_YET ERROR_CODE_PAIR_DELISTED ERROR_CODE_PAIR_CANCEL_ONLY ERROR_CODE_PAIR_POST_ONLY ERROR_CODE_PAIR_REDUCE_ONLY ERROR_CODE_RISK_LIMIT ERROR_CODE_MARKET_HALTED ERROR_CODE_ACCOUNT_UNKNOWN ERROR_CODE_POST_ONLY_CROSS ERROR_CODE_REDUCE_ONLY_BLOCKED ERROR_CODE_PRICE_BAND_VIOLATION ERROR_CODE_MARKET_CAP_VIOLATION ERROR_CODE_EMPTY_BOOK ERROR_CODE_FOK_INSUFFICIENT_LIQUIDITY ERROR_CODE_ORDER_ALREADY_TERMINAL ERROR_CODE_TRIGGER_PRICE_INVALID ERROR_CODE_TRIGGER_PRICE_SOURCE_UNSUPPORTED ERROR_CODE_TRAILING_DISTANCE_INVALID ERROR_CODE_TRIGGER_NOT_FOUND ERROR_CODE_TRIGGER_STATUS_INVALID ERROR_CODE_TRIGGER_NOT_MODIFIABLE ERROR_CODE_CONFLICT_DUPLICATE_CLIENT_TRIGGER_ID ERROR_CODE_MAX_SLIPPAGE_INVALID ERROR_CODE_STALE_QUOTE ERROR_CODE_VALIDATION_ERROR ERROR_CODE_OVERLOADED ERROR_CODE_MAX_QUOTE_DEBIT_TOO_SMALL ERROR_CODE_RATE_LIMIT_EXCEEDED ERROR_CODE_SUBACCOUNT_READ_FORBIDDEN ERROR_CODE_POLICY_SPOT_READ_DENY ERROR_CODE_API_KEY_SPOT_READ_DENY ERROR_CODE_CANCEL_REQUEST_EXPIRED ERROR_CODE_MAX_QTY ERROR_CODE_MAX_NOTIONAL ERROR_CODE_QTY_AT_OR_BELOW_FILLED ERROR_CODE_GATEWAY_MISCONFIGURED ERROR_CODE_INVALID_ORDER_ID ERROR_CODE_CHILD_QTY_RAISE_NOT_ALLOWED ERROR_CODE_ATTACHED_RISK_NOT_SUPPORTED ERROR_CODE_SETTLEMENT_BACKLOGGED ERROR_CODE_PRICE_LEVEL_QUANTITY_LIMIT ERROR_CODE_MARKET_QUOTE_STALE ERROR_CODE_MARKET_QUOTE_UNHEALTHY ERROR_CODE_INVALID_TIME_IN_FORCE ERROR_CODE_QUICKSWAP_NOT_PERMITTED ERROR_CODE_DUPLICATE_ORDER_ID ERROR_CODE_MAX_OPEN_ORDERS_TOTAL ERROR_CODE_STP_MODE_NOT_ALLOWED ERROR_CODE_PAIR_BACKLOGGED ERROR_CODE_PRICE_LEVELS_EXHAUSTED ERROR_CODE_CLIENT_ORDER_IDS_EXHAUSTED ERROR_CODE_ORDER_ID_CONFLICT ERROR_CODE_INVALID_SIDE ERROR_CODE_INVALID_ORDER_TYPE ERROR_CODE_INVALID_STP_MODE ERROR_CODE_INVALID_ORDER_FLAGS ERROR_CODE_BATCH_OTHER_ITEM_INVALID ERROR_CODE_REPLACE_ONTO_OWN_ID ERROR_CODE_INVALID_CLIENT_ORDER_ID ERROR_CODE_ORDER_SEQUENCE_EXHAUSTED ERROR_CODE_INVALID_HANDLING_MODE ERROR_CODE_FEE_SCHEDULE_UNAVAILABLE ERROR_CODE_POLICY_UNAVAILABLE ERROR_CODE_CANCEL_ALL_AFTER_TIMEOUT_INVALID ERROR_CODE_CANCEL_SCOPE_TOO_LARGE ERROR_CODE_RATE_LIMIT_POLICY_UNAVAILABLE ERROR_CODE_SYSTEM_RATE_LIMITED ERROR_CODE_ORDER_MODIFY_IN_PROGRESS ERROR_CODE_ORDER_PLACEMENT_PENDING ERROR_CODE_INVALID_MODIFY_BEHAVIOR ERROR_CODE_BATCH_REPLACE_ONLY_REQUIRED ERROR_CODE_BATCH_SINGLE_SYMBOL_REQUIRED ERROR_CODE_REQUEST_RECEIPTS_EXHAUSTED ERROR_CODE_INTENT_ID_INVALID ERROR_CODE_DRY_RUN_INVALID ERROR_CODE_CANCEL_ALL_AFTER_SCOPE_CONFLICT ERROR_CODE_NEW_ACCOUNT_CAPACITY_REACHED ERROR_CODE_TRIGGER_CHILD_PRICE_NOT_MODIFIABLE ERROR_CODE_TRIGGER_GENERATIONS_EXHAUSTED ERROR_CODE_TRIGGER_CONTROL_SHARE_EXHAUSTED ERROR_CODE_TRIGGER_CONTROLS_BUSY ERROR_CODE_TRIGGER_TYPE_NOT_SUPPORTED ERROR_CODE_INVALID_TRIGGER_TYPE ERROR_CODE_TRIGGER_DIRECTION_INVALID ERROR_CODE_TRIGGER_QTY_INVALID ERROR_CODE_TRIGGER_BUY_REQUIRES_LIMIT ERROR_CODE_ACCOUNT_ROUTING_INVALID ERROR_CODE_TRIGGER_LIMIT_EXCEEDED ERROR_CODE_TRIGGER_CONTROL_IN_PROGRESS ERROR_CODE_TRIGGER_PATCH_EMPTY ERROR_CODE_CLIENT_TRIGGER_ID_INVALID ERROR_CODE_TRIGGER_ACTIVATION_PRICE_INVALID ERROR_CODE_SLIPPAGE_TICKS_INVALID ERROR_CODE_SLIPPAGE_BPS_INVALID ERROR_CODE_TRIGGER_CONTROL_OUTCOME_UNKNOWN ERROR_CODE_TRIGGER_CAPACITY_REACHED ERROR_CODE_RESERVATION_CAPACITY_REACHED ERROR_CODE_CLIENT_ORDER_ID_CAPACITY_REACHED ERROR_CODE_ACCOUNT_RESERVATION_LIMIT_REACHED ERROR_CODE_INVALID_TRIGGER_CONTROL ERROR_CODE_TRIGGER_PATCH_NOT_ALLOWED ERROR_CODE_TRIGGER_PATCH_FIELD_UNKNOWN ERROR_CODE_TRIGGER_PATCH_VALUE_UNMASKED ERROR_CODE_TRIGGER_PATCH_PRICE_MODE_INVALID ERROR_CODE_ACCOUNT_ORDERS_SUSPENDED ERROR_CODE_TRAILING_SIDE_NOT_SUPPORTED ERROR_CODE_TRAILING_CHILD_NOT_MARKET ERROR_CODE_TWAP_DURATION_INVALID ERROR_CODE_LIMIT_CHILD_SLIPPAGE_SET ERROR_CODE_SLIPPAGE_BOUNDS_CONFLICT ERROR_CODE_TWAP_INTERVAL_INVALID ERROR_CODE_LADDER_LEVEL_REJECTED ERROR_CODE_LADDER_RANGE_TOO_NARROW ERROR_CODE_LADDER_LEVELS_INVALID ERROR_CODE_ORDER_LIMITS_UNAVAILABLE ERROR_CODE_ORDER_TYPE_NOT_ALLOWED_IN_AUCTION ERROR_CODE_POST_ONLY_NOT_ALLOWED_IN_AUCTION ERROR_CODE_QUICKSWAP_FEE_DETAILS_INCOMPLETE ERROR_CODE_QUICKSWAP_MARKET_NOT_PRICED ERROR_CODE_QUICKSWAP_BROKER_FEE_TERMS_MISMATCH ERROR_CODE_QUICKSWAP_FEE_RECIPIENT_IS_PAYER ERROR_CODE_QUICKSWAP_BROKER_FEE_TERMS_UNAVAILABLE ERROR_CODE_QUICKSWAP_BROKER_ACCOUNT_UNAVAILABLE ERROR_CODE_QUICKSWAP_ACCOUNT_OWNER_UNKNOWN ERROR_CODE_QUICKSWAP_DISABLED ERROR_CODE_QUICKSWAP_ATTACHED_RISK_NOT_ALLOWED ERROR_CODE_QUICKSWAP_ORDER_NOT_MODIFIABLE ERROR_CODE_QUICKSWAP_FEE_TOTAL_TOO_HIGH ERROR_CODE_QUICKSWAP_BROKER_FEE_TERMS_INVALID ERROR_CODE_QUICKSWAP_BROKER_INVALID ERROR_CODE_QUICKSWAP_FEE_SCHEDULE_INVALID ERROR_CODE_QUICKSWAP_MARKET_FEE_INVALID ERROR_CODE_QUICKSWAP_SETUP_INVALID ERROR_CODE_QUICKSWAP_CAPACITY_REACHED ERROR_CODE_ATTACHED_EXIT_WORKING ERROR_CODE_MARKET_TRIGGER_LIMIT_EXCEEDED ERROR_CODE_MARKET_TWAP_LIMIT_EXCEEDED ERROR_CODE_MARKET_LADDER_LIMIT_EXCEEDED ERROR_CODE_CHILD_QTY_EXCEEDS_REMAINING ERROR_CODE_ORDER_CANCEL_OUTCOME_UNKNOWN ERROR_CODE_ORDER_MODIFY_OUTCOME_UNKNOWN ERROR_CODE_ORDER_REPAIRING ERROR_CODE_ACCOUNT_REPAIRING ERROR_CODE_TRIGGER_WOULD_TRIGGER_IMMEDIATELY ERROR_CODE_ORDER_CREATE_OUTCOME_UNKNOWN ERROR_CODE_TRIGGER_CREATE_OUTCOME_UNKNOWN ERROR_CODE_TRIGGER_SYMBOL_MISMATCH ERROR_CODE_MAX_OPEN_ORDERS_PER_PAIR ERROR_CODE_SELF_TRADE_PREVENTED ERROR_CODE_ATTACHED_LEGS_EXCEEDED ERROR_CODE_FEE_ASSET_INVALID ERROR_CODE_FEE_CEILING_INVALID ERROR_CODE_UNSUPPORTED_FIELD_SET ERROR_CODE_TRIGGER_FIRE_LIMIT_REACHED ERROR_CODE_CONDITION_FLAGS_INVALID ERROR_CODE_CONDITION_PARAMETER_SET ERROR_CODE_TWAP_CAPACITY_REACHED ERROR_CODE_CHILD_ORDER_INCONSISTENT

cancelReason enum

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

CANCEL_REASON_USER_REQUEST CANCEL_REASON_IOC_REMAINDER CANCEL_REASON_MARKET_REMAINDER CANCEL_REASON_STP_EXPIRE_MAKER CANCEL_REASON_STP_EXPIRE_TAKER CANCEL_REASON_STP_EXPIRE_BOTH CANCEL_REASON_REPLACED CANCEL_REASON_GTD_EXPIRED CANCEL_REASON_QTY_AT_OR_BELOW_FILLED CANCEL_REASON_PAIR_DRAIN CANCEL_REASON_ATTACHED_RISK_REFUSED CANCEL_REASON_CANCEL_ALL_AFTER CANCEL_REASON_ACCOUNT_REPAIR CANCEL_REASON_TWAP_ROLLOVER CANCEL_REASON_STRATEGY_CANCEL CANCEL_REASON_SYSTEM CANCEL_REASON_MARKET_HALTED CANCEL_REASON_ATTACHED_EXIT_FIRED

4 fields

2 fields

7 fields

trailingDistanceTicks string (int64) > 0

Trailing distance as a price delta in 1e-9 quote-unit ticks.

trailingDistanceBps integer (int32) > 0, ≤ 10000

Trailing distance in basis points (1 bp = 0.01%).

maxSlippageTicks string (int64) > 0

Positive maximum absolute price delta in Q9 execution-price ticks (1 tick = 1e-9 quote units).

maxSlippageBps integer (int32) > 0, ≤ 10000

Maximum allowed slippage in basis points (1 bp = 0.01%), from 1 to 9999 whichever side the exit trades. An order whose trailing stop sets 10000 is rejected with ERROR_CODE_MAX_SLIPPAGE_INVALID, because a 100% cap would leave an exit that sells no positive price to sell at.

activationPriceTicks string (int64)

Optional activation price: trailing only starts after this price is reached. If omitted, trailing starts immediately after the parent order fills. Expressed in quote units scaled by 1e9.

triggerPriceSource enum must be defined value

Price the trailing stop watches and trails: its peak or trough, activation and fire all follow this price. Unspecified or LAST_PRICE watches the last traded price. INDEX_PRICE watches the market's index price; on a market without an index price the order is rejected with terminal reason INDEX_PRICE_UNAVAILABLE before any fill, and a modify that adds such a leg is refused with ERROR_CODE_TRIGGER_PRICE_SOURCE_UNSUPPORTED, leaving the order and its legs unchanged. MARK_PRICE is not supported. A modify naming another source replaces the leg.

LAST_PRICE INDEX_PRICE MARK_PRICE

limitPriceTicks string (int64) > 0

Maximum price of a trailing stop that buys back, in quote units scaled by 1e9: the most its exit pays per unit, at which the quote it may spend is reserved with the exit's fee. Required when the parent order sells, so the trailing stop buys; must be unset when the parent order buys. A rise that fires above it still fires, and the exit fills only at or below it. Changing it with ModifyOrder replaces the leg.

5 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.

5 fields

marketClientRefPriceTicks string (int64)

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

marketMaxSlippageTicks string (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.

marketMaxSlippageBps integer (int32)

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

version integer (int32) 0–2147483647

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.

batchRequestId string (fixed64)

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

submittedMaxQuoteDebitScaled string (int64)

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.

2 fields

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.

nextPageToken string max 512 chars

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.

Possible errors: 33

Key	HTTP status	Connect code	Error	When
api-key-policy-required	403	permission_denied	API Key Policy Required	This API key must have a policy attached before it can be used for reading.
api-key-root-scope-only	403	permission_denied	API Key Root Scope Only	This API key is scoped to the master account and cannot read sub-accounts.
api-key-spot-read-deny	403	permission_denied	API Key Spot Read Denied	API key policy does not allow reading spot data.
api-key-subaccount-mismatch	403	permission_denied	API Key Subaccount Mismatch	This API key is scoped to a different sub-account than the one requested.
api-key-sub-scope-only	403	permission_denied	API Key Sub Scope Only	This API key is scoped to a specific sub-account and cannot read the master account.
api-key-unknown	403	permission_denied	API Key Unknown	API key referenced in the request could not be resolved by the Orders service.
invalid-argument	400	invalid_argument	Invalid Argument	Invalid argument.
invalid-before-ts-ns	400	invalid_argument	Invalid beforeTsNs	beforeTsNs must be an unsigned integer.
invalid-end-time	400	invalid_argument	Invalid End Time	endTime must be RFC3339.
invalid-limit	400	invalid_argument	Invalid Limit	Limit must be between 1 and 1000.
invalid-offset	400	invalid_argument	Invalid Offset	Offset must be zero or positive.
invalid-order-id	400	invalid_argument	Invalid Order ID	order_id is invalid.
invalid-order-status	400	invalid_argument	Invalid Order Status	Order status value is invalid.
invalid-page-token	400	invalid_argument	Invalid Page Token	pageToken is invalid for this account or request.
invalid-side	400	invalid_argument	Invalid Side	Side must be BUY or SELL.
invalid-start-time	400	invalid_argument	Invalid Start Time	startTime must be RFC3339.
invalid-subaccount-id	400	invalid_argument	Invalid Subaccount ID	Subaccount ID is invalid.
invalid-symbol	400	invalid_argument	Invalid Symbol	Symbol format is invalid.
invalid-trigger-id	400	invalid_argument	Invalid Trigger ID	trigger_id is invalid.
invalid-trigger-status	400	invalid_argument	Invalid Trigger Status	Trigger status value is invalid.
invalid-trigger-type	400	invalid_argument	Invalid Trigger Type	triggerType value is invalid.
not-found	404	not_found	Not Found	Not found.
order-id-required	400	invalid_argument	Order ID Required	order_id is required.
permission-denied	403	permission_denied	Permission Denied	Permission denied.
policy-spot-read-deny	403	permission_denied	Spot Read Denied	Effective policy does not allow reading spot data for this API key or sub-account.
request-too-large	413	invalid_argument	Request Too Large	Request body too large.
subaccount-read-forbidden	403	permission_denied	Sub-account Read Forbidden	You do not have permission to read this sub-account.
trigger-id-required	400	invalid_argument	Trigger ID Required	trigger_id is required.
unauthenticated	401	unauthenticated	Unauthenticated	Authentication required.
unavailable	503	unavailable	Service Unavailable	Service unavailable.
unknown-symbol	400	invalid_argument	Unknown Symbol	Unknown symbol.
upstream-error	502	unavailable	Upstream Error	Upstream dependency error.
validation-error	400	invalid_argument	Validation Error	Request validation failed.

POST

orders.v1.OrdersReadService/GetOrderHistory

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/orders.v1.OrdersReadService/GetOrderHistory' \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{
  "endTsNs": "1735689600000000000",
  "includeAttachedRisk": false,
  "includeAttachedRiskState": false,
  "limit": 100,
  "pageToken": "eyJvZmZzZXQiOjEwMH0",
  "side": "BUY",
  "startTsNs": "1735689600000000000",
  "status": "PENDING",
  "subaccountId": "6789012345678",
  "symbolId": [
    1
  ],
  "triggerId": "9155001234567"
}'

Responses

{
  "nextPageToken": "eyJvZmZzZXQiOjIwMH0",
  "orders": [
    {
      "attachedRisk": {
        "oco": false,
        "stopLoss": {
          "policy": {
            "child": {},
            "triggerPriceSource": "LAST_PRICE",
            "triggerPriceTicks": "61000250000000"
          },
          "state": {
            "armedTsNs": "1735689600000000000",
            "childOrderId": "9876543210123",
            "status": "NOT_CONFIGURED",
            "terminalTsNs": "1735689600000000000",
            "triggerId": "9155001234567"
          }
        },
        "takeProfit": {
          "policy": {
            "child": {},
            "triggerPriceSource": "LAST_PRICE",
            "triggerPriceTicks": "61000250000000"
          },
          "state": {
            "armedTsNs": "1735689600000000000",
            "childOrderId": "9876543210123",
            "status": "NOT_CONFIGURED",
            "terminalTsNs": "1735689600000000000",
            "triggerId": "9155001234567"
          }
        },
        "trailingStop": {
          "policy": {
            "activationPriceTicks": "61000250000000",
            "limitPriceTicks": "61000250000000",
            "maxSlippageTicks": "1",
            "trailingDistanceTicks": "1",
            "triggerPriceSource": "LAST_PRICE"
          },
          "state": {
            "armedTsNs": "1735689600000000000",
            "childOrderId": "9876543210123",
            "status": "NOT_CONFIGURED",
            "terminalTsNs": "1735689600000000000",
            "triggerId": "9155001234567"
          }
        }
      },
      "avgPriceE18": {
        "hi": "1",
        "lo": "1"
      },
      "avgPriceTicks": "61000250000000",
      "batchRequestId": "1",
      "cancelReason": "CANCEL_REASON_USER_REQUEST",
      "clientOrderId": "cli-ord-20250101-001",
      "createdTsNs": "1735689600000000000",
      "cumNotional": {
        "hi": "1",
        "lo": "1"
      },
      "cumQtyScaled": "100000",
      "expireAt": "2025-01-01T00:00:00Z",
      "feeAsset": "QUOTE",
      "feeTotal": {
        "amountE18": {
          "hi": "1",
          "lo": "1"
        },
        "isRebate": false,
        "qtyScaled": "100000"
      },
      "inheritedCumQtyScaled": "100000",
      "leavesQtyScaled": "100000",
      "lineage": {
        "generation": 1,
        "id": "1"
      },
      "marketClientRefPriceTicks": "61000250000000",
      "marketMaxSlippageBps": 1,
      "marketMaxSlippageTicks": "1",
      "orderId": "9876543210123",
      "orderType": "LIMIT",
      "origQtyScaled": "100000",
      "origin": {
        "childSeq": 1,
        "parentOrderId": "9876543210123",
        "scope": "DIRECT",
        "triggerId": "9155001234567",
        "triggerType": "STOP_LOSS"
      },
      "postOnly": false,
      "priceTicks": "61000250000000",
      "rejectReason": "ERROR_CODE_BAD_REQUEST",
      "selfTradePreventionMode": "EXPIRE_MAKER",
      "side": "BUY",
      "status": "PENDING",
      "submittedMaxQuoteDebitScaled": "100000000",
      "symbolId": 1,
      "terminalTsNs": "1735689600000000000",
      "timeInForce": "GTC",
      "version": 0
    }
  ]
}