保险金与 ADL

ZTDX USDⓈ-M 永续合约通过两阶段瀑布机制吸收坏账、保护用户：

1. 保险金（Insurance Fund） —— 按交易对独立的资金池，当被强平仓位的剩余 保证金跌至负值时用于覆盖坏账。
2. 自动减仓（ADL，Auto-Deleveraging） —— 仅在保险金无法覆盖缺口时启动； 按排名减少对手方盈利仓位以填平账面。

本页说明该机制的细节、所有公开 REST 端点，以及如何检测自己的账户是否被任一 环节波及。

坏账瀑布

当某仓位触及维持保证金、按 mark_price 被强平时：

remaining_collateral = collateral_amount
                     + realized_pnl(mark_price)
                     - accumulated_funding_fee
                     - accumulated_borrowing_fee
                     - liquidation_fee          (size_in_usd × 0.5%)
                     - insurance_contribution   (size_in_usd × 0.1%)
                     - liquidator_reward        (size_in_usd × 0.1%，若有 keeper)

阶段 1 —— 用户保证金

若 remaining_collateral ≥ 0，用户保证金足够吸收损失：仓位平掉、扣完手续费 后任何剩余金额回到 available_balance。保险金照常收取 insurance_contribution 切片，ADL 不触发。

阶段 2 —— 保险金赔付

若 remaining_collateral < 0，保险金按以下公式覆盖缺口：

insurance_payout = min( |remaining_collateral|,
                        fund.balance × max_insurance_payout_rate )

max_insurance_payout_rate 默认 0.5（单次清算事件最多消耗当前保险金余额 的 50%），防止单一极端行情把整个池子抽干。

阶段 3 —— ADL（自动减仓）

若保险金赔付后仍有未覆盖的缺口，引擎触发 adl 事件。与被强平方向相反 的盈利仓位按排名被部分（或全部）按当前 mark price 减仓；这部分本应归他们的 已实现盈亏被截留，用于填平剩余缺口。

对统一保证金账户而言，每一步清算记录中的 liquidation_type 在该分支被触发 时会标记为 "adl"（详见 统一保证金清算历史）。

保险金资金来源

保险金是 按交易对独立 的，不是全局共享。每个交易对的池子由一笔固定的 仓位名义价值的 0.1%（10 bps） 抽水填充，所有被强平仓位都会扣这一笔 （insurance_fund_fee_rate，可按市场单独配置）。交易手续费、资金费、借币费 不会 流入保险金 —— 它们直接进入协议收入。

只有阶段 2 触发时，保险金才会被支取。

ADL 排名规则

ADL 仅考虑当前盯市价格下盈利（unrealized_pnl > 0）且与被强平仓位 方向 相反 的仓位。每个候选仓位计算评分：

adl_score = pnl_weight       × pnl_percentage
          + leverage_weight  × leverage
          + size_weight      × (size / max_size_in_market)

按评分从高到低排序，rank 1 最先被减。权威排名 —— 包含真实 rank、 adl_score 以及计算用到的所有输入字段 —— 通过 GET /api/v1/adl/{symbol}/rankings?side=long|short 获取。

各市场的 ADL 行为参数（权重、单次事件最多影响仓位数、最小/最大减仓比例、 是否启用）通过 GET /api/v1/adl/{symbol}/config 暴露。

排名由后台 worker 每 30 秒 重算一次。

关于 /fapi/v1/adlQuantile —— 该 Binance 兼容端点目前返回的是按持仓 方向粗略简化的分位值（尚未对接实时 adl_rankings 数据）。需要精确排名请 用下文的原生端点 GET /api/v1/adl/{symbol}/rankings。

公开 REST 端点

/api/v1/... 下的端点全部公开（无鉴权、无签名）；/fapi/v1/... 是 Binance 兼容端点，需 HMAC SHA256 签名。

端点	返回内容
GET /api/v1/insurance-fund/{symbol}	当前交易对的保险金余额 + 累计贡献/支取
GET /api/v1/liquidations/{symbol}	该市场最近的强平记录（含 insurance_fund_contribution）
GET /api/v1/liquidations/{symbol}/config	该市场的强平参数（insurance_fund_fee_rate、max_insurance_payout_rate 等）
GET /api/v1/adl/{symbol}/rankings	实时 ADL 排名快照（按方向）
GET /api/v1/adl/{symbol}/events	该市场的 ADL 历史事件
GET /api/v1/adl/{symbol}/config	该市场的 ADL 参数及 enabled 标志
GET /fapi/v1/adlQuantile	仓位 ADL 分位值（0–4），Binance 兼容、需签名
GET /fapi/v1/forceOrders	调用者的强平单历史，Binance 兼容、需签名

强平记录的完整字段说明请参考 forceOrders（Binance 兼容）和 unified/liquidations （ZTDX 原生，仅统一保证金）。

GET /api/v1/insurance-fund/{symbol}

返回单个交易对的实时保险金状态。公开，无需鉴权。

路径参数

名称	类型	是否必需	描述
symbol	STRING	YES	例如 BTCUSDT

响应

{
  "fund": {
    "id": "8e7c2a1b-4d3e-4f5a-9b0c-1d2e3f4a5b6c",
    "symbol": "BTCUSDT",
    "balance": "14448.566075868791505285",
    "total_contributions": "27508.804093804413605641",
    "total_payouts": "13060.238017935622100451",
    "updated_at": "2026-05-07T08:12:52.919276Z",
    "created_at": "2025-11-14T03:00:00.000000Z"
  }
}

字段	含义
balance	该交易对当前可用于覆盖坏账的资金
total_contributions	累计来自强平的贡献（0.1% × 名义价值）
total_payouts	累计用于填补坏账的支取
updated_at	行最近一次被更新的时间（即该交易对最近一次强平）

若该交易对从未被触发，端点会按需创建一行余额为 0 的记录后返回。

GET /api/v1/liquidations/{symbol}/config

返回引擎使用的该市场强平参数。

{
  "config": {
    "symbol": "BTCUSDT",
    "liquidation_fee_rate": "0.005",
    "max_leverage": 50,
    "maintenance_margin_rate": "0.005",
    "min_collateral_usd": "10",
    "insurance_fund_fee_rate": "0.001",
    "max_insurance_payout_rate": "0.5",
    "liquidator_reward_rate": "0.001"
  }
}

这些值同时会被快照写入每一行 liquidations 记录，因此下游分析无需假设当前 配置对历史事件依然有效。

GET /api/v1/adl/{symbol}/rankings

返回单方向的实时排名快照，按 rank 升序（rank 1 = 下一次 ADL 触发时最先 被减仓）。排名每 30 秒重算一次。

查询参数

名称	类型	是否必需	默认值	描述
side	STRING	YES	—	"long" 或 "short"
limit	INT	NO	50	每页条数

响应

{
  "market_symbol": "BTCUSDT",
  "side": "long",
  "rankings": [
    {
      "id": "...",
      "market_symbol": "BTCUSDT",
      "side": "long",
      "position_id": "...",
      "user_address": "0x...",
      "position_size": "50000.00",
      "unrealized_pnl": "1234.56",
      "pnl_percentage": "12.345",
      "leverage": "10",
      "adl_score": "1.7234",
      "rank": 1,
      "computed_at": "2026-05-07T08:12:30Z"
    }
  ]
}

只有盈利仓位会出现在排名里；亏损仓位永远不是 ADL 候选。

GET /api/v1/adl/{symbol}/events

该市场的 ADL 执行历史。返回空数组意味着保险金至今覆盖了所有缺口 —— 这是稳态。

{
  "events": [
    {
      "id": "...",
      "market_symbol": "BTCUSDT",
      "liquidation_id": "...",
      "insurance_fund_shortfall": "850.000000000000000000",
      "total_reduced_size": "8500.000000000000000000",
      "total_pnl_realized": "850.000000000000000000",
      "positions_affected": 3,
      "status": "completed",
      "created_at": "2026-04-13T05:12:34.567890Z",
      "completed_at": "2026-04-13T05:12:34.892011Z"
    }
  ]
}

status 取值：pending（执行中）、completed（缺口完全覆盖）、 partial（未能完全覆盖 —— 异常情况）、failed（无可减仓的对手方 —— 异常情况）。

在账户数据中检测保险金 / ADL 影响

你想知道…	去哪查
我的仓位被强平了吗？	/fapi/v1/forceOrders —— Binance 兼容
我的统一保证金账户被逐步清算了吗？	/api/v1/unified/liquidations。liquidation_type == "adl" ⇒ 该步触发了 ADL
我下次会不会被 ADL？	GET /api/v1/adl/{symbol}/rankings?side=... —— 找到自己的 position_id，rank 越小越早被减仓。（/fapi/v1/adlQuantile 当前是粗略 stub —— 请用原生端点。）
某个仓位是不是被 ADL 减仓的？	该仓位会出现在 adl_reductions 表中；用户侧的 trade history 里能看到一条按 ADL 执行价合成的平仓记录

代码示例 —— 拉取所有交易对的保险金余额

import requests

BASE_URL = "https://api.ztdx.io"

# 1. 获取活跃交易对列表
markets = requests.get(f"{BASE_URL}/api/v1/markets").json()
symbols = [m["symbol"] for m in markets]

# 2. 并行查询
total_balance = 0.0
for symbol in symbols:
    r = requests.get(f"{BASE_URL}/api/v1/insurance-fund/{symbol}")
    fund = r.json()["fund"]
    bal = float(fund["balance"])
    total_balance += bal
    print(f"{symbol:14s}  balance={bal:>14.4f}  "
          f"contrib={float(fund['total_contributions']):>14.4f}  "
          f"payouts={float(fund['total_payouts']):>14.4f}")

print(f"\n所有市场保险金合计：{total_balance:,.2f} USDT")

常见问题

为什么保险金按交易对独立而不是全局共享？ 独立资金池避免传染：某个流动性差的山寨币闪崩不会把 BTC 市场的池子抽干。

保险金可以人工充值吗？ 没有公开端点。唯一的入金路径就是强平时的 0.1% 抽水。运维侧的特殊注资 （例如协议方主动补血）属于内部管理操作，不在公开 API 范围。

保险金归零会怎样？ 阶段 2 直接赔付 0，阶段 3（ADL）覆盖整个坏账切片。市场继续运行，不会停摆。

为什么有 50% 单次封顶？ 单一异常事件不应能把整个池子一次抽干。有了 50% 上限，最坏的强平最多消耗当前 余额的一半，留下另一半应对下一次事件。剩下的缺口走 ADL —— ADL 本身就是 为了应对无上限事件而设计的，所以这个分工是合理的。

保险金贡献能在 protocol_fee_ledger 看到吗？ 能。每次强平会写三行：liquidation_fee（正数，协议收入）、 insurance_contribution（正数，对应保险金的入账）、 liquidator_reward（如果支付给 keeper 则为负数，因为这部分 USDT 会从 vault 实际出账）。