chrisleekr/binance-trading-bot · 账户接入与授权
binance-trading-bot 接入币安：API Key 权限与 IP 白名单怎么配
机器人不用你的账户密码，它只通过币安 API Key 操作账户。Key 的权限勾选与 IP 白名单，是整个部署里最关键、也最容易配错的一步：多勾一项就多一份泄露风险，少勾一项订单会被币安直接拒绝。本页把官方 install 文档第 6–7 步、用户指南的 API key 页与官方排错文档里的相关内容，整理成一份可照做的中文清单。
最小权限接入流程
权限怎么勾：四项开关，一项都不能凭感觉
官方 install 文档第 6 步只要求两件事：勾选「读取」和「现货与杠杆交易」，并把提现关掉；再加上 IP 白名单，接入部分就算配置完成。下表把每一项的取舍与后果写清楚，照着核对即可。
| 权限 / 设置项 | 勾还是关 | 为什么 | 不这样做的后果 |
|---|---|---|---|
| Enable Reading（读取） | 勾 | 读取钱包余额与账户快照是运行的基线能力：下单前的可用资金判断、持仓对账、账户健康条都依赖它 | 机器人看不到余额与账户状态，无法判断能下多大的单，也无法把钱包里的真实持仓和本地记录对齐 |
| Enable Spot & Margin Trading（现货与杠杆交易） | 勾 | 下单与撤单所需的最低权限，官方 install 第 6 步明确要求同时开启这一项 | 订单会被币安拒绝，典型表现是返回 -2015；界面上看起来一切都配好了，但机器人就是不动 |
| Enable Withdrawals（提现） | 关 | 机器人永远不需要提现功能，官方明确要求保持关闭 | 多出来的这一项权限只增加泄露后的损失面：拿到 Key 的人可以直接把资产转走，而机器人本身用不到 |
| Restrict access to trusted IPs only（IP 白名单） | 开 | 官方把「单租户部署 + 币安 IP 白名单」列为密钥泄露后的主要缓解措施，因为库里的 Key 是明文 | 不开白名单，任何拿到 Key 的人在任何一台机器上都能操作你的账户 |
| 服务器出口 IP（加进白名单） | 填 | 只允许你自己的服务器发起调用；在服务器上执行 curl -s ifconfig.me 就能看到当前出口 IP | 漏填或填错会导致全部调用被拒（同样是 -2015）；换机器、换机房或换出口网络后 IP 变化，也会立刻失效 |
| 其他高级权限（如提现之外的额外开关） | 关 | 内置的三套策略只做币安现货买卖，用不到更多权限，最小权限原则在这里是硬要求 | 权限大于实际需要：一旦 Key 泄露，损失范围会超出这台机器人的能力边界 |
| 这把 Key 的使用范围 | 只给这一个实例 | 一机一 Key，便于事后审计与泄露后轮换 | 多个应用共用一把 Key 时，轮换要同时改多处，而且无法判断异常调用来自谁 |
接入币安的六个步骤
全程都在做两件事：在币安侧把权限收窄到刚好够用，在应用侧把 Key 交给机器人并由它当场校验。每一步都给出预期结果，方便你确认自己走对了。
在币安创建 API Key
打开币安的 API Management，新建一把 Key，把 Key 与 Secret 复制到一个临时安全的地方（Secret 只显示一次）。
预期结果：拿到一对 Key 与 Secret；此时还不要粘贴到任何地方，先按下一步收窄权限。
勾两项权限，关掉提现
勾选 Enable Reading 与 Enable Spot & Margin Trading，确认 Enable Withdrawals 没有勾选。这一步是官方 install 第 6 步原文要求，别跳。
预期结果：编辑页上只亮着两项权限，提现开关处于关闭状态。
取服务器的出口 IP
登录你将要跑机器人的那台服务器，执行下面这条命令，把返回的 IP 记下来。注意是服务器的出口 IP，不是你本地电脑的。
shell · 在服务器上执行curl -s ifconfig.me预期结果：返回一个公网 IP，例如
203.0.113.10。这就是要加进白名单的地址。开启 IP 白名单并填入该地址
在币安 API Management 中编辑这把 Key，打开 Restrict access to trusted IPs only，把上一步的 IP 加进去，保存。
预期结果：白名单列表里出现该 IP；如果你打算换机器，先把新 IP 也加上再切换，避免中间出现调用全被拒的窗口。
在应用里粘贴 Key 与 Secret
打开面板，进入该账户的 API keys 页面，把 Key 和 Secret 粘进去保存。粘贴时不要带引号或前后空格——这是
-2014最常见的成因。预期结果：应用会立刻拿这对凭据向币安校验一次，并在页面上显示状态；校验通过时状态灯变绿。
状态不是绿色时按下一节逐条排查
红色状态通常只对应三种情况：权限不对、白名单不匹配、或者 Key 已被撤销或过期。先看下一节的对照表，再去改配置，不要盲目重建 Key。
预期结果：状态变绿后，这个账户就可以开始建 Profile 了。
状态灯与报错对照表：看到什么，改什么
下面每一条都来自官方 install、deploy 与排错文档中出现过的真实症状。排查原则是先确认「权限—白名单—Key 状态」这三项，再去怀疑策略或预算。
| 现象 / 报错原文 | 真实原因 | 处置 |
|---|---|---|
币安返回 -2014 | Key 本身的格式不对，最常见的原因是复制时带上了空格或前缀 | 重新粘贴 Key，去掉引号、前后空格与任何多余字符 |
币安返回 -2015 | 调用「被配置拒绝」：服务器的出口 IP 不在该 Key 的白名单里，或者这把 Key 缺少现货交易权限 | 回到前两节：先在服务器取出口 IP 并确认已在白名单中，再确认两项权限都已勾选 |
| 面板上 Key 状态不是绿色 | Key 被撤销或过期，或权限、白名单与当前服务器不匹配 | 创建一把新 Key 重新粘贴；应用在你保存时会立即向币安校验并刷新状态 |
| 订单被币安拒绝 | 订单不满足交易所规则，例如金额低于最小下单额，或价格离市价太远 | 到该 Profile 的 History → Logs 看币安返回的原文原因；展开该行的 Context 可以看到完整拒绝负载，再据此调整预算或步长 |
| 保存后出现「order sizing was not verified」告警 | 保存本身是成功的，服务端只是没能完成「这套设置到底能不能下出单」的预检——它需要该币的交易规则与当前价，而这两项都来自短期缓存 | 不需要重做刚才的修改，也不会回滚任何东西；按下面三条文案分别处理 |
Binance … trading rules have not loaded yet | 该币的交易规则不在缓存里 | 后台会自行刷新，通常在应用启动后几分钟内完成；稍等再打开该页或重新保存一次即可拿到预检结果 |
No … price is cached for this symbol yet | 这个币还没有缓存价格——价格只为正在运行的 Profile 关注的币保留 | 刚加的币出现这条属正常。把该 Profile 启用、让它开始跟踪这个币之后，价格就会出现在缓存里 |
These settings could not be read by the strategy that would run them | 保存下来的设置与该 Profile 的策略期望不再匹配，通常发生在切换策略之后 | 打开该 Profile 的 Strategy 区，重新保存一次配置，把它对齐回当前策略 |
Key 是填在哪儿、由谁校验
官方文档给出的账户 API Key 页面截图。截图取自官方文档、内容为种子演示数据，但它能说明流程的关键一点：Key 填在应用里，由应用直接向币安校验，而不是让你自己去判断配得对不对。
测试网、实盘与 LIVE_DEMO 沙盒的边界
这套系统把「环境」做成了账户的属性：一个币安账户就是一套 API Key 对、一个环境（测试网或实盘）、一个钱包。三者的边界与后果如下。
| 环境 / 开关 | 它是什么 | 边界与后果 |
|---|---|---|
| 实盘账户（live） | 一个币安账户 = 一套 API Key 对 + 一个环境 + 一个钱包；实盘账户下单动的是真实资金 | 官方在 README 与文档首页都明确不建议投入真实资金；无通知器的实盘 Profile 会在面板上告警 |
| 测试网账户（testnet） | 币安的练习环境，与实盘是两个环境、两个钱包，需要单独的凭据 | 面板顶部的「今日盈亏」在测试网账户上不显示——练习盈亏不会被当作真实收益展示；测试网的盘口深度与真实市场不同，跑得顺不代表实盘一样 |
LIVE_DEMO=1 | 把实例变成公开沙盒：免登录（每个请求注入唯一 operator），凭据/通知器/备份恢复/建号改号删号/保留期修改等路由返回 403，worker 抑制所有通知发送 | 交易仍然只在币安测试网上进行；只要库里存在任何实盘账户，进程就会拒绝启动；解析严格，只有 1 或 true 生效，false/0/不设置都算关闭 |
| AUTH_SECRET 未修改 | 它是签名登录 Cookie 的密钥，默认占位符故意写得很短 | 短于 32 字符会直接启动失败——这是刻意的，避免带着一个公开已知的密钥把服务跑起来 |
| 单操作员认证模型 | 登录使用 Better Auth，只有一个主账号，没有邮箱验证也没有二次验证 | 没有第二道门，风险集中在「这一个账号 + 币安白名单」上，因此白名单不是可选项 |
./backups/*.dump 与 Postgres 数据卷同样含明文密钥。处置办法：首次运行后执行 chmod 700 ./backups deploy/secrets；把异地备份仓库（官方推荐 restic）当作敏感存储，口令文件不要放在这台服务器上；一旦这两处中的任何一处泄露，唯一的正确动作是去币安轮换密钥，而不是改配置。币已经在手上：怎么告诉机器人成本价
如果你之前就在币安 App 里买过某个币，想让机器人接手管理并负责卖出，就需要把你自己的平均买入价告诉它。这里有个反直觉但很重要的设计：你填的是价格，不是数量。
方式一：加币种时顺手填上
添加币种的界面里有一个选填的 Average entry price 字段。填上它，加币与定成本价一步完成。
预期结果：该币被加入 Profile，同时写入成本价台账。
注意：这条组合路径没有历史台账行可以回退，所以需要 Profile 处于启用状态，机器人才能读到你的余额来完成这一步。
方式二：事后补录或更正
进入该币的 Symbol 页 → Logs 标签 → 打开 Show advanced → Set average entry price。
预期结果：这个动作会写入成本价台账，并给 worker 排一个
apply-avg-entry-price作业，把运行中策略的进场价直接设好，下一个 tick 就开始管理这笔持仓——不需要重启。它也是权威操作：既能给刚接手的币定价，也能更正一个机器人已经在管理的仓位的成本价（普通的 tick 或重新配置都不会覆盖已经定价的仓位）。理解「数量以钱包为准」
机器人每个 tick 都从钱包读取实际持有的数量，并把它当作唯一事实来源；你记录的数量只是一个上界——它永远不会写出超过钱包实际持有量的仓位（允许一个可交易步长的误差）。所以记录填大了也不会虚增策略要卖出的数量。
预期结果：你只需要对价格负责，数量由机器人自己盯着钱包。
出现「Not held — nothing sellable backs this cost basis」时怎么办
这条界面提示的意思是：钱包里这个币少于一个可交易步长，或者只值交易所最小下单额的零头，任何东西都卖不掉，于是机器人没有把仓位交给策略。它仍然保存了你填的价格，你的进场记录不会丢。
预期结果与自动恢复：该提示会在下列任一情况下自行消失——每 15 分钟一次的持仓对账确认钱包已能支撑这个成本价、这个币出现一次买入成交、或你重新保存一次价格。反过来，如果机器人还拿不到该币缓存价、或者从没 tick 过这个币，它会继续等一次「有依据的对账」，而不是在没核对过的情况下把提示清掉。
接入币安的常见问题
可以用币安子账号的 API Key 吗？
官方文档把账户模型描述为「一个操作员登录 → 若干个币安账户，每个账户一套 API Key 对、一个环境、一个钱包」，并没有对子账号做专门说明。不论你用主账号还是子账号，币安侧的权限与白名单要求完全一样：读权限 + 现货与杠杆交易、提现关闭、IP 白名单打开。是否使用子账号、以及子账号的具体能力，请以官方 auth / install 文档与币安官方说明为准。
只给「读取」权限能不能跑起来？
不能。读取权限让机器人看到余额与账户快照，但下单与撤单需要「现货与杠杆交易」权限——官方 install 第 6 步要求两项同时开启。少了后者，订单会被币安拒绝，典型报错就是本文提到的 -2015。权限页面的权威说明请以官方用户指南的 API key 文档为准。
换了服务器或换了网络，Key 突然就用不了了？
多半是出口 IP 变了，原来加进白名单的地址已经不对。在新机器上执行 curl -s ifconfig.me 取当前出口 IP，到币安 API Management 把白名单更新成这个地址（要平滑切换的话，先把新 IP 加上、再删旧 IP），保存后回到应用的账户页重新校验一次即可。以币安与官方 install 文档的说法为准。
Key 泄露了该怎么办？
第一时间去币安撤销这把 Key 并新建一把，只把新 Key 配到这一台服务器上。这不是可以拖的事：官方明确 Key 在数据库里是明文存储，因此 ./backups 里的 dump 与 Postgres 数据卷同样含明文；同时把 deploy/secrets 与 ./backups 的权限收紧到 700，异地备份仓库的口令要单独保管。处置之后建议核对账户健康条与该 Profile 的审计日志，确认期间没有异常下单。具体流程以官方安全与部署文档为准。
测试网可以一直用来练手吗？
测试网与实盘是两套环境、两个钱包，环境在建立账户时确定；练习交易不会动到真实资金，面板也会在测试网账户上隐藏「今日盈亏」，不把练习盈亏当成真实收益。官方文档没有给出使用期限的限制，具体以币安与官方文档为准。需要注意测试网的盘口深度、成交活跃度与真实市场差别很大，在测试网顺利不代表实盘会有同样的体验。
我不想配 API Key，只想先看看行情和做研究，可以吗？
可以走 EasyClaw 的研究路线：本机已核验的财经数据技能里包含加密货币行情查询能力，不需要币安 Key，也不需要服务器；量化研究类技能还能做策略回测与风险指标，出图类技能可以把结果画成图表。但边界要讲清楚：EasyClaw 本机技能中没有下单类技能，也无法管理你的币安账户；binance-trading-bot 与 EasyClaw 之间没有已证实集成，两者是面向不同任务的路线。研究结论仅供研究，不构成投资建议。两条路线的完整对照见对比页。