欧易 API 量化入门:从申 Key 到跑通第一个下单脚本

你大概是这样到这儿的:看了几个量化博主的收益截图,心动了,打开欧易后台准备动手,结果第一关就卡住——「API 管理」点进去一堆选项,apiKey、Secret、Passphrase、读取、交易、提现、IP 白名单,每个词都认识,连起来不知道该怎么填。然后你关掉页面,告诉自己「以后再说」。

这篇就是帮你把这关过掉。我们(量化喵编辑组)把从零开 API 到用 Python 跑通第一个下单脚本的全过程拆成几步,每一步都自己做过一遍,包括那些官方文档不会写、但你十有八九会撞上的坑。读完你应该能:在欧易后台正确建一个安全的 API Key,用十几行代码确认它通了,然后在模拟盘里下出、撤掉你的第一个委托单。不需要你是程序员,跟着抄就行。

先问自己:你真的需要 API 吗

这是被大多数教程跳过、却最该先想清楚的问题。开 API、写脚本是有成本的——你要装环境、调代码、防着自己手滑下错单。如果你的需求其实很简单,完全可能不用碰 API。

欧易后台自带的「策略交易」里有现成的网格机器人、DCA 定投、合约套利这些工具。你在网页或 App 上点几下设好参数,它就替你跑,不用写一行代码。对绝大多数刚入门、只想让程序帮忙挂买卖单的人来说,内置机器人够用了,而且出问题时有界面能直接看、直接停。

那什么时候才值得开 API?我们的判断是这几种情况:

• 你想要的策略逻辑内置机器人做不到,比如根据某个指标动态调仓、跨多个币种联动。
• 你要做回测,需要批量拉历史 K 线、模拟成交。
• 你想同时跑好几套策略,用脚本统一管理比手点高效。
• 你单纯想学量化,把交易所当成练手的沙盒。

如果你对号入座了,那继续往下读。如果你发现自己其实只是想「挂个网格睡觉时帮我赚震荡」,那不妨先去后台开个内置网格试试,等真碰到内置工具的天花板,再回来开 API 也不迟。我们另有一篇专门讲网格机器人参数怎么设,适合走这条路的你。

开 Key 之前要懂的三件事

真正动手建 Key 之前,有三件事你得先搞明白。不懂这三件事就去点「创建」,大概率不是连不上,就是给自己埋了安全隐患。

① 你会拿到三个凭证,不是两个

很多人以为 API 就是「一个账号一个密码」,到了欧易这儿会愣住——它给你三样东西:

• apiKey:这个 Key 的公开标识,相当于「用户名」。
• secret(Secret Key):用来给请求签名的密钥,相当于「密码」,只在创建时显示一次。
• Passphrase:你创建时自己设定的一串口令,欧易特有。

第三个 Passphrase 是新手翻车的重灾区。它不是你登录欧易的账户密码,而是你建这个 Key 时另外设的一串字符。更坑的是,在 Python 的 ccxt 库里,这个字段不叫 passphrase,而叫 password。于是无数人想当然地把登录密码填进去,然后对着「鉴权失败」的报错抓耳挠腮。记住一句话就行:ccxt 里的 password = 你建 Key 时设的 Passphrase。

② 权限只勾「交易」,绝不勾「提现」

建 Key 时欧易会让你选这个 Key 能做什么,主要有三档:

• 读取:查行情、查余额、查订单。最低风险。
• 交易:下单、撤单、改单。跑策略必需。
• 提现:把币转出账户。

这里有一条几乎没有例外的安全底线:跑量化的 Key,只勾「读取」和「交易」,永远别勾「提现」。道理很直接:勾了提现,泄露就等于把保险柜钥匙交出去;不勾,别人至少没法直接把币提走。但别把「不勾提现」当成保险 —— 只带交易权限一样能让你亏光:拿到 Key 的人可以在冷门、盘口薄的交易对上主动挂单成交、自己在对手方接盘,你的本金以「交易亏损」的形式流走,而账单上看起来全是正常成交,事后追也比可疑提现难得多。所以真正管用的是三条叠着用:不勾提现、绑 IP 白名单、定期换 Key。自动化交易根本用不到提现这个动作,所以这个权限对你只有坏处没有好处。

③ IP 白名单要不要设

欧易允许你给 Key 绑定 IP 白名单——只有来自指定 IP 的请求才被接受。这是一道很值的额外保险。

判断标准很简单:如果你的脚本跑在一台 IP 固定的机器上(比如云服务器、家里宽带是固定公网 IP),那就把这个 IP 加进白名单,安全性立刻上一个台阶。如果你在自己电脑上跑,而家里宽带 IP 经常变,那设了白名单反而会因为 IP 变动天天被拒,反复折腾。这种情况可以先不设,但务必把凭证保管好。等你把脚本搬到固定 IP 的服务器上长期跑时,再补上白名单。

在欧易后台申请 API Key

三件事懂了,现在去后台建 Key。下面是真实路径,以欧易当前后台为准(界面偶有微调,但逻辑不变):

1. 登录欧易(OKX),把鼠标移到右上角你的头像,在下拉菜单里找到「API」或「API 管理」,点进去。
2. 进入 API 管理页,点「创建 API Key」。如果它问你用途,选自用交易类即可,不要选第三方接入。
3. 给这个 Key 起个名字(备注),比如 meow-grid-bot,方便你以后一眼认出它是干嘛的。
4. 设置 Passphrase。这一步是你自己定一串口令,记牢它——后面 ccxt 要用,而且它只跟这个 Key 绑定,弄丢只能删了重建。
5. 勾选权限:勾「读取」和「交易」,不勾「提现」。(参照上一节的底线。)
6. 如果你在固定 IP 的机器上跑,填 IP 白名单;不确定就先留空。
7. 点确认,通过二次验证(手机 / 邮箱 / 谷歌验证器)。
8. 页面会显示 apiKey 和 Secret Key。Secret 只显示这一次,马上复制保存到安全的地方。关掉页面就再也看不到了,丢了只能删 Key 重建。

到这一步,你手上应该有三样东西了:apiKey、Secret、还有你刚才自己设的 Passphrase。把它们存进一个本地的、不会被同步上传的文件里——别截图发微信,别贴进任何在线笔记。下一步我们就用这三个凭证去连。

用 Python + ccxt 连上,确认通了

凭证到手,接下来是验证它真的能用。我们用 ccxt 这个库——它把上百家交易所的 API 封装成了统一接口,你不用去啃欧易的原始签名细节,几行代码就能查余额、下单。

先装库。打开终端(命令行)敲:

pip install ccxt

装好后,新建一个文件 okx_check.py,把下面这段抄进去,把三个引号里的占位换成你自己的凭证:

import ccxt

# 三个凭证:apiKey、secret、password(=Passphrase)
okx = ccxt.okx({
    'apiKey':   '你的_apiKey',
    'secret':   '你的_secret',
    'password': '你的_Passphrase',   # 欧易特有,新手最常漏的就是它
})

# 拉账户余额,确认鉴权通过
balance = okx.fetch_balance()
print('USDT 可用:', balance['USDT']['free'])
print('USDT 总额:', balance['USDT']['total'])

保存,在终端里跑 python okx_check.py。如果它打印出了你的 USDT 余额(哪怕是 0),恭喜,鉴权通了,API 连上了。如果它报错,先别慌——八成是三个凭证里有一个填错或填漏了,翻到本文「新手最常踩的几个坑」一节对照排查,那里列了每种报错对应的原因。

多说一句关于凭证存放:上面为了讲清楚,把凭证直接写进了代码里,但这只适合你本地一次性测试。一旦脚本要长期跑、甚至放到服务器上,就别把凭证写死在代码里——改用环境变量或单独的配置文件,并确保这个文件不会被同步、不会被提交到代码仓库。这是把账户被盗概率降到最低的关键习惯。

第一个下单脚本:下单与撤单

能查余额,说明读取权限正常;现在试交易权限——下一个委托单,再把它撤掉。这里我们用限价单而不是市价单,因为限价单你能自己定价,把价格定得离市价远远的,它就不会立刻成交,方便你练习下单和撤单而不会真花钱。

下单前要先搞懂两件小事:

symbol(交易对)怎么写。在 ccxt 里,现货交易对统一写成 基础币/计价币 的格式,比如比特币兑 USDT 就是 BTC/USDT,以太坊兑 USDT 是 ETH/USDT。注意是正斜杠,大写。写错格式是另一个高频报错来源。

下单参数。ccxt 的下单方法是 create_order(symbol, type, side, amount, price),五个参数分别是:交易对、订单类型(limit 限价 / market 市价)、方向(buy 买 / sell 卖)、数量、价格。

下面这段会下一个故意不会成交的低价限价买单,拿到订单号后立刻撤掉。这段会真的向交易所提交订单,所以下面直接用模拟盘凭证写——模拟盘 Key 怎么建、sandbox 开关是什么意思,下一节展开:

import ccxt, time

# 🔴 这一段会真的下单,所以凭证必须填模拟盘(Demo Trading)那把 Key。
#    模拟盘的 Key 要在模拟交易环境里单独创建,实盘那把不是同一套。
okx = ccxt.okx({
    'apiKey':   '模拟盘的_apiKey',
    'secret':   '模拟盘的_secret',
    'password': '模拟盘的_Passphrase',
})

# 关键一行:不加这行,下面的下单就是拿真钱在实盘挂单
okx.set_sandbox_mode(True)

# 自检:必须打印 1,打印 None 就别往下跑
print(okx.headers.get('x-simulated-trading'))

symbol = 'BTC/USDT'

# 下一个故意不成交的限价买单:价格远低于市价
order = okx.create_order(
    symbol=symbol,
    type='limit',
    side='buy',
    amount=0.0001,     # 数量很小,先以最小可下单量为准
    price=20000,       # 远低于当前 BTC 市价,挂着不会成交
)
order_id = order['id']
print('已下单,订单号:', order_id)

time.sleep(2)

# 把刚才的单撤掉
canceled = okx.cancel_order(order_id, symbol)
print('已撤单:', canceled['id'])

跑通后你会看到两行输出:先是订单号,两秒后是撤单确认。这说明你的脚本已经能完整地「下单—撤单」了,量化最基础的两个动作齐了。剩下的策略——网格、定投、对冲——本质上都是在这两个动作上加判断逻辑和循环而已。

关于 amount(数量):每个交易对都有最小下单量和精度限制,填太小会被交易所拒。如果报「数量不符合规则」,可以先用 okx.load_markets() 查一下这个交易对的 limits 和 precision,按它要求的最小值来填。

先上模拟盘:用假钱跑通

上面所有代码,我们强烈建议你先在模拟盘跑,确认一切正常再切真金。模拟盘用的是虚拟资金,下错单、写错逻辑都不会让你真亏钱——这是入门阶段最划算的一步,几乎没有理由跳过。

欧易的模拟盘叫 Demo Trading(模拟交易),在 App 和网页端都能切换进去。要注意的是:模拟盘要用它自己的 API Key——官方给的路径是在模拟交易里单独创建一把 Demo Trading API Key,而不是给实盘 Key 加个开关。凭证换好之后,让 ccxt 走模拟盘只要在初始化后打开 sandbox 开关:

import ccxt

# 注意:这三项填模拟盘(Demo Trading)那把 Key,不是实盘的
okx = ccxt.okx({
    'apiKey':   '模拟盘的_apiKey',
    'secret':   '模拟盘的_secret',
    'password': '模拟盘的_Passphrase',
})

# 关键一行:让 ccxt 给后续请求带上模拟盘标记头
okx.set_sandbox_mode(True)

# 自检:这一行必须打印 1,否则你还在实盘
print(okx.headers.get('x-simulated-trading'))

# 之后所有请求都带模拟盘标记,用的是虚拟资金
balance = okx.fetch_balance()
print('模拟盘 USDT 可用:', balance['USDT']['free'])

别拿配置里的 sandboxMode 代替这一行:模拟盘标记头是 set_sandbox_mode() 方法自己加的,写在构造函数的 options 里不会触发它,请求照样打在实盘上。确认那句 print 打出 1 之后,前面那个下单—撤单脚本你就能放心地反复跑了:就算手滑把价格写成市价附近、真成交了,花掉的也是虚拟 USDT。

一个值得养成的习惯是:任何新策略、任何改过的代码,都先在模拟盘连续跑够一段时间,确认下单回调、撤单、余额变化都符合预期,再把那行 set_sandbox_mode(True) 去掉、凭证换回实盘那把 Key,切到实盘,而且第一次上实盘只用很小的金额。这个顺序能救你好几次——很多逻辑 bug 都会在模拟盘阶段就暴露,要是直接上真金,代价不止是钱。

新手最常踩的几个坑

这一节是这篇文章最该收藏的部分。下面每一条都是社群里反复出现的高频报错,对照着排查能省你几个小时。

Passphrase 漏填 / 填错(最高频)

报错通常是鉴权类的(类似 "Invalid sign" 或 "passphrase incorrect")。检查 ccxt 里的 password 字段填的是不是你建 Key 时设的那串 Passphrase,而不是登录密码、也不是 secret。这一条占了新手鉴权失败的一大半。

时间戳错误 / 请求过期

欧易对请求时间戳有容差,如果你电脑或服务器的系统时间不准(偏差超过几十秒),签名会因为时间戳过期被拒。解决办法是把系统时间同步到准确的网络时间(开 NTP 自动校时)。云服务器一般默认开了,本地机器偶尔会漂。

权限不足

能查余额却不能下单,基本就是建 Key 时只勾了「读取」没勾「交易」。回 API 管理里给这个 Key 补勾交易权限即可,不用重建。

触发限频(Rate Limit)

如果你在循环里疯狂查行情或下撤单,会撞上接口限频,报 "Too Many Requests" 之类。最省事的办法是在初始化时打开 ccxt 的限速:ccxt.okx({..., 'enableRateLimit': True}),它会自动帮你在请求间插入间隔。别用 while True 不加任何延时去打接口。

symbol 写错

把 BTC/USDT 写成 BTCUSDT、btc/usdt、或者用了合约的格式去下现货单,都会报「交易对不存在」。记住现货是 大写/大写 带斜杠;拿不准就先 print(okx.load_markets().keys()) 看看可用的交易对到底长什么样。

IP 不在白名单

设过白名单的人,换了网络环境(比如开了代理、或者宽带 IP 变了)就会被拒。确认你当前的出口 IP 还在那个 Key 的白名单里,不在就去后台更新名单。

风控与心态:量化不等于稳赚

能跑脚本了,我们得给你泼盆冷水。把交易交给程序,不会让你自动赚钱——它只是把你的决策执行得更快、更不掺情绪。如果你的策略本身是亏的,自动化只会让你亏得更快、更稳定。

而且 API 自动化有它独有的风险:程序不会像人一样犹豫。一个写错的循环、一个搞反的买卖方向、一个少打了小数点的数量,人手动操作时可能在按下确认前就发现了,脚本却会忠实地、连续地把错误执行几十遍。我们在模拟盘阶段就见过自己写的循环因为一个判断条件写反,几秒内挂出一串本不该挂的单。要是在实盘,那就是真金白银的损失。

所以给刚上手的你几条实在的建议:

• 先小额。第一次上实盘,用你就算全亏了也不心疼的金额。把它当学费,不当本金。
• 设好仓位上限。在脚本里写死单次和总持仓的上限,别让程序有机会把你全部资金压上去。
• 留止损。无论策略多好看,给它配一个明确的止损或最大回撤线,触发就停。
• 合约和杠杆慎碰。本文讲的都是现货。带杠杆的合约能在极短时间内让本金归零,新手阶段强烈建议先只做现货,把流程和心态练稳再说。
• 看着它跑一阵。新策略上实盘的头几天,别真的撒手不管,盯着它,确认它的行为和你在模拟盘看到的一致。

常见问题

把 API 这关过掉之后,你接下来大概会想找个具体策略练手。我们建议从最好理解的网格机器人开始,或者先用小工具把参数和手续费算清楚再动手。无论走哪条路,记住今天这篇的顺序:先模拟盘,再小额实盘,先活下来,再谈收益。