Positions
Developing
GET
https://api.onetrading.com/fast/v1/account/futures/positions-history
P&L Calculation
closing_pnl = profit or loss from all exit trades, based on notional values (exclusive of fees and funding payments)realised_pnl = closing_pnl + total_funding_payments − total_trade_feesNote: Liquidation fees are calculated at account level and are therefore not linked to individual positions.
Parameter Specification
| Parameter | Accepted Formats | Example Values |
|---|---|---|
from | ISO 8601 | 2025-09-25T13:45:30Z (s), 2025-09-25T13:45:30.123Z (ms), 2025-09-25T13:45:30.123456Z (us) |
| Epoch | 1695647130 (s), 1695647130123 (ms), 1695647130123456 (us) | |
| Date | 2025-09-25 | |
to | ISO 8601 | 2025-09-26T18:00:00Z (s), 2025-09-26T18:00:00.456Z (ms), 2025-09-26T18:00:00.456789Z (us) |
| Epoch | 1695734400 (s), 1695734400456 (ms), 1695734400456789 (us) | |
| Date | 2025-09-26 | |
instrument_code | String | BTC_USD_P (single) |
| List | BTC_USD_P,ETH_USD_P (comma-separated list) | |
order | String | DESC or ASC |
limit | Integer | 3 |
cursor | String | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... |
Parameter Constraints
| Parameter | Constraints |
|---|---|
from | Must be between 2024-01-01 and present |
to | Must not be earlier than from |
limit | Integer between 1 and 10 |
order | DESC or ASC |
instrument_code | Optional; must be valid market code(s) |
cursor | Optional; string returned by previous response |
Parameter Defaults
| Parameter(s) | Default Behavior |
|---|---|
from / to | Neither provided: from = 7 days ago at midnight UTC, to = present time |
from / to | Only from provided: to = 7 days later or present time, whichever is smaller |
from / to | Only to provided: from = 7 days earlier |
instrument_code | Defaults to all perpetual markets |
limit | Defaults to 5 |
Request
Query Params
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request GET 'https://api.onetrading.com/fast/v1/account/futures/positions-history?from=2026-01-02&to=2026-02-01&instrument_code=&limit=10&cursor=eyJlcG9jaCI6IjE3NjgzMTczNzUxMjA2MDM0ODQiLCJjcW8iOiIyMTA5NjgzNjQxNTIyNTc2In0' \
--header 'Authorization: Bearer <token>'Response Response Example
200 - Example 1
{
"positions": [
{
"account_id": "aaaba8bd-3195-4f72-87ff-98720a940f23",
"position_id": "2111199765938682",
"instrument_code": "BTC_USD_P",
"is_open": false,
"open_timestamp": "2026-01-28T08:19:25.380629346Z",
"close_timestamp": "2026-02-13T10:27:14.886985638Z",
"direction": "LONG",
"max_position_amount": "0.01000",
"total_entry_amount": "0.01000",
"total_exit_amount": "0.01000",
"entry_trade_count": 1,
"exit_trade_count": 2,
"average_entry_price": "89075.950",
"average_exit_price": "69107.489",
"entry_notional": "890.7595",
"exit_notional": "691.0749",
"closing_pnl": "-199.6846",
"realised_pnl": "-198.8334",
"total_trade_fees": "0.0000",
"funding_payment_count": 93,
"total_funding_payments": "0.4255",
"has_liquidation_events": false
},
{
"account_id": "aaaba8bd-3195-4f72-87ff-98720a940f23",
"position_id": "2109683641526368",
"instrument_code": "BTC_USD_P",
"is_open": false,
"open_timestamp": "2026-01-13T15:16:26.038074298Z",
"close_timestamp": "2026-01-13T15:16:36.081981640Z",
"direction": "SHORT",
"max_position_amount": "0.20000",
"total_entry_amount": "0.20000",
"total_exit_amount": "0.20000",
"entry_trade_count": 1,
"exit_trade_count": 1,
"average_entry_price": "92432.750",
"average_exit_price": "92479.010",
"entry_notional": "18486.5500",
"exit_notional": "18495.8020",
"closing_pnl": "-9.2520",
"realised_pnl": "-9.2536",
"total_trade_fees": "0.0000",
"funding_payment_count": 0,
"total_funding_payments": "0.0000",
"has_liquidation_events": false
}
],
"from": "2026-01-01T00:00:00.000000000Z",
"to": "2026-02-01T00:00:00.000000000Z",
"cursor": "eyJlcG9jaCI6IjE3NjgzMTczNzUxMjA2MDM0ODQiLCJjcW8iOiIyMTA5NjgzNjQxNTIyNTc2In0="
}