Liquidation History

Return the caller's forced-liquidation events recorded while in unified mode, most recent first.

Each record corresponds to one position closed by the unified-margin liquidation waterfall (one per 2s tick while the account stays below uniMMR ≤ 1.05). If the engine needed ADL to cover an insurance-fund shortfall, liquidation_type == "adl".

HTTP Request

GET /api/v1/unified/liquidations (HMAC SHA256)

Request Parameters

Name	Type	Required	Default	Description
limit	INT	NO	20	Page size, 1 ≤ limit ≤ 200
offset	INT	NO	0	Pagination offset
timestamp	LONG	YES	—	Timestamp

Response Example

{
    "liquidations": [
        {
            "id": "e8d3ff4c-2a19-4b77-a5c5-8e2c6cc23e14",
            "position_id": "91e9a82c-5df1-4f72-9e01-7f56f1d7df02",
            "symbol": "BTCUSDT",
            "side": "long",
            "closed_size_usd": "50000.000000000000000000",
            "closed_size_tokens": "0.500000000000000000",
            "mark_price": "98500.000000000000000000",
            "pnl_realized": "-1500.000000000000000000",
            "collateral_returned": "350.000000000000000000",
            "trigger_uni_mmr": "1.031000000000000000",
            "trigger_equity": "120.500000000000000000",
            "post_uni_mmr": null,
            "liquidation_type": "full",
            "created_at": "2026-04-13T05:12:34.567890Z"
        }
    ],
    "total": 1
}

Field semantics

Field	Meaning
position_id	The closed position's UUID
closed_size_usd / closed_size_tokens	Size closed at mark price
mark_price	Price used to close the position
pnl_realized	Realized PnL of the closed slice
collateral_returned	Collateral returned to available_balance after fees / insurance
trigger_uni_mmr / trigger_equity	Snapshot at the moment liquidation fired
post_uni_mmr	uniMMR immediately after this step (may be null if no positions remain)
liquidation_type	"full" — insurance fund covered any shortfall; "adl" — ADL engaged to cover residual shortfall

Related

• Real-time push: unified_account WS channel emits a liquidation_step event in the same tick the DB row is written.
• Account status reaches liquidating when uniMMR ≤ 1.05; see Overview.

Code Examples

curl

API_KEY="your_api_key"
API_SECRET="your_api_secret"
TIMESTAMP=$(date +%s%3N)
QUERY="limit=20&timestamp=${TIMESTAMP}"
SIGNATURE=$(echo -n "${QUERY}" | openssl dgst -sha256 -hmac "${API_SECRET}" | awk '{print $2}')
curl -s -H "X-MBX-APIKEY: ${API_KEY}" \
  "https://api.ztdx.io/api/v1/unified/liquidations?${QUERY}&signature=${SIGNATURE}"

Python

import time, hmac, hashlib, requests

API_KEY = "your_api_key"
API_SECRET = "your_api_secret"

ts = int(time.time() * 1000)
q = f"limit=20&timestamp={ts}"
sig = hmac.new(API_SECRET.encode(), q.encode(), hashlib.sha256).hexdigest()
r = requests.get(
    f"https://api.ztdx.io/api/v1/unified/liquidations?{q}&signature={sig}",
    headers={"X-MBX-APIKEY": API_KEY},
)
for liq in r.json()["liquidations"]:
    print(f"{liq['created_at']}  {liq['symbol']} {liq['side']} "
          f"pnl={liq['pnl_realized']} type={liq['liquidation_type']}")