---
title: "GET /private/get_user_trades_by_instrument_and_time"
method: GET
path: "/private/get_user_trades_by_instrument_and_time"
tags: ["Trading", "Private"]
---

# GET /private/get_user_trades_by_instrument_and_time

`GET /private/get_user_trades_by_instrument_and_time`

## Request

- Base URL: `https://test.deribit.com/api/v2`
- URL: `https://test.deribit.com/api/v2/private/get_user_trades_by_instrument_and_time`
- Auth: none declared

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.

Main accounts may use the `subaccount_id` parameter to retrieve trade data for a specific subaccount (requires `mainaccount` scope).

**📖 Related Article:** [Accessing Historical Trades and Orders Using API](https://docs.deribit.com/articles/accessing-historical-trades-orders)

**Scope:** `trade:read`

[Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Fget_user_trades_by_instrument_and_time)

## Query parameters

- `instrument_name` string, required: Unique instrument identifier
- `start_timestamp` integer: The timestamp (milliseconds since the Unix epoch)
- `end_timestamp` integer: The timestamp (milliseconds since the Unix epoch)
- `count` integer
- `sorting` 'asc' | 'desc' | 'default'
- `historical` boolean
- `subaccount_id` integer

## Response `200`

Success response

- PrivateGetUserTradesHistoryResponse
  - `jsonrpc` '2.0', required: The JSON-RPC version (2.0)
  - `id` integer: The id that was sent in the request
  - `result` object, required
    - `trades` UserTrade[], required
      - `trade_id` string, required: Unique (per currency) trade identifier
      - `trade_seq` integer, required: The sequence number of the trade within instrument
      - `instrument_name` string, required: Unique instrument identifier
      - `timestamp` integer, required: The timestamp of the trade (milliseconds since the UNIX epoch)
      - `starbase_timestamp` integer: The Starbase causal timestamp of the trade (nanoseconds since the Unix epoch)
      - `starbase_order_id` integer: Raw Starbase order id of the user's order, in Starbase's own (non currency-prefixed) id namespace (present only for trades matched in Starbase)
      - `starbase_client_order_id` string: Client order id of the user's own order (maker or taker side) submitted directly to [Starbase](https://docs.deribit.com/starbase/overview) via direct access; not returned for orders placed through the Deribit API; for self-trades this is the taker order's client order id
      - `order_type` 'limit' | 'market' | 'liquidation': Order type: `"limit"`, `"market"`, or `"liquidation"`
      - `original_order_type` 'market' | 'market_limit': Original API order type when an order is represented internally as a limit order. For example, Starbase market orders use `"limit"` as `order_type` with `"market"` in this optional field.
      - `advanced` 'usd' | 'implv': Advanced type of user order: `"usd"` or `"implv"` (only for options; omitted if not applicable)
      - `order_id` string, nullable, required: Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
      - `matching_id` string, nullable, required: Matched order id for self-trades; null otherwise.
      - `direction` 'buy' | 'sell', required: Direction: `buy`, or `sell`
      - `tick_direction` 0 | 1 | 2 | 3, required: Direction of the "tick" (`0` = Plus Tick, `1` = Zero-Plus Tick, `2` = Minus Tick, `3` = Zero-Minus Tick).
      - `index_price` number, required: Index Price at the moment of trade
      - `price` number, required: Price in the instrument's price units (quote currency for futures and spot).
      - `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.
      - `contracts` number: Trade size in contract units (optional, may be absent in historical trades)
      - `iv` number: Option implied volatility for the price (Option only)
      - `underlying_price` number: Underlying price for implied volatility calculations (Options only)
      - `liquidation` 'M' | 'T' | 'MT': 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
      - `liquidity` 'M' | 'T': Describes what was role of users order: `"M"` when it was maker order, `"T"` when it was taker order
      - `fee` number, required: User's fee in units of the specified `fee_currency`
      - `fee_currency` 'BTC' | 'ETH' | 'USDC' | 'USDT' | 'EURR', required: Currency, i.e `"BTC"`, `"ETH"`, `"USDC"`
      - `label` string: User defined label (presented only when previously set for order by user)
      - `state` 'open' | 'filled' | 'rejected' | 'cancelled' | 'untriggered' | 'archive', required: Order state: `"open"`, `"filled"`, `"rejected"`, `"cancelled"`, `"untriggered"` or `"archive"` (if order was archived)
      - `block_trade_id` string: Block trade id - when trade was part of a block trade
      - `block_trade_leg_count` integer: Block trade leg count - when trade was part of a block trade
      - `block_rfq_id` integer: ID of the Block RFQ - when trade was part of the Block RFQ
      - `block_rfq_quote_id` integer: ID of the Block RFQ quote - when trade was part of the Block RFQ
      - `reduce_only` boolean: `true` if user order is reduce-only; omitted for spot trades.
      - `post_only` boolean: `true` if user order is post-only
      - `mmp` boolean: `true` if user order is MMP
      - `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)
      - `api` boolean: `true` if user order was created with API
      - `profit_loss` number: Profit and loss in base currency.
      - `mark_price` number, nullable, required: Mark Price at the moment of trade
      - `legs` unknown[]: Optional field containing leg trades if trade is a combo trade (present when querying for **only** combo trades and in `combo_trades` events). Each leg trade has the same fields as a top-level user trade, including `starbase_match_id`, `starbase_order_id`, and `starbase_timestamp` when matched in Starbase, and `starbase_client_order_id` for orders submitted via [Starbase](https://docs.deribit.com/starbase/overview) direct access.
        - unknown
      - `combo_id` string: Optional field containing combo instrument name if the trade is a combo trade
      - `combo_trade_id` string: Optional field containing combo trade identifier if the trade is a combo trade
      - `starbase_match_id` integer: Optional field containing the Starbase match identifier (present only for trades matched via Starbase)
      - `quote_set_id` string: QuoteSet of the user order (optional, present only for orders placed with `private/mass_quote`)
      - `quote_id` string: QuoteID of the user order (optional, present only for orders placed with `private/mass_quote`)
      - `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.
        - `user_id` integer: User ID to which part of the trade is allocated. For brokers the User ID is obstructed.
        - `amount` number, required: Amount allocated to this user.
        - `fee` number, required: Fee for the allocated part of the trade.
        - `client_info` object: Optional client allocation info for brokers.
          - `client_id` integer: ID of a client; available to broker. Represents a group of users under a common name.
          - `client_link_id` integer: ID assigned to a single user in a client; available to broker.
          - `name` string: Name of the linked user within the client; available to broker.
    - `has_more` boolean, required

## Changes

- **2026-10-29** `82518876f388`: 5 breaking, 2 info
  - the response property `result/trades/items/mark_price` became nullable for the status `200`
  - the response property `result/trades/items/matching_id` became nullable for the status `200`
  - the response property `result/trades/items/order_id` became nullable for the status `200`
  - the `result/trades/items/post_only` response's property type changed from `string` to `boolean` for status `200`
  - …3 more
- **2026-08-04** `78a0783dbfcc`: 1 info
  - added the optional property `result/trades/items/starbase_client_order_id` to the response with the `200` status
- **2026-07-31** `bee2616f5f18`: 3 info
  - added the optional property `result/trades/items/block_trade_leg_count` to the response with the `200` status
  - added the optional property `result/trades/items/original_order_type` to the response with the `200` status
  - added the optional property `result/trades/items/starbase_order_id` to the response with the `200` status

[Operation history](https://skmtc.dev/deribit/apis/deribit-api/changes/private/get_user_trades_by_instrument_and_time/get.md)

---

[API](https://skmtc.dev/deribit/apis/deribit-api.md) - [All operations](https://skmtc.dev/deribit/apis/deribit-api/llms.txt) - [OpenAPI document](https://skmtc.dev/deribit/apis/deribit-api/revisions/82518876f388?raw)