量化喵是独立第三方信息站,与任何交易所都没有隶属关系。本页不含推广链接与邀请码。 完整披露 →

欧易 · 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-SWAPETH-USDT-SWAP
ctVal合约面值0.010.1
ctValCcy面值的计价币种BTCETH
ctMult合约乘数11
ctType合约类型linear(正向)linear(正向)
lotSz下单数量精度,单位张0.010.01
minSz最小下单数量,单位张0.010.01
maxMktSz市价单单笔最大数量,单位张3500090000
tickSz下单价格精度0.10.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-SWAPETH-USDT-SWAP
假设 markPx78,0003,000
一张面值 = ctVal × markPx780 USDT300 USDT
500 ÷ 一张面值0.6410… 张1.6666… 张
向下取到 lotSz 的倍数0.64 张1.66 张
实际面值499.2 USDT498 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=longside=buy,posSide 不传或 net
开空side=sell,posSide=shortside=sell,posSide 不传或 net
平多side=sell,posSide=longside=sell,reduceOnly=true
平空side=buy,posSide=shortside=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 的组合。
欧易帮助中心如何开启双向持仓模式页面,包含双向持仓的定义、App 与网页端的切换步骤,以及切换前需无未平仓位的说明
持仓模式在 App 和网页上怎么切,欧易帮助中心《如何开启双向持仓模式?》写了步骤,也写明切换前要先没有未平仓位(2026 年 11 月截)

平仓单的 sz 也按张填。开平仓模式下平仓单自带只减仓逻辑,不受 reduceOnly 传值影响;买卖模式下的 reduceOnly 适用于合约模式和跨币种保证金模式的账户。只减仓单的 sz 超过持仓数量,整笔单会被拒绝,系统不会自动截到持仓量。其他错误码见欧易 API 常见报错与排查清单:照着这张表修。换算和下单体改完,先用模拟盘的 Key 发一遍,做法见欧易模拟盘怎么用:先拿假钱把策略跑通(ccxt 实操)。

风险提示:sz 的单位填错时,订单可能不报错就按错的数量下出去;合约面值会随价格变化。本文是接口参数说明,不构成投资建议;合约与杠杆交易可能亏掉全部本金,请只用你能承受全部损失的闲钱,并遵守所在地的法律法规。

合约单被拒后去查产品参数和账户模式

欧易 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 就是现货模式。第一次设置要在交易页面主菜单的设置选项里改账户模式。