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
  }
}
'

import requests

url = "https://test.deribit.com/api/v2/private/get_user_trades_by_instrument_and_time"

payload = {
    "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
    }
}
headers = {"Content-Type": "application/json"}

response = requests.get(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
    }
  })
};

fetch('https://test.deribit.com/api/v2/private/get_user_trades_by_instrument_and_time', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://test.deribit.com/api/v2/private/get_user_trades_by_instrument_and_time",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => json_encode([
    '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
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://test.deribit.com/api/v2/private/get_user_trades_by_instrument_and_time"

	payload := strings.NewReader("{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 276,\n  \"method\": \"private/get_user_trades_by_instrument_and_time\",\n  \"params\": {\n    \"instrument_name\": \"BTC-PERPETUAL\",\n    \"start_timestamp\": 1590470872894,\n    \"end_timestamp\": 1590480872894,\n    \"count\": 2\n  }\n}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://test.deribit.com/api/v2/private/get_user_trades_by_instrument_and_time")
  .header("Content-Type", "application/json")
  .body("{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 276,\n  \"method\": \"private/get_user_trades_by_instrument_and_time\",\n  \"params\": {\n    \"instrument_name\": \"BTC-PERPETUAL\",\n    \"start_timestamp\": 1590470872894,\n    \"end_timestamp\": 1590480872894,\n    \"count\": 2\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://test.deribit.com/api/v2/private/get_user_trades_by_instrument_and_time")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 276,\n  \"method\": \"private/get_user_trades_by_instrument_and_time\",\n  \"params\": {\n    \"instrument_name\": \"BTC-PERPETUAL\",\n    \"start_timestamp\": 1590470872894,\n    \"end_timestamp\": 1590480872894,\n    \"count\": 2\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "jsonrpc": "2.0",
  "id": 276,
  "result": {
    "trades": [
      {
        "trade_seq": 30289127,
        "trade_id": "48078944",
        "timestamp": 1590480866924,
        "tick_direction": 2,
        "state": "filled",
        "reduce_only": false,
        "price": 8988.5,
        "post_only": false,
        "order_type": "limit",
        "order_id": "4008716877",
        "matching_id": null,
        "mark_price": 8990.52,
        "liquidity": "T",
        "instrument_name": "BTC-PERPETUAL",
        "index_price": 8995.15,
        "fee_currency": "BTC",
        "fee": 0.00037465,
        "direction": "sell",
        "amount": 4490
      },
      {
        "trade_seq": 30289128,
        "trade_id": "48078945",
        "timestamp": 1590480866924,
        "tick_direction": 2,
        "state": "filled",
        "reduce_only": false,
        "price": 8983.5,
        "post_only": false,
        "order_type": "limit",
        "order_id": "4008716877",
        "matching_id": null,
        "mark_price": 8990.52,
        "liquidity": "T",
        "instrument_name": "BTC-PERPETUAL",
        "index_price": 8995.15,
        "fee_currency": "BTC",
        "fee": 0.00001503,
        "direction": "sell",
        "amount": 180
      }
    ],
    "has_more": true
  }
}

Trading

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.

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

Scope: trade:read

Try in API console

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
  }
}
'

import requests

url = "https://test.deribit.com/api/v2/private/get_user_trades_by_instrument_and_time"

payload = {
    "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
    }
}
headers = {"Content-Type": "application/json"}

response = requests.get(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
    }
  })
};

fetch('https://test.deribit.com/api/v2/private/get_user_trades_by_instrument_and_time', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://test.deribit.com/api/v2/private/get_user_trades_by_instrument_and_time",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => json_encode([
    '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
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://test.deribit.com/api/v2/private/get_user_trades_by_instrument_and_time"

	payload := strings.NewReader("{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 276,\n  \"method\": \"private/get_user_trades_by_instrument_and_time\",\n  \"params\": {\n    \"instrument_name\": \"BTC-PERPETUAL\",\n    \"start_timestamp\": 1590470872894,\n    \"end_timestamp\": 1590480872894,\n    \"count\": 2\n  }\n}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://test.deribit.com/api/v2/private/get_user_trades_by_instrument_and_time")
  .header("Content-Type", "application/json")
  .body("{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 276,\n  \"method\": \"private/get_user_trades_by_instrument_and_time\",\n  \"params\": {\n    \"instrument_name\": \"BTC-PERPETUAL\",\n    \"start_timestamp\": 1590470872894,\n    \"end_timestamp\": 1590480872894,\n    \"count\": 2\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://test.deribit.com/api/v2/private/get_user_trades_by_instrument_and_time")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 276,\n  \"method\": \"private/get_user_trades_by_instrument_and_time\",\n  \"params\": {\n    \"instrument_name\": \"BTC-PERPETUAL\",\n    \"start_timestamp\": 1590470872894,\n    \"end_timestamp\": 1590480872894,\n    \"count\": 2\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "jsonrpc": "2.0",
  "id": 276,
  "result": {
    "trades": [
      {
        "trade_seq": 30289127,
        "trade_id": "48078944",
        "timestamp": 1590480866924,
        "tick_direction": 2,
        "state": "filled",
        "reduce_only": false,
        "price": 8988.5,
        "post_only": false,
        "order_type": "limit",
        "order_id": "4008716877",
        "matching_id": null,
        "mark_price": 8990.52,
        "liquidity": "T",
        "instrument_name": "BTC-PERPETUAL",
        "index_price": 8995.15,
        "fee_currency": "BTC",
        "fee": 0.00037465,
        "direction": "sell",
        "amount": 4490
      },
      {
        "trade_seq": 30289128,
        "trade_id": "48078945",
        "timestamp": 1590480866924,
        "tick_direction": 2,
        "state": "filled",
        "reduce_only": false,
        "price": 8983.5,
        "post_only": false,
        "order_type": "limit",
        "order_id": "4008716877",
        "matching_id": null,
        "mark_price": 8990.52,
        "liquidity": "T",
        "instrument_name": "BTC-PERPETUAL",
        "index_price": 8995.15,
        "fee_currency": "BTC",
        "fee": 0.00001503,
        "direction": "sell",
        "amount": 180
      }
    ],
    "has_more": true
  }
}

Query Parameters

instrument_name

string

required

Instrument name Unique instrument identifier

Example:

"BTC-PERPETUAL"

start_timestamp

integer

Inclusive earliest timestamp (milliseconds since the Unix epoch). Time-based methods require at least one of start_timestamp or end_timestamp. The timestamp (milliseconds since the Unix epoch)

Example:

1536569522277

end_timestamp

integer

Inclusive latest timestamp (milliseconds since the Unix epoch). Time-based methods require at least one of start_timestamp or end_timestamp. 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>

Result ordering: asc, desc, or the method-specific default.

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

subaccount_id

integer

Id of a subaccount

Example:

9

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 | null

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 | null

required

Matched order id for self-trades; null otherwise.

result.trades.direction

enum<string>

required

Trade direction of the user

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 | null

required

Mark Price at the moment of trade

result.trades.starbase_timestamp

integer

Optional field: the Starbase causal timestamp of the trade, in nanoseconds since the UNIX epoch (present only for trades matched in Starbase)

Example:

1536569522277000000

result.trades.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)

Example:

103148386170

result.trades.starbase_client_order_id

string

Client order id of the user's own order (maker or taker side) submitted directly to Starbase via direct access; not returned for orders placed through the Deribit API; for self-trades this is the taker order's client order id

result.trades.order_type

enum<string>

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

Available options:

limit,

market,

liquidation

result.trades.original_order_type

enum<string>

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.

Available options:

market,

market_limit

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_trade_leg_count

integer

Block trade leg count - when trade was part of a block trade

Example:

3

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

boolean

true if user order is reduce-only; omitted for spot trades.

result.trades.post_only

boolean

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). 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 direct access.

result.trades.combo_id

string

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

result.trades.combo_trade_id

string

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

result.trades.starbase_match_id

integer

Optional field containing the Starbase match identifier (present only for trades matched via Starbase)

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

integer

The id that was sent in the request

Methods overview

Methods

private/get_user_trades_by_instrument_and_time

Query Parameters

Response