Get Trades

Retrieve trade execution history (fills) from Synthetix's orderbook. Each trade represents a filled order or partial fill that has been executed. Returns trades for the specified subaccount.

Endpoint

POST https://papi.synthetix.io/v1/trade

Request

Request Format

{
  "params": {
    "action": "getTrades",
    "subAccountId": "1867542890123456789",
    "symbol": "BTC-USDT",
    "limit": 100,
    "offset": 0,
    "startTime": 1730678400000,
    "endTime": 1730764800000
  },
  "nonce": 1704067200000,
  "expiresAfter": 1704067300000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  }
}

Request Parameters

Action Parameters

Parameter	Type	Required	Description
`params`	object	Yes	Request parameters wrapper
`params.action`	string	Yes	Must be `"getTrades"`
`params.subAccountId`	string	Yes	SubAccount ID to retrieve trades for
`params.symbol`	string	No	Filter trades by market symbol (e.g., `"BTC-USDT"`)
`params.limit`	integer	No	Maximum number of trades to return (default: 100, max: 1000)
`params.offset`	integer	No	Number of trades to skip for pagination (default: 0)
`params.startTime`	integer	No	Start timestamp in milliseconds (inclusive)
`params.endTime`	integer	No	End timestamp in milliseconds (inclusive)

Common Request Parameters

Parameter	Type	Required	Description
`nonce`	uint64	Yes	Unix milliseconds timestamp (must be monotonically increasing)
`signature`	object	Yes	EIP-712 signature object
`expiresAfter`	uint64	No	Unix milliseconds expiration timestamp (5x rate limit on stale cancels)

Parameter	Type	Required	Description
`expiresAfter`	integer	No	Optional expiration timestamp in milliseconds

Response

Response Structure

Field	Type	Description
`status`	string	Always `"ok"` for successful requests or `"error"` for failures
`response`	object	Response object containing trades array and pagination info (omitted when `status` is `"error"`)
`response.trades`	array	Array of trade objects matching filter criteria
`response.hasMore`	boolean	Whether more trades exist beyond current result
`response.total`	integer	Total number of trades matching the query
`error`	object	Error details (only present when `status` is `"error"`)
`request_id`	string	Request tracking identifier
`timestamp`	string	RFC3339 timestamp

Success Response Examples

Multiple Trades with Various Details

{
  "status": "ok",
  "response": {
    "trades": [
      {
        "tradeId": "123456789",
        "orderId": "1948058938469519360",
        "clientOrderId": "0x1234567890abcdef1234567890abcdef",
        "symbol": "BTC-USDT",
        "side": "buy",
        "direction": "LONG",
        "price": "50000.50",
        "quantity": "0.1",
        "realizedPnl": "125.50",
        "fee": "5.00",
        "feeRate": "0.001",
        "markPrice": "50025.00",
        "entryPrice": "49500.00",
        "timestamp": 1704067200500,
        "maker": false,
        "reduceOnly": false,
        "triggeredByLiquidation": false
      },
      {
        "tradeId": "123456790",
        "orderId": "1948058938469519361",
        "clientOrderId": "0x9876543210fedcba9876543210fedcba",
        "symbol": "ETH-USDT",
        "side": "sell",
        "direction": "SHORT",
        "price": "2999.25",
        "quantity": "1.5",
        "realizedPnl": "-75.25",
        "fee": "4.50",
        "feeRate": "0.001",
        "markPrice": "3000.00",
        "entryPrice": "2950.00",
        "timestamp": 1704067201000,
        "maker": true,
        "reduceOnly": true,
        "triggeredByLiquidation": false
      },
      {
        "tradeId": "123456791",
        "orderId": "1948058938469519362",
        "clientOrderId": "",
        "symbol": "BTC-USDT",
        "side": "sell",
        "direction": "SHORT",
        "price": "49500.00",
        "quantity": "0.05",
        "realizedPnl": "0.00",
        "fee": "2.48",
        "feeRate": "0.001",
        "markPrice": "49450.00",
        "entryPrice": "50000.00",
        "timestamp": 1704067201500,
        "maker": false,
        "reduceOnly": false,
        "triggeredByLiquidation": true
      }
    ],
    "hasMore": false,
    "total": 3
  },
  "request_id": "5ccf215d37e3ae6d",
  "timestamp": "2025-01-01T00:00:00Z"
}

Single Symbol Filter

{
  "status": "ok",
  "response": {
    "trades": [
      {
        "tradeId": "123456792",
        "orderId": "1948058938469519363",
        "clientOrderId": "",
        "symbol": "BTC-USDT",
        "side": "buy",
        "direction": "LONG",
        "price": "50250.00",
        "quantity": "0.2",
        "realizedPnl": "50.00",
        "fee": "10.05",
        "feeRate": "0.001",
        "markPrice": "50275.00",
        "entryPrice": "50100.00",
        "timestamp": 1704067202000,
        "maker": false,
        "reduceOnly": false,
        "triggeredByLiquidation": false
      }
    ],
    "hasMore": true,
    "total": 150
  },
  "request_id": "5ccf215d37e3ae6e",
  "timestamp": "2025-01-01T00:00:00Z"
}

Empty Result Set

{
  "status": "ok",
  "response": {
    "trades": [],
    "hasMore": false,
    "total": 0
  },
  "request_id": "5ccf215d37e3ae6f",
  "timestamp": "2025-01-01T00:00:00Z"
}

Trade Object

Field	Type	Description
`tradeId`	string	Unique trade execution identifier
`orderId`	string	Associated order ID
`clientOrderId`	string	Client-provided order ID (if exists)
`symbol`	string	Market symbol (e.g., "BTC-USDT")
`side`	string	Trade side: "buy" or "sell"
`price`	string	Actual filled price of this trade
`quantity`	string	Actual filled quantity of this trade
`realizedPnl`	string	Realized P&L from position closure
`fee`	string	Trading fee amount
`feeRate`	string	Fee rate applied
`timestamp`	integer	Trade timestamp (Unix milliseconds)
`maker`	boolean	`true` if maker order, `false` if taker
`reduceOnly`	boolean	`true` if trade reduced existing position
`postOnly`	boolean	`true` if order was post-only (maker-only)
`markPrice`	string	Mark price at time of trade
`entryPrice`	string	Position average entry price at time of trade
`triggeredByLiquidation`	boolean	`true` if triggered by liquidation
`direction`	string	Position direction after trade

Trade Field Explanations

Field	Description
`tradeId`	Unique identifier for this specific trade execution
`orderId`	Order that generated this trade
`clientOrderId`	Optional client-specified order identifier
`price`	Actual execution price at which this trade was filled (not the mark price or entry price)
`quantity`	Actual filled quantity for this trade execution
`realizedPnl`	Profit/loss realized from this trade
`fee`	Trading fee charged for this execution
`feeRate`	Fee rate applied (maker/taker rate)
`markPrice`	Mark price at time of trade execution (used for unrealized P&L and liquidations)
`entryPrice`	Position's average entry price at time of trade (weighted average of all entries)
`isMaker`	Whether this trade provided liquidity (maker) or took liquidity (taker)
`reduceOnly`	Whether this trade reduced an existing position
`liquidation`	Whether this trade was part of a liquidation

Error Response

{
  "status": "error",
  "error": {
    "message": "Invalid time range: startTime must be less than or equal to endTime",
    "code": "VALIDATION_ERROR"
  },
  "request_id": "5ccf215d37e3ae6d",
  "timestamp": "2025-01-01T00:00:00Z"
}

Examples

Get Recent Trades (Own Account)

{
  "params": {
    "action": "getTrades",
    "subAccountId": "1867542890123456789",
    "limit": 50
  },
  "nonce": 1704067200000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  }
}

Filter by Symbol

{
  "params": {
    "action": "getTrades",
    "subAccountId": "1867542890123456789",
    "symbol": "ETH-USDT",
    "limit": 100
  },
  "nonce": 1704067200000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  }
}

Sorting

Trades are returned in descending order by timestamp (newest first).

Implementation Notes

Subaccount parameter required for trade retrieval scope
Time range cannot exceed 30 days (2,592,000,000 milliseconds)
Pagination supports up to 1000 trades per request (default: 100)
Time filtering uses inclusive millisecond timestamp bounds
Symbol filtering reduces response size for multi-market accounts
Trade identification uses unique tradeId with order linking via orderId
Position tracking available through startPosition and endPosition fields

Trade Types

Regular Trades

Standard trades from limit or market orders:

Contains standard execution information
May be partial fills (group by orderId to see all fills for the same order)

Liquidation Trades

Forced trades due to insufficient margin:

Contains liquidation object with additional details
liquidatedUser identifies the account that was liquidated
method indicates how the liquidation was executed

Maker vs Taker

Maker: Order added liquidity to the orderbook (maker: true)
- Typically receives fee rebate or reduced fees
Taker: Order removed liquidity from the orderbook (maker: false)
- Typically pays higher fees

Error Handling

Common Errors

Error	Description	Solution
`Invalid time range`	Start time is after end time, or time range exceeds 30 days	Ensure `startTime` < `endTime` and range ≤ 30 days
`Invalid limit`	Limit exceeds maximum	Use limit ≤ 1000
`Invalid offset`	Negative offset value	Use offset ≥ 0
`Invalid symbol`	Market symbol not recognized	Check available markets
`Authentication failed`	Invalid signature	Verify signature generation
`Unauthorized access`	No permission for specified subAccountId	Ensure you have access to the specified subaccount

Rate Limiting

Each request counts as 1 against rate limits
Large queries (high limits) may have higher weight
Consider caching trade history for frequently accessed data
See Rate Limits for details

Next Steps

Place Orders - Create new orders
Cancel Orders - Cancel existing orders
WebSocket Trading - Real-time trade updates