Skip to main content
GET
Get user trade history

Authorizations

X-Monaco-Signature
string
header
required

Ed25519 session-key request signing. Every authenticated request carries three headers: X-Monaco-PublicKey (64-char lowercase-hex session public key), X-Monaco-Timestamp (Unix milliseconds, within 30s of server time), and X-Monaco-Signature (hex ed25519 signature). The signature is over METHOD\npath?query\ntimestamp_ms\nSHA256_hex(body), where the body hash is the SHA-256 of the empty byte string when there is no body. Obtain the session keypair from POST /api/v1/auth/challenge followed by POST /api/v1/auth/verify.

Query Parameters

pageSize
integer<uint32>
default:20

Items per page (max: 100 in page-number mode; up to 1000 when pageToken is present)

Required range: 1 <= x <= 1000
tradingPairId
string<uuid>

Trading pair identifier (UUID)

Minimum string length: 1
pageToken
string

Pagination cursor with two states:

  • Omitted or empty string (""): start a cursor walk with no prior position, from the newest row.
  • Non-empty: an opaque cursor from a previous response's nextPageToken; results resume immediately after that position.

Every walk covers full trade history — hot and archived rows merged. An unfiltered response carries a bounded item count (total); a response filtered by trading_pair_id carries none. Filters must match the request that produced the token.

marginAccountId
string

Optional margin account UUID filter: only trades where this user's side of the fill was placed from this margin account. A self-trade is read as its maker side, so it matches through its maker order's account. Like trading_pair_id, a filtered response carries no total, and the filter must match the request that produced a page_token.

orderId
string

Optional order UUID filter: only trades where this user's side of the fill was placed by this order. A self-trade is read as its maker side, so it matches its maker order only. A filtered response carries no total, and the filter must match the request that produced a page_token.

Response

OK

trades
object[] | null
pageSize
string | null

Items per page

Example:

"20"

nextPageToken
string | null

Cursor for the next page. Present whenever that page returned any rows (AIP-158 "maybe more" semantics), not only when the page is exactly full. Empty only when a page returned zero rows, which is the sole proof the walk is exhausted; a non-empty token does not guarantee further results, so keep following it until a response returns zero rows and an empty token.

total
integer<uint32> | null

Number of trades a full walk returns, hot and archived, with a self-trade counted once; bounded by the server ceiling (10,000), a lower bound when totalCapped is true. Can briefly differ from a walk while the read replica catches up. Absent when tradingPairId filters the request or the count ran out of time: treat absent as unknown.

Example:

150

totalPages
integer<uint32> | null

Number of pages at this pageSize, from the same bounded count as total; a lower bound when totalCapped is true. Absent exactly when total is.

Example:

8

totalCapped
boolean | null

True when more than the server ceiling of trades matched, so the count stopped at the ceiling and total/totalPages are a lower bound. False when total is exact, including exactly the ceiling, and when total is absent.

Example:

false