> ## 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.
# Open positions
> List all currently open collateral trading positions on a WhiteBIT account via the V4 API.
## Rate limit
* [Close position](/api-reference/collateral-trading/close-position) — Close an open position
* [Positions history](/api-reference/collateral-trading/positions-history) — View closed position history
* [Funding history](/api-reference/collateral-trading/funding-history) — Review funding payments on positions
* [ADL quantile](/api-reference/collateral-trading/adl-quantile) — Per-market deleveraging-priority value for open perpetual 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/open
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/open:
post:
tags:
- Collateral Trading
summary: Open Positions
description: >
The endpoint returns all open [collateral](/glossary#balance-collateral)
positions for the authenticated account. Each position includes entry
price, unrealized PnL, margin allocation, liquidation price, and
take-profit/stop-loss configuration. Use the optional `market` parameter
to filter results to a single trading pair.
Rate limit: 12000 requests/10 sec.
- `30` - default validation error code (returned when the optional `market` filter is malformed)
operationId: getOpenPositions
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
market:
type: string
description: |
Filter by specific market. For example: BTC_USDT
If not specified, returns all open positions.
example: BTC_USDT
request:
type: string
description: Request signature
example: '{{request}}'
nonce:
type: integer
description: Unique request identifier
example: 1594297865000
example:
market: BTC_USDT
request: '{{request}}'
nonce: 1594297865000
responses:
'200':
description: Successful response - returns array of open positions
content:
application/json:
schema:
type: array
items:
type: object
properties:
positionId:
type: integer
description: Unique position identifier
example: 527
market:
type: string
description: Market name
example: BTC_USDT
amount:
type: string
description: Position amount
example: '0.1'
basePrice:
type: string
description: Base price of position
example: '45658.349'
pnl:
type: string
description: >-
Realized profit and loss accumulated from partial
position closes, in money currency. Zero for newly
opened positions that have not been partially closed.
example: '-168.42'
pnlPercent:
type: string
description: Unrealized profit and loss in percentage
example: '-0.43'
margin:
type: string
description: Amount of funds in open position money
example: '8316.74'
freeMargin:
type: string
description: Free funds for trading
example: '619385.67'
funding:
type: string
description: >-
Cumulative funding fees paid over the entire lifetime of
the position, in money currency. For futures markets
(e.g., BTC_PERP and other _PERP pairs), the value is
always "0" — futures funding is applied via periodic
balance updates rather than being tracked per position.
example: '0'
unrealizedPnl:
type: string
description: >-
Floating (mark-to-market) unrealized profit and loss in
money currency. Updates continuously as the market price
changes.
example: '0.0019142920201966'
positionSide:
type: string
description: Position side
enum:
- LONG
- SHORT
- BOTH
example: LONG
openDate:
type: number
description: Date of position opening in Unix timestamp format
example: 1651568067.789679
modifyDate:
type: number
description: >-
Date of position modifying (current event) in Unix
timestamp format
example: 1651568067.789679
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
tpsl:
type: object
description: Take profit and stop loss configuration
nullable: true
properties:
takeProfitId:
type: integer
description: Take profit order ID
example: 123
takeProfit:
type: string
description: Take profit price
example: '50000'
stopLossId:
type: integer
description: Stop loss order ID
example: 124
stopLoss:
type: string
description: Stop loss price
example: '35000'
unrealizedFunding:
type: string
description: >-
Funding fees accrued since the last position state
change and not yet realized. For margin positions, the
value accumulates continuously and is settled into the
funding field when the position state changes (e.g., on
partial or full close). For futures markets (BTC_PERP
and other _PERP pairs), always "0" — futures funding is
applied via periodic balance updates, not tracked per
position.
example: '0.0019142920201966'
example:
- positionId: 527
market: BTC_USDT
openDate: 1651568067.789679
modifyDate: 1651568067.789679
amount: '0.1'
basePrice: '45658.349'
liquidationPrice: null
liquidationState: margin_call
pnl: '-168.42'
pnlPercent: '-0.43'
margin: '8316.74'
freeMargin: '619385.67'
funding: '0'
unrealizedFunding: '0.0019142920201966'
tpsl:
takeProfitId: 123
takeProfit: '50000'
stopLossId: 124
stopLoss: '35000'
positionSide: LONG
- positionId: 528
market: ETH_USDT
openDate: 1651568067.789679
modifyDate: 1651568067.789679
amount: '0.1'
basePrice: '5658.349'
liquidationPrice: null
liquidationState: margin_call
pnl: '-168.42'
pnlPercent: '-0.43'
margin: '8316.74'
freeMargin: '19385.67'
funding: '0'
unrealizedFunding: '0.0020142920201966'
tpsl: null
positionSide: LONG
'422':
description: Inner validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'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)).
````