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.
Instrument type
type: DATED_FUTURE (with contract_expiry_date and contract_duration), EQUITY_FUTURE, or PERP. Dated futures positions opened before 2026-04-23T11:00:00Z are reported as PERP.from/to accept epoch (s, ms, µs or ns) or an ISO 8601 UTC timestamp ending in Z (or YYYY-MM-DD). from must be on or after 2024-01-01, not in the future, and strictly before to; to is exclusive.cursor is an opaque string. Pass the value from the previous response unchanged; it is null (or absent) on the last page. If a position's statistics cannot be computed it is omitted, so a page can contain fewer than limit positions while cursor is not null.400 UNEXPECTED_PARAMETERS.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), 1695647130123456789 (ns) | |
| 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), 1695734400456789012 (ns) | |
| 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 | eyJlcG9jaCI6IjE3NjgzMTczNzUxMjA2MDM0ODQiLCJjcW8iOiIyMTA5NjgzNjQxNTIyNTc2In0= |
Parameter Constraints
| Parameter | Constraints |
|---|---|
from | Must be between 2024-01-01 and present |
to | Must be strictly after from; the period between from and to must not exceed 31 days |
limit | Integer between 1 and 10 |
order | DESC or ASC |
instrument_code | Optional; must be valid futures market code(s) |
cursor | Optional; string returned by previous response |
Parameter Defaults
| Parameter(s) | Default Behaviour |
|---|---|
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 = midnight UTC, 7 days earlier |
instrument_code | Defaults to all futures markets |
limit | Defaults to 5 |
order | Defaults to DESC |
Request
Query Params
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.onetrading.com/fast/v1/account/futures/positions-history?from=2026-01-02&to=2026-02-01&instrument_code=&limit=10&cursor=eyJlcG9jaCI6IjE3NjgzMTczNzUxMjA2MDM0ODQiLCJjcW8iOiIyMTA5NjgzNjQxNTIyNTc2In0%3D&order=DESC' \
--header 'Authorization: Bearer <token>'Response Response Example
200 - Success Example
{
"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.01",
"total_entry_amount": "0.01",
"total_exit_amount": "0.01",
"entry_trade_count": 1,
"exit_trade_count": 2,
"average_entry_price": "89075.95",
"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",
"funding_payment_count": 93,
"total_funding_payments": "0.4255",
"has_liquidation_events": false,
"type": "PERP"
},
{
"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.2",
"total_entry_amount": "0.2",
"total_exit_amount": "0.2",
"entry_trade_count": 1,
"exit_trade_count": 1,
"average_entry_price": "92432.75",
"average_exit_price": "92479.01",
"entry_notional": "18486.55",
"exit_notional": "18495.802",
"closing_pnl": "-9.252",
"realised_pnl": "-9.2536",
"total_trade_fees": "0",
"funding_payment_count": 0,
"total_funding_payments": "0",
"has_liquidation_events": false,
"type": "PERP"
}
],
"from": "2026-01-01T00:00:00.000000000Z",
"to": "2026-02-01T00:00:00.000000000Z",
"cursor": "eyJlcG9jaCI6IjE3NjgzMTczNzUxMjA2MDM0ODQiLCJjcW8iOiIyMTA5NjgzNjQxNTIyNTc2In0="
}