marketdata.v1.MarketDataService
GetTrades
Retrieve recent public trades for a spot market. Results are ordered newest-first and support optional aggressor side, inclusive time-range, and opaque keyset pagination filters. With after_trade_id, it walks the symbol's trades by trade identifier, oldest first and gap-free, to backfill trades missed on a live stream.
Request
curl --request POST \ \
--url 'https://api.testnet.polyester.com/marketdata.v1.MarketDataService/GetTrades' \
--header 'Content-Type: application/json' \
--header 'Connect-Protocol-Version: 1' \
--data '{
"afterTradeId": "1",
"endTime": "2025-01-01T00:00:00Z",
"limit": 100,
"pageToken": "eyJvZmZzZXQiOjEwMH0",
"side": "BUY",
"startTime": "2025-01-01T00:00:00Z",
"symbolId": 1
}'Responses
{
"completeThroughTradeId": "1",
"epochEnds": [
{
"epoch": "1",
"lastTradeId": "1"
}
],
"nextAfterTradeId": "1",
"nextPageToken": "eyJvZmZzZXQiOjIwMH0",
"trades": [
{
"isBuy": true,
"matchId": "100001",
"priceTicks": "61000250000000",
"qtyScaled": "100000",
"symbolId": 1,
"tsNs": "1735689600000000000"
}
]
}marketdata.v1.GetTradesRequestmarketdata.v1.GetTradesResponseStable numeric pair id from GetSpotConfig.
Maximum number of trades to return. Defaults to 100 when unset; max 1000.
Inclusive lower bound for trade execution time. Must not be more than 5 minutes in the future.
Inclusive upper bound for trade execution time. Must be greater than or equal to start_time when both are set, and must not be more than 5 minutes in the future.
Optional filter by trade aggressor side. Unspecified returns both sides.
Opaque keyset cursor from a previous response. The cursor is exclusive and bound to symbol, time bounds, side filter, and newest-first sort order.
Exclusive trade-identifier cursor for gap-free backfill. When set, the results are the symbol's trades with match_id greater than after_trade_id, ascending by match_id, up to limit, and only trades at or below the response's complete_through_trade_id: every page is gap-free. Trade identifiers order trades across epochs too, so a walk crosses epoch ends without a gap. Pass 0 to start from the symbol's first trade, then the response's next_after_trade_id. Cannot be combined with start_time, end_time, side or page_token.
Stable numeric pair id from GetSpotConfig.
Stable trade id within the symbol, suitable for pagination and de-duplication.
True when the taker/aggressor bought the base asset; false when the taker/aggressor sold the base asset.
Trade price in quote-asset units scaled by 1e9.
Traded base-asset quantity scaled by the pair's base_quantity_scale from GetSpotConfig.
Trade execution timestamp, in nanoseconds since the Unix epoch (UTC).
Opaque cursor for the next page. Empty when no more results exist, and always empty with after_trade_id.
Set only with after_trade_id; 0 otherwise. Every trade of the symbol with match_id at or below this value exists and is returned by this method. Identifiers in that range that no trade has, the rest of an ended epoch and every identifier below a later epoch's first, are covered too. Newer trades may exist that are not available here yet; it only grows.
Set only with after_trade_id; 0 otherwise. The after_trade_id of the next call; it never moves backwards. On a full page (limit trades) it is the last trade's match_id. Otherwise it is the greater of after_trade_id and complete_through_trade_id, so a walk progresses across epoch ends and empty epochs without trades to carry it. When it equals the request's after_trade_id, nothing newer is available yet: retry later with backoff.
The epoch.
match_id of the epoch's last trade; (epoch-1) * 2^40 when the epoch ended without trades.
| Key | HTTP status | Connect code | Error | When |
|---|---|---|---|---|
| bad-request | 400 | invalid_argument | Bad Request | The request was malformed or missing required parameters. |
| invalid-argument | 400 | invalid_argument | Invalid Argument | One or more request arguments are invalid. |
| not-found | 404 | not_found | Not Found | The requested resource was not found. |
| unavailable | 503 | unavailable | Service Unavailable | The service is temporarily unavailable. |
| unknown-symbol | 404 | invalid_argument | Unknown Symbol | The requested trading pair symbol was not found. |
| upstream-error | 502 | unavailable | Upstream Error | An upstream service error occurred. |