欧易 · API 下单
欧易永续合约下单时 sz 要填币数除以 ctVal 得出的张数
欧易 POST /api/v5/trade/order 下永续、交割或期权单时,sz 是合约张数。BTC-USDT-SWAP 一张是 0.01 BTC,想开 0.05 BTC 就填 "5";手里是一笔 USDT 预算,还要再除以价格。
报 51000 Parameter posSide error 时,查账户的持仓模式:开平仓模式下 posSide 必须写 long 或 short,买卖模式下不传或传 net。现货和杠杆单不传这个字段。
永续合约的 sz 单位是张,一张多少币要查 ctVal
币币市价单能用 tgtCcy 指定 sz 按哪种货币算,合约单没有这个选项。币币那边的两种取值见欧易 API 市价单 sz 填币数还是 USDT。
一张合约有多大,从公共接口查,不需要身份验证:
GET /api/v5/public/instruments?instType=SWAP&instId=BTC-USDT-SWAP
下表是 2026 年 11 月 2 日接口返回的值。它们会调整,脚本里从接口取,别写成常量。
| 字段 | 含义 | BTC-USDT-SWAP | ETH-USDT-SWAP |
|---|---|---|---|
| ctVal | 合约面值 | 0.01 | 0.1 |
| ctValCcy | 面值的计价币种 | BTC | ETH |
| ctMult | 合约乘数 | 1 | 1 |
| ctType | 合约类型 | linear(正向) | linear(正向) |
| lotSz | 下单数量精度,单位张 | 0.01 | 0.01 |
| minSz | 最小下单数量,单位张 | 0.01 | 0.01 |
| maxMktSz | 市价单单笔最大数量,单位张 | 35000 | 90000 |
| tickSz | 下单价格精度 | 0.1 | 0.01 |
两个合约的 ctMult 都是 1,换算时不影响结果。最小能下 0.01 张,BTC 永续折合 0.0001 BTC,ETH 永续折合 0.001 ETH。限价单的 px 按 tickSz 的精度写;市价单一笔不能超过 maxMktSz 张,数量更大就要拆单。
单位填错时,订单本身可能完全合法。把 500 USDT 预算直接写成 "sz": "500",下的是 500 张 BTC 永续,也就是 5 BTC;按 78,000 USDT 的假设价,面值 390,000 USDT,是预算的 780 倍。反过来,想买 0.01 BTC 却写 "sz": "0.01",下的是 0.01 张,按同一假设价只有 7.8 USDT 面值。
USDT 金额换算成张数要除以 ctVal 和价格
下单接口的说明给了正向合约的面值公式:合约面值 = sz × ctVal × markPx。倒过来就是换算公式,ctType 为 linear 的合约才能这样套:
sz = 币数 ÷ ctVal
sz = USDT 面值 ÷ (ctVal × markPx)
markPx 从 GET /api/v5/public/mark-price?instType=SWAP&instId=BTC-USDT-SWAP 取,这个接口同样不需要身份验证。算出来的数通常不是整数倍,要向下取到 lotSz 的倍数,再跟 minSz 比。价格是假设值,都按 500 USDT 预算算:
| 步骤 | BTC-USDT-SWAP | ETH-USDT-SWAP |
|---|---|---|
| 假设 markPx | 78,000 | 3,000 |
| 一张面值 = ctVal × markPx | 780 USDT | 300 USDT |
| 500 ÷ 一张面值 | 0.6410… 张 | 1.6666… 张 |
| 向下取到 lotSz 的倍数 | 0.64 张 | 1.66 张 |
| 实际面值 | 499.2 USDT | 498 USDT |
脚本里用 Decimal 算,避开浮点误差。接口返回的这些字段本来就是字符串,直接传进去:
from decimal import Decimal, ROUND_DOWN
def usdt_to_sz(usdt, mark_px, ct_val, lot_sz, min_sz):
usdt, mark_px, ct_val, lot_sz, min_sz = (
Decimal(x) for x in (usdt, mark_px, ct_val, lot_sz, min_sz)
)
lots = (usdt / (ct_val * mark_px) / lot_sz).to_integral_value(rounding=ROUND_DOWN)
sz = lots * lot_sz
if sz < min_sz:
raise ValueError("预算不够最小下单数量")
return format(sz.normalize(), "f")
print(usdt_to_sz("500", "78000", "0.01", "0.01", "0.01")) # 0.64
下单前再把 sz 算回面值,和预算比一次。0.64 张算回来是 0.64 × 0.01 × 78,000 = 499.2 USDT,币数是 0.64 × 0.01 = 0.0064 BTC。把金额错写进 sz 时,500 张算回来远超预算,这段校验会让脚本停下:
def check_notional(sz, ct_val, mark_px, budget):
notional = Decimal(sz) * Decimal(ct_val) * Decimal(mark_px)
if notional > Decimal(budget):
raise ValueError(f"面值 {notional} 超过预算 {budget}")
return notional
不想自己换算,可以调张币转换接口,它同样在公共数据模块里:
GET /api/v5/public/convert-contract-coin?type=1&instId=BTC-USDT-SWAP&sz=500&px=78000&unit=usds&opType=open
type:1 是币转张(默认),2 是张转币。unit:usds表示传入的sz是 USDT 或 USDC 金额,coin表示币的数量(默认),只用于 U 本位的交割和永续。px:U 本位合约里,USDT 与张互转时必填,币与张互转时可以不填。opType:open把sz舍位,close四舍五入,默认close。
返回的 sz 就是换算后的张数。开仓记得传 opType=open:上表 ETH 那笔按默认的四舍五入保留到 0.01 张,可能取到 1.67 张,面值 501 USDT,比预算多出 1 USDT。
本地算还是调接口,看下单频率。下单接口限速 60 次/2 秒,按 User ID + Instrument ID 计;张币转换和标记价接口都是 10 次/2 秒,前者按 IP 计,后者按 IP + Instrument ID 计。下单频繁的脚本要是每单都调转换接口,会先碰到它的限速,本地算更合适;低频脚本两种都行。这些限速怎么计算,见欧易 API 限速是多少?下单频率怎么算、报 50061 怎么办。
posSide 报 51000 时先看账户的持仓模式
51000 在错误码表里是通用的「参数错误」,先读返回里的 sMsg,写着 posSide 才是这一节要处理的情况。持仓模式用 GET /api/v5/account/config 查,返回的 posMode 有两个值:long_short_mode 是开平仓模式,net_mode 是买卖模式。
买卖模式下一个合约只有一个方向的仓位;开平仓模式可以同时持有多、空两个方向。策略不需要同一合约双向持仓时,买卖模式的下单体少一个字段,写起来更省事。两种模式的写法对照:
| 动作 | 开平仓模式 | 买卖模式 |
|---|---|---|
| 开多 | side=buy,posSide=long | side=buy,posSide 不传或 net |
| 开空 | side=sell,posSide=short | side=sell,posSide 不传或 net |
| 平多 | side=sell,posSide=long | side=sell,reduceOnly=true |
| 平空 | side=buy,posSide=short | side=buy,reduceOnly=true |
开平仓模式下漏传 posSide,接口直接返回 51000;买卖模式下 posSide 也只接受 net 或不传。下面是开平仓模式的开多单,接上一节算出的 0.64 张。账户是买卖模式的,删掉 posSide 那一行就行。
{
"instId": "BTC-USDT-SWAP",
"tdMode": "cross",
"side": "buy",
"posSide": "long",
"ordType": "limit",
"px": "78000",
"sz": "0.64"
}
代码和账户模式不一致时,按你的情况处理:
- 想让账户跟着代码走:调
POST /api/v5/account/set-position-mode,请求体{"posMode":"net_mode"}或{"posMode":"long_short_mode"}。收到 59000 时,错误码表的说明是设置前要关闭挂单或持仓,所以先确认挂单和持仓都处理完,再发这个请求。 - 想让代码跟着账户走:脚本启动时读一次
posMode,再决定下单体带不带posSide。 - 账户是组合保证金模式:交割和永续只支持买卖模式,
posSide别写 long 或 short。 - 平仓时报 51169:账户里没有这个方向的持仓,回头核对
posSide和side的组合。
平仓单的 sz 也按张填。开平仓模式下平仓单自带只减仓逻辑,不受 reduceOnly 传值影响;买卖模式下的 reduceOnly 适用于合约模式和跨币种保证金模式的账户。只减仓单的 sz 超过持仓数量,整笔单会被拒绝,系统不会自动截到持仓量。其他错误码见欧易 API 常见报错与排查清单:照着这张表修。换算和下单体改完,先用模拟盘的 Key 发一遍,做法见欧易模拟盘怎么用:先拿假钱把策略跑通(ccxt 实操)。
合约单被拒后去查产品参数和账户模式
欧易 API 合约能直接按 USDT 金额下单吗?
合约单的 sz 只按张计算,tgtCcy 也只用于币币市价单,传 USDT 金额会被当成张数。要按金额下单,先用 ctVal 和价格换算成张数,或者调张币转换接口,把 unit 设成 usds、px 填价格,拿返回的张数再下单。
BTC 永续最少能下多少?
2026 年 11 月 2 日接口返回 BTC-USDT-SWAP 的 minSz 是 0.01 张,所以最少下 0.01 张。数量低于最小下单数量会报 51020。这个值可能调整,脚本里从 instruments 接口现取,不要写死,ETH-USDT-SWAP 也一样。
报 51121 下单张数应为一手张数的倍数怎么改?
张数要是整数倍:错误码表说一手张数的倍数,API 常见问题页说最小委托数量的整数倍,这两个合约的 lotSz 和 minSz 相同。像 0.641 这样的数先除以 lotSz 向下取整,再乘回去得到 0.64,转成字符串传给 sz。
下合约单报 51010 是什么原因?
51010 表示当前账户模式不支持此操作。现货模式下做不了合约,要换成合约、跨币种保证金或组合保证金模式。GET /api/v5/account/config 返回的 acctLv 为 1 就是现货模式。第一次设置要在交易页面主菜单的设置选项里改账户模式。