VIP 等级与手续费规则

概述

永续合约手续费采用 6 档 VIP 阶梯，依据用户在所有 USDⓈ-M 永续交易对上的 14 天滚动名义成交量（Maker 和 Taker 均计入）决定档位。所有手续费均从用户抵押保证金中扣除，不做外部费用结算。

用户实际支付的手续费率计算方式：

effective_rate = base_rate × (1 − referral_discount) × (1 − token_staking_discount)
effective_fee  = notional × effective_rate          (向上取整至 6 位小数)

字段	当前取值
`referral_discount`	`0.10`（10%）
`token_staking_discount`	`0.00`（接口保留，当前恒为 0）
`discount_multiplier`	`(1 − 0.10) × (1 − 0.00) = 0.90`
`notional`	`amount × mark_price`
精度	6 位小数（USDC）

档位表

等级	14 天成交量（USD）	Taker	Maker
VIP 0	`<` 5 M	0.040%	0.010%
VIP 1	5 M – 25 M	0.036%	0.008%
VIP 2	25 M – 100 M	0.032%	0.004%
VIP 3	100 M – 500 M	0.028%	0.000%
VIP 4	500 M – 2 B	0.026%	0.000%
VIP 5	`≥` 2 B	0.024%	0.000%

VIP 3 及以上 Maker 免费。

升档 / 降档语义

升档：在任意一次 fee-info 读取、下单预览或订单成交中观察到用户跨越下一档阈值时，即时生效。
降档：延迟生效，不立即下调。新的（更低的）档位记录在 pending_tier，到下一个 UTC 00:00 才真正应用。该设计给用户 24 小时缓冲，避免短时成交量回落导致频繁降档。
每次 upgrade_immediate、downgrade_scheduled、downgrade_applied 状态变化都会在 vip_tier_events 表写入一条审计记录。

`GET /account/fee-info`

返回当前用户的 VIP 档位、完整档位表、14/30 天滚动成交量、距离下一档的进度，以及当前生效的折扣栈。

请求

鉴权：JWT（钱包登录）或 API Key。无查询参数。

GET /api/v1/account/fee-info
Authorization: Bearer <jwt>

响应

{
  "current_tier": 3,
  "current_label": "VIP 3",
  "current_maker": "0.00000",
  "current_taker": "0.00028",
  "effective_maker": "0.000000",
  "effective_taker": "0.000252",
  "volume_14d": "138206820.47",
  "volume_30d": "215440192.11",
  "fee_tiers": [
    { "level": 0, "label": "VIP 0", "maker": "0.00010", "taker": "0.00040", "volume_min": "0",           "volume_max": "5000000"   },
    { "level": 1, "label": "VIP 1", "maker": "0.00008", "taker": "0.00036", "volume_min": "5000000",     "volume_max": "25000000"  },
    { "level": 2, "label": "VIP 2", "maker": "0.00004", "taker": "0.00032", "volume_min": "25000000",    "volume_max": "100000000" },
    { "level": 3, "label": "VIP 3", "maker": "0.00000", "taker": "0.00028", "volume_min": "100000000",   "volume_max": "500000000" },
    { "level": 4, "label": "VIP 4", "maker": "0.00000", "taker": "0.00026", "volume_min": "500000000",   "volume_max": "2000000000"},
    { "level": 5, "label": "VIP 5", "maker": "0.00000", "taker": "0.00024", "volume_min": "2000000000"  }
  ],
  "progress_to_next": {
    "next_level":        4,
    "next_label":        "VIP 4",
    "required_volume":   "500000000",
    "remaining_volume":  "361793179.53",
    "percent":           "0.276413640"
  },
  "pending_tier": null,
  "pending_effective_at": null,
  "discounts": {
    "referral":       "0.10",
    "token_staking":  "0",
    "multiplier":     "0.90"
  }
}

字段说明：

current_maker / current_taker：折扣前的基础费率
effective_maker / effective_taker：已乘 discount_multiplier，前端展示及与 POST /orders/preview 对账时请直接使用这两个值
progress_to_next：用户已处于 VIP 5 时本字段缺省
pending_tier 与 pending_effective_at：仅在已调度降档时为非 null

`POST /orders/preview` —— 手续费字段

预览接口返回的费率已包含折扣乘数，前端不需要再次乘折扣：

{
  "order_value":     "500.000",
  "taker_fee_rate":  "0.000252",
  "maker_fee_rate":  "0.000000",
  "est_fee":         "0.126000",
  ...
}

est_fee = order_value × (taker 或 maker 费率)，具体用哪个费率由 order_type 决定：

`order_type`	使用的费率
`market`	`taker_fee_rate`
`limit`	`maker_fee_rate`

WebSocket 推送 —— `vip_tier` 频道

已鉴权的客户端可订阅私有 vip_tier 频道，在档位发生变化时收到推送通知。

推送载荷

{
  "channel": "vip_tier",
  "type":    "vip_tier_changed",
  "data": {
    "user_address":   "0xbc7c75bf109cda7104c2467532c578c0e8b0efe0",
    "old_tier":       2,
    "new_tier":       3,
    "volume_14d":     "138206820.47",
    "reason":         "upgrade_immediate",
    "timestamp":      1776311435000
  }
}

reason 取值：

取值	含义
`upgrade_immediate`	成交量向上跨越阈值，新档位已即时生效
`downgrade_scheduled`	成交量回落，较低的档位将于下一个 UTC 00:00 生效；`data.new_tier` 为调度目标档位
`downgrade_applied`	先前调度的降档刚刚生效

后台任务节奏

惰性路径（Lazy）：任意一次 GET /account/fee-info 或 POST /orders/preview 调用都会触发 vip_tier::resolve()，即时重新计算并持久化用户档位。升档立刻生效，降档进入调度。
每日扫描（Daily Sweep）：后台 Worker 每 10 分钟 tick 一次，在 00:00–00:10 UTC 窗口执行两件事：① 应用所有 pending_effective_at <= NOW() 到期的降档；② 对过去 14 天内有成交的所有用户重算一遍档位（确保即使从未调用接口的用户，档位也始终保持最新）。

数据模型

VIP 等级服务为每位用户持久化以下信息：

current_tier — 当前生效的等级
effective_since — 该等级的生效时间
pending_tier + pending_effective_at — 待生效的降档目标及生效时间（无待降档时为空）
last_volume_14d — 用于评级的 14 日累计交易量
updated_at — 最近一次重算时间

另外有一份只追加的事件日志，记录每次等级变更（旧等级、新等级、当时的 14 日交易量、变更原因），用于完整审计升档与降档历史。

代码示例

curl

curl -s -H "Authorization: Bearer ${JWT}" \
  https://api-sepolia.ztdx.io/api/v1/account/fee-info | jq

Python

import requests

r = requests.get(
    "https://api.ztdx.io/api/v1/account/fee-info",
    headers={"Authorization": f"Bearer {jwt}"},
    timeout=10,
)
info = r.json()
print(f"VIP {info['current_tier']}  "
      f"taker={info['effective_taker']}  maker={info['effective_maker']}  "
      f"volume_14d={info['volume_14d']}")

FAQ

Q：每日扫描会在日中把用户档位调低吗？ 不会。current_tier 一旦确定，只有 00:00 窗口的 pending_effective_at <= NOW() 判定才能将其下调。日内的惰性读取只会升档。

Q：用户连续 14 天以上不交易会怎样？ 其 volume_14d 最终会降为 0，resolve() 会调度降档至 VIP 0，并在下一个 UTC 00:00 生效。

Q：VIP 3+ 的 Maker 是否会产生返佣（负费率）？ 不会 —— VIP 3+ 的 Maker 为零，但不为负。做市商的负费率合约由单独的 MM 管理后台接口管理。

Q：discount_multiplier 可能大于 1 吗？ 不会。referral_discount 与 token_staking_discount 均被约束在 [0, 1) 区间，因此乘数始终落在 (0, 1]。

概述​

档位表​

升档 / 降档语义​

GET /account/fee-info​

请求​

响应​

POST /orders/preview —— 手续费字段​

WebSocket 推送 —— vip_tier 频道​

订阅​

推送载荷​

后台任务节奏​

数据模型​

代码示例​

curl​

Python​

FAQ​

概述

档位表