Sign in

v1

latestOpenAPI 3.0.32026-07-2613529376.3 KB
Collateral Trading

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.

<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>
post/api/v4/collateral-account/positions/history

Request body

marketstring

Filter by specific market. Example: BTC_USDT

If not specified, returns position history for all markets.

positionIdinteger

Filter by specific position identifier. If not specified, returns history for all positions.

startDateinteger

Start of the query window as a Unix timestamp in seconds. Optional, no default. Must be ≤ endDate.

endDateinteger

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.

requeststring
nonceinteger

Example request

{
  "market": "BTC_USDT",
  "positionId": 1,
  "startDate": 1650400000,
  "endDate": 1650500000,
  "request": "{{request}}",
  "nonce": 1594297865000
}

Response

Successful response - returns array of position history

positionIdinteger

Position identifier

marketstring

Position market

openDatenumber

Date of position opening in Unix timestamp format

modifyDatenumber

Date of position modification (current event) in Unix timestamp format

amountstring

Position amount

basePricestring

Base price of position

realizedFundingstring

Funding fee for whole position lifetime till current state

liquidationPricestring nullable

Liquidation price according to current state of position

liquidationState'margin_call' | 'liquidation' nullable

State of liquidation

side'LONG' | 'SHORT' | 'BOTH'

Position direction. BOTH indicates a one-way mode position; LONG or SHORT indicates a hedge mode position. See position side.

isHedgeboolean

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.

Example response

[
  {
    "positionId": 111,
    "market": "BTC_USDT",
    "openDate": 1650400589.882613,
    "modifyDate": 1650400589.882613,
    "amount": "0.1",
    "basePrice": "45658.349",
    "realizedFunding": "0",
    "orderDetail": {
      "id": 97067934,
      "tradeAmount": "0.1",
      "price": "41507.59",
      "tradeFee": "415.07"
    },
    "side": "LONG"
  }
]