curl --request POST \
--url https://whitebit.com/api/v4/collateral-account/positions/history \
--header 'Content-Type: application/json' \
--header 'X-TXC-APIKEY: <api-key>' \
--header 'X-TXC-PAYLOAD: <api-key>' \
--header 'X-TXC-SIGNATURE: <api-key>' \
--data '
{
"market": "BTC_USDT",
"positionId": 1,
"request": "{{request}}",
"nonce": 1594297865000
}
'import requests
url = "https://whitebit.com/api/v4/collateral-account/positions/history"
payload = {
"market": "BTC_USDT",
"positionId": 1,
"request": "{{request}}",
"nonce": 1594297865000
}
headers = {
"X-TXC-APIKEY": "<api-key>",
"X-TXC-PAYLOAD": "<api-key>",
"X-TXC-SIGNATURE": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-TXC-APIKEY': '<api-key>',
'X-TXC-PAYLOAD': '<api-key>',
'X-TXC-SIGNATURE': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
market: 'BTC_USDT',
positionId: 1,
request: '{{request}}',
nonce: 1594297865000
})
};
fetch('https://whitebit.com/api/v4/collateral-account/positions/history', 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://whitebit.com/api/v4/collateral-account/positions/history",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'market' => 'BTC_USDT',
'positionId' => 1,
'request' => '{{request}}',
'nonce' => 1594297865000
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-TXC-APIKEY: <api-key>",
"X-TXC-PAYLOAD: <api-key>",
"X-TXC-SIGNATURE: <api-key>"
],
]);
$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://whitebit.com/api/v4/collateral-account/positions/history"
payload := strings.NewReader("{\n \"market\": \"BTC_USDT\",\n \"positionId\": 1,\n \"request\": \"{{request}}\",\n \"nonce\": 1594297865000\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-TXC-APIKEY", "<api-key>")
req.Header.Add("X-TXC-PAYLOAD", "<api-key>")
req.Header.Add("X-TXC-SIGNATURE", "<api-key>")
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.post("https://whitebit.com/api/v4/collateral-account/positions/history")
.header("X-TXC-APIKEY", "<api-key>")
.header("X-TXC-PAYLOAD", "<api-key>")
.header("X-TXC-SIGNATURE", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"market\": \"BTC_USDT\",\n \"positionId\": 1,\n \"request\": \"{{request}}\",\n \"nonce\": 1594297865000\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://whitebit.com/api/v4/collateral-account/positions/history")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-TXC-APIKEY"] = '<api-key>'
request["X-TXC-PAYLOAD"] = '<api-key>'
request["X-TXC-SIGNATURE"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"market\": \"BTC_USDT\",\n \"positionId\": 1,\n \"request\": \"{{request}}\",\n \"nonce\": 1594297865000\n}"
response = http.request(request)
puts response.read_body[
{
"positionId": 111,
"market": "BTC_USDT",
"openDate": 1650400589.882613,
"modifyDate": 1650400589.882613,
"amount": "0.1",
"basePrice": "45658.349",
"realizedFunding": "0",
"liquidationPrice": null,
"liquidationState": "margin_call",
"orderDetail": {
"id": 97067934,
"tradeAmount": "0.1",
"price": "41507.59",
"tradeFee": "415.07",
"fundingFee": null,
"realizedPnl": null
},
"side": "LONG",
"isHedge": false
}
]{
"code": 30,
"message": "Validation failed",
"errors": {}
}{
"code": 30,
"message": "Validation failed",
"errors": {}
}Positions history
The endpoint returns the history of collateral position state changes for the authenticated account. Each record represents a position event (open, partial close, full close, or liquidation) and includes the order details that triggered the change. Use the optional market and positionId parameters to filter results.
Rate limit: 12000 requests/10 sec.
Date filter window: startDate and endDate are optional and have no defaults. The endpoint enforces no maximum window and no lower-bound floor. The only ordering constraint is startDate ≤ endDate ≤ now + 1s — requests that violate the ordering are rejected with a validation error.
Breaking change — April 29, 2026. The positionSide field is no longer returned in the Position History response. Use side (same enum: LONG, SHORT, BOTH) plus isHedge (boolean) instead. Integrations reading positionSide from /api/v4/collateral-account/positions/history must migrate before consuming the new response.
curl --request POST \
--url https://whitebit.com/api/v4/collateral-account/positions/history \
--header 'Content-Type: application/json' \
--header 'X-TXC-APIKEY: <api-key>' \
--header 'X-TXC-PAYLOAD: <api-key>' \
--header 'X-TXC-SIGNATURE: <api-key>' \
--data '
{
"market": "BTC_USDT",
"positionId": 1,
"request": "{{request}}",
"nonce": 1594297865000
}
'import requests
url = "https://whitebit.com/api/v4/collateral-account/positions/history"
payload = {
"market": "BTC_USDT",
"positionId": 1,
"request": "{{request}}",
"nonce": 1594297865000
}
headers = {
"X-TXC-APIKEY": "<api-key>",
"X-TXC-PAYLOAD": "<api-key>",
"X-TXC-SIGNATURE": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-TXC-APIKEY': '<api-key>',
'X-TXC-PAYLOAD': '<api-key>',
'X-TXC-SIGNATURE': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
market: 'BTC_USDT',
positionId: 1,
request: '{{request}}',
nonce: 1594297865000
})
};
fetch('https://whitebit.com/api/v4/collateral-account/positions/history', 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://whitebit.com/api/v4/collateral-account/positions/history",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'market' => 'BTC_USDT',
'positionId' => 1,
'request' => '{{request}}',
'nonce' => 1594297865000
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-TXC-APIKEY: <api-key>",
"X-TXC-PAYLOAD: <api-key>",
"X-TXC-SIGNATURE: <api-key>"
],
]);
$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://whitebit.com/api/v4/collateral-account/positions/history"
payload := strings.NewReader("{\n \"market\": \"BTC_USDT\",\n \"positionId\": 1,\n \"request\": \"{{request}}\",\n \"nonce\": 1594297865000\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-TXC-APIKEY", "<api-key>")
req.Header.Add("X-TXC-PAYLOAD", "<api-key>")
req.Header.Add("X-TXC-SIGNATURE", "<api-key>")
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.post("https://whitebit.com/api/v4/collateral-account/positions/history")
.header("X-TXC-APIKEY", "<api-key>")
.header("X-TXC-PAYLOAD", "<api-key>")
.header("X-TXC-SIGNATURE", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"market\": \"BTC_USDT\",\n \"positionId\": 1,\n \"request\": \"{{request}}\",\n \"nonce\": 1594297865000\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://whitebit.com/api/v4/collateral-account/positions/history")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-TXC-APIKEY"] = '<api-key>'
request["X-TXC-PAYLOAD"] = '<api-key>'
request["X-TXC-SIGNATURE"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"market\": \"BTC_USDT\",\n \"positionId\": 1,\n \"request\": \"{{request}}\",\n \"nonce\": 1594297865000\n}"
response = http.request(request)
puts response.read_body[
{
"positionId": 111,
"market": "BTC_USDT",
"openDate": 1650400589.882613,
"modifyDate": 1650400589.882613,
"amount": "0.1",
"basePrice": "45658.349",
"realizedFunding": "0",
"liquidationPrice": null,
"liquidationState": "margin_call",
"orderDetail": {
"id": 97067934,
"tradeAmount": "0.1",
"price": "41507.59",
"tradeFee": "415.07",
"fundingFee": null,
"realizedPnl": null
},
"side": "LONG",
"isHedge": false
}
]{
"code": 30,
"message": "Validation failed",
"errors": {}
}{
"code": 30,
"message": "Validation failed",
"errors": {}
}Authorizations
The public WhiteBIT API key.
Base64-encoded JSON request body.
HMAC-SHA512 signature of the payload, hex-encoded. Computed as hex(HMAC-SHA512(payload, api_secret)).
Body
Filter by specific market. Example: BTC_USDT
If not specified, returns position history for all markets.
"BTC_USDT"
Filter by specific position identifier. If not specified, returns history for all positions.
1
Start of the query window as a Unix timestamp in seconds. Optional, no default. Must be ≤ endDate.
1650400000
End of the query window as a Unix timestamp in seconds. Optional, no default. Must be ≥ startDate and ≤ now + 1s; violating values are rejected with a validation error.
1650500000
"{{request}}"
1594297865000
Response
Successful response - returns array of position history
Position identifier
111
Position market
"BTC_USDT"
Date of position opening in Unix timestamp format
1650400589.882613
Date of position modification (current event) in Unix timestamp format
1650400589.882613
Position amount
"0.1"
Base price of position
"45658.349"
Funding fee for whole position lifetime till current state
"0"
Liquidation price according to current state of position
null
State of liquidation
margin_call, liquidation null
Details of order which changes position
Show child attributes
Show child attributes
Position direction. BOTH indicates a one-way mode position; LONG or SHORT indicates a hedge mode position. See position side.
LONG, SHORT, BOTH "LONG"
Indicates whether hedge mode was active when the position was opened. Hedge-mode toggling requires zero open positions, so the value also reflects the account mode at every event in the position's lifetime.
false
Was this page helpful?