独立指南 · 币安与第三方工具
LINKDESKCONNECTION FIELD NOTES币安 API · 第三方交易工具 · 权限管理
连接更清楚,授权更有数。
02 · API 权限怎么选

币安 API 的合约权限勾不上:密钥建早了、开了统一账户,还是没绑 IP?

工具要你开合约权限,API 管理里却勾不上,或者开过又消失了。分清是密钥建得早、开过统一账户,还是没设 IP 限制,再决定新建密钥时勾哪几个开关。

LINKDESK 编辑整理 · · 7 分钟阅读
开关勾不上时

【启用合约】勾不上,帮助中心写明的原因有两种:这把密钥是在开通合约账户之前建的,或者账户开过统一账户。还有一种情况是除了读取,其余开关全是灰的,那是系统生成的密钥没有设 IP 访问限制。前两种在旧密钥上改不回来,只能新建一把。

三种情况各对应一个处理办法:密钥早于合约账户就新建;开了统一账户就新建,而且新密钥走统一账户那组接口;没有 IP 限制就先加受信任 IP。

币安 API 的合约权限勾不上,先分清是哪一种

假设你给一个合约网格工具准备了一把现成的 API 密钥,工具连上后能读到余额,一下合约单就报错;回到 API 管理里想补勾【启用合约】,发现勾不上。这时候先别急着把所有开关都试一遍,三种情况的表现不一样:

  • 只有【启用合约】勾不上,现货交易能勾:多半是密钥建在合约账户开通之前,或者账户开过统一账户。
  • 除了读取,其余开关一律勾不上:看这把密钥有没有设置 IP 访问限制。
  • 以前勾着,某天发现没了:先回想是不是开通过统一账户,这是帮助中心写明会自动移除合约权限的那种情况。

工具那一侧通常看不到这些细节。它请求合约接口被拒,日志里多半只是一条 -2015(文档原文 Invalid API-key, IP, or permissions for action),和 IP 不对、密钥填错是同一个错误码。连接报错的分层排查在API 连不上那篇,这里只讲权限这一层。

API 密钥比合约账户先建:旧密钥补不上合约权限

帮助中心《如何在币安创建API密钥》的常见问题里有一句原文:“如果API密钥在您启用合约账户之前创建,或您已经开通统一账户,则API密钥将无法启用合约交易权限。”

前半句对应这样一种顺序:先为一个只读看板建了密钥,几个月后开通了合约,再想让同一把密钥去下合约单。规则没有给这种密钥留补救的入口,处理办法只有新建:确认合约账户已经开通,再创建一把新的 API 密钥,这时候【启用合约】才会出现在可选范围里。

同一页开头还写了建密钥的前提:创建 API 密钥前,需要向现货钱包充值任意金额来激活账户,并完成身份认证。新开的账户一路照着工具说明做,卡在这一步的话,原因不在合约。

如果手里有好几把密钥,分不清哪把建得早,可以请工具维护者调用开发者文档里的“查询 API 密钥权限”接口(GET /sapi/v1/account/apiRestrictions)。返回里有 createTime(创建时间)和 enableFutures(是否已启用合约)两个字段,拿创建时间对一下合约账户的开通时间就知道了。这个接口要签名,只能用密钥本身去查,不要把密钥发给别人代查。

开通统一账户后,【启用合约】从所有旧密钥上消失

后半句说的是统一账户(Portfolio Margin)。帮助中心《币安统一账户 API》写得比创建密钥那页更具体:启用统一账户后,【启用合约】权限会自动从现有的全部 API 密钥中移除;即使之后关闭统一账户,也无法为原有的任何 API 密钥更改【启用合约】权限。【启用统一账户交易】这个开关遵循同样的逻辑。

币安帮助中心《币安统一账户 API》公开页面,第一节写明启用统一账户后【启用合约】权限会从现有全部 API 密钥中移除,关闭统一账户后也无法为原有密钥更改该权限
帮助中心统一账户 API 一页的第一节,可以核对【启用合约】和【启用统一账户交易】两个开关在旧密钥上的规则;页面顶部的日期是 2026-05-22,截于 2026 年 10 月

对接工具来说,这一条影响的不只是开关。同一页说明,开通统一账户后,fapi 与 dapi 这两组合约接口只能用来取市场数据,交易和用户数据相关的端点不能再用;统一账户有自己的一组 PAPI 端点。所以开了统一账户以后,新建一把密钥并不等于万事大吉,还要问工具一句:它下单走的是 PAPI,还是仍然走 fapi / dapi?只支持后者的工具,在统一账户下换几把密钥也下不了单。

启用统一账户模式的帮助页(英文版标题 How to Activate the Portfolio Margin Mode on Binance)还有一句建议:启用或停用统一账户模式后,重新创建 API 密钥,以免 API 访问中断。打算开统一账户之前,先把连在这个账户上的工具列一遍,哪些会受影响心里有数,再动手。

除了读取全是灰的:没有设置 IP 访问限制

这种情况不只针对合约。创建密钥那页常见问题的第一条就是“为什么无法启用除读取之外的任何权限?”,回答是:无 IP 访问限制的 HMAC API 密钥除读取权限之外没有任何权限;要启用提现权限,还必须添加 IPv4 格式的 IP 访问限制。

币安帮助中心《如何在币安创建API密钥》公开页面,显示最后更新时间 2025 年 3 月 20 日、创建前需充值激活并完成身份认证的提示,以及常见问题第一条“为什么无法启用除读取之外的任何权限”
创建 API 密钥的帮助页:红字是建密钥前的两个前提,下方常见问题第一条解释了为什么只剩读取可勾;截于 2026 年 10 月

HMAC 是币安系统生成的那种密钥。自行生成 Ed25519 或 RSA 密钥对、只把公钥交给币安的是另一类,选哪种先看工具支持什么,见密钥类型那篇。

补 IP 限制时,填的是真正发出请求的那台机器的出口地址。工具跑在云端,就要工具方给出它的固定出口;地址填错的结果是开关能勾了,请求却一样被拒。怎么找出口、出口变了怎么办,IP 白名单那篇一步步讲过。

新建密钥之前,问清工具到底要哪几个开关

既然前两种情况都要新建密钥,新建这一刻就是收窄权限的好时机。开发者文档“查询 API 密钥权限”返回的字段,正好对应 API 管理里的几个开关,可以拿来和工具方逐项对:

  • enableReading:读取。几乎所有工具都要。
  • enableSpotAndMarginTrading:现货与杠杆交易。只做合约的工具,不一定需要它。
  • enableFutures:合约。U 本位、币本位合约下单要它;统一账户下不适用。
  • enablePortfolioMarginTrading:统一账户交易。只有工具支持 PAPI 时才有意义。
  • enableMargin:杠杆借贷、还款与划转,和“现货与杠杆交易”是两个开关。
  • permitsUniversalTransfer:万向划转。工具声称会自动在现货和合约之间调资金时才涉及。
  • enableWithdrawals:提现。交易工具不应该要它。

对不上的,就是需要追问的。比如一个只跑 U 本位合约的工具同时要求杠杆借贷和万向划转,可以请它说明具体调用了哪个接口、为什么需要;说不清楚的开关先不勾,等它报错再按报错补,比一次全开容易收拾。只读、交易、提币三档的区别,在权限选择那篇里有更完整的对照。

开发者文档里还有一个容易被忽略的字段:ipRestrict,表示这把密钥有没有绑定 IP。新密钥建好后请维护者查一次,ipRestrict 为 true、enableWithdrawals 为 false,再开始跑。

换上新密钥后,旧的那把怎么处理

旧密钥勾不上合约,不代表它没有用处,也不代表它没有风险:它可能仍带着读取或现货交易权限,还连在别的看板上。新旧交替的顺序可以这样排:

  1. 建新密钥,只勾工具确认要用的开关,绑好 IP。
  2. 在工具里替换成新密钥,先跑一次读取,再小额验证合约接口能通。
  3. 确认没有别的工具还在用旧密钥,然后删除它。

做完第 2 步别停。旧密钥如果只是“不再用了”而没删,就成了一把谁也不记得的钥匙。计划轮换和疑似泄露的处理顺序不一样,详细的切换与验证步骤见密钥轮换那篇。

想把合约工具单独放进子账户时

合约工具出错的代价往往比现货工具大,可以考虑单独开一个子账户把它圈起来。子账户密钥的建法、主账户能改什么、怎样收尾,见子账户 API 密钥那篇。

要提醒的是顺序。帮助中心那句“密钥早于合约账户就无法启用合约”没有区分主账户和子账户,下面这一点是我们的判断,不是官方原文:给子账户建密钥之前,先确认这个子账户自己的合约账户已经开通,免得建完才发现又是一把勾不上合约的密钥。

按用途核对该给哪些开关,可以用权限检查先过一遍,再去 API 管理里新建。

按用途核对需要的权限 ↗

继续阅读

05 · API 密钥轮换与撤销

计划换钥匙,还是马上撤销?两种 API 密钥处理顺序

区分正常维护与疑似泄露,整理切换依赖、读取验证和旧凭证清理,避免把新秘密放回旧漏洞。

阅读指南 ↗
02 · API 权限怎么选

云端工具的 IP 白名单填谁?从请求出口找答案

分清浏览器、云端服务器和请求出口,核对 IP 来源、迁移通知与连接测试。

阅读指南 ↗