> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cdp.coinbase.com/llms.txt
> Use this file to discover all available pages before exploring further.
# private/get_user_trades_by_currency_and_time
> Retrieves the latest user trades that have occurred for instruments in a specific currency within a specified time range. Returns trade details including price, amount, direction, timestamp, trade ID, and order ID for all instruments in the currency.
Results can be filtered by instrument kind. Use the `count` parameter to limit the number of trades returned, and `sorting` to control the order. Use `historical` to retrieve historical trade data. This method is useful for analyzing trading activity across a currency 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:** `rat#view` or `wallet:transactions:read`
[Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Fget_user_trades_by_currency_and_time)
## OpenAPI
````yaml /api-reference/coinbase-deribit-app-api/adv-starbase-openapi.json get /private/get_user_trades_by_currency_and_time
openapi: 3.0.0
info:
description: Coinbase Retail Advanced Trade API for derivatives trading.
title: Coinbase Retail Advanced Trade (Deribit) API
version: 2.1.1
servers:
- url: https://drb.coinbase.com/api/v2
security: []
tags:
- description: Can only be used over websockets.
name: WebSocket Only
- description: Public methods can be used without authentication.
name: Public
- description: >-
Private methods require authentication. All requests must include a
valid OAuth2 token.
A token can be requested using the /public/auth method.
When using the websockets protocol, the token must be included as a
parameter access_token in the message. When using REST (HTTP
GET), the token may also be passed in the Authorization
header.
name: Private
- name: Authentication
- name: Session Management
- description: >-
Subscription works as [notifications](#notifications), so users will
automatically (after subscribing) receive messages from the server.
Overview for each channel response format is described in
[subscriptions](#subscriptions) section.
name: Subscription Management
- name: Account Management
- name: Trading
- name: Market Data
paths:
/private/get_user_trades_by_currency_and_time:
get:
tags:
- Trading
- Private
description: >+
Retrieves the latest user trades that have occurred for instruments in a
specific currency within a specified time range. Returns trade details
including price, amount, direction, timestamp, trade ID, and order ID
for all instruments in the currency.
Results can be filtered by instrument kind. Use the `count` parameter to
limit the number of trades returned, and `sorting` to control the order.
Use `historical` to retrieve historical trade data. This method is
useful for analyzing trading activity across a currency 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:** `rat#view` or `wallet:transactions:read`
[Try in API
console](https://test.deribit.com/api_console?method=%2Fprivate%2Fget_user_trades_by_currency_and_time)
parameters:
- description: The currency symbol
in: query
name: currency
required: true
schema:
$ref: '#/components/schemas/currency'
- description: >-
Instrument kind, `"combo"` for any combo or `"any"` for all. If not
provided instruments of all kinds are considered
in: query
name: kind
required: false
schema:
$ref: '#/components/schemas/kind_with_combo_all'
- description: >-
The earliest timestamp to return result from (milliseconds since the
UNIX epoch). When param is provided trades are returned from the
earliest
in: query
name: start_timestamp
required: true
schema:
$ref: '#/components/schemas/timestamp'
- description: >-
The most recent timestamp to return result from (milliseconds since
the UNIX epoch). Only one of params: start_timestamp, end_timestamp
is truly required
in: query
name: end_timestamp
required: true
schema:
$ref: '#/components/schemas/timestamp'
- description: Number of requested items, default - `10`, maximum - `1000`
in: query
name: count
required: false
schema:
maximum: 1000
minimum: 1
type: integer
- description: >-
Direction of results sorting (`default` value means no sorting,
results will be returned in order in which they left the database)
in: query
name: sorting
required: false
schema:
$ref: '#/components/schemas/sorting'
- description: >
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](https://docs.deribit.com/articles/accessing-historical-trades-orders)
in: query
name: historical
required: false
schema:
type: boolean
- description: Id of a subaccount
in: query
name: subaccount_id
required: false
schema:
example: 9
type: integer
requestBody:
content:
application/json:
examples:
request:
description: JSON-RPC Request Example
value:
id: 9292
jsonrpc: '2.0'
method: private/get_user_trades_by_currency_and_time
params:
count: 2
currency: BTC
end_timestamp: 1510480630731
start_timestamp: 1590480630731
description: JSON-RPC request body
responses:
'200':
$ref: '#/components/responses/PrivateGetUserTradesHistoryResponse'
components:
schemas:
currency:
description: Currency, i.e `"BTC"`, `"ETH"`, `"USDC"`
enum:
- BTC
- ETH
- USDC
- USDT
- EURR
type: string
kind_with_combo_all:
description: >-
Instrument kind: `"future"`, `"option"`, `"spot"`, `"future_combo"`,
`"option_combo"`, `"combo"` for any combo or `"any"` for all
enum:
- future
- option
- spot
- future_combo
- option_combo
- combo
- any
type: string
timestamp:
description: The timestamp (milliseconds since the Unix epoch)
example: 1536569522277
type: integer
sorting:
enum:
- asc
- desc
- default
type: string
PrivateGetUserTradesHistoryResponse:
properties:
id:
description: The id that was sent in the request
type: integer
jsonrpc:
description: The JSON-RPC version (2.0)
enum:
- '2.0'
type: string
result:
properties:
has_more:
type: boolean
trades:
items:
$ref: '#/components/schemas/user_trade'
type: array
required:
- trades
- has_more
type: object
required:
- jsonrpc
- result
type: object
user_trade:
properties:
advanced:
description: >-
Advanced type of user order: `"usd"` or `"implv"` (only for options;
omitted if not applicable)
enum:
- usd
- implv
type: string
amount:
description: >-
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.
type: number
api:
description: '`true` if user order was created with API'
type: boolean
block_rfq_id:
description: ID of the Block RFQ - when trade was part of the Block RFQ
type: integer
block_rfq_quote_id:
description: ID of the Block RFQ quote - when trade was part of the Block RFQ
type: integer
block_trade_id:
$ref: '#/components/schemas/block_trade_id_in_result'
combo_id:
description: >-
Optional field containing combo instrument name if the trade is a
combo trade
type: string
combo_trade_id:
description: >-
Optional field containing combo trade identifier if the trade is a
combo trade
type: number
contracts:
description: >-
Trade size in contract units (optional, may be absent in historical
trades)
type: number
direction:
$ref: '#/components/schemas/direction'
description: Trade direction of the taker
fee:
description: User's fee in units of the specified `fee_currency`
type: number
fee_currency:
$ref: '#/components/schemas/currency'
index_price:
description: Index Price at the moment of trade
type: number
instrument_name:
$ref: '#/components/schemas/instrument_name'
iv:
description: Option implied volatility for the price (Option only)
type: number
label:
$ref: '#/components/schemas/label_presentation'
legs:
description: >-
Optional field containing leg trades if trade is a combo trade
(present when querying for **only** combo trades and in
`combo_trades` events)
type: array
liquidation:
description: >-
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
enum:
- M
- T
- MT
type: string
liquidity:
description: >-
Describes what was role of users order: `"M"` when it was maker
order, `"T"` when it was taker order
enum:
- M
- T
type: string
mark_price:
description: Mark Price at the moment of trade
type: number
matching_id:
description: Always `null`
type: string
mmp:
description: '`true` if user order is MMP'
type: boolean
order_id:
description: >-
Id of the user order (maker or taker), i.e. subscriber's order id
that took part in the trade
type: string
order_type:
description: 'Order type: `"limit`, `"market"`, or `"liquidation"`'
enum:
- limit
- market
- liquidation
type: string
post_only:
description: '`true` if user order is post-only'
type: string
price:
$ref: '#/components/schemas/price'
description: The price of the trade
profit_loss:
$ref: '#/components/schemas/profit_loss'
quote_id:
description: >-
QuoteID of the user order (optional, present only for orders placed
with `private/mass_quote`)
type: string
quote_set_id:
description: >-
QuoteSet of the user order (optional, present only for orders placed
with `private/mass_quote`)
type: string
reduce_only:
description: '`true` if user order is reduce-only'
type: string
risk_reducing:
description: >-
`true` if user order is marked by the platform as a risk reducing
order (can apply only to orders placed by PM users)
type: boolean
state:
$ref: '#/components/schemas/order_state_in_user_trade'
tick_direction:
$ref: '#/components/schemas/tick_direction'
timestamp:
$ref: '#/components/schemas/trade_timestamp'
trade_allocations:
description: >-
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.
items:
properties:
amount:
description: Amount allocated to this user.
type: number
client_info:
description: Optional client allocation info for brokers.
properties:
client_id:
description: >-
ID of a client; available to broker. Represents a group of
users under a common name.
type: integer
client_link_id:
description: >-
ID assigned to a single user in a client; available to
broker.
type: integer
name:
description: >-
Name of the linked user within the client; available to
broker.
type: string
type: object
fee:
description: Fee for the allocated part of the trade.
type: number
user_id:
description: >-
User ID to which part of the trade is allocated. For brokers
the User ID is obstructed.
type: integer
required:
- amount
- fee
type: object
type: array
trade_id:
$ref: '#/components/schemas/trade_id'
trade_seq:
$ref: '#/components/schemas/trade_seq'
underlying_price:
description: Underlying price for implied volatility calculations (Options only)
type: number
required:
- trade_id
- trade_seq
- instrument_name
- timestamp
- order_id
- matching_id
- direction
- tick_direction
- index_price
- price
- amount
- fee
- fee_currency
- state
- mark_price
type: object
block_trade_id_in_result:
description: Block trade id - when trade was part of a block trade
example: '154'
type: string
direction:
description: 'Direction: `buy`, or `sell`'
enum:
- buy
- sell
type: string
instrument_name:
description: Unique instrument identifier
example: BTC-PERPETUAL
type: string
label_presentation:
description: >-
User defined label (presented only when previously set for order by
user)
type: string
price:
description: Price in base currency
type: number
profit_loss:
description: Profit and loss in base currency.
type: number
order_state_in_user_trade:
description: >-
Order state: `"open"`, `"filled"`, `"rejected"`, `"cancelled"`,
`"untriggered"` or `"archive"` (if order was archived)
enum:
- open
- filled
- rejected
- cancelled
- untriggered
- archive
type: string
tick_direction:
description: >-
Direction of the "tick" (`0` = Plus Tick, `1` = Zero-Plus Tick, `2` =
Minus Tick, `3` = Zero-Minus Tick).
enum:
- 0
- 1
- 2
- 3
type: integer
trade_timestamp:
description: The timestamp of the trade (milliseconds since the UNIX epoch)
example: 1517329113791
type: integer
trade_id:
description: Unique (per currency) trade identifier
type: string
trade_seq:
description: The sequence number of the trade within instrument
type: integer
responses:
PrivateGetUserTradesHistoryResponse:
content:
application/json:
examples:
response:
description: Response example
value:
id: 9292
jsonrpc: '2.0'
result:
has_more: false
trades:
- amount: 1
direction: sell
fee: 0.0004
fee_currency: BTC
index_price: 8993.47
instrument_name: BTC-27MAY20-8750-C
iv: 38.51
liquidity: M
mark_price: 0.03135383
matching_id: null
order_id: '4008699030'
order_type: limit
post_only: false
price: 0.028
reduce_only: false
state: filled
tick_direction: 1
timestamp: 1590480620145
trade_id: '48078936'
trade_seq: 1
underlying_price: 8994.95
- amount: 10
direction: buy
fee: -2.1e-7
fee_currency: BTC
index_price: 9679.48
instrument_name: BTC-26JUN20
liquidity: M
mark_price: 9684
matching_id: null
order_id: '3993343822'
order_type: limit
post_only: false
price: 9681.5
reduce_only: false
state: filled
tick_direction: 2
timestamp: 1589923311862
trade_id: '47958936'
trade_seq: 299513
schema:
$ref: '#/components/schemas/PrivateGetUserTradesHistoryResponse'
description: Success response
````