orders.v1.OrdersService
GetUserTrades
Retrieve per-user trade fills for an account. Supports exact physical-order or logical-lineage scope, an inclusive generation cutoff, and subaccount, symbol, side and time filters with cursor pagination.
Request
curl --request POST \ \
--url 'https://api.testnet.polyester.com/orders.v1.OrdersReadService/GetUserTrades' \
--header 'Content-Type: application/json' \
--header 'Connect-Protocol-Version: 1' \
--data '{
"afterMatchId": "100001",
"endTsNs": "1735689600000000000",
"includeTransfers": false,
"limit": 100,
"orderId": "9876543210123",
"pageToken": "eyJvZmZzZXQiOjEwMH0",
"side": "BUY",
"startTsNs": "1735689600000000000",
"subaccountId": "6789012345678",
"symbolId": 1,
"throughGeneration": 1
}'Responses
{
"nextPageToken": "eyJvZmZzZXQiOjIwMH0",
"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.GetUserTradesRequestorders.v1.GetUserTradesResponseOptional public subaccount ID. When omitted, subaccount-scoped API keys use their bound subaccount; other callers use their authenticated root account.
Optional filter by symbol_id.
Optional side filter.
Inclusive start of the time range, in nanoseconds since epoch (UTC).
Inclusive end of the time range, in nanoseconds since epoch (UTC).
Max number of trades to return (1-1000, default 100).
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.
Return only durable fills whose per-symbol match ID is greater than this value. Subscribe to the execution WebSocket before calling this method and de-duplicate overlapping results by (symbol_id, match_id, order_id).
Exactly this physical order's executions; never includes predecessors.
Executions across this logical order's accepted generations.
Inclusive generation ceiling; requires lineage_id. Does not freeze an actively filling generation.
Include account settlement legs linked to matches on this page. Legs may repeat across pages when two fills share a match; deduplicate by tx_id.
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.
Opaque cursor for the next page. Empty when no more results exist.
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.
| 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. |