欧易 API · 密钥安全
欧易 API Key 绑定 IP 白名单的步骤与 14 天自动删除规则
创建 API Key 时把「IP 地址白名单」留空、又勾了交易权限,这把 Key 只要连续 14 天没有一次需要鉴权的调用,就会被系统自动删除。网格脚本停了两周、再启动时鉴权失败的,先去 Key 列表看看它还在不在。
脚本跑在出口 IP 固定的 VPS 或云服务器上,就把这台机器的公网出口 IP 绑进 Key:到那台机器上查出口地址,在创建或编辑 Key 的页面填进白名单,再从同一台机器调一次 GET /api/v5/account/config,确认返回的 ip 字段里有这个地址。家里宽带这种出口会变的网络,下文单独讲怎么取舍。
不绑 IP 的 API Key 什么情况下会被删
| 规则出自 2026 年 11 月 10 日的欧易帮助中心 《欧易 API 常见问题》与 API v5 文档 | |
|---|---|
| 条目 | 规则 |
| 会被自动删除的 Key | 未绑定 IP,且具有交易或提币权限 |
| 删除时限 | 14 天无活动 |
| 怎样算有活动 | 调用需要身份认证的私有或账户相关接口,例如查看账户余额、账单数据、下单 |
| 不算使用 | 调用不需要鉴权的接口,即使请求里带了 Key 信息 |
| WebSocket | 只有登录这一步算使用了 Key;登录后在连接上订阅、下单都不算 |
| 模拟盘的 Key | 不会被删除 |
| 每把 Key 能绑的 IP | 最多 20 个,用逗号或空格分隔;支持 IPv4、IPv6 和网段格式 |
| 每个账户能建的 Key | 最多 50 个(超出返回 59501) |
| 查看未绑 IP 的 Key 用过没有 | 有交易或提币权限、未绑 IP 的 Key,使用记录可以在安全中心查 |
帮助中心同一问里还有一句:「只有绑定了 IP 或特定权限的只读 API 密钥才不会过期。」英文版是 Only read-only API keys bound to an IP or specific permissions will not expire. 这句断句有歧义,单看它说不清绑了 IP 的交易 Key 算不算「不过期」。能确定的是上面那条删除规则的条件:未绑 IP,并且有交易或提币权限,两条同时成立才会被删。给交易 Key 绑上 IP,第一个条件就不成立了。
白名单还有另一层用处:请求的来源 IP 不在名单里,接口返回 50110,Key 即使被别人拿到,换一台机器也调不通。权限本身怎么勾,见API 密钥泄露会发生什么:权限设计与最小授权。
出口 IP 会变或用第三方软件时怎么取舍
出口 IP 固定的服务器,直接绑,这是最省心的一种。下面几种情况要多想一步。
家里宽带、手机热点这类出口地址会变的网络:绑死一个 IP,换了地址脚本就报 50110。可以把脚本挪到有固定公网 IP 的 VPS 上再绑;白名单也接受网段格式,但网段写得越宽,白名单挡人的作用就越弱。实在要留空,就别给这把 Key 开提币权限,并让脚本在 14 天内至少有一次需要鉴权的 REST 调用,查一次余额就算。
接第三方量化软件:帮助中心在 50110 那一问里写的是,Key 类型和第三方软件绑定不兼容时可能出现这个错误,可以试着申请交易类型、不绑定 IP 列表的 Key 再重新连接。走这条路的 Key 落在上面那条删除规则里,要靠软件持续调用来维持;另一种做法是向软件方要它的服务器出口 IP 来绑,报错码 50118 说的就是这种情况:To link the app using your API key, your broker needs to share their IP to be whitelisted.
子账户:在目标子账户下单独创建 Key,用这个子账户自己的权限、密码短语和站点域名,不要和母账户的 Key、Secret、密码短语混用。用接口给子账户建 Key 的,发起请求的母账户 Key 必须已经绑定 IP。
VPS 的公网出口 IP 怎么查
交易所看到的是请求离开你这台机器时的公网地址,不一定是 ip addr 里列出的网卡地址,有的云服务器网卡上只配了内网地址。最直接的办法是在跑脚本的那台机器上,用回显公网 IP 的服务问一次:
curl -4 ifconfig.me
curl -6 ifconfig.me
第一行查 IPv4,第二行查 IPv6。两行都有结果,说明这台机器可能从任一协议出去,把两个地址都绑上,省得某天切到 IPv6 就被拒。第二行报错或超时,说明没有可用的 IPv6 出口,只绑 IPv4。
脚本走了代理的,出口是代理的地址:把同样的 curl 套上脚本用的那个代理再查一次,绑代理的出口。Docker 容器里跑的,在容器里执行这两行,结果和宿主机不一定相同。
在创建或编辑 Key 的页面填进 IP 白名单
新建一把 Key 的入口:
- App:登录后点左上角的九宫格,往下滑点【API】,再点【创建 API key】;依次填写【备注名】、点选【账户】及【用途】、输入【IP 地址白名单】、点选【权限】、输入【密码短语】。
- 网页:点右上角头像,进【API 与连接】,点【创建 API key】;填写的项目和 App 一样。
已经在用的 Key 不必重建:进【个人资料】>【API】,在列表里点开那一把,可以编辑名称、权限(读取、交易、提币)和绑定的 IP 地址。IPv4 和 IPv6 两个地址都要绑的,填在同一栏,中间用逗号或空格隔开。
只有新建时要留意两件事。密码短语建完以后看不到,忘了只能删掉重建;创建还有一个门槛,账户资产管理规模(AUM)要大于 100 美元,英文版帮助页注明这条只适用于部分地区的用户。
绑完从那台机器调一次 account/config 核对
GET /api/v5/account/config(查看账户配置)的返回里有两个字段正好用来核对:ip 是这把 Key 绑定的 IP,多个用逗号隔开,没绑时是空字符串;perm 是它的权限,取值 read_only、trade、withdraw。这个接口限速 5 次 / 2 秒。用官方 Python SDK 调用是这样:
import okx.Account as Account
flag = "0" # 实盘 "0",模拟盘 "1"
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
cfg = accountAPI.get_account_config()
print(cfg)
在绑定的那台机器上跑:返回的 code 为 0,data 里的 ip 能看到刚才查到的地址,perm 和你勾的权限一致,就绑对了。再换一台没绑的机器跑同一段,应当返回 50110。两边结果都对上,白名单才算真正生效。
绑 IP 前后报 50110、50111 等错误时怎么排查
| 下表按 欧易 API v5 文档 Error Code 表与帮助中心《欧易 API 常见问题》整理,两处页面均为 2026-11-10 读到的内容 | ||
|---|---|---|
| 接口返回 | 卡在哪里 | 接下来怎么办 |
| 50110 Your IP {param0} is not included in your API key's IP whitelist. | 请求的出口 IP 不在这把 Key 的白名单里 | 回到跑脚本的机器重查出口 IP(IPv6、代理、容器都查),编辑 Key 补上 |
| 50111 Invalid OK-ACCESS-KEY. | 请求头里的 Key 无效 | 到【个人资料】>【API】看这把 Key 还在不在;不在了就新建并绑 IP,在的话核对复制时有没有多带空格 |
| 50119 API key doesn't exist | 账户所在站点和请求的域名不匹配 | EEA 用户改用 eea.okx.com,美国用户改用 us.okx.com,不要再请求 www.okx.com |
| 50101 APIKey does not match current environment. | Key 和实盘 / 模拟盘环境对不上 | 实盘 Key 配请求头 x-simulated-trading: 0,模拟盘 Key 配 1 |
| 50102 Timestamp request expired. | 请求时间戳和服务器时间相差超过 30 秒 | 时间戳一律用 UTC,下单前用 GET /api/v5/public/time 同步 |
| 59503 Each API key can bind up to 20 IP addresses | 绑定的地址超过 20 个 | 删掉不用的旧地址,或者把同一网段的地址合成一条网段写法 |
换了 VPS 之后报错,先对 50110 这一行:新机器的出口地址可能还没加进去。把出错的接口、错误码原文和发生时间记下来,需要找 API 客服时直接给;Secret、密码短语和未脱敏的签名任何时候都不要发出去。地址和域名本身该填哪个,见欧易 API 地址现在填哪个?REST、WebSocket 与模拟盘(2026)。
已经在跑的 Key 什么时候需要重新改
用 WebSocket 下单的机器人会被当成 14 天无活动吗?
只靠 WebSocket 下单、又没绑 IP 的 Key 有这个风险:文档的说法是 WebSocket 只有登录那一步算使用了 Key,登录后在连接上订阅、下单都不算。这种 Key 可以让脚本定期调一次需要鉴权的 REST 接口,比如查余额,或者直接给它绑上 IP。
换了 VPS 要重新创建 API Key 吗?
不用重建,进【个人资料】>【API】点开那把 Key,编辑绑定的 IP 地址,加上新机器的出口 IP、删掉旧的就行,每把 Key 最多 20 个地址。改完从新机器调一次 GET /api/v5/account/config,看返回的 ip 字段里有没有新地址。