币安 API Key 三档权限、IP 白名单与泄露应急处置全景指南
币安 API Key 分为只读、交易、提现三档权限，提现默认关闭，IP 白名单最多绑定 4 个 IPv4。本文覆盖创建、HMAC-SHA256 签名基础、量化机器人隔离与 30 秒内密钥泄露应急处置。
币安 API Key 的安全模型建立在三个核心开关上：只读权限（Read Info）、现货/合约交易权限（Enable Spot & Margin Trading）、提现权限（Enable Withdrawals，默认关闭）；同时每个 API Key 最多绑定 4 个 IPv4 到 IP 白名单，请求使用 HMAC-SHA256 签名。密钥一旦泄露必须在 30 秒内完成删除、平仓、改密三大动作，才有可能保住剩余资产。
一、三档权限的差异与最佳组合
理解权限档位是正确使用 API 的第一步，很多用户为图省事一律全开，结果一次泄露就损失惨重。
1.1 只读权限（Read Info）
只读权限允许获取账户余额、订单记录、K 线数据、持仓明细，但无法下单、无法转账。适用于税务申报工具、行情看板、数据备份脚本。安全等级最高，即便密钥泄露最多也只是隐私外泄。
1.2 现货 / 合约交易权限
交易权限允许下单、撤单、开合约仓、平仓，但依然不能提币。这是量化机器人使用最多的组合。若攻击者拿到这类密钥，最坏情况是将账户资产砸盘或恶意开高杠杆爆仓，因此必须配合 IP 白名单严格限制。
1.3 提现权限（Enable Withdrawals）
提现权限允许通过 API 直接把资金转出到白名单地址。绝大多数场景不需要开启，因此币安官网默认将该开关关闭且灰化，必须先绑定 IP 白名单并二次 2FA 才能激活。
1.4 权限组合建议
| 用途 | Read | Trade | Withdraw | 备注 |
|---|---|---|---|---|
| 税务/看板 | 是 | 否 | 否 | 最安全 |
| 量化机器人 | 是 | 是 | 否 | 主流做法 |
| 做市自动化 | 是 | 是 | 否 | 强制 IP 白名单 |
| 冷钱包定时归集 | 是 | 否 | 是 | 极少数场景 |
| 一次性搬砖 | 是 | 是 | 否 | 用完即删 |
二、IP 白名单的绑定规则
IP 白名单是币安 API 安全模型的第二道锁，其重要性甚至超过 2FA。
2.1 数量与格式限制
- 单个 API Key 最多绑定 4 个 IPv4
- 暂不支持 IPv6，如果你的服务器只有 IPv6，需要额外绑定 IPv4 隧道
- 不接受 CIDR 段（例如 1.2.3.0/24）
- 无 IP 白名单的 Key 仅有 90 天有效期，到期自动失效
2.2 云主机常见坑
在 AWS/Google Cloud/Azure 等平台，API Key 白名单应绑定实例的 EIP/静态 IP。如果绑定的是弹性 IP 又在弹性伸缩组内，实例重启后 IP 变化会立刻导致 API 403。建议：
- 使用 Elastic IP 并 Reserve
- 在同一 VPC 内固定 NAT Gateway IP
- 通过反向代理集中出口
- 结合 CloudWatch 监控 IP 变化，触发 SNS 告警
2.3 IP 白名单与请求签名的协作
即便 IP 匹配，请求依然需要 HMAC-SHA256 签名与 API Secret 一致，两者是"并且"关系。这一层双保险意味着单纯的 IP 伪造无法通过币安校验。
三、HMAC-SHA256 签名基础
对于第一次接触币安 API 的开发者，签名是入门最大的门槛。理解流程后调试事半功倍。
3.1 签名参数拼接
签名的原始字符串由所有查询参数按顺序拼接组成，例如：
symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1699999999999
其中 timestamp 必须为毫秒级 Unix 时间戳，与服务器时间偏差不能超过 recvWindow（默认 5000 毫秒，最大 60000 毫秒）。
3.2 签名计算与请求头
- 算法：HMAC-SHA256(key = API Secret, message = 上述原始字符串)
- 结果 hex 追加到查询参数末尾：
...&signature=xxx - HTTP Header：
X-MBX-APIKEY: <API Key>
3.3 常见报错对照
| 错误码 | 含义 | 处理 |
|---|---|---|
| -1021 | Timestamp 偏差过大 | 校准 NTP，检查时区 |
| -1022 | 签名无效 | 参数顺序/URL 编码 |
| -2015 | 无效 Key、IP 不在白名单或权限不足 | 三选一逐项排查 |
| -1003 | 请求太多超频 | 降速或使用 WebSocket |
| -4028 | 密钥即将过期 | 提前 7 天生成新 Key |
Q：我调用现货下单，参数一切正确，却持续 -1022，为什么？
A：99% 是查询参数中包含 URL 编码后的加号 +（应为 %2B）或空格未编码。可以打印实际发给币安的 URL 与本地签名前的字符串，逐字符比对。
四、量化机器人 Key 隔离策略
大型量化团队通常一次持有几十把 API Key，隔离策略是运维底线。
4.1 一策略一 Key
每一个策略（做市、跟单、网格、期现套利）配一把独立 Key，同一策略的多台服务器共用 Key 但绑定 4 个 IP。任何一策略出问题，只影响该 Key。
4.2 权限最小化
即便策略需要现货 + 合约同时下单，也不要为它开启统一账户"全权限"。可以细分为两把 Key：一把只允许现货交易、另一把只允许合约交易，再用同一份代码切换调用。
4.3 定期轮换
高频策略建议每 30 天轮换一次 Key，中低频策略每 90 天轮换一次。可通过 币安官方App推送提醒到期时间，避免遗忘导致策略中断。更多细节可参考 安全设置 与 下载中心 的辅助工具。
4.4 环境变量与秘钥管理
- 严禁把 Key 硬编码在源代码或 Git 提交历史中
- 建议使用 Hashicorp Vault、AWS Secrets Manager 或 KMS 加密后加载
- 本地开发使用
.env时务必加入.gitignore - CI/CD 环境通过密文变量注入，构建日志脱敏
五、密钥泄露的 30 秒应急清单
一旦发现 Key 可能泄露，行动越快损失越小。以下是"黄金 30 秒"标准动作。
5.1 立即删除 Key
登录币安官网，进入 API 管理页面，找到疑似泄露的 Key，点击"删除"。删除是立即生效的最强手段，攻击者无法继续下单。
5.2 平仓与撤单
在删除 Key 之后，快速检查合约仓位是否已被开出巨额高杠杆头寸；若有，立刻在网页端手动平仓并撤销所有挂单，避免连锁爆仓。
5.3 修改登录密码与 2FA
按流程重置账户登录密码；如无法确认 2FA 是否也被拿走，重新绑定 Google Authenticator。相关操作可参考本站《币安 2FA 换机迁移完全手册》。
5.4 开启审计与提交工单
访问安全中心的"账户活动日志"，导出最近 30 天 API 调用记录并保存证据；随后通过工单提交给币安安全团队，请求账户风控冻结与资产回溯。
⚠️ 风险提示：任何自称"币安工程师帮你追回损失但需要你先支付服务费"的联系人一定是骗子，官方从不主动 DM 用户，也不会索取任何形式费用。
六、常见问题
我 3 个月没用 API Key，还能继续用吗？
要看是否绑定了 IP 白名单。绑定的 Key 无期限，只要账户还在就一直有效；未绑定 IP 白名单的 Key 每 90 天自动失效，需要重新创建。
我的量化脚本报 -2015，怎么排查？
按顺序检查：Key 是否已被删除；请求出口 IP 是否在白名单 4 个 IPv4 之内；操作是否超出该 Key 权限（如用只读 Key 下单）。三项都排除后再考虑签名问题。
一定要用 HMAC-SHA256 吗？可以用 Ed25519 吗？
币安 2024 年之后逐步开放 Ed25519 与 RSA 签名，属于高性能替代方案。但对新手不推荐，因为需要额外的密钥生成流程；主流 SDK 仍以 HMAC-SHA256 为默认。
API Key 数量有上限吗？
单账户可创建最多 30 把 API Key，超过后需要先删除旧的。机构 VIP 账户可申请提升到 60 把。
未使用的 Key 会不会自动被清理？
未绑定 IP 的 Key 每 90 天失效；绑定 IP 的 Key 除非账户被停用，否则不会自动清理。为减少泄露面，建议每季度手工审计一次 Key 列表，删除长期不用的条目。
文档发布于 2026-07-01，下次复测计划 2026-10-01