private/get_user_trades_by_instrument_and_time

Retrieves the latest user trades that have occurred for a specific instrument within a specified time range. Returns trade details including price, amount, direction, timestamp, trade ID, and order ID.

Use the count parameter to limit the number of trades returned, and sorting to control the order (ascending or descending by trade ID). Use historical to retrieve historical trade data. This method is useful for analyzing trading activity over specific time periods.

📖 Related Article: Accessing Historical Trades and Orders Using API

Scope: trade:read

Try in API console

cURL

cURL

curl --request GET \
  --url https://test.deribit.com/api/v2/private/get_user_trades_by_instrument_and_time \
  --header 'Content-Type: application/json' \
  --data '
{
  "jsonrpc": "2.0",
  "id": 276,
  "method": "private/get_user_trades_by_instrument_and_time",
  "params": {
    "instrument_name": "BTC-PERPETUAL",
    "start_timestamp": 1590470872894,
    "end_timestamp": 1590480872894,
    "count": 2
  }
}
'

200

{
  "jsonrpc": "2.0",
  "id": 9292,
  "result": {
    "trades": [
      {
        "underlying_price": 8994.95,
        "trade_seq": 1,
        "trade_id": "48078936",
        "timestamp": 1590480620145,
        "tick_direction": 1,
        "state": "filled",
        "reduce_only": false,
        "price": 0.028,
        "post_only": false,
        "order_type": "limit",
        "order_id": "4008699030",
        "matching_id": null,
        "mark_price": 0.03135383,
        "liquidity": "M",
        "iv": 38.51,
        "instrument_name": "BTC-27MAY20-8750-C",
        "index_price": 8993.47,
        "fee_currency": "BTC",
        "fee": 0.0004,
        "direction": "sell",
        "amount": 1
      },
      {
        "trade_seq": 299513,
        "trade_id": "47958936",
        "timestamp": 1589923311862,
        "tick_direction": 2,
        "state": "filled",
        "reduce_only": false,
        "price": 9681.5,
        "post_only": false,
        "order_type": "limit",
        "order_id": "3993343822",
        "matching_id": null,
        "mark_price": 9684,
        "liquidity": "M",
        "instrument_name": "BTC-26JUN20",
        "index_price": 9679.48,
        "fee_currency": "BTC",
        "fee": -2.1e-7,
        "direction": "buy",
        "amount": 10
      }
    ],
    "has_more": false
  }
}

Query Parameters

instrument_name · string · required

Instrument name Unique instrument identifier

Example:

"BTC-PERPETUAL"

start_timestamp · integer · required

The earliest timestamp to return result from (milliseconds since the UNIX epoch). When param is provided trades are returned from the earliest The timestamp (milliseconds since the Unix epoch)

Example:

1536569522277

end_timestamp · integer · required

The most recent timestamp to return result from (milliseconds since the UNIX epoch). Only one of params: start_timestamp, end_timestamp is truly required The timestamp (milliseconds since the Unix epoch)

Example:

1536569522277

count · integer

Number of requested items, default - 10, maximum - 1000

Required range: 1 <= x <= 1000

sorting · enum<string>

Direction of results sorting (default value means no sorting, results will be returned in order in which they left the database)

Available options: asc, desc, default

historical · boolean

Determines whether historical trade and order records should be retrieved.

• false (default): Returns recent records: orders for 30 min, trades for 24h.
• true: Fetches historical records, available after a short delay due to indexing. Recent data is not included.

📖 Related Article: Accessing Historical Trades and Orders Using API

Response

200 - application/json

Success response

jsonrpc · enum<string> · required

The JSON-RPC version (2.0)

Available options: 2.0

result · object · required

Hide child attributes

result. trades · object[] · required

Hide child attributes

result.trades. trade_id · string · required

Unique (per currency) trade identifier

result.trades. trade_seq · integer · required

The sequence number of the trade within instrument

result.trades. instrument_name · string · required

Unique instrument identifier

Example:

"BTC-PERPETUAL"

result.trades. timestamp · integer · required

The timestamp of the trade (milliseconds since the UNIX epoch)

Example:

1517329113791

result.trades. order_id · string · required

Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade

result.trades. matching_id · string · required

Always null

result.trades. direction · enum<string> · required

Trade direction of the taker

Available options: buy, sell

result.trades. tick_direction · enum<integer> · required

Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).

Available options: 0, 1, 2, 3

result.trades. index_price · number · required

Index Price at the moment of trade

result.trades. price · number · required

The price of the trade

result.trades. amount · number · required

Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.

result.trades. fee · number · required

User's fee in units of the specified fee_currency

result.trades. fee_currency · enum<string> · required

Currency, i.e "BTC", "ETH", "USDC"

Available options: BTC, ETH, USDC, USDT, EURR

result.trades. state · enum<string> · required

Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)

Available options: open, filled, rejected, cancelled, untriggered, archive

result.trades. mark_price · number · required

Mark Price at the moment of trade

result.trades. order_type · enum<string>

Order type: "limit, "market", or "liquidation"

Available options: limit, market, liquidation

result.trades. advanced · enum<string>

Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)

Available options: usd, implv

result.trades. contracts · number

Trade size in contract units (optional, may be absent in historical trades)

result.trades. iv · number

Option implied volatility for the price (Option only)

result.trades. underlying_price · number

Underlying price for implied volatility calculations (Options only)

result.trades. liquidation · enum<string>

Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation

Available options: M, T, MT

result.trades. liquidity · enum<string>

Describes what was role of users order: "M" when it was maker order, "T" when it was taker order

Available options: M, T

result.trades. label · string

User defined label (presented only when previously set for order by user)

result.trades. block_trade_id · string

Block trade id - when trade was part of a block trade

Example:

"154"

result.trades. block_rfq_id · integer

ID of the Block RFQ - when trade was part of the Block RFQ

result.trades. block_rfq_quote_id · integer

ID of the Block RFQ quote - when trade was part of the Block RFQ

result.trades. reduce_only · string

true if user order is reduce-only

result.trades. post_only · string

true if user order is post-only

result.trades. mmp · boolean

true if user order is MMP

result.trades. risk_reducing · boolean

true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)

result.trades. api · boolean

true if user order was created with API

result.trades. profit_loss · number

Profit and loss in base currency.

result.trades. legs · array

Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

result.trades. combo_id · string

Optional field containing combo instrument name if the trade is a combo trade

result.trades. combo_trade_id · number

Optional field containing combo trade identifier if the trade is a combo trade

result.trades. quote_set_id · string

QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)

result.trades. quote_id · string

QuoteID of the user order (optional, present only for orders placed with private/mass_quote)

result.trades. trade_allocations · object[]

List of allocations for Block RFQ pre-allocation. Each allocation specifies user_id, amount, and fee for the allocated part of the trade. For broker client allocations, a client_info object will be included.

Hide child attributes

result.trades.trade_allocations. amount · number · required

Amount allocated to this user.

result.trades.trade_allocations. fee · number · required

Fee for the allocated part of the trade.

result.trades.trade_allocations. user_id · integer

User ID to which part of the trade is allocated. For brokers the User ID is obstructed.

result.trades.trade_allocations. client_info · object

Optional client allocation info for brokers.

Hide child attributes

result.trades.trade_allocations.client_info. client_id · integer

ID of a client; available to broker. Represents a group of users under a common name.

result.trades.trade_allocations.client_info. client_link_id · integer

ID assigned to a single user in a client; available to broker.

result.trades.trade_allocations.client_info. name · string

Name of the linked user within the client; available to broker.

result. has_more · boolean · required

id · integer

The id that was sent in the request