> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitebit.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Positions history
> Retrieve the history of closed collateral trading positions on a WhiteBIT account via the V4 API.
* [Open positions](/api-reference/collateral-trading/open-positions) — List current open positions
* [Close position](/api-reference/collateral-trading/close-position) — Close an open position
* [Funding history](/api-reference/collateral-trading/funding-history) — Review funding payments on positions
* [Collateral account summary](/api-reference/collateral-trading/collateral-account-summary) — View account-level margin and equity
## OpenAPI
````yaml /openapi/private/http-trade-v4.yaml POST /api/v4/collateral-account/positions/history
openapi: 3.0.3
info:
title: Private HTTP API V4 - Collateral Trading
description: |
WhiteBIT Private HTTP API V4 for collateral/margin trading operations.
Base URL: https://whitebit.com
All endpoints return time in Unix-time format.
All endpoints return either a JSON object or array.
For receiving responses from API calls please use http method POST.
Authentication required for all endpoints.
version: 4.0.0
license:
name: WhiteBIT Terms of Service
url: https://whitebit.com/terms
servers:
- url: https://whitebit.com
description: WhiteBIT Global Server
- url: https://whitebit.eu
description: WhiteBIT EU Server
security:
- ApiKeyAuth: []
PayloadAuth: []
SignatureAuth: []
tags:
- name: Collateral Trading
description: Endpoints for collateral/margin trading operations
- name: Spot Trading
description: Endpoints for spot trading operations
- name: Market Fee
description: Endpoints for querying trading fees
paths:
/api/v4/collateral-account/positions/history:
post:
tags:
- Collateral Trading
summary: Positions History
description: >
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.
Rate limit: 12000 requests/10 sec.
- `30` - default validation error code (invalid pagination — `limit` outside 1–100 or negative `offset` — or a date filter that violates `startDate` ≤ `endDate` ≤ `now + 1s`)
**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.
operationId: getPositionsHistory
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
market:
type: string
description: |
Filter by specific market. Example: BTC_USDT
If not specified, returns position history for all markets.
example: BTC_USDT
positionId:
type: integer
description: >-
Filter by specific position identifier. If not specified,
returns history for all positions.
example: 1
startDate:
type: integer
description: >-
Start of the query window as a Unix timestamp in seconds.
Optional, no default. Must be ≤ `endDate`.
example: 1650400000
endDate:
type: integer
description: >-
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.
example: 1650500000
request:
type: string
example: '{{request}}'
nonce:
type: integer
example: 1594297865000
example:
market: BTC_USDT
positionId: 1
request: '{{request}}'
nonce: 1594297865000
responses:
'200':
description: Successful response - returns array of position history
content:
application/json:
schema:
type: array
description: Array of position history entries
items:
type: object
properties:
positionId:
type: integer
description: Position identifier
example: 111
market:
type: string
description: Position market
example: BTC_USDT
openDate:
type: number
description: Date of position opening in Unix timestamp format
example: 1650400589.882613
modifyDate:
type: number
description: >-
Date of position modification (current event) in Unix
timestamp format
example: 1650400589.882613
amount:
type: string
description: Position amount
example: '0.1'
basePrice:
type: string
description: Base price of position
example: '45658.349'
realizedFunding:
type: string
description: >-
Funding fee for whole position lifetime till current
state
example: '0'
liquidationPrice:
type: string
description: Liquidation price according to current state of position
nullable: true
example: null
liquidationState:
type: string
description: State of liquidation
enum:
- margin_call
- liquidation
nullable: true
example: null
orderDetail:
type: object
description: Details of order which changes position
properties:
id:
type: integer
description: Order identifier
example: 97067934
tradeAmount:
type: string
description: Trade amount of order
example: '0.1'
price:
type: string
description: Order price
example: '41507.59'
tradeFee:
type: string
description: Order trade fee
example: '415.07'
fundingFee:
type: string
description: Funding fee captured by this position change
nullable: true
example: null
realizedPnl:
type: string
description: Realized profit and loss
nullable: true
example: null
side:
type: string
enum:
- LONG
- SHORT
- BOTH
description: >-
Position direction. `BOTH` indicates a one-way mode
position; `LONG` or `SHORT` indicates a hedge mode
position. See [position side](/glossary#position-side).
example: LONG
isHedge:
type: boolean
description: >-
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.
example: false
example:
- 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
'400':
description: Inner validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Request validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal error
'503':
description: Service temporarily unavailable
security:
- ApiKeyAuth: []
PayloadAuth: []
SignatureAuth: []
components:
schemas:
ErrorResponse:
type: object
properties:
code:
type: integer
description: Error code
example: 30
message:
type: string
description: Error message
example: Validation failed
errors:
type: object
additionalProperties:
type: array
items:
type: string
description: Detailed error information
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-TXC-APIKEY
description: The public WhiteBIT API key.
PayloadAuth:
type: apiKey
in: header
name: X-TXC-PAYLOAD
description: Base64-encoded JSON request body.
SignatureAuth:
type: apiKey
in: header
name: X-TXC-SIGNATURE
description: >-
HMAC-SHA512 signature of the payload, hex-encoded. Computed as
hex(HMAC-SHA512(payload, api_secret)).
````