MarketDataService

Get Trades

Retrieve recent public trades for a spot symbol, ordered newest first. Supports optional aggressor side, inclusive time-range, and opaque page-token pagination filters. With afterTradeId, walks the symbol's trades by trade identifier, oldest first and gap-free, to backfill trades missed on a live stream.

Method

GET

Path

/v1/spot/markets/{symbol}/trades

Visibility

Public endpoint

GET

/v1/spot/markets/{symbol}/trades

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/spot/markets/BTC-USDT/trades?limit=100' \
  --header 'Accept: */*'

Responses

{
  "completeThroughTradeId": "1",
  "epochEnds": [
    {
      "epoch": "1",
      "lastTradeId": "1"
    }
  ],
  "nextAfterTradeId": "1",
  "nextPageToken": "eyJvZmZzZXQiOjIwMH0",
  "trades": [
    {
      "executedAt": "2025-01-01T00:00:00Z",
      "matchId": "100001",
      "price": "61000.25",
      "qty": "0.001",
      "side": "BUY",
      "symbol": "BTC-USDT"
    }
  ]
}

symbol string required

Trading pair symbol, e.g. BTC-USDT

afterTradeId string

Exclusive trade-identifier cursor (unsigned 64-bit decimal string) for gap-free backfill: returns trades with matchId above it, ascending, up to completeThroughTradeId. Use 0 to start from the first trade, then nextAfterTradeId. Cannot be combined with side, startTime, endTime or pageToken.

endTime string (date-time)

Filter trades executed at or before this time (inclusive, RFC3339)

limit integer ≤ 1000

Maximum trades to return. Default 100, max 1000.

pageToken string max 512 chars

Opaque cursor from the previous response.

side enum must be defined value

Filter by aggressor side. BUY means the taker bought the base asset; SELL means the taker sold the base asset.

startTime string (date-time)

Filter trades executed at or after this time (inclusive, RFC3339)

completeThroughTradeId string /^[0-9]+$/

With afterTradeId only: every trade with matchId at or below it exists and is returned by this endpoint.

Example 1

2 fields

nextAfterTradeId string /^[0-9]+$/

With afterTradeId only: the afterTradeId of the next call. It never moves backwards; equal to the request's afterTradeId when nothing newer is available yet.

Example 1

nextPageToken string

Opaque cursor for the next page. Empty when no more results exist, and always empty with after_trade_id.

Example eyJvZmZzZXQiOjIwMH0

6 fields

Possible errors: 5

Key	HTTP status	Connect code	Error	When
unauthenticated	401	unauthenticated	Unauthenticated	Authentication required.
permission-denied	403	permission_denied	Permission Denied	Permission denied.
invalid-argument	400	invalid_argument	Invalid Argument	Invalid argument.
not-found	404	not_found	Not Found	Not found.
unavailable	503	unavailable	Unavailable	Service unavailable.