orders.v1.OrdersService
GetOrder
Retrieve order state and a bounded page of its lineage executions by order or client order ID. Use GetUserTrades for paginated execution history and optional settlement legs. Recent accepted orders may wait briefly for read availability; retry UNAVAILABLE with the same lookup key.
Request
curl --request POST \ \
--url 'https://api.testnet.polyester.com/orders.v1.OrdersReadService/GetOrder' \
--header 'Content-Type: application/json' \
--header 'Connect-Protocol-Version: 1' \
--data '{
"includeAttachedRisk": false,
"includeAttachedRiskState": false,
"includeExecutionHistory": false,
"limit": 100,
"orderId": "9876543210123",
"pageToken": "eyJvZmZzZXQiOjEwMH0",
"subaccountId": "6789012345678"
}'Responses
{
"executionsComplete": false,
"nextPageToken": "eyJvZmZzZXQiOjIwMH0",
"order": {
"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
},
"trades": [
{
"feeAmountE18": {
"hi": "1",
"lo": "1"
},
"feeAsset": "QUOTE",
"feeIsRebate": false,
"isMaker": false,
"lineage": {
"generation": 1,
"id": "1"
},
"matchId": "100001",
"orderId": "9876543210123",
"priceTicks": "61000250000000",
"qtyScaled": "100000",
"referralShareAmountE18": {
"hi": "1",
"lo": "1"
},
"side": "BUY",
"symbolId": 1,
"tsNs": "1735689600000000000"
}
],
"transfers": [
{
"accountCode": "FUNDING",
"amountE18": {
"hi": "1",
"lo": "1"
},
"assetId": 100,
"isDebit": false,
"matchId": "100001",
"symbolId": 1,
"transferCode": "DEPOSIT",
"tsNs": "1735689600000000000",
"txId": "0xabc123"
}
]
}orders.v1.GetOrderRequestorders.v1.GetOrderResponseOptional public subaccount ID. When omitted, subaccount-scoped API keys use their bound subaccount; other callers use their authenticated root account.
Public order ID (base58-encoded fixed64 on REST).
Client order ID. When provided, server resolves latest matching order for the account.
Include attached-risk policy details in response.order (defaults to false when unset).
Include attached-risk state details in response.order (defaults to false when unset).
Include a page of lineage trades and their settlement transfers (default true). Set false for state-only polling; limit and page_token must then be omitted.
Maximum executions to return (1-1000, default 100).
Execution cursor from this order's previous response. Use order_id rather than a reused client_order_id to keep the requested generation stable.
Public order identifier as fixed64.
Trading symbol numeric identifier.
Client-provided, account-scoped identifier for correlation, lookup, and cancellation. Empty when none was supplied.
Order side.
Current order lifecycle status.
Order type.
Time-in-force policy.
Self-trade prevention mode.
Fee asset selected for fills.
True if the order was submitted as post-only (maker-only).
Current accepted total order quantity, updated by successful modifies, scaled by the pair's base_quantity_scale from GetSpotConfig for symbol_id.
Cumulative filled quantity across the lineage through this generation, scaled by the pair's base_quantity_scale from GetSpotConfig for symbol_id.
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.
Remaining working quantity scaled by the pair's base_quantity_scale from GetSpotConfig for symbol_id. Zero for terminal orders.
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.
Most significant 64 bits.
Least significant 64 bits.
Most significant 64 bits.
Least significant 64 bits.
Most significant 64 bits.
Least significant 64 bits.
True when the covered fills' rebates exceed their fees, so the amount was credited to the account rather than charged.
Executed quantity of the fills the total covers, scaled by the pair's base_quantity_scale from GetSpotConfig. Equal to the order's cum_qty_scaled once every fill's fee is recorded. While a fill is still being recorded the two differ, and a later read of the order includes it.
Limit price in quote units scaled by 1e9. Zero for MARKET orders.
Creation timestamp in nanoseconds since epoch (UTC).
Terminal timestamp in nanoseconds since epoch (UTC). Zero for open orders.
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.
For a CANCELED order, why it ended. Not set for every other status; JSON and REST responses then omit it.
Trigger price in quote units scaled by 1e9.
Child execution when the threshold is crossed.
Price the take-profit watches. 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.
Current runtime lifecycle status for this attached-risk leg.
Time the leg was armed, in nanoseconds since epoch (UTC). Zero if not armed.
Time the leg reached a terminal state, in nanoseconds since epoch (UTC). Zero if not terminal.
Trigger identifier for this attached-risk leg.
Child order ID created by this leg after it fires.
Trigger price in quote units scaled by 1e9.
Child execution when the threshold is crossed.
Price the stop-loss watches. 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.
Current runtime lifecycle status for this attached-risk leg.
Time the leg was armed, in nanoseconds since epoch (UTC). Zero if not armed.
Time the leg reached a terminal state, in nanoseconds since epoch (UTC). Zero if not terminal.
Trigger identifier for this attached-risk leg.
Child order ID created by this leg after it fires.
Trailing distance as a price delta in 1e-9 quote-unit ticks.
Trailing distance in basis points (1 bp = 0.01%).
Positive maximum absolute price delta in Q9 execution-price ticks (1 tick = 1e-9 quote units).
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.
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.
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.
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.
Current runtime lifecycle status for this attached-risk leg.
Time the leg was armed, in nanoseconds since epoch (UTC). Zero if not armed.
Time the leg reached a terminal state, in nanoseconds since epoch (UTC). Zero if not terminal.
Trigger identifier for this attached-risk leg.
Child order ID created by this leg after it fires.
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.
Broad class describing how the order was created.
Trigger strategy that created this order. Not set for direct orders; JSON and REST responses then omit it.
Trigger identifier when the order was created by a trigger.
Parent order ID for attached-risk child orders.
Child sequence number for multi-child trigger strategies. Zero when not applicable.
Optional client-side reference price used for MARKET slippage protection, in quote units scaled by 1e9.
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.
Optional MARKET max slippage in basis points (1 bp = 0.01%).
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.
Batch-replace identity that admitted this order. Zero for other origins.
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.
Stable logical-order ID: the first generation's public order ID. Replace preserves this ID; an independent new order starts a new lineage.
One-based replacement generation, distinct from per-order state version.
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.
Trading symbol numeric identifier.
Match identifier (monotonic per symbol).
Order identifier as fixed64.
Fill side.
True if this fill was maker-side.
Execution price in quote units scaled by 1e9.
Executed quantity scaled by the pair's base_quantity_scale from GetSpotConfig for symbol_id.
Most significant 64 bits.
Least significant 64 bits.
Fee asset charged or credited for this fill.
Most significant 64 bits.
Least significant 64 bits.
Execution timestamp in nanoseconds since epoch.
Whether this fill earned a rebate instead of paying a fee.
Stable logical-order ID: the first generation's public order ID. Replace preserves this ID; an independent new order starts a new lineage.
One-based replacement generation, distinct from per-order state version.
Match identifier that linked this transfer to an execution, scoped by symbol_id.
Market of the execution; together with match_id identifies its match.
Asset identifier for the transferred asset.
Most significant 64 bits.
Least significant 64 bits.
True when the transfer debits the account; false when it credits the account.
Product reason for this transfer leg.
Account bucket affected by this transfer leg.
Transfer timestamp in nanoseconds since epoch (UTC).
Transfer transaction identifier.
Cursor for the next execution page. Empty when no further rows are visible; this is not a settlement or order-state reconciliation watermark.
True when the order's trades through its generation, across every page, add up exactly to its cum_qty_scaled. False while a recent execution is still being recorded: trades then lists the executions recorded so far, and a later read returns the rest. Always false when execution history is not included.
| 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. |