---
title: "Positions History"
method: POST
path: "/api/v4/collateral-account/positions/history"
tags: ["Collateral Trading"]
---

# Positions History

`POST /api/v4/collateral-account/positions/history`

The endpoint returns the history of [collateral](/glossary#balance-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.

<Warning>
Rate limit: 12000 requests/10 sec.
</Warning>

<Accordion title="Error Codes">
  - `30` - default validation error code (invalid pagination — `limit` outside 1–100 or negative `offset` — or a date filter that violates `startDate` ≤ `endDate` ≤ `now + 1s`)
</Accordion>

<Note>
**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.
</Note>

<Warning>
**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.
</Warning>

## Request body

- object
  - `market` string — Filter by specific market. Example: BTC_USDT If not specified, returns position history for all markets.
  - `positionId` integer — Filter by specific position identifier. If not specified, returns history for all positions.
  - `startDate` integer — Start of the query window as a Unix timestamp in seconds. Optional, no default. Must be ≤ `endDate`.
  - `endDate` integer — 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.
  - `request` string
  - `nonce` integer

## Response `200`

Successful response - returns array of position history

- object[] — Array of position history entries
  - `positionId` integer — Position identifier
  - `market` string — Position market
  - `openDate` number — Date of position opening in Unix timestamp format
  - `modifyDate` number — Date of position modification (current event) in Unix timestamp format
  - `amount` string — Position amount
  - `basePrice` string — Base price of position
  - `realizedFunding` string — Funding fee for whole position lifetime till current state
  - `liquidationPrice` string, nullable — Liquidation price according to current state of position
  - `liquidationState` 'margin_call' | 'liquidation', nullable — State of liquidation
  - `orderDetail` object — Details of order which changes position
    - `id` integer — Order identifier
    - `tradeAmount` string — Trade amount of order
    - `price` string — Order price
    - `tradeFee` string — Order trade fee
    - `fundingFee` string, nullable — Funding fee captured by this position change
    - `realizedPnl` string, nullable — Realized profit and loss
  - `side` 'LONG' | 'SHORT' | 'BOTH' — Position direction. `BOTH` indicates a one-way mode position; `LONG` or `SHORT` indicates a hedge mode position. See [position side](/glossary#position-side).
  - `isHedge` boolean — Indicates whether [hedge mode](/glossary#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.

## Other responses

- `400` — Inner validation failed
- `422` — Request validation failed
- `500` — Internal error
- `503` — Service temporarily unavailable

---

[API](https://skmtc.net/whitebit/apis/whitebit-private-http-api-v4.md) · [All operations](https://skmtc.net/whitebit/apis/whitebit-private-http-api-v4/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/whitebit/whitebit-private-http-api-v4/revisions/76c9def9942f/schema)