导航
English
HTTP Python

概览

欢迎查看 V5 API文档。我们提供完整的REST和WebSocket API以满足您的交易需求。
V5 API只适用于交易账户

API学习资源与技术支持

教程


Python包


客户服务

创建我的APIKey

点击跳转至官网创建V5APIKey的页面 创建我的APIKey

生成APIKey

在对任何请求进行签名之前,您必须通过交易网站创建一个APIKey。创建APIKey后,您将获得3个必须记住的信息:

APIKey和SecretKey将由平台随机生成和提供,Passphrase将由您提供以确保API访问的安全性。平台将存储Passphrase加密后的哈希值进行验证,但如果您忘记Passphrase,则无法恢复,请您通过交易网站重新生成新的APIKey。

API key 有如下3种权限,一个 API key 可以有一个或多个权限。

REST 请求验证

发起请求

所有REST私有请求头都必须包含以下内容:

所有请求都应该含有application/json类型内容,并且是有效的JSON。

签名

生成签名

OK-ACCESS-SIGN的请求头是对timestamp + method + requestPath + body字符串(+表示字符串连接),以及SecretKey,使用HMAC SHA256方法加密,通过Base-64编码输出而得到的。

如:sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(timestamp + 'GET' + '/api/v5/account/balance?ccy=BTC', SecretKey))

其中,timestamp的值与OK-ACCESS-TIMESTAMP请求头相同,为ISO格式,如2020-12-08T09:08:57.715Z

method是请求方法,字母全部大写:GET/POST

requestPath是请求接口路径。如:/api/v5/account/balance

body是指请求主体的字符串,如果请求没有主体(通常为GET请求)则body可省略。如:{"instId":"BTC-USDT","lever":"5","mgnMode":"isolated"}

SecretKey为用户申请APIKey时所生成。如:22582BD0CFF14C41EDBF1AB98506286D

WebSocket

概述

WebSocket是HTML5一种新的协议(Protocol)。它实现了用户端与服务器全双工通信, 使得数据可以快速地双向传播。通过一次简单的握手就可以建立用户端和服务器连接, 服务器根据业务规则可以主动推送信息给用户端。其优点如下:

连接

连接限制:1次/秒 (基于IP)

当订阅公有频道时,使用公有服务的地址;当订阅私有频道时,使用私有服务的地址

请求限制

每个连接 对于 订阅/取消订阅/登录 请求的总次数限制为 480 次/小时

登录

请求示例

{
 "op": "login",
 "args":
  [
     {
       "apiKey": "985d5b66-57ce-40fb-b714-afc0b9787083",
       "passphrase": "123456",
       "timestamp": "1538054050",
       "sign": "7L+zFQ+CEgGu5rzCj4+BdV2/uUHGqddA9pI6ztsRRPs=" 
      }
   ]
}

请求参数

参数 类型 是否必须 描述
op String 操作,login
args Array 账户列表
> apiKey String APIKey
> passphrase String APIKey 的密码
> timestamp String 时间戳,Unix Epoch时间,单位是秒
> sign String 签名字符串

全部成功返回示例

{
  "event": "login",
  "code": "0",
  "msg": "",
  "connId": "a4d3ae55"
}

全部失败返回示例

{
  "event": "error",
  "code": "60009",
  "msg": "Login failed.",
  "connId": "a4d3ae55"
}

返回参数

参数 类型 是否必须 描述
event String 操作,login error
code String 错误码
msg String 错误消息
connId String WebSocket连接ID

api_key:调用API的唯一标识。需要用户手动设置一个 passphrase:APIKey的密码 timestamp:Unix Epoch 时间戳,单位为秒 sign:签名字符串,签名算法如下:

先将timestampmethodrequestPath 进行字符串拼接,再使用HMAC SHA256方法将拼接后的字符串和SecretKey加密,然后进行Base64编码

SecretKey:用户申请APIKey时所生成的安全密钥,如:22582BD0CFF14C41EDBF1AB98506286D

其中 timestamp 示例:const timestamp = '' + Date.now() / 1,000

其中 sign 示例: sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(timestamp +'GET'+ '/users/self/verify', secret))

method 总是 'GET'

requestPath 总是 '/users/self/verify'

订阅

订阅说明

请求格式说明

{
    "op": "subscribe",
    "args": ["<SubscriptionTopic> "]
}

WebSocket 频道分成两类: 公共频道私有频道

公共频道无需登录,包括行情频道,K线频道,交易数据频道,资金费率频道,限价范围频道,深度数据频道,标记价格频道等。

私有频道需登录,包括用户账户频道,用户交易频道,用户持仓频道等。

用户可以选择订阅一个或者多个频道,多个频道总长度不能超过 64 KB。

以下是一个请求参数的例子。每一个频道的请求参数的要求都不一样。请根据每一个频道的需求来订阅频道。

请求示例

{
    "op":"subscribe",
    "args":[
        {
            "channel":"tickers",
            "instId":"LTC-USD-200327"
        },
        {
            "channel":"candle1m",
            "instId":"LTC-USD-200327"
        }
    ]
}

请求参数

参数 类型 是否必须 描述
op String 操作,subscribe
args Array 请求订阅的频道列表
> channel String 频道名
> instType String 产品类型
SPOT:币币
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
ANY: 全部
> instFamily String 交易品种
适用于交割/永续/期权
> instId String 产品ID

返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "tickers",
        "instId": "LTC-USD-200327"
    },
  "connId": "a4d3ae55"
}

返回参数

参数 类型 是否必须 描述
event String 事件,subscribe error
arg Object 订阅的频道
> channel String 频道名
> instType String 产品类型
SPOT:币币
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION : 期权
ANY: 全部
> instFamily String 交易品种
适用于交割/永续/期权
> instId String 产品ID
code String 错误码
msg String 错误消息
connId String WebSocket连接ID

取消订阅

可以取消一个或者多个频道

请求格式说明

{
    "op": "unsubscribe",
    "args": ["< SubscriptionTopic > "]
}

请求示例

{
 "op": "unsubscribe",
 "args":
  [
      {
       "channel"   : "tickers",
       "instId":"LTC-USD-200327"
      },
      {
       "channel"   : "candle1m",
       "instId":"LTC-USD-200327"
      }
   ]
}

请求参数

参数 类型 是否必须 描述
op String 操作,unsubscribe
args Array 取消订阅的频道列表
> channel String 频道名
> instType String 产品类型
SPOT:币币
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
ANY: 全部
> instFamily String 交易品种
适用于交割/永续/期权
> instId String 产品ID

返回示例

{
    "event": "unsubscribe",
    "arg": {
        "channel": "tickers",
        "instId": "LTC-USD-200327"
    },
  "connId": "a4d3ae55"
}

返回参数

参数 类型 是否必须 描述
event String 事件,unsubscribe error
arg Object 取消订阅的频道
> channel String 频道名
> instType String 产品类型
SPOT:币币
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
ANY: 全部
> instFamily String 交易品种
适用于交割/永续/期权
> instId String 产品ID
code String 错误码
msg String 错误消息
connId String WebSocket连接ID

账户模式

为了方便您的交易体验,请在开始交易前设置适当的账户模式。

交易账户交易系统提供四个账户模式,分别为简单交易模式单币种保证金模式跨币种保证金模式以及组合保证金模式

账户模式的首次设置,需要在网页或手机app上进行。

实盘交易

实盘API交易地址如下:

AWS 地址如下:

模拟盘交易

目前可以进行V5 API的模拟盘交易,部分功能不支持如提币充值申购赎回等。

模拟盘API交易地址如下:

模拟盘的账户与欧易的账户是互通的,如果您已经有欧易账户,可以直接登录。

模拟盘API交易需要在模拟盘上创建APIKey:

登录欧易账户—>交易—>模拟交易—>个人中心—>创建模拟盘APIKey—>开始模拟交易

请求头示例

Content-Type: application/json

OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418

OK-ACCESS-SIGN: leaVRETrtaoEQ3yI9qEtI1CZ82ikZ4xSG5Kj8gnl3uw=

OK-ACCESS-PASSPHRASE: 1****6

OK-ACCESS-TIMESTAMP: 2020-03-28T12:21:41.274Z

x-simulated-trading: 1

模拟盘交互式浏览器

该功能接口用户需先登录,接口只会请求模拟环境

立即体验 交互式浏览器

基本信息

交易所层面的下单规则如下:


交易限制规则如下:


返回数据规则如下:


交易品种instFamily参数说明:

交易时效性

由于网络延时或者OKX服务器繁忙会导致订单无法及时处理。如果您对交易时效性有较高的要求,可以灵活设置请求有效截止时间expTime以达到你的要求。

(批量)下单,(批量)改单接口请求中如果包含expTime,如果服务器当前系统时间超过expTime,则该请求不会被服务器处理。

你应跟我们服务器系统时间同步。请用获取系统时间来获取系统时间。

REST API

请求头中设置如下参数

参数名 类型 是否必须 描述
expTime String 请求有效截止时间。Unix时间戳的毫秒数格式,如 1597026383085

目前支持如下接口:

请求示例

curl -X 'POST' \
  'https://www.okx.com/api/v5/trade/order' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'OK-ACCESS-KEY: *****' \
  -H 'OK-ACCESS-SIGN: *****'' \
  -H 'OK-ACCESS-TIMESTAMP: *****'' \
  -H 'OK-ACCESS-PASSPHRASE: *****'' \
  -H 'expTime: 1597026383085' \   // 有效截止时间
  -d '{
  "instId": "BTC-USDT",
  "tdMode": "cash",
  "side": "buy",
  "ordType": "limit",
  "px": "1000",
  "sz": "0.01"
}'

WebSocket

请求中设置如下参数

参数名 类型 是否必须 描述
expTime String 请求有效截止时间。Unix时间戳的毫秒数格式,如 1597026383085

目前支持如下接口:

请求示例

{
    "id": "1512",
    "op": "order",
    "expTime":"1597026383085",  // 有效截止时间
    "args": [{
        "side": "buy",
        "instId": "BTC-USDT",
        "tdMode": "isolated",
        "ordType": "market",
        "sz": "100"
    }]
}

限速

我们的 REST 和 WebSocket API 使用限速来保护我们的 API 免受恶意使用,因此我们的交易平台可以可靠和公平地运行。
当请求因限速而被我们的系统拒绝时,系统会返回错误代码 50011(用户请求频率过快,超过该接口允许的限额。请参考 API 文档并限制请求)。
每个接口的限速都不同。 您可以从接口详细信息中找到每个接口的限制。 限速定义详述如下:

对于与交易相关的 API(下订单、取消订单和修改订单),以下条件适用:

最佳实践

如果您需要的请求速率高于我们的限速,您可以设置不同的子账户来批量请求限速。 我们建议使用此方法来限制或间隔请求,以最大化每个帐户的限速并避免断开连接或拒绝请求。

做市商申请

满足以下任意条件的用户即可申请加入欧易做市商计划:

提供以下信息发送邮件至:institutional@okx.com或咨询大客户经理

为鼓励做市商为平台提供更好的流动性,可以享受更优的交易手续费,同时也承担相应的做市责任。具体做市责任及手续费申请成功后提供相关资料。

经纪商申请

如果您的业务平台提供数字货币服务,您就可以申请加入欧易经纪商项目,成为欧易的经纪商合作伙伴,享受专属的经纪商服务,并通过用户在欧易产生的交易手续费赚取高额返佣。
经纪商业务包含且不限:聚合交易平台、交易机器人、跟单平台、交易策略提供方、量化策略机构、资管平台等。

具体经纪商业务文档及产品服务在申请成功后提供相关资料。

交易账户

账户功能模块下的API接口需要身份验证。

REST API

查看账户余额

获取交易账户中资金余额信息。

限速:10次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/balance

请求示例

获取账户中所有资产余额
GET /api/v5/account/balance

获取账户中BTC、ETH两种资产余额
GET /api/v5/account/balance?ccy=BTC,ETH

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 查看账户余额
result = accountAPI.get_account_balance()
print(result)

请求参数

参数名 类型 是否必须 描述
ccy String 币种,如 BTC
支持多币种查询(不超过20个),币种之间半角逗号分隔

返回结果

{
    "code": "0",
    "data": [
        {
            "adjEq": "10679688.0460531643092577",
            "borrowFroz": "",
            "details": [
                {
                    "availBal": "",
                    "availEq": "9930359.9998",
                    "cashBal": "9930359.9998",
                    "ccy": "USDT",
                    "crossLiab": "0",
                    "disEq": "9439737.0772999514",
                    "eq": "9930359.9998",
                    "eqUsd": "9933041.196999946",
                    "fixedBal": "0",
                    "frozenBal": "0",
                    "interest": "0",
                    "isoEq": "0",
                    "isoLiab": "0",
                    "isoUpl":"0",
                    "liab": "0",
                    "maxLoan": "10000",
                    "mgnRatio": "",
                    "notionalLever": "",
                    "ordFrozen": "0",
                    "twap": "0",
                    "uTime": "1620722938250",
                    "upl": "0",
                    "uplLiab": "0",
                    "stgyEq":"0",
                    "spotInUseAmt":"",
                    "borrowFroz": "",
                    "spotIsoBal": "0"
                },
                {
                    "availBal": "",
                    "availEq": "33.6799714158199414",
                    "cashBal": "33.2009985",
                    "ccy": "BTC",
                    "crossLiab": "0",
                    "disEq": "1239950.9687532129092577",
                    "eq": "33.771820625136023",
                    "eqUsd": "1239950.9687532129092577",
                    "fixedBal": "0",
                    "frozenBal": "0.0918492093160816",
                    "interest": "0",
                    "isoEq": "0",
                    "isoLiab": "0",
                    "isoUpl":"0",
                    "liab": "0",
                    "maxLoan": "1453.92289531493594",
                    "mgnRatio": "",
                    "notionalLever": "",
                    "ordFrozen": "0",
                    "twap": "0",
                    "uTime": "1620722938250",
                    "upl": "0.570822125136023",
                    "uplLiab": "0",
                    "stgyEq":"0",
                    "spotInUseAmt":"",
                    "borrowFroz": "",
                    "spotIsoBal": "0"
                }
            ],
            "imr": "3372.2942371050594217",
            "isoEq": "0",
            "mgnRatio": "70375.35408747017",
            "mmr": "134.8917694842024",
            "notionalUsd": "33722.9423710505978888",
            "ordFroz": "0",
            "totalEq": "11172992.1657531589092577",
            "uTime": "1623392334718"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
uTime String 账户信息的更新时间,Unix时间戳的毫秒数格式,如 1597026383085
totalEq String 美金层面权益
isoEq String 美金层面逐仓仓位权益
适用于单币种保证金模式跨币种保证金模式组合保证金模式
adjEq String 美金层面有效保证金
适用于跨币种保证金模式组合保证金模式
ordFroz String 美金层面全仓挂单占用保证金
仅适用于跨币种保证金模式
imr String 美金层面占用保证金
适用于跨币种保证金模式组合保证金模式
mmr String 美金层面维持保证金
适用于跨币种保证金模式组合保证金模式
borrowFroz String 账户美金层面潜在借币占用保证金
仅适用于跨币种保证金模式组合保证金模式. 在其他账户模式下为"".
mgnRatio String 美金层面保证金率
适用于跨币种保证金模式组合保证金模式
notionalUsd String 以美金价值为单位的持仓数量,即仓位美金价值
适用于跨币种保证金模式组合保证金模式
details Array 各币种资产详细信息
> ccy String 币种
> eq String 币种总权益
> cashBal String 币种余额
> uTime String 币种余额信息的更新时间,Unix时间戳的毫秒数格式,如 1597026383085
> isoEq String 币种逐仓仓位权益
适用于单币种保证金模式跨币种保证金模式组合保证金模式
> availEq String 可用保证金
适用于单币种保证金模式跨币种保证金模式组合保证金模式
> disEq String 美金层面币种折算权益
> fixedBal String 抄底宝、逃顶宝功能的币种冻结金额
> availBal String 可用余额
适用于简单交易模式单币种保证金模式跨币种保证金模式组合保证金模式
> frozenBal String 币种占用金额
> ordFrozen String 挂单冻结数量
> liab String 币种负债额
值为正数,如:"21625.64",适用于跨币种保证金模式组合保证金模式
> upl String 未实现盈亏
适用于单币种保证金模式跨币种保证金模式组合保证金模式
> uplLiab String 由于仓位未实现亏损导致的负债
适用于跨币种保证金模式组合保证金模式
> crossLiab String 币种全仓负债额
适用于跨币种保证金模式组合保证金模式
> isoLiab String 币种逐仓负债额
适用于跨币种保证金模式组合保证金模式
> mgnRatio String 保证金率
适用于单币种保证金模式
> interest String 计息,应扣未扣利息。
值为正数,如:"9.01",适用于跨币种保证金模式组合保证金模式
> twap String 当前负债币种触发系统自动换币的风险
0、1、2、3、4、5其中之一,数字越大代表您的负债币种触发自动换币概率越高
适用于跨币种保证金模式组合保证金模式
> maxLoan String 币种最大可借
适用于跨币种保证金模式组合保证金模式 的全仓
> eqUsd String 币种权益美金价值
> borrowFroz String 币种美金层面潜在借币占用保证金
仅适用于跨币种保证金模式组合保证金模式. 在其他账户模式下为"".
> notionalLever String 币种杠杆倍数
适用于单币种保证金模式
> stgyEq String 策略权益
> isoUpl String 逐仓未实现盈亏
适用于单币种保证金模式跨币种保证金模式组合保证金模式
> spotInUseAmt String 现货对冲占用数量
适用于组合保证金模式
> spotIsoBal String 现货逐仓余额,仅适用于现货带单/跟单

各账户等级下有效字段分布

参数 简单交易模式 单币种保证金模式 跨币种保证金模式
uTime
totalEq
isoEq
adjEq
ordFroz
imr
mmr
mgnRatio
notionalUsd
details
> ccy
> eq
> cashBal
> uTime
> isoEq
> availEq
> disEq
> availBal
> frozenBal
> ordFrozen
> liab
> upl
> uplLiab
> crossLiab
> isoLiab
> mgnRatio
> interest
> twap
> maxLoan
> eqUsd
> notionalLever
> stgyEq
> isoUpl

查看持仓信息

获取该账户下拥有实际持仓的信息。账户为买卖模式会显示净持仓(net),账户为开平仓模式下会分别返回开多(long)或开空(short)的仓位。按照仓位创建时间倒序排列。

限速:10次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/positions

请求示例

# 查看BTC-USDT的持仓信息
GET /api/v5/account/positions?instId=BTC-USDT

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 查看持仓信息
result = accountAPI.get_positions()
print(result)

请求参数

参数名 类型 是否必须 描述
instType String 产品类型
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
instTypeinstId同时传入的时候会校验instIdinstType是否一致。
instId String 交易产品ID,如:BTC-USD-190927-5000-C
支持多个instId查询(不超过10个),半角逗号分隔
posId String 持仓ID
支持多个posId查询(不超过20个)。
存在有效期的属性,自最近一次完全平仓算起,满30天 posId 以及整个仓位会被清除。

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "adl":"1",
        "availPos":"1",
        "avgPx":"2566.31",
        "cTime":"1619507758793",
        "ccy":"ETH",
        "deltaBS":"",
        "deltaPA":"",
        "gammaBS":"",
        "gammaPA":"",
        "imr":"",
        "instId":"ETH-USD-210430",
        "instType":"FUTURES",
        "interest":"0",
        "idxPx":"2566.13",
        "last":"2566.22",
        "usdPx":"",
        "bePx":"2353.949",
        "lever":"10",
        "liab":"",
        "liabCcy":"",
        "liqPx":"2352.8496681818233",
        "markPx":"2353.849",
        "margin":"0.0003896645377994",
        "mgnMode":"isolated",
        "mgnRatio":"11.731726509588816",
        "mmr":"0.0000311811092368",
        "notionalUsd":"2276.2546609009605",
        "optVal":"",
        "pTime":"1619507761462",
        "pos":"1",
        "posCcy":"",
        "posId":"307173036051017730",
        "posSide":"long",
        "spotInUseAmt": "",
        "spotInUseCcy": "",
        "thetaBS":"",
        "thetaPA":"",
        "tradeId":"109844",
        "bizRefId": "",
        "bizRefType": "",
        "quoteBal": "0",
        "baseBal": "0",
        "baseBorrowed": "",
        "baseInterest": "",
        "quoteBorrowed": "",
        "quoteInterest": "",
        "uTime":"1619507761462",
        "upl":"-0.0000009932766034",
        "uplLastPx":"-0.0000009932766034",
        "uplRatio":"-0.0025490556801078",
        "uplRatioLastPx":"-0.0025490556801078",
        "vegaBS":"",
        "vegaPA":"",
        "realizedPnl":"0.001",
        "pnl":"0.0011",
        "fee":"-0.0001",
        "fundingFee":"0",
        "liqPenalty":"0",
        "closeOrderAlgo":[
            {
                "algoId":"123",
                "slTriggerPx":"123",
                "slTriggerPxType":"mark",
                "tpTriggerPx":"123",
                "tpTriggerPxType":"mark",
                "closeFraction":"0.6"
            },
            {
                "algoId":"123",
                "slTriggerPx":"123",
                "slTriggerPxType":"mark",
                "tpTriggerPx":"123",
                "tpTriggerPxType":"mark",
                "closeFraction":"0.4"
            }
       ]
    }]
}

返回参数

参数名 类型 描述
instType String 产品类型
mgnMode String 保证金模式
cross:全仓
isolated:逐仓
posId String 持仓ID
posSide String 持仓方向
long:开平仓模式开多,pos为正
short:开平仓模式开空,pos为正
net:买卖模式(交割/永续/期权pos为正代表开多,pos为负代表开空。币币杠杆时,pos均为正,posCcy为交易货币时,代表开多;posCcy为计价货币时,代表开空。)
pos String 持仓数量,逐仓自主划转模式下,转入保证金后会产生pos为0的仓位
baseBal String 交易币余额,适用于 币币杠杆(逐仓自主划转模式 和 一键借币模式)
quoteBal String 计价币余额 ,适用于 币币杠杆(逐仓自主划转模式 和 一键借币模式)
baseBorrowed String 交易币已借,适用于 币币杠杆(逐仓一键借币模式)
baseInterest String 交易币计息,适用于 币币杠杆(逐仓一键借币模式)
quoteBorrowed String 计价币已借,适用于 币币杠杆(逐仓一键借币模式)
quoteInterest String 计价币计息,适用于 币币杠杆(逐仓一键借币模式)
posCcy String 仓位资产币种,仅适用于币币杠杆仓位
availPos String 可平仓数量,适用于 币币杠杆,交割/永续(开平仓模式),期权
对于杠杆仓位,平仓时,杠杆还清负债后,余下的部分会视为币币交易,如果想要减少币币交易的数量,可通过"获取最大可用数量"接口获取只减仓的可用数量。
avgPx String 开仓平均价
upl String 未实现收益(以标记价格计算)
uplRatio String 未实现收益率(以标记价格计算
uplLastPx String 以最新成交价格计算的未实现收益,主要做展示使用,实际值还是 upl
uplRatioLastPx String 以最新成交价格计算的未实现收益率
instId String 产品ID,如 BTC-USD-180216
lever String 杠杆倍数,不适用于期权
liqPx String 预估强平价
不适用于期权
markPx String 最新标记价格
imr String 初始保证金,仅适用于全仓
margin String 保证金余额,可增减,仅适用于逐仓
mgnRatio String 保证金率
mmr String 维持保证金
liab String 负债额,仅适用于币币杠杆
liabCcy String 负债币种,仅适用于币币杠杆
interest String 利息,已经生成的未扣利息
tradeId String 最新成交ID
optVal String 期权市值,仅适用于期权
notionalUsd String 以美金价值为单位的持仓数量
adl String 信号区
分为5档,从1到5,数字越小代表adl强度越弱
ccy String 占用保证金的币种
last String 最新成交价
idxPx String 最新指数价格
usdPx String 美金价格
bePx String 盈亏平衡价
deltaBS String 美金本位持仓仓位delta,仅适用于期权
deltaPA String 币本位持仓仓位delta,仅适用于期权
gammaBS String 美金本位持仓仓位gamma,仅适用于期权
gammaPA String 币本位持仓仓位gamma,仅适用于期权
thetaBS String 美金本位持仓仓位theta,仅适用于期权
thetaPA String 币本位持仓仓位theta,仅适用于期权
vegaBS String 美金本位持仓仓位vega,仅适用于期权
vegaPA String 币本位持仓仓位vega,仅适用于期权
cTime String 持仓创建时间,Unix时间戳的毫秒数格式,如 1597026383085
uTime String 最近一次持仓更新时间,Unix时间戳的毫秒数格式,如 1597026383085
spotInUseAmt String 现货对冲占用数量
适用于组合保证金模式
spotInUseCcy String 现货对冲占用币种,如 BTC
适用于组合保证金模式
realizedPnl String 已实现收益
pnl String 平仓订单累计收益额
fee String 累计手续费金额,正数代表平台返佣 ,负数代表平台扣除
fundingFee String 累计资金费用
liqPenalty String 累计爆仓罚金,有值时为负数。
closeOrderAlgo Array 平仓策略委托订单。调用策略委托下单,且closeFraction=1 时,该数组才会有值。
> algoId String 策略委托单ID
> slTriggerPx String 止损触发价
> slTriggerPxType String 止损触发价类型
last:最新价格
index:指数价格
mark:标记价格
> tpTriggerPx String 止盈委托价
> tpTriggerPxType String 止盈触发价类型
last:最新价格
index:指数价格
mark:标记价格
> closeFraction String 策略委托触发时,平仓的百分比。1 代表100%
cTime String 持仓创建时间,Unix时间戳的毫秒数格式,如 1597026383085
uTime String 最近一次持仓更新时间,Unix时间戳的毫秒数格式,如 1597026383085
bizRefId String 外部业务id,e.g. 体验券id
bizRefType String 外部业务类型

查看历史持仓信息

获取最近3个月有更新的仓位信息,按照仓位更新时间倒序排列。组合保证金账户模式不支持查询历史持仓。

限速:1次/10s

限速规则:UserID

HTTP请求

GET /api/v5/account/positions-history

请求示例

GET /api/v5/account/positions-history
import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 查看历史持仓信息
result = accountAPI.get_positions_history()
print(result)

请求参数

参数名 类型 是否必须 描述
instType String 产品类型
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
instId String 交易产品ID,如:BTC-USD-SWAP
mgnMode String 保证金模式
cross:全仓,isolated:逐仓
type String 平仓类型
1:部分平仓;2:完全平仓;3:强平;4:强减; 5:ADL自动减仓;
状态叠加时,以最新的平仓类型为准状态为准。
posId String 持仓ID。存在有效期的属性,自最近一次完全平仓算起,满30天 posId 会失效,之后的仓位,会使用新的 posId。
after String 查询仓位更新 (uTime) 之前的内容,值为时间戳,Unix 时间戳为毫秒数格式,如 1597026383085
before String 查询仓位更新 (uTime) 之后的内容,值为时间戳,Unix 时间戳为毫秒数格式,如 1597026383085
limit String 分页返回结果的数量,最大为100,默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "cTime": "1654177169995",
            "ccy": "BTC",
            "closeAvgPx": "29786.5999999789081085",
            "closeTotalPos": "1",
            "instId": "BTC-USD-SWAP",
            "instType": "SWAP",
            "lever": "10.0",
            "mgnMode": "cross",
            "openAvgPx": "29783.8999999995535393",
            "openMaxPos": "1",
            "realizedPnl": "0.001",
            "fee": "-0.0001",
            "fundingFee": "0",
            "liqPenalty": "0",
            "pnl": "0.0011",
            "pnlRatio": "0.000906447858888",
            "posId": "452587086133239818",
            "direction": "long",
            "triggerPx": "",
            "type": "1",
            "uTime": "1654177174419",
            "uly": "BTC-USD"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
instType String 产品类型
instId String 交易产品ID
mgnMode String 保证金模式
cross:全仓,isolated:逐仓
type String 平仓类型
1:部分平仓;2:完全平仓;3:强平;4:强减; 5:ADL自动减仓;
状态叠加时,以最新的平仓类型为准状态为准。
cTime String 仓位创建时间
uTime String 仓位更新时间
openAvgPx String 开仓均价
closeAvgPx String 平仓均价
posId String 仓位ID
openMaxPos String 最大持仓量
closeTotalPos String 累计平仓量
realizedPnl String 已实现收益
fee String 累计手续费金额,正数代表平台返佣 ,负数代表平台扣除
fundingFee String 累计资金费用
liqPenalty String 累计爆仓罚金,有值时为负数。
pnl String 平仓收益额
pnlRatio String 平仓收益率
lever String 杠杆倍数
direction String 持仓方向 long:多 short:空
仅适用于 币币杠杆/交割/永续/期权
triggerPx String 触发标记价格
uly String 标的指数
ccy String 占用保证金的币种

查看账户持仓风险

查看账户整体风险。

限速:10次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/account-position-risk

请求示例

GET /api/v5/account/account-position-risk

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 查看账户特定风险状态
result = accountAPI.get_account_position_risk()
print(result)

请求参数

参数名 类型 是否必须 描述
instType String 产品类型
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权

返回结果

{
    "code":"0",
    "data":[
        {
            "adjEq":"174238.6793649711331679",
            "balData":[
                {
                    "ccy":"BTC",
                    "disEq":"78846.7803721021362242",
                    "eq":"1.3863533369419636"
                },
                {
                    "ccy":"USDT",
                    "disEq":"73417.2495112863300127",
                    "eq":"73323.395564963177146"
                }
            ],
            "posData":[
                {
                    "baseBal": "0.4",
                    "ccy": "",
                    "instId": "BTC-USDT",
                    "instType": "MARGIN",
                    "mgnMode": "isolated",
                    "notionalCcy": "0",
                    "notionalUsd": "0",
                    "pos": "0",
                    "posCcy": "",
                    "posId": "310388685292318723",
                    "posSide": "net",
                    "quoteBal": "0"
                }
            ],
            "ts":"1620282889345"
        }
    ],
    "msg":""
}

返回参数

参数名 类型 描述
ts String 获取账户信息数据的时间,Unix时间戳的毫秒数格式,如 1597026383085
adjEq String 美金层面有效保证金
适用于跨币种保证金模式组合保证金模式
balData Array 币种资产信息
> ccy String 币种
> eq String 币种总权益
> disEq String 美金层面币种折算权益
posData Array 持仓详细信息
> instType String 产品类型
> mgnMode String 保证金模式
cross:全仓
isolated:逐仓
> posId String 持仓ID
> instId String 产品ID,如 BTC-USD-180216
> pos String 为单位的持仓数量,逐仓自主划转模式下,转入保证金后会产生pos为0的仓位
> baseBal String 交易币余额,适用于 币币杠杆(逐仓自主划转模式和逐仓一键借币模式)
> quoteBal String 计价币余额 ,适用于 币币杠杆(逐仓自主划转模式和逐仓一键借币模式)
> posSide String 持仓方向
long:开平仓模式开多
short:开平仓模式开空
net:买卖模式(交割/永续/期权pos为正代表开多,pos为负代表开空。币币杠杆posCcy为交易货币时,代表开多;posCcy为计价货币时,代表开空。)
> posCcy String 仓位资产币种,仅适用于币币杠杆仓位
> ccy String 占用保证金的币种
> notionalCcy String 为单位的持仓数量
> notionalUsd String 美金价值为单位的持仓数量

账单流水查询(近七天)

帐户资产流水是指导致帐户余额增加或减少的行为。本接口可以查询最近7天的账单数据。

限速:5次/s

限速规则:UserID

HTTP请求

GET /api/v5/account/bills

请求示例

GET /api/v5/account/bills

GET /api/v5/account/bills?instType=MARGIN

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 查看账户账单详情 (近七日内)
result = accountAPI.get_account_bills()
print(result)

请求参数

参数名 类型 是否必须 描述
instType String 产品类型
SPOT:币币
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
ccy String 账单币种
mgnMode String 仓位类型
isolated:逐仓
cross:全仓
ctType String linear: 正向合约
inverse: 反向合约
交割/永续有效
type String 账单类型
1:划转 2:交易 3:交割 4:自动换币 5:强平 6:保证金划转 7:扣息 8:资金费 9:自动减仓 10:穿仓补偿 11:系统换币 12:策略划拨 13:对冲减仓 14: 大宗交易 15: 一键借币 22: 一键还债 24: 价差交易 250: 分润支出; 251: 分润退还; 252: 分润收入;
subType String 账单子类型
1:买入 2:卖出 3:开多 4:开空 5:平多 6:平空 9:市场借币扣息 11:转入 12:转出 14:尊享借币扣息 160:手动追加保证金 161:手动减少保证金 162:自动追加保证金 114:自动换币买入 115:自动换币卖出 118:系统换币转入 119:系统换币转出 100:强减平多 101:强减平空 102:强减买入 103:强减卖出 104:强平平多 105:强平平空 106:强平买入 107:强平卖出 108:穿仓补偿 110:强平换币转入 111:强平换币转出 125:自动减仓平多 126:自动减仓平空 127:自动减仓买入 128:自动减仓卖出 131:对冲买入 132:对冲卖出 170:到期行权(实值期权买方) 171:到期被行权(实值期权卖方) 172:到期作废(非实值期权的买方和卖方) 112:交割平多 113:交割平空 117:交割/行权穿仓补偿 173:资金费支出 174:资金费收入 200:系统转入 201:手动转入 202:系统转出 203:手动转出 204: 大宗交易买 205: 大宗交易卖 206: 大宗交易开多 207: 大宗交易开空 208: 大宗交易平多 209: 大宗交易平空 210: 一键借币的手动借币 211: 一键借币的手动还币 212: 一键借币的自动借币 213:一键借币的自动还币" 16:强制还币 17:强制借币还息 224: 还债转入 225: 还债转出 250: 永续分润支出; 251: 永续分润退还; 280: 现货分润支出; 281: 现货分润退还; 270: 价差交易买; 271: 价差交易卖; 272: 价差交易开多; 273: 价差交易开空; 274: 价差交易平多; 275: 价差交易平空
after String 请求此id之前(更旧的数据)的分页内容,传的值为对应接口的billId
before String 请求此id之后(更新的数据)的分页内容,传的值为对应接口的billId
begin String 筛选的开始时间戳,Unix 时间戳为毫秒数格式,如 1597026383085
end String 筛选的结束时间戳,Unix 时间戳为毫秒数格式,如 1597027383085
limit String 分页返回的结果集数量,最大为100,不填默认返回100条

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "bal": "8694.2179403378290202",
        "balChg": "0.0219338232210000",
        "billId": "623950854533513219",
        "ccy": "USDT",
        "clOrdId": "",
        "execType": "T",
        "fee": "-0.000021955779",
        "fillFwdPx": "",
        "fillIdxPx": "27104.1",
        "fillMarkPx": "",
        "fillMarkVol": "",
        "fillPxUsd": "",
        "fillPxVol": "",
        "fillTime": "1695033476166",
        "from": "",
        "instId": "BTC-USDT",
        "instType": "SPOT",
        "interest": "0",
        "mgnMode": "isolated",
        "notes": "",
        "ordId": "623950854525124608",
        "pnl": "0",
        "posBal": "0",
        "posBalChg": "0",
        "px": "27105.9",
        "subType": "1",
        "sz": "0.021955779",
        "tag": "",
        "to": "",
        "tradeId": "586760148",
        "ts": "1695033476167",
        "type": "2"
    }]
} 

返回参数

参数名 类型 描述
instType String 产品类型
billId String 账单ID
type String 账单类型
subType String 账单子类型
ts String 余额更新完成的时间,Unix时间戳的毫秒数格式,如 1597026383085
balChg String 账户层面的余额变动数量
posBalChg String 仓位层面的余额变动数量
bal String 账户层面的余额数量
posBal String 仓位层面的余额数量
sz String 数量
px String 价格,与 subType 相关。
为成交价格时有 1: 买入 2: 卖出 3:开多 4:开空 5:平多 6:平空 204: 大宗交易买 205: 大宗交易卖 206: 大宗交易开多 207: 大宗交易开空 208: 大宗交易平多 209: 大宗交易平空 114:自动换币买入 115:自动换币卖出
强平价格,100:强减平多 101:强减平空 102:强减买入 103:强减卖出 104:强平平多 105:强平平空 106:强平买入 107:强平卖出 16:强制还币 17:强制借币还息 110:强平换币转入 111:强平换币转出
交割价格,112:交割平多 113:交割平空
行权价格,170:到期行权 171:到期被行权 172:到期作废
标记价格,173:资金费支出 174:资金费收入
ccy String 账户余额币种
pnl String 收益
fee String 手续费
正数代表平台返佣 ,负数代表平台扣除
mgnMode String 保证金模式
isolated:逐仓 cross:全仓
账单不是由仓位变化产生的,该字段返回 ""
instId String 产品ID,如 BTC-USD-190927-5000-C
ordId String 订单ID
当type为2:交易时,返回相应订单id。无订单时,该字段返回 ""
execType String 流动性方向 T:taker M:maker
from String 转出账户
6:资金账户 18:交易账户
仅适用于资金划转,不是资金划转时,返回 ""
to String 转入账户
6:资金账户 18:交易账户
仅适用于资金划转,不是资金划转时,返回 ""
notes String 备注
interest String 利息
tag String 订单标签
字母(区分大小写)与数字的组合,可以是纯字母、纯数字,且长度在1-16位之间。
fillTime String 最新成交时间
tradeId String 最新成交ID
clOrdId String 客户自定义订单ID
fillIdxPx String 交易执行时的指数价格
对于交叉现货币对,返回 baseCcy-USDT 的指数价格。 例如LTC-ETH,该字段返回LTC-USDT的指数价格。
fillMarkPx String 成交时的标记价格,仅适用于 交割/永续/期权
fillPxVol String 成交时的隐含波动率,仅适用于期权,其他业务线返回空字符串""
fillPxUsd String 成交时的期权价格,以USD为单位,仅适用于期权,其他业务线返回空字符串""
fillMarkVol String 成交时的标记波动率,仅适用于期权,其他业务线返回空字符串""
fillFwdPx String 成交时的远期价格,仅适用于期权,其他业务线返回空字符串""

账单流水查询(近三月)

帐户资产流水是指导致帐户余额增加或减少的行为。本接口可以查询最近3个月的账单数据。

限速:5次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/bills-archive

请求示例

GET /api/v5/account/bills-archive

GET /api/v5/account/bills-archive?instType=MARGIN

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 查看账户账单详情 (近三个月内)
result = accountAPI.get_account_bills_archive()
print(result)

请求参数

参数名 类型 是否必须 描述
instType String 产品类型
SPOT:币币
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
ccy String 账单币种
mgnMode String 仓位类型
isolated:逐仓 cross:全仓
ctType String linear: 正向合约
inverse: 反向合约
交割/永续有效
type String 账单类型
1:划转 2:交易 3:交割 4:自动换币 5:强平 6:保证金划转 7:扣息 8:资金费 9:自动减仓 10:穿仓补偿 11:系统换币 12:策略划拨 13:对冲减仓 14: 大宗交易 15: 一键借币 22: 一键还债 24: 价差交易 250: 永续分润支出; 251: 永续分润退还; 280: 现货分润支出; 281: 现货分润退还;
subType String 账单子类型
1:买入 2:卖出 3:开多 4:开空 5:平多 6:平空 9:市场借币扣息 11:转入 12:转出 14:尊享借币扣息 160:手动追加保证金 161:手动减少保证金 162:自动追加保证金 114:自动换币买入 115:自动换币卖出 118:系统换币转入 119:系统换币转出 100:强减平多 101:强减平空 102:强减买入 103:强减卖出 104:强平平多 105:强平平空 106:强平买入 107:强平卖出 108:穿仓补偿 110:强平换币转入 111:强平换币转出 125:自动减仓平多 126:自动减仓平空 127:自动减仓买入 128:自动减仓卖出 131:对冲买入 132:对冲卖出 170:到期行权(实值期权买方) 171:到期被行权(实值期权卖方) 172:到期作废(非实值期权的买方和卖方) 112:交割平多 113:交割平空 117:交割/行权穿仓补偿 173:资金费支出 174:资金费收入 200:系统转入 201:手动转入 202:系统转出 203:手动转出 204: 大宗交易买 205: 大宗交易卖 206: 大宗交易开多 207: 大宗交易开空 208: 大宗交易平多 209: 大宗交易平空 210: 一键借币的手动借币 211: 一键借币的手动还币 212: 一键借币的自动借币 213:一键借币的自动还币 16:强制还币 17:强制借币还息 224: 还债转入 225: 还债转出 250: 分润支出; 251: 分润退还; 252: 分润收入; 270: 价差交易买; 271: 价差交易卖; 272: 价差交易开多; 273: 价差交易开空; 274: 价差交易平多; 275: 价差交易平空
after String 请求此id之前(更旧的数据)的分页内容,传的值为对应接口的billId
before String 请求此id之后(更新的数据)的分页内容,传的值为对应接口的billId
begin String 筛选的开始时间戳,Unix 时间戳为毫秒数格式,如 1597026383085
end String 筛选的结束时间戳,Unix 时间戳为毫秒数格式,如 1597027383085
limit String 分页返回的结果集数量,最大为100,不填默认返回100条

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "bal": "8694.2179403378290202",
        "balChg": "0.0219338232210000",
        "billId": "623950854533513219",
        "ccy": "USDT",
        "clOrdId": "",
        "execType": "T",
        "fee": "-0.000021955779",
        "fillFwdPx": "",
        "fillIdxPx": "27104.1",
        "fillMarkPx": "",
        "fillMarkVol": "",
        "fillPxUsd": "",
        "fillPxVol": "",
        "fillTime": "1695033476166",
        "from": "",
        "instId": "BTC-USDT",
        "instType": "SPOT",
        "interest": "0",
        "mgnMode": "isolated",
        "notes": "",
        "ordId": "623950854525124608",
        "pnl": "0",
        "posBal": "0",
        "posBalChg": "0",
        "px": "27105.9",
        "subType": "1",
        "sz": "0.021955779",
        "tag": "",
        "to": "",
        "tradeId": "586760148",
        "ts": "1695033476167",
        "type": "2"
    }]
} 

返回参数

参数名 类型 描述
instType String 产品类型
billId String 账单ID
type String 账单类型
subType String 账单子类型
ts String 余额更新完成的时间,Unix时间戳的毫秒数格式,如 1597026383085
balChg String 账户层面的余额变动数量
posBalChg String 仓位层面的余额变动数量
bal String 账户层面的余额数量
posBal String 仓位层面的余额数量
sz String 数量
px String 价格,与 subType 相关。
为成交价格时有 1: 买入 2: 卖出 3:开多 4:开空 5:平多 6:平空 204: 大宗交易买 205: 大宗交易卖 206: 大宗交易开多 207: 大宗交易开空 208: 大宗交易平多 209: 大宗交易平空 114:自动换币买入 115:自动换币卖出
强平价格,100:强减平多 101:强减平空 102:强减买入 103:强减卖出 104:强平平多 105:强平平空 106:强平买入 107:强平卖出 16:强制还币 17:强制借币还息 110:强平换币转入 111:强平换币转出
交割价格,112:交割平多 113:交割平空
行权价格,170:到期行权 171:到期被行权 172:到期作废
标记价格,173:资金费支出 174:资金费收入
ccy String 账户余额币种
pnl String 收益
fee String 手续费
正数代表平台返佣 ,负数代表平台扣除
mgnMode String 保证金模式
isolated:逐仓 cross:全仓
无仓位类型字段,该字段返回 ""
instId String 产品ID,如 BTC-USD-190927-5000-C
ordId String 订单ID
当type为2:交易时,返回相应订单id。无订单时,该字段返回 ""
execType String 流动性方向 T:taker M:maker
from String 转出账户
6:资金账户 18:交易账户
仅适用于资金划转,不是资金划转时,返回 ""
to String 转入账户
6:资金账户 18:交易账户
仅适用于资金划转,不是资金划转时,返回 ""
notes String 备注
interest String 利息
tag String 订单标签
字母(区分大小写)与数字的组合,可以是纯字母、纯数字,且长度在1-16位之间。
fillTime String 最新成交时间
tradeId String 最新成交ID
clOrdId String 客户自定义订单ID
fillIdxPx String 交易执行时的指数价格
对于交叉现货币对,返回 baseCcy-USDT 的指数价格。 例如LTC-ETH,该字段返回LTC-USDT的指数价格。
fillMarkPx String 成交时的标记价格,仅适用于 交割/永续/期权
fillPxVol String 成交时的隐含波动率,仅适用于期权,其他业务线返回空字符串""
fillPxUsd String 成交时的期权价格,以USD为单位,仅适用于期权,其他业务线返回空字符串""
fillMarkVol String 成交时的标记波动率,仅适用于期权,其他业务线返回空字符串""
fillFwdPx String 成交时的远期价格,仅适用于期权,其他业务线返回空字符串""

查看账户配置

查看当前账户的配置信息。

限速:5次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/config

请求示例

GET /api/v5/account/config

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 查看账户配置
result = accountAPI.get_account_config()
print(result)

请求参数

返回结果

{
    "code": "0",
    "data": [
        {
            "acctLv": "3",
            "autoLoan": true,
            "ctIsoMode": "automatic",
            "greeksType": "PA",
            "level": "Lv1",
            "levelTmp": "",
            "mgnIsoMode": "automatic",
            "posMode": "net_mode",
            "spotOffsetType": "",
            "uid": "44705892343619584",
            "label": "V5 Test",
            "roleType": "0",
            "traderInsts": [],
            "spotRoleType": "0",
            "spotTraderInsts": [],
            "opAuth": "0",
            "kycLv": "3",
            "ip": "120.255.24.182,49.245.196.13",
            "perm": "read_only,withdraw,trade",
            "mainUid": "444810535339712570"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
uid String 当前请求的账户ID,账户uid和app上的一致
mainUid String 当前请求的母账户ID
如果 uid = mainUid,代表当前账号为母账户;如果 uid != mainUid,代表当前账户为子账户。
acctLv String 账户层级
1:简单交易模式
2:单币种保证金模式
3:跨币种保证金模式
4:组合保证金模式
posMode String 持仓方式
long_short_mode:开平仓模式
net_mode:买卖模式
仅适用交割/永续
autoLoan Boolean 是否自动借币
true:自动借币 false:非自动借币
greeksType String 当前希腊字母展示方式
PA:币本位 BS:美元本位
level String 当前在平台上真实交易量的用户等级,例如 lv1
levelTmp String 特约用户的临时体验用户等级,例如 lv3
ctIsoMode String 衍生品的逐仓保证金划转模式
automatic:开仓划转
autonomy:自主划转
mgnIsoMode String 币币杠杆的逐仓保证金划转模式
automatic:开仓划转
quick_margin:一键借币(对于新的账户,包括新的子账户,有些默认是开仓划转,另外的默认是一键借币)
spotOffsetType String 现货对冲类型
1:现货对冲模式U模式
2:现货对冲模式币模式
3:非现货对冲模式
适用于组合保证金模式
roleType String 用户角色
0:普通用户
1:带单者
2:跟单者
traderInsts Array 当前账号已经设置的带单合约,仅适用于带单者
spotRoleType String 现货跟单角色。
0:普通用户;1:带单者;2:跟单者
spotTraderInsts String 当前账号已经设置的带单合约,仅适用于带单者
opAuth String 是否开通期权交易
0:未开通
1:已经开通
kycLv String 母账户KYC等级
0: 未认证
1: 已完成 level 1 认证
2: 已完成 level 2 认证
3: 已完成 level 3认证
如果请求来自子账户, kycLv 为其母账户的等级
如果请求来自母账户, kycLv 为当前请求的母账户等级
label String 当前请求API key的备注名,不超过50位字母(区分大小写)或数字,可以是纯字母或纯数字。
ip String 当前请求API key绑定的ip地址,多个ip用半角逗号隔开,如:117.37.203.58,117.37.203.57
如果没有绑定ip,会返回空字符串""
perm String 当前请求的 API key权限
read_only:读取
trade:交易
withdraw:提币

设置持仓模式

单币种账户和跨币种账户模式:交割和永续合约支持开平仓模式和买卖模式。买卖模式只会有一个方向的仓位;开平仓模式可以分别持有多、空2个方向的仓位。
组合保证金模式:交割和永续仅支持买卖模式

限速:5次/2s

限速规则:UserID

HTTP请求

POST /api/v5/account/set-position-mode

请求示例

POST /api/v5/account/set-position-mode
body 
{
    "posMode":"long_short_mode"
}

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 设置持仓模式
result = accountAPI.set_position_mode(
    posMode="long_short_mode"
)
print(result)

请求参数

参数名 类型 是否必须 描述
posMode String 持仓方式
long_short_mode:开平仓模式 net_mode:买卖模式
仅适用交割/永续

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "posMode": "long_short_mode"
    }]
}

返回参数

参数名 类型 描述
posMode String 持仓方式

设置杠杆倍数


一个产品可以有如下10种杠杆倍数的设置场景:

  1. 逐仓交易模式下,设置币币杠杆的杠杆倍数(币对层面);
  2. 单币种保证金账户在全仓交易模式下,设置币币杠杆的杠杆倍数(币对层面);
  3. 跨币种保证金账户在全仓交易模式下,设置币币杠杆的杠杆倍数(币种层面);
  4. 组合保证金账户在全仓交易模式下,设置币币杠杆的杠杆倍数(币种层面);
  5. 全仓交易模式下,设置交割的杠杆倍数(指数层面);
  6. 逐仓交易模式、买卖持仓模式下,设置交割的杠杆倍数(合约层面);
  7. 逐仓交易模式、开平仓持仓模式下,设置交割的杠杆倍数(合约与持仓方向层面);
  8. 全仓交易模式下,设置永续的杠杆倍数(合约层面);
  9. 逐仓交易模式、买卖持仓模式下,设置永续的杠杆倍数(合约层面);
  10. 逐仓交易模式、开平仓持仓模式下,设置永续的杠杆倍数(合约与持仓方向层面);

注意请求参数 posSide 仅在交割/永续开平仓持仓模式下才需要填写(参见场景7和10)。
请参阅右侧对应的每个案例的请求示例。

限速:20次/2s

限速规则:UserID

HTTP请求

POST /api/v5/account/set-leverage

请求示例

# 1.在`逐仓`交易模式下,设置`币币杠杆`的杠杆倍数(币对层面)
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT",
    "lever":"5",
    "mgnMode":"isolated"
}

# 2.`单币种保证金`账户在`全仓`交易模式下,设置`币币杠杆`的杠杆倍数(币对层面)
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT",
    "lever":"5",
    "mgnMode":"cross"
}

# 3.`跨币种保证金`账户在`全仓`交易模式下,设置`币币杠杆`的杠杆倍数(币种层面)
POST /api/v5/account/set-leverage
body
{
    "ccy":"BTC",
    "lever":"5",
    "mgnMode":"cross"
}

# 4. `组合保证金`账户在`全仓`交易模式下,设置`币币杠杆`的杠杆倍数(币种层面)
POST /api/v5/account/set-leverage
body
{
    "ccy":"BTC",
    "lever":"5",
    "mgnMode":"cross"
}

# 5.在`全仓`交易模式下,设置`交割`的杠杆倍数(指数层面)
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT-200802",
    "lever":"5",
    "mgnMode":"cross"
}

# 6.在`逐仓`交易模式、`买卖`持仓模式下,设置`交割`的杠杆倍数(合约层面)
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT-200802",
    "lever":"5",
    "mgnMode":"isolated"
}

# 7.在`逐仓`交易模式、`开平仓`持仓模式下,设置`交割`的杠杆倍数(合约与头寸层面)
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT-200802",
    "lever":"5",
    "posSide":"long",
    "mgnMode":"isolated"
}

# 8.在`全仓`交易模式下,设置`永续`的杠杆倍数(合约层面)
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT-SWAP",
    "lever":"5",
    "mgnMode":"cross"
}

# 9.在`逐仓`交易模式、`买卖`持仓模式下,设置`永续`的杠杆倍数(合约层面)
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT-SWAP",
    "lever":"5",
    "mgnMode":"isolated"
}

# 10.在`逐仓`交易模式、`开平仓`持仓模式下,设置`永续`的杠杆倍数(合约与头寸层面)
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT-SWAP",
    "lever":"5",
    "posSide":"long",
    "mgnMode":"isolated"
}
import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 在逐仓交易模式下,设置币币杠杆的杠杆倍数(币对层面)
result = accountAPI.set_leverage(
    instId="BTC-USDT",
    lever="5",
    mgnMode="isolated"
)
print(result)

请求参数

参数名 类型 是否必须 描述
instId String 可选 产品ID:币对、合约
全仓下,instIdccy至少要传一个;如果两个都传,默认使用instId
ccy String 可选 保证金币种
仅适用于跨币种保证金模式组合保证金模式全仓 币币杠杆。设置自动借币的杠杆倍数时必填
lever String 杠杆倍数
mgnMode String 保证金模式
isolated:逐仓 cross:全仓
如果ccy有效传值,该参数值只能为cross
posSide String 可选 持仓方向
long:开平仓模式开多
short:开平仓模式开空
仅适用于逐仓交割/永续
在开平仓模式且保证金模式为逐仓条件下必填

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "lever": "30",
        "mgnMode": "isolated",
        "instId": "BTC-USDT-SWAP",
        "posSide": "long"
    }]
}

返回参数

参数名 类型 描述
lever String 杠杆倍数
mgnMode String 保证金模式
isolated:逐仓 cross:全仓
instId String 产品ID
posSide String 持仓方向

获取最大可买卖/开仓数量

限速:20次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/max-size

请求示例

GET /api/v5/account/max-size?instId=BTC-USDT&tdMode=isolated

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 获取最大可买卖/开仓数量
result = accountAPI.get_max_order_size(
    instId="BTC-USDT",
    tdMode="isolated"
)
print(result)

请求参数

参数名 类型 是否必须 描述
instId String 产品ID,如 BTC-USDT
支持多产品ID查询(不超过5个),半角逗号分隔
tdMode String 交易模式
cross:全仓 isolated:逐仓 cash:非保证金
ccy String 可选 保证金币种,仅适用于单币种保证金模式下的全仓杠杆订单
px String 委托价格
当不填委托价时会按当前最新成交价计算
当指定多个产品ID查询时,忽略该参数,按当前最新成交价计算
leverage String 开仓杠杆倍数
默认为当前杠杆倍数
仅适用于币币杠杆/交割/永续
unSpotOffset Boolean true:禁止现货对冲,false:允许现货对冲
默认为false
仅适用于组合保证金模式
开启现货对冲模式下有效,否则忽略此参数。

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "ccy": "BTC",
        "instId": "BTC-USDT",
        "maxBuy": "0.0500695098559788",
        "maxSell": "64.4798671570072269"
    }]
}

返回参数

参数名 类型 描述
instId String 产品ID
ccy String 保证金币种
maxBuy String 币币/币币杠杆:最大可买的交易币数量
单币种保证金模式下的全仓杠杆订单,为交易币数量
交割/永续/期权:最大可开多的合约张数
maxSell String 币币/币币杠杆:最大可卖的计价币数量
单币种保证金模式下的全仓杠杆订单,为交易币数量
交割/永续/期权:最大可开空的合约张数

获取最大可用数量

限速:20次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/max-avail-size

请求示例

# 获取BTC-USDT全仓币币杠杆指定BTC作为保证金最大可用数量
GET /api/v5/account/max-avail-size?instId=BTC-USDT&tdMode=cross&ccy=BTC

# 获取BTC-USDT币币最大可用数量
GET /api/v5/account/max-avail-size?instId=BTC-USDT&tdMode=cash

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 获取BTC-USDT币币最大可用数量
result = accountAPI.get_max_avail_size(
    instId="BTC-USDT",
    tdMode="cash"
)
print(result)

请求参数

参数名 类型 是否必须 描述
instId String 产品ID,如 BTC-USDT
支持多产品ID查询(不超过5个),半角逗号分隔
tdMode String 交易模式
cross:全仓 isolated:逐仓 cash:非保证金
ccy String 可选 保证金币种,仅适用于单币种保证金模式下的全仓杠杆订单
reduceOnly Boolean 是否为只减仓模式,仅适用于币币杠杆
px String 对应平仓价格下的可用数量,默认为市价。
仅适用于杠杆只减仓
unSpotOffset Boolean true:禁止现货对冲,false:允许现货对冲
默认为false
仅适用于组合保证金模式
开启现货对冲模式下有效,否则忽略此参数。
quickMgnType String 一键借币类型,仅适用于杠杆逐仓的一键借币模式:
manual:手动,auto_borrow: 自动借币,auto_repay: 自动还币
默认是manual:手动

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "instId": "BTC-USDT-200802",
        "availBuy": "1",
        "availSell": "1"
    }]
}

返回参数

参数名 类型 描述
instId String 产品ID
availBuy String 最大买入可用数量
availSell String 最大卖出可用数量

调整保证金

增加或者减少逐仓保证金。减少保证金可能会导致实际杠杆倍数发生变化。

限速:20次/2s

限速规则:UserID

HTTP请求

POST /api/v5/account/position/margin-balance

请求示例

POST /api/v5/account/position/margin-balance 
body
{
    "instId":"BTC-USDT-SWAP",
    "posSide":"short",
    "type":"add",
    "amt":"1"
}

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 调整保证金
result = accountAPI.adjustment_margin(
    instId="BTC-USDT-SWAP",
    posSide="short",
    type= "add",
    amt="1"
)
print(result)

请求参数

参数名 类型 是否必须 描述
instId String 产品ID
posSide String 持仓方向,默认值是net
long:开平仓模式开多
short:开平仓模式开空
net:买卖模式
type String 增加/减少保证金
add:增加,或者转入质押资产(一键借币)
reduce:减少,或者转出质押资产(一键借币)
amt String 增加或减少的保证金数量
ccy String 增加或减少的保证金的币种,
仅适用于逐仓自主划转和一键借币模式下的币币杠杆
auto Boolean 是否自动借币转 true 或 false,默认false
仅适用于逐仓自主划转保证金模式下的币币杠杆

返回结果

{
    "code": "0",
    "data": [
        {
            "amt": "0.3",
            "ccy": "BTC",
            "instId": "BTC-USDT",
            "leverage": "",
            "posSide": "net",
            "type": "add"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
instId String 产品ID
posSide String 持仓方向
amt String 已增加/减少的保证金数量
type String 增加/减少保证金
leverage String 调整保证金后的实际杠杆倍数
ccy String 增加或减少的保证金的币种

获取杠杆倍数

限速:20次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/leverage-info

请求示例

GET /api/v5/account/leverage-info?instId=BTC-USDT&mgnMode=cross

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 获取杠杆倍数
result = accountAPI.get_leverage(
    instId="BTC-USDT",
    mgnMode="cross"
)
print(result)

请求参数

参数名 类型 是否必须 描述
instId String 产品ID
支持多个instId查询,半角逗号分隔。instId个数不超过20个
mgnMode String 保证金模式
isolated:逐仓 cross:全仓

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "instId": "BTC-USDT-200626",
        "mgnMode": "cross",
        "posSide": "long",
        "lever": "10"
    },{
        "instId": "BTC-USDT-200626",
        "mgnMode": "cross",
        "posSide": "short",
        "lever": "10"
    }]
}

返回参数

参数名 类型 描述
instId String 产品ID
mgnMode String 保证金模式
posSide String 持仓方向
long:开平仓模式开多
short:开平仓模式开空
net:买卖模式
开平仓模式下会返回两个方向的杠杆倍数
lever String 杠杆倍数

获取杠杆倍数预估信息

获取指定杠杆倍数下,相关的预估信息。

限速:5次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/adjust-leverage-info

请求示例

GET /api/v5/account/adjust-leverage-info?instType=MARGIN&mgnMode=isolated&lever=3&instId=BTC-USDT

请求参数

参数名 类型 是否必须 描述
instType String 产品类型
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
mgnMode String 保证金模式
isolated:逐仓 cross:全仓
lever String 杠杆倍数
instId String 可选 产品 ID,如 BTC-USDT
必填的场景有:交割永续,逐仓杠杆,以及单币种全仓杠杆。
ccy String 可选 保证金币种,如 BTC
单币种保证金模式跨币种保证金模式组合保证金模式的全仓杠杆时必填。
posSide String 持仓方向
net: 默认值,代表买卖模式
long: 开平模式下的多仓
short:开平模式下的空仓
仅适用交割、永续。

返回结果

{
    "code": "0",
    "data": [
        {
            "estAvailQuoteTrans": "",
            "estAvailTrans": "1.1398040558348279",
            "estLiqPx": "",
            "estMaxAmt": "10.6095865868904898",
            "estMgn": "0.0701959441651721",
            "estQuoteMaxAmt": "176889.6871254563042714",
            "estQuoteMgn": "",
            "existOrd": false,
            "maxLever": "10",
            "minLever": "0.01"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
estAvailQuoteTrans String 对应杠杆倍数下,计价货币预估可转出的保证金数量
全仓时,为交易账户最大可转出
逐仓时,为逐仓仓位可减少的保证金
estAvailTrans String 对应杠杆倍数下,交易货币的预估可转出的保证金数量
全仓时,为交易账户最大可转出
逐仓时,为逐仓仓位可减少的保证金
estLiqPx String 对应杠杆倍数下的预估强平价,仅在有仓位时有值
estMgn String 对应杠杆倍数下,仓位预估所需的保证金数量
对于杠杆仓位,为所需交易货币保证金
对于交割或永续仓位,为仓位所需保证金
estQuoteMgn String 对应杠杆倍数下,仓位预估所需的计价货币保证金数量
estMaxAmt String 对于杠杆,为对应杠杆倍数下,交易货币预估最大可借
对于交割和永续,为对应杠杆倍数下,预估的最大可开张数
estQuoteMaxAmt String 对应杠杆倍数下,杠杆计价货币预估最大可借
existOrd Boolean 当前是否存在挂单
true:存在挂单
false:不存在挂单
maxLever String 最大杠杆倍数
minLever String 最小杠杆倍数

获取交易产品最大可借

限速:20 次/2s

限速规则:UserID

HTTP 请求

GET /api/v5/account/max-loan

请求示例

# 单币种逐仓账户获取币币杠杆最大可借
GET  /api/v5/account/max-loan?instId=BTC-USDT&mgnMode=isolated

# 单币种全仓账户获取币币杠杆最大可借(指定保证金为BTC)
GET  /api/v5/account/max-loan?instId=BTC-USDT&mgnMode=cross&mgnCcy=BTC

# 跨币种全仓账户获取币币杠杠最大可借
GET  /api/v5/account/max-loan?instId=BTC-USDT&mgnMode=cross

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 单币种全仓账户获取币币杠杆最大可借(指定保证金为BTC)
result = accountAPI.get_max_loan(
    instId="BTC-USDT",
    mgnMode="cross",
    mgnCcy="BTC"
)
print(result)

请求参数

参数名 类型 是否必须 描述
instId String 产品 ID,如 BTC-USDT
支持多产品ID查询(不超过5个),半角逗号分隔
mgnMode String 仓位类型
isolated:逐仓
cross:全仓
mgnCcy String 可选 保证金币种,如 BTC
币币杠杆单币种全仓情况下必须指定保证金币种

返回结果

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "instId": "BTC-USDT",
      "mgnMode": "isolated",
      "mgnCcy": "",
      "maxLoan": "0.1",
      "ccy": "BTC",
      "side": "sell"
    },
    {
      "instId": "BTC-USDT",
      "mgnMode": "isolated",
      "mgnCcy": "",
      "maxLoan": "0.2",
      "ccy": "USDT",
      "side": "buy"
    }
  ]
}

返回参数

参数名 类型 描述
instId String 产品 ID
mgnMode String 仓位类型
mgnCcy String 保证金币种
maxLoan String 最大可借
ccy String 币种
side String 订单方向

获取当前账户交易手续费费率

限速:5次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/trade-fee

请求示例

# 获取币币BTC-USDT交易手续费率  
GET /api/v5/account/trade-fee?instType=SPOT&instId=BTC-USDT
import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 获取当前账户交易手续费费率
result = accountAPI.get_fee_rates(
    instType="SPOT",
    instId="BTC-USDT"
)
print(result)

请求参数

参数名 类型 是否必须 描述
instType String 产品类型
SPOT:币币
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
instId String 产品ID,如 BTC-USDT
仅适用于instType为币币/币币杠杆
uly String 标的指数
适用于交割/永续/期权,如 BTC-USD
instFamily String 交易品种
适用于交割/永续/期权,如 BTC-USD

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
            "category": "1", //已废弃
            "delivery": "",
            "exercise": "",
            "instType": "SPOT",
            "level": "lv1",
            "maker": "-0.0008",
            "makerU": "",
            "makerUSDC": "",
            "taker": "-0.001",
            "takerU": "",
            "takerUSDC": "",
            "ts": "1608623351857",
            "fiat": []
        }
    ]
}

返回参数

参数名 类型 描述
level String 手续费等级
taker String 对于币币/杠杆,为 USDT 交易区的吃单手续费率;
对于永续,交割和期权合约,为币本位合约费率
maker String 对于币币/杠杆,为 USDT 交易区的挂单手续费率;
对于永续,交割和期权合约,为币本位合约费率
takerU String USDT 合约吃单手续费率,仅适用于交割/永续
makerU String USDT 合约挂单手续费率,仅适用于交割/永续
delivery String 交割手续费率
exercise String 行权手续费率
instType String 产品类型
takerUSDC String 对于币币/杠杆,为 USDⓈ&Crypto 交易区的吃单手续费率;
对于永续和交割合约,为 USDC 合约费率
makerUSDC String 对于币币/杠杆,为 USDⓈ&Crypto 交易区的挂单手续费率;
对于永续和交割合约,为 USDC 合约费率
ts String 数据返回时间,Unix时间戳的毫秒数格式,如 1597026383085
category String 币种类别(已废弃)
fiat Array 法币费率
> ccy String 法币币种
> taker String 吃单手续费率
> maker String 挂单手续费率

获取计息记录

限速:5次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/interest-accrued

请求示例

GET /api/v5/account/interest-accrued

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 获取计息记录
result = accountAPI.get_interest_accrued()
print(result)

请求参数

参数名 类型 是否必须 描述
type String 借币类型
1:尊享借币
2:市场借币
默认为市场借币
ccy String 借贷币种,如 BTC
仅适用于市场借币
仅适用于币币杠杆
instId String 产品ID,如 BTC-USDT
仅适用于市场借币
mgnMode String 保证金模式
cross:全仓
isolated:逐仓
仅适用于市场借币
after String 请求此时间戳之前(更旧的数据)的分页内容,Unix时间戳的毫秒数格式,如 1597026383085
before String 请求此时间戳之后(更新的数据)的分页内容,Unix时间戳的毫秒数格式,如 1597026383085
limit String 分页返回的结果集数量,最大为100,不填默认返回100条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "instId": "",
            "interest": "0.0003960833333334",
            "interestRate": "0.0000040833333333",
            "liab": "97",
            "mgnMode": "",
            "ts": "1637312400000",
            "type": "1"
        }
        {
            "ccy": "USDT",
            "instId": "",
            "interest": "0.0004083333333334",
            "interestRate": "0.0000040833333333",
            "liab": "100",
            "mgnMode": "",
            "ts": "1637049600000",
            "type": "1"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
type String 类型
1:尊享借币
2:市场借币
ccy String 借贷币种,如 BTC
instId String 产品ID,如 BTC-USD-180216
仅适用于市场借币
mgnMode String 保证金模式
cross:全仓
isolated:逐仓
interest String 利息
interestRate String 计息利率(小时)
liab String 计息负债
ts String 计息时间,Unix时间戳的毫秒数格式,如 1597026383085

获取用户当前市场借币利率

限速:5次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/interest-rate

请求示例

GET /api/v5/account/interest-rate

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 获取用户当前市场借币利率
result = accountAPI.get_interest_rate()
print(result)

请求参数

参数名 类型 是否必须 描述
ccy String 币种

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "ccy":"BTC",
            "interestRate":"0.0001"
        },
        {
            "ccy":"LTC",
            "interestRate":"0.0003"
        }
    ]
}

返回参数

参数名 类型 描述
interestRate String 市场借币利率(当前小时)
ccy String 币种

期权greeks的PA/BS切换

设置greeks的展示方式。

限速:5次/2s

限速规则:UserID

HTTP请求

POST /api/v5/account/set-greeks

请求示例

POST /api/v5/account/set-greeks 
body
{
    "greeksType":"PA"
}

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 期权greeks的PA/BS切换
result = accountAPI.set_greeks(greeksType="PA")
print(result)

请求参数

参数名 类型 是否必须 描述
greeksType String 希腊字母展示方式
PA:币本位,BS:美元本位

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "greeksType": "PA"
    }]
}

返回参数

参数名 类型 描述
greeksType String 当前希腊字母展示方式

逐仓交易设置

可以通过该接口设置币币杠杆和交割、永续的逐仓仓位保证金的划转模式

限速:5次/2s

限速规则:UserID

HTTP请求

POST /api/v5/account/set-isolated-mode

请求示例

POST /api/v5/account/set-isolated-mode
body
{
    "isoMode":"automatic",
    "type":"MARGIN"
}
import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 逐仓交易设置
result = accountAPI.set_isolated_mode(
    isoMode="automatic",
    type="MARGIN"
)
print(result)

请求参数

参数名 类型 是否必须 描述
isoMode String 逐仓保证金划转模式
automatic:开仓自动划转
autonomy:自主划转 (仅适用在合约)
quick_margin:一键借币 (仅适用在币币杠杆)
type String 业务线类型
MARGIN:币币杠杆
CONTRACTS:合约

返回结果

{
    "code": "0",
    "data": [
        {
            "isoMode": "automatic"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
isoMode String 逐仓保证金划转模式
automatic:开仓自动划转
autonomy:自主划转
quick_margin:一键借币

查看账户最大可转余额

当指定币种时会返回该币种的交易账户到资金账户的最大可划转数量,不指定币种会返回所有拥有的币种资产可划转数量。

限速:20次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/max-withdrawal

请求示例

GET /api/v5/account/max-withdrawal

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 查看账户最大可转余额
result = accountAPI.get_max_withdrawal()
print(result)

请求参数

参数名 类型 是否必须 描述
ccy String 币种,如 BTC
支持多币种查询(不超过20个),币种之间半角逗号分隔

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
            "ccy": "BTC",
            "maxWd": "124",
            "maxWdEx": "125",
            "spotOffsetMaxWd": "",
            "spotOffsetMaxWdEx": ""
        },
        {
            "ccy": "ETH",
            "maxWd": "10",
            "maxWdEx": "12",
            "spotOffsetMaxWd": "",
            "spotOffsetMaxWdEx": ""
        }
    ]
}

返回参数

参数名 类型 描述
ccy String 币种
maxWd String 最大可划转数量(不包含 跨币种保证金模式/组合保证金模式 借币金额)
maxWdEx String 最大可划转数量(包含 跨币种保证金模式/组合保证金模式 借币金额)
spotOffsetMaxWd String 现货对冲不支持借币最大可转数量
仅适用于组合保证金模式
spotOffsetMaxWdEx String 现货对冲支持借币的最大可转数量
仅适用于组合保证金模式

查看账户特定风险状态

仅适用于PM账户

限速:10次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/risk-state

请求示例

GET /api/v5/account/risk-state

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 查看账户持仓风险
result = accountAPI.get_account_position_risk()
print(result)

返回结果

{
    "code": "0",
    "data": [
        {
            "atRisk": false,
            "atRiskIdx": [],
            "atRiskMgn": [],
            "ts": "1635745078794"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
atRisk String 自动借币模式下的账户风险状态
true: 当前账户为特定风险状态
false: 当前不是特定风险状态
atRiskIdx Array 衍生品的risk unit列表
atRiskMgn Array 杠杆的risk unit列表
ts String 接口数据返回时间 ,Unix时间戳的毫秒数格式,如 1597026383085

一键借币模式手动借币还币

限速:5次/2s

限速规则:UserID

HTTP请求

POST /api/v5/account/quick-margin-borrow-repay

请求示例

POST /api/v5/account/quick-margin-borrow-repay 
body
{
    "instId":"BTC-USDT",
    "ccy":"USDT",
    "side":"borrow",
    "amt":"100"
}

请求参数

参数名 类型 是否必须 描述
instId String 产品ID,如BTC-USDT
ccy String 借贷币种,如 BTC
side String borrow:借币,repay:还币
amt String 借/还币的数量

返回结果

{
    "code": "0",
    "data": [
        {
            "amt": "100",
            "instId":"BTC-USDT",
            "ccy": "USDT",
            "side": "borrow"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
instId String 产品ID,如BTC-USDT
ccy String 借贷币种,如 BTC
side String borrow:借币,repay:还币
amt String 借/还币的数量

获取一键借币还币历史

限速:5次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/quick-margin-borrow-repay-history

请求示例

GET /api/v5/account/quick-margin-borrow-repay-history

请求参数

参数名 类型 是否必须 描述
instId String 产品ID,如 BTC-USDT
ccy String 借贷币种,如 BTC
side String borrow:借币,repay:还币
after String 请求此 ID 之前(更旧的数据)的分页内容,传的值为对应接口的refId
before String 请求此 ID 之后(更新的数据)的分页内容,传的值为对应接口的refId
begin String 筛选的开始时间戳,Unix 时间戳为毫秒数格式,如 1597026383085
end String 筛选的结束时间戳,Unix 时间戳为毫秒数格式,如 1597027383085
limit String 返回结果的数量,最大为100,默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "instId": "BTC-USDT",
            "ccy": "USDT",
            "side": "borrow",
            "accBorrowed": "0.01",
            "amt": "0.005",
            "refId": "1637310691470124",
            "ts": "1637310691470"
        },
        {
            "instId": "BTC-USDT",
            "ccy": "USDT",
            "side": "borrow",
            "accBorrowed": "0.01",
            "amt": "0.005",
            "refId": "1637310691470123",
            "ts": "1637310691400"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
instId String 产品ID,如 BTC-USDT
ccy String 借贷币种,如 BTC
side String borrow:借币,repay:还币
accBorrowed String 累计借币
amt String 借/还币的数量
refId String 对应记录ID,借币或还币的ID
ts String 借/还币时间

尊享借币还币

单个币种的借币订单数量最多为20个

限速:6次/s

限速规则:UserID

HTTP请求

POST /api/v5/account/borrow-repay

请求示例

POST /api/v5/account/borrow-repay 
body
{
    "ccy":"USDT",
    "side":"borrow",
    "amt":"100"
}

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 尊享借币还币
result = accountAPI.borrow_repay(
    ccy="USDT",
    side="borrow",
    amt="100"
)
print(result)

请求参数

参数名 类型 是否必须 描述
ccy String 借贷币种,如 BTC
side String borrow:借币,repay:还币
amt String 借/还币的数量
ordId String 可选 借币订单ID,还币时,该字段必填

返回结果

{
    "code": "0",
    "data": [
        {
            "amt": "70809.316200",
            "ccy": "USDT",
            "ordId": "544199684697214976",
            "side": "borrow",
            "state": "1"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
ccy String 借贷币种,如 BTC
side String borrow:借币,repay:还币
amt String 已借/还币的数量
ordId String 借币订单ID
state String 订单状态
1:借币申请中
2:借币中
3:还币申请中
4:已还币
5:借币失败

获取尊享借币还币历史

限速:5次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/borrow-repay-history

请求示例

GET /api/v5/account/borrow-repay-history

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 获取尊享借币还币历史
result = accountAPI.get_borrow_repay_history()
print(result)

请求参数

参数名 类型 是否必须 描述
ccy String 借贷币种,如 BTC
after String 请求此时间戳之前(更旧的数据)的分页内容,Unix时间戳的毫秒数格式,如 1597026383085
before String 请求此时间戳之后(更新的数据)的分页内容,Unix时间戳的毫秒数格式,如 1597026383085
limit String 分页返回的结果集数量,最大为100,不填默认返回100条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "tradedLoan": "102",
            "ts": "1637310691470",
            "type": "2",
            "usedLoan": "97"
        },
        {
            "ccy": "USDT",
            "tradedLoan": "102",
            "ts": "1637050435058",
            "type": "2",
            "usedLoan": "199"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
ccy String 借贷币种,如 BTC
type String 类型
1:借币
2:还币
3:扣息失败系统还币
tradedLoan String 借/还币数量
usedLoan String 当前账户已借额度
ts String 借/还币时间

获取尊享借币计息记录

限速:5次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/vip-interest-accrued

请求示例

GET /api/v5/account/vip-interest-accrued

请求参数

参数名 类型 是否必须 描述
ccy String 借贷币种,如 BTC,仅适用于币币杠杆
ordId String 借币订单ID
after String 请求此时间戳之前(更旧的数据)的分页内容,Unix时间戳的毫秒数格式,如 1597026383085
before String 请求此时间戳之后(更新的数据)的分页内容,Unix时间戳的毫秒数格式,如 1597026383085
limit String 分页返回的结果集数量,最大为100,不填默认返回100条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "interest": "0.0003960833333334",
            "interestRate": "0.0000040833333333",
            "liab": "97",
            "ordId": "16373124000001235",
            "ts": "1637312400000"
        },
        {
            "ccy": "USDT",
            "interest": "0.0004083333333334",
            "interestRate": "0.0000040833333333",
            "liab": "100",
            "ordId": "16370496000001234",
            "ts": "1637049600000"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
ordId String 借币订单ID
ccy String 借贷币种,如 BTC
interest String 利息
interestRate String 计息利率(小时)
liab String 计息负债
ts String 计息时间,Unix时间戳的毫秒数格式,如 1597026383085

获取尊享借币扣息记录

限速:5次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/vip-interest-deducted

请求示例

GET /api/v5/account/vip-interest-deducted

请求参数

参数名 类型 是否必须 描述
ordId String 借币订单ID
ccy String 借贷币种,如 BTC,仅适用于币币杠杆
after String 请求此时间戳之前(更旧的数据)的分页内容,Unix时间戳的毫秒数格式,如 1597026383085
before String 请求此时间戳之后(更新的数据)的分页内容,Unix时间戳的毫秒数格式,如 1597026383085
limit String 分页返回的结果集数量,最大为100,不填默认返回100条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "interest": "0.0003960833333334",
            "interestRate": "0.0000040833333333",
            "liab": "97",
            "ordId": "16373124000001235",
            "ts": "1637312400000"
        },
        {
            "ccy": "USDT",
            "interest": "0.0004083333333334",
            "interestRate": "0.0000040833333333",
            "liab": "100",
            "ordId": "16370496000001234",
            "ts": "1637049600000"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
ordId String 借币订单ID
ccy String 借贷币种,如 BTC
interest String 利息
interestRate String 计息利率(小时)
liab String 计息负债
ts String 计息时间,Unix时间戳的毫秒数格式,如 1597026383085

尊享借币订单列表

限速:5次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/vip-loan-order-list

请求示例

GET /api/v5/account/vip-loan-order-list

请求参数

参数名 类型 是否必须 描述
ordId String 借币订单ID
state String 订单状态
1:借币申请中
2:借币中
3:还币申请中
4:已还币
5:借币失败
ccy String 借贷币种,如 BTC
after String 请求此ID之前(更旧的数据)的分页内容,传的值为对应接口的ordId
before String 请求此ID之后(更新的数据)的分页内容,传的值为对应接口的ordId
limit String 返回结果的数量,最大为100,默认100条

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
         {
            "borrowAmt": "1.5000000000000000",
            "ccy": "USDT",
            "curRate": "0.0000169999999992",
            "dueAmt": "0.0000000000000000",
            "nextRefreshTime": "1688172235000",
            "ordId": "584301085292781568",
            "origRate": "0.0000169999999992",
            "repayAmt": "1.5000000000000000",
            "state": "4",
            "ts": "1685580235000"
        }
   ]
}

返回参数

参数名 类型 描述
ts String 订单创建时间,Unix时间戳的毫秒数格式,如 1597026383085
nextRefreshTime String 下一次理论刷新时间,Unix时间戳的毫秒数格式,如 1597026383085
ccy String 借贷币种,如 BTC
ordId String 订单ID
state String 订单状态
1:借币申请中
2:借币中
3:还币申请中
4:已还币
5:业务异常,借币失败
origRate String 订单原始利率
curRate String 借贷币种当前利率
dueAmt String 待还数量
borrowAmt String 借币数量
repayAmt String 还币数量

尊享借币订单详情

限速:5次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/vip-loan-order-detail

请求示例

GET /api/v5/account/vip-loan-order-detail

请求参数

参数名 类型 是否必须 描述
ordId String 借币订单ID
ccy String 借贷币种,如 BTC
before String 请求此时间戳之后(更新的数据)的分页内容,Unix时间戳的毫秒数格式,如 1597026383085
after String 请求此时间戳之前(更旧的数据)的分页内容,Unix时间戳的毫秒数格式,如 1597026383085
limit String 返回结果的数量,最大为100,默认100条

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "amt": "1.5000000000000000",
            "ccy": "USDT",
            "failReason": "",
            "rate": "0.0000000000000000",
            "ts": "1685580264572",
            "type": "2"
        }
   ]
}

返回参数

参数名 类型 描述
ts String 操作时间
ccy String 借贷币种,如 BTC
type String 操作类型
1:借币
2:还币
3:系统还币
4:利率刷新
rate String 订单当前利率(日利率)
amt String 借还数量
failReason String 失败原因

获取借币利率与限额

限速:5次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/interest-limits

请求示例

GET /api/v5/account/interest-limits?type=1&ccy=BTC

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 获取借币利率与限额
result = accountAPI.get_interest_limits(
    type="1",
    ccy="BTC"
)
print(result)

请求参数

参数名 类型 是否必须 描述
type String 借币类型
1:尊享借币
2:市场借币
默认为市场借币
ccy String 借贷币种,如 BTC

返回结果

{
    "code": "0",
    "data": [
        {
            "debt": "97.06402000000000000000000000000000",
            "interest": "",
            "nextDiscountTime": "1637312400000",
            "nextInterestTime": "1637312400000",
            "loanAlloc": "", 
            "records": [
                {
                    "availLoan": "0.0000000000000000",
                    "ccy": "BTC",
                    "interest": "",
                    "loanQuota": "600.0000000000000000",
                    "posLoan": "0",
                    "rate": "0.00199200",
                    "avgRate": "0.00199200",
                    "surplusLmt": "600.0000000000000000",
                    "surplusLmtDetails":{
                        "allAcctRemainingQuota": "600.00",
                        "curAcctRemainingQuota": "600.00",
                        "platRemainingQuota": "600.00"
                    },
                    "usedLmt": "0",
                    "usedLoan": "0.0000000000000000"
                }
            ]
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
debt String 当前负债,单位为USDT
interest String 当前记息,单位为USDT
仅适用于市场借币
nextDiscountTime String 下次扣息时间,Unix时间戳的毫秒数格式,如 1597026383085
nextInterestTime String 下次计息时间,Unix时间戳的毫秒数格式,如 1597026383085
loanAlloc String 当前交易账户尊享借币可用额度的比率(百分比)
1. 范围为[0, 100]. 精度为 0.01% (2位小数)
2. 0 代表母账户没有为子账户分配;
3. "" 代表母子账户共享
records Array 各币种详细信息
> ccy String 借贷币种,如 BTC
> rate String 日利率
> loanQuota String 母账户维度借币限额
如果已配置可用额度,该字段代表当前交易账户的借币限额
> surplusLmt String 母子账户剩余可借
如果已配置可用额度,该字段代表当前交易账户的剩余可借
> surplusLmtDetails Array 母子账户剩余可借额度详情,母子账户剩余可借额度的值取该数组中的最小值,可以用来判断是什么原因导致可借额度不足
仅适用于尊享借币
>> allAcctRemainingQuota String 母子账户剩余额度
>> curAcctRemainingQuota String 当前账户剩余额度
仅适用于为子账户分配限额的场景
>> platRemainingQuota String 平台剩余额度,当平台剩余额度大于curAcctRemainingQuota或者allAcctRemainingQuota时,会显示大于某个值,如">1000"
> usedLmt String 母子账户已借额度
如果已配置可用额度,该字段代表当前交易账户的已借额度
> interest String 已计未扣利息
仅适用于市场借币
> posLoan String 当前账户负债占用(锁定额度内)
仅适用于尊享借币
> availLoan String 当前账户剩余可用(锁定额度内)
仅适用于尊享借币
> usedLoan String 当前账户已借额度
仅适用于尊享借币
> avgRate String 币种已借平均(小时)利率,仅适用于尊享借币

组合保证金的虚拟持仓保证金计算

计算用户的模拟头寸或当前头寸的投资组合保证金信息,一次请求最多添加200个虚拟仓位

限速:2次/2s

限速规则:UserID

权限:读取

HTTP请求

POST /api/v5/account/simulated_margin

请求示例

# 计算指定业务线已有真实仓位和虚拟仓位的投资组合保证金
POST /api/v5/account/simulated_margin
body
{
   "instType":"SWAP",
   "inclRealPos":true,
   "simPos":[
     {
          "pos":"10",
          "instId":"BTC-USDT-SWAP"
     },
     {
          "pos":"10",
          "instId":"LTC-USDT-SWAP"
     }
   ]
}

# 只计算已有真实仓位
POST /api/v5/account/simulated_margin
body
{
   "inclRealPos":true
}


# 只计算虚拟仓位
POST /api/v5/account/simulated_margin
body
{
   "inclRealPos": false,
   "simPos":[
     {
          "pos":"10",
          "instId":"BTC-USDT-SWAP"
     },
     {
          "pos":"10",
          "instId":"LTC-USDT-SWAP"
     }
   ]
}

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 计算指定业务线已有真实仓位和虚拟仓位的投资组合保证金
result = accountAPI.get_simulated_margin(
    instType="SWAP",
    inclRealPos=True,
    simPos=[
        {
            "pos": "10",
            "instId": "BTC-USDT-SWAP"
        },
        {
            "pos": "10",
            "instId": "LTC-USDT-SWAP"
        }
    ]
)
print(result)

请求参数

参数名 类型 是否必须 描述
instType String 产品类型
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
inclRealPos Boolean 是否代入已有仓位
true:调整被代入的已有仓位信息
false:不代入已有仓位,仅使用simPos里新增的模拟仓位进行计算,默认为True
spotOffsetType String 现货对冲模式
1:现货对冲模式U模式 2:现货对冲模式币模式 3:衍生品模式
默认是 3
simPos Array 模拟仓位列表
> instId String 交易产品ID
> pos String 持仓量

返回结果

{
    "code": "0",
    "data": [
        {
            "imr": "0.005432310199023",
            "mmr": "0.0041787001530946",
            "acctImr": "6847.294720745276",
            "acctMmr": "5140.116514138115",
            "mr1": "0.0041787001530946",
            "mr2": "0.0000734347499275",
            "mr3": "0",
            "mr4": "0",
            "mr5": "0",
            "mr6": "0.0028031968471",
            "mr7": "0.0022",
            "posData": [
                {
                    "delta": "-0.008926024905498",
                    "gamma": "-0.0707804093543001",
                    "instId": "BTC-USD-220325-50000-C",
                    "instType": "OPTION",
                    "notionalUsd": "3782.9800000000005",
                    "pos": "-1",
                    "theta": "0.000093015207115",
                    "vega": "-0.0000382697346669"
                }
            ],
            "riskUnit": "BTC-USD",
            "ts": "1646639497536"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
riskUnit String 账户内所有持仓的riskUnit
ts String 账户信息的更新时间,Unix时间戳的毫秒数格式,如 1597026383085
mmr String riskUnit维度的维持保证金
imr String riskUnit维度的最低初始保证金
acctImr String 账户维度的最低初始保证金
acctMmr String 账户维度的维持保证金
mr1 String 现货&波动率压力测试值
mr2 String 时间价值压力测试值
mr3 String 波动率跨期压力测试值
mr4 String 基差压力测试值
mr5 String 利率风险压力测试值
mr6 String 极端市场波动压力测试值
mr7 String 减仓成本压力测试值
posData Array 持仓列表
> instId String 产品ID,如 BTC-USD-180216
> instType String 产品类型
> pos String 持仓量
> notionalUsd String 以美金价值为单位的持仓数量
> delta String 期权价格对uly价格的敏感度
> gamma String delta对uly价格的敏感度
> vega String 期权价格对隐含波动率的敏感度
> theta String 期权价格对剩余期限的敏感度

查看账户Greeks

获取账户资产的greeks信息。

限速:10次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/greeks

请求示例

获取账户中所有资产的greeks
GET /api/v5/account/greeks

获取账户中BTC的greeks
GET /api/v5/account/greeks?ccy=BTC

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 查看账户Greeks
result = accountAPI.get_greeks()
print(result)

请求参数

参数名 类型 是否必须 描述
ccy String 币种,如 BTC

返回结果

{
    "code":"0",
    "data":[
        {            
           "thetaBS": "",
           "thetaPA":"",
           "deltaBS":"",
           "deltaPA":"",
           "gammaBS":"",
           "gammaPA":"",
           "vegaBS":"",    
           "vegaPA":"",
           "ccy":"BTC"
           "ts":"1620282889345"
        }
    ],
    "msg":""
}

返回参数

参数名 类型 描述
deltaBS String 美金本位账户资产delta
deltaPA String 币本位账户资产delta
gammaBS String 美金本位账户资产gamma,仅适用于期权
gammaPA String 币本位账户资产gamma,仅适用于期权
thetaBS String 美金本位账户资产theta,仅适用于期权
thetaPA String 币本位账户资产theta,仅适用于期权
vegaBS String 美金本位账户资产vega,仅适用于期权
vegaPA String 币本位账户资产vega,仅适用于期权
ccy String 币种
ts String 获取greeks的时间,Unix时间戳的毫秒数格式,如 1597026383085

获取组合保证金模式仓位限制

仅支持获取组合保证金模式下,交割、永续和期权的全仓仓位限制。

限速:10次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/position-tiers

请求示例

# 查看BTC-USDT在组合保证金模式下的全仓限制
GET /api/v5/account/position-tiers?instType=SWAP&uly=BTC-USDT

import okx.Account as Account

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘:0 , 模拟盘:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# 获取组合保证金模式仓位限制
result = accountAPI.get_account_position_tiers(
    instType="SWAP",
    uly="BTC-USDT"
)
print(result)

请求参数

参数名 类型 是否必须 描述
instType String 产品类型
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
uly String 可选 标的指数,如 BTC-USDT,支持多个查询(不超过3个),uly之间半角逗号分隔
适用于交割/永续/期权
ulyinstFamily必须传一个,若传两个,以instFamily为主
instFamily String 可选 交易品种,如 BTC-USDT,支持多个查询(不超过5个),instFamily之间半角逗号分隔
适用于交割/永续/期权
ulyinstFamily必须传一个,若传两个,以instFamily为主

返回结果

{
  "code": "0",
  "data": [
    {
      "instFamily": "BTC-USD",
      "maxSz": "10000",
      "posType": "",
      "uly": "BTC-USDT"
    }
  ],
  "msg": ""
}

返回参数

参数名 类型 描述
uly String 标的指数
适用于交割/永续/期权
instFamily String 交易品种
适用于交割/永续/期权
maxSz String 最大持仓量
posType String 限仓类型,仅适用于组合保证金模式下的期权全仓。
1:所有合约挂单 + 持仓张数,2:所有合约总挂单张数,3:所有合约总挂单单数,4:同方向合约挂单 + 持仓张数,5:单一合约总挂单单数,6:单一合约挂单 + 持仓张数,7:单笔挂单张数"

设置组合保证金账户风险对冲模式

设置组合保证金账户风险对冲模式

限速:10次/2s

限速规则:UserID

HTTP请求

POST /api/v5/account/set-riskOffset-type

请求示例

POST /api/v5/account/set-riskOffset-type
body 
{
    "type":"1"
}

请求参数

参数名 类型 是否必须 描述
type String 风险对冲模式
1:现货对冲(USDT)
2:现货对冲(币)
3:衍生品对冲

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "type":"1"
    }]
}

返回参数

参数名 类型 描述
type String 风险对冲模式
1:现货对冲(USDT)
2:现货对冲(币)
3:衍生品对冲

开通期权交易

限速:5次/2s

限速规则:UserID

HTTP请求

POST /api/v5/account/activate-option

请求参数

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "ts": "1600000000000"
    }]
}

返回参数

参数名 类型 描述
ts String 开通时间

设置自动借币

仅适用于跨币种保证金模式和组合保证金模式

限速:5次/2s

限速规则:UserID

HTTP请求

POST /api/v5/account/set-auto-loan

请求示例

POST /api/v5/account/set-auto-loan
body
{
    "autoLoan":true,
}

请求参数

参数名 类型 是否必须 描述
autoLoan Boolean 是否自动借币
有效值为true, false
默认为 true

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "autoLoan": true
    }]
}

返回参数

参数名 类型 描述
autoLoan Boolean 是否自动借币

设置账户模式

账户模式的首次设置,需要在网页或手机app上进行。

限速:5次/2s

限速规则:UserID

HTTP请求

POST /api/v5/account/set-account-level

请求示例

POST /api/v5/account/set-account-level
body
{
    "acctLv":"1"
}

请求参数

参数名 类型 是否必须 描述
acctLv String 账户模式
1: 简单交易模式
2: 单币种保证金模式
3: 跨币种保证金模式
4: 组合保证金模式

返回结果

{
    "code":"0",
    "msg":"",
    "data" :[
          {
            "acctLv":"1"
          }
    ]  
}

返回参数

参数名 类型 描述
acctLv String 账户模式

重置 MMP 状态

一旦 MMP 被触发,可以使用该接口解冻。
仅适用于组合保证金账户模式下的期权订单,且有 MMP 权限。

限速:5次/2s

限速规则:UserID

HTTP请求

POST /api/v5/account/mmp-reset

请求示例

POST /api/v5/account/mmp-reset
body
{
    "instType":"OPTION",
    "instFamily":"BTC-USD"
}

请求参数

参数名 类型 是否必须 描述
instType String 交易产品类型
OPTION:期权
默认为期权
instFamily String 交易品种

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "result":true
        }
    ]
}

返回参数

参数名 类型 描述
result Boolean 重置结果
true:将做市商保护状态重置为了 inactive 状态
false:重置失败

设置 MMP

可以使用该接口进行 MMP 的配置。
仅适用于组合保证金账户模式下的期权订单,且有 MMP 权限。

限速:2次/10s

限速规则:UserID

HTTP请求

POST /api/v5/account/mmp-config

请求示例

POST /api/v5/account/mmp-config
body
{
    "instFamily":"BTC-USD",
    "timeInterval":"5000",
    "frozenInterval":"2000",
    "qtyLimit": "100"
}

请求参数

参数名 类型 是否必须 描述
instFamily String 交易品种
timeInterval String 时间窗口 (毫秒)。
"0" 代表不使用 MMP
frozenInterval String 冻结时间长度 (毫秒)。
"0" 代表一直冻结,直到调用 "重置 MMP 状态" 接口解冻
qtyLimit String 成交数量的上限
需大于 0

返回结果

{
  "code": "0",
  "msg": "",
  "data": [
    {
        "frozenInterval":"2000",
        "instFamily":"BTC-USD",
        "qtyLimit": "100",
        "timeInterval":"5000"
    }
  ]
}

返回参数

参数名 类型 描述
instFamily String 交易品种
timeInterval String 时间窗口 (毫秒)
frozenInterval String 冻结时间长度 (毫秒)
qtyLimit String 成交张数的上限

查看 MMP 配置

可以使用该接口获取 MMP 的配置信息。
仅适用于组合保证金账户模式下的期权订单,且有 MMP 权限。

限速:20次/2s

限速规则:UserID

HTTP请求

GET /api/v5/account/mmp-config

请求示例

GET /api/v5/account/mmp-config?instFamily=BTC-USD

请求参数

参数名 类型 是否必须 描述
instFamily String 交易品种

返回结果

{
  "code": "0",
  "data": [
    {
      "frozenInterval": "2000",
      "instFamily": "ETH-USD",
      "mmpFrozen": true,
      "mmpFrozenUntil": "2326882",
      "qtyLimit": "10",
      "timeInterval": "5000"
    }
  ],
  "msg": ""
}

返回参数

参数名 类型 描述
instFamily String 交易品种
mmpFrozen Boolean 是否 MMP 被触发. true 或者 false
mmpFrozenUntil String 如果配置了frozenInterval且mmpFrozen = true,则为不再触发MMP时的时间窗口(单位为ms),否则为“”
timeInterval String 时间窗口 (毫秒)。
"0" 代表不使用 MMP
frozenInterval String 冻结时间长度 (毫秒)。
"0" 代表一直冻结,直到调用 "重置 MMP 状态" 接口解冻
qtyLimit String 成交张数的上限

WebSocket

账户频道

获取账户信息,首次订阅按照订阅维度推送数据,此外,当下单、撤单、成交等事件触发时,推送数据以及按照订阅维度定时推送数据

请求示例:单个

{
    "op": "subscribe",
    "args": [{
        "channel": "account",
        "ccy": "BTC"
    }]
}

请求示例

{
    "op": "subscribe",
    "args": [
    {
      "channel": "account",
      "extraParams": "
        {
          \"updateInterval\": \"0\"
        }
      "
    }
  ]
}

请求参数

参数 类型 是否必须 描述
op String 操作,subscribe unsubscribe
args Array 请求订阅的频道列表
> channel String 频道名,account
> ccy String 币种
> extraParams String 额外配置
>> updateInterval int 0: 仅根据账户事件推送数据
若不添加该字段或将其设置为除0外的其他值,数据将根据事件推送并定时推送。
使用该字段需严格遵守以下格式。
"extraParams": "
{
\"updateInterval\": \"0\"
}
"

成功返回示例:单个

{
    "event": "subscribe",
    "arg": {
        "channel": "account",
        "ccy": "BTC"
    },
  "connId": "a4d3ae55"
}

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "account"
    },
  "connId": "a4d3ae55"
}

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"account\", \"ccy\" : \"BTC\"}]}",
  "connId": "a4d3ae55"
}

返回参数

参数 类型 是否必须 描述
event String 事件,subscribe unsubscribe error
arg Object 订阅的频道
> channel String 频道名,account
> ccy String 币种
code String 错误码
msg String 错误消息
connId String WebSocket连接ID

推送示例:单个

{
  "arg": {
    "channel": "account",
    "ccy": "BTC",
    "uid": "77982378738415879"
  },
  "data": [
    {
      "uTime": "1597026383085",
      "totalEq": "41624.32",
      "isoEq": "3624.32",
      "adjEq": "41624.32",
      "ordFroz": "0",
      "imr": "4162.33",
      "mmr": "4",
      "borrowFroz": "",
      "notionalUsd": "",
      "mgnRatio": "41624.32",
      "details": [
        {
          "availBal": "",
          "availEq": "1",
          "ccy": "BTC",
          "cashBal": "1",
          "uTime": "1617279471503",
          "disEq": "50559.01",
          "eq": "1",
          "eqUsd": "45078.3790756226851775",
          "frozenBal": "0",
          "interest": "0",
          "isoEq": "0",
          "liab": "0",
          "maxLoan": "",
          "mgnRatio": "",
          "notionalLever": "0.0022195262185864",
          "ordFrozen": "0",
          "upl": "0",
          "uplLiab": "0",
          "crossLiab": "0",
          "isoLiab": "0",
          "coinUsdPrice": "60000",
          "stgyEq":"0",
          "spotInUseAmt":"",
          "isoUpl":"",
          "borrowFroz": ""
        }
      ]
    }
  ]
}

推送示例

{
  "arg": {
    "channel": "account",
    "uid": "77982378738415879"
  },
  "data": [
    {
      "uTime": "1614846244194",
      "totalEq": "91884.8502560037982063",
      "adjEq": "91884.8502560037982063",
      "isoEq": "0",
      "ordFroz": "0",
      "imr": "0",
      "mmr": "0",
      "borrowFroz": "",
      "notionalUsd": "",
      "mgnRatio": "100000",
      "details": [{
          "availBal": "",
          "availEq": "1",
          "ccy": "BTC",
          "cashBal": "1",
          "uTime": "1617279471503",
          "disEq": "50559.01",
          "eq": "1",
          "eqUsd": "45078.3790756226851775",
          "fixedBal": "0",
          "frozenBal": "0",
          "interest": "0",
          "isoEq": "0",
          "liab": "0",
          "maxLoan": "",
          "mgnRatio": "",
          "notionalLever": "0.0022195262185864",
          "ordFrozen": "0",
          "upl": "0",
          "uplLiab": "0",
          "crossLiab": "0",
          "isoLiab": "0",
          "coinUsdPrice": "60000",
          "stgyEq":"0",
          "spotInUseAmt":"",
          "isoUpl":"",
          "borrowFroz": ""
        },
        {
          "availBal": "",
          "availEq": "41307.251992607125",
          "ccy": "USDT",
          "cashBal": "41307.251992607125",
          "uTime": "1617279471503",
          "disEq": "41325.8402560037982063",
          "eq": "41307.251992607125",
          "eqUsd": "45078.3790756226851775",
          "fixedBal": "0",
          "frozenBal": "0",
          "interest": "0",
          "isoEq": "0",
          "liab": "0",
          "maxLoan": "",
          "mgnRatio": "",
          "notionalLever": "0.0022195262185864",
          "ordFrozen": "0",
          "upl": "0",
          "uplLiab": "0",
          "crossLiab": "0",
          "isoLiab": "0",
          "coinUsdPrice": "1.00007",
          "stgyEq":"0",
          "spotInUseAmt":"",
          "isoUpl":"",
          "borrowFroz": ""
        }
      ]
    }
  ]
}

推送数据参数

参数名 类型 描述
arg Object 请求订阅的频道
> channel String 频道名
> uid String 用户标识
data Array 订阅的数据
> uTime String 获取账户信息的最新时间,Unix时间戳的毫秒数格式,如 1597026383085
> totalEq String 美金层面权益
> isoEq String 美金层面逐仓仓位权益
适用于单币种保证金模式跨币种保证金模式组合保证金模式
> adjEq String 美金层面有效保证金
适用于跨币种保证金模式组合保证金模式
> ordFroz String 美金层面全仓挂单占用保证金
仅适用于跨币种保证金模式
> imr String 美金层面占用保证金
适用于跨币种保证金模式组合保证金模式
> mmr String 美金层面维持保证金
适用于跨币种保证金模式组合保证金模式
> borrowFroz String 账户美金层面潜在借币占用保证金
仅适用于跨币种保证金模式组合保证金模式. 在其他账户模式下为"".
> mgnRatio String 美金层面保证金率
适用于跨币种保证金模式组合保证金模式
> notionalUsd String 以美金价值为单位的持仓数量,即仓位美金价值
适用于跨币种保证金模式组合保证金模式
> details Array 各币种资产详细信息
>> ccy String 币种
>> eq String 币种总权益
>> cashBal String 币种余额
>> uTime String 币种余额信息的更新时间,Unix时间戳的毫秒数格式,如 1597026383085
>> isoEq String 币种逐仓仓位权益
适用于单币种保证金模式跨币种保证金模式组合保证金模式
>> availEq String 可用保证金
适用于单币种保证金模式跨币种保证金模式组合保证金模式
>> disEq String 美金层面币种折算权益
>> fixedBal String 抄底宝、逃顶宝功能的币种冻结金额
>> availBal String 可用余额
适用于简单交易模式, 单币种保证金模式, 跨币种保证金模式组合保证金模式
>> frozenBal String 币种占用金额
>> ordFrozen String 挂单冻结数量
>> liab String 币种负债额
值为正数,如:"21625.64",适用于跨币种保证金模式组合保证金模式
>> upl String 未实现盈亏
适用于单币种保证金模式跨币种保证金模式组合保证金模式
>> uplLiab String 由于仓位未实现亏损导致的负债
适用于跨币种保证金模式组合保证金模式
>> crossLiab String 币种全仓负债额
适用于跨币种保证金模式组合保证金模式
>> isoLiab String 币种逐仓负债额
适用于跨币种保证金模式组合保证金模式
>> mgnRatio String 保证金率
适用于单币种保证金模式
>> interest String 计息
值为正数,如:"9.01",适用于跨币种保证金模式组合保证金模式
>> twap String 当前负债币种触发系统自动换币的风险
0、1、2、3、4、5其中之一,数字越大代表您的负债币种触发自动换币概率越高
适用于跨币种保证金模式组合保证金模式
>> maxLoan String 币种最大可借
适用于跨币种保证金模式组合保证金模式 的全仓
>> eqUsd String 币种权益美金价值
>> notionalLever String 币种杠杆倍数
适用于单币种保证金模式
>> coinUsdPrice String 币种美元指数
>> stgyEq String 策略权益
>> isoUpl String 逐仓未实现盈亏
适用于单币种保证金模式跨币种保证金模式组合保证金模式
>> borrowFroz String 币种美金层面潜在借币占用保证金
仅适用于跨币种保证金模式组合保证金模式. 在其他账户模式下为"".
>> spotInUseAmt String 现货对冲占用数量
适用于组合保证金模式

持仓频道

获取持仓信息,首次订阅按照订阅维度推送数据,此外,当下单、撤单等事件触发时,推送数据以及按照订阅维度定时推送数据

请求示例:单个

{
    "op": "subscribe",
    "args": [{
        "channel": "positions",
        "instType": "FUTURES",
        "instFamily": "BTC-USD",
        "instId": "BTC-USD-200329"
    }]
}

请求示例

{
    "op": "subscribe",
    "args": [
        {
            "channel": "positions",
            "instType": "ANY",
            "extraParams": "
                {
                    \"updateInterval\": \"0\"
                }
            "
        }
    ]
}

请求参数

参数 类型 是否必须 描述
op String 操作,subscribe unsubscribe
args Array 请求订阅的频道列表
> channel String 频道名,positions
> instType String 产品类型
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
ANY:全部
> instFamily String 交易品种
适用于交割/永续/期权
> instId String 产品ID
> extraParams String 额外配置
>> updateInterval int 0: 仅根据持仓事件推送数据
若不添加该字段或将其设置为除0外的其他值,数据将根据事件推送并定时推送。
使用该字段需严格遵守以下格式。
"extraParams": "
{
\"updateInterval\": \"0\"
}
"

成功返回示例:单个

{
    "event": "subscribe",
    "arg": {
        "channel": "positions",
        "instType": "FUTURES",
        "instFamily": "BTC-USD",
        "instId": "BTC-USD-200329"
    },
    "connId": "a4d3ae55"
}

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "positions",
        "instType": "ANY"
    },
    "connId": "a4d3ae55"
}

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"positions\", \"instType\" : \"FUTURES\"}]}",
    "connId": "a4d3ae55"
}

返回参数

参数 类型 是否必须 描述
event String 事件,subscribe unsubscribe error
arg Object 订阅的频道
> channel String 频道名
> instType String 产品类型
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
ANY:全部
> instFamily String 交易品种
适用于交割/永续/期权
> instId String 产品ID
code String 错误码
msg String 错误消息
connId String WebSocket连接ID

推送示例:单个

{
    "arg":{
        "channel":"positions",
        "uid": "77982378738415879",
        "instType":"FUTURES"
    },
    "data":[
        {
            "adl":"1",
            "availPos":"1",
            "avgPx":"2566.31",
            "cTime":"1619507758793",
            "ccy":"ETH",
            "deltaBS":"",
            "deltaPA":"",
            "gammaBS":"",
            "gammaPA":"",
            "imr":"",
            "instId":"ETH-USD-210430",
            "instType":"FUTURES",
            "interest":"0",
            "idxPx":"2566.13",
            "last":"2566.22",
            "lever":"10",
            "liab":"",
            "liabCcy":"",
            "liqPx":"2352.8496681818233",
            "markPx":"2353.849",
            "margin":"0.0003896645377994",
            "mgnMode":"isolated",
            "mgnRatio":"11.731726509588816",
            "mmr":"0.0000311811092368",
            "notionalUsd":"2276.2546609009605",
            "optVal":"",
            "pTime":"1619507761462",
            "pos":"1",
            "baseBorrowed": "",
            "baseInterest": "",
            "quoteBorrowed": "",
            "quoteInterest": "",
            "posCcy":"",
            "posId":"307173036051017730",
            "posSide":"long",
            "spotInUseAmt": "",
            "spotInUseCcy": "",
            "bizRefId": "",
            "bizRefType": "",
            "thetaBS":"",
            "thetaPA":"",
            "tradeId":"109844",
            "uTime":"1619507761462",
            "upl":"-0.0000009932766034",
            "uplLastPx":"-0.0000009932766034",
            "uplRatio":"-0.0025490556801078",
            "uplRatioLastPx":"-0.0025490556801078",
            "vegaBS":"",
            "vegaPA":"",
            "realizedPnl":"0.001",
            "pnl":"0.0011",
            "fee":"-0.0001",
            "fundingFee":"0",
            "liqPenalty":"0",
            "closeOrderAlgo":[
                {
                    "algoId":"123",
                    "slTriggerPx":"123",
                    "slTriggerPxType":"mark",
                    "tpTriggerPx":"123",
                    "tpTriggerPxType":"mark",
                    "closeFraction":"0.6"
                },
                {
                    "algoId":"123",
                    "slTriggerPx":"123",
                    "slTriggerPxType":"mark",
                    "tpTriggerPx":"123",
                    "tpTriggerPxType":"mark",
                    "closeFraction":"0.4"
                }
            ]
        }
    ]
}

推送示例

{
    "arg": {
        "channel": "positions",
        "uid": "77982378738415879",
        "instType": "ANY"
    },
    "data": [{
    "adl":"1",
    "availPos":"1",
    "avgPx":"2566.31",
    "cTime":"1619507758793",
    "ccy":"ETH",
    "deltaBS":"",
    "deltaPA":"",
    "gammaBS":"",
    "gammaPA":"",
    "imr":"",
    "instId":"ETH-USD-210430",
    "instType":"FUTURES",
    "interest":"0",
    "idxPx":"2566.13",
    "last":"2566.22",
    "usdPx":"",
    "bePx":"2353.949",
    "lever":"10",
    "liab":"",
    "liabCcy":"",
    "liqPx":"2352.8496681818233",
    "markPx":"2353.849",
    "margin":"0.0003896645377994",
    "mgnMode":"isolated",
    "mgnRatio":"11.731726509588816",
    "mmr":"0.0000311811092368",
    "notionalUsd":"2276.2546609009605",
    "optVal":"",
    "pTime":"1619507761462",
    "pos":"1",
    "baseBorrowed": "",
    "baseInterest": "",
    "quoteBorrowed": "",
    "quoteInterest": "",
    "posCcy":"",
    "posId":"307173036051017730",
    "posSide":"long",
    "spotInUseAmt": "",
    "spotInUseCcy": "",
    "bizRefId": "",
    "bizRefType": "",
    "thetaBS":"",
    "thetaPA":"",
    "tradeId":"109844",
    "uTime":"1619507761462",
    "upl":"-0.0000009932766034",
    "uplLastPx":"-0.0000009932766034",
    "uplRatio":"-0.0025490556801078",
    "uplRatioLastPx":"-0.0025490556801078",
    "vegaBS":"",
    "vegaPA":"",
    "realizedPnl":"0.001",
    "pnl":"0.0011",
    "fee":"-0.0001",
    "fundingFee":"0",
    "liqPenalty":"0",
    "closeOrderAlgo":[
        {
            "algoId":"123",
            "slTriggerPx":"123",
            "slTriggerPxType":"mark",
            "tpTriggerPx":"123",
            "tpTriggerPxType":"mark",
            "closeFraction":"0.6"
        },
        {
            "algoId":"123",
            "slTriggerPx":"123",
            "slTriggerPxType":"mark",
            "tpTriggerPx":"123",
            "tpTriggerPxType":"mark",
            "closeFraction":"0.4"
        }
    ]
}, {
    "adl":"1",
    "availPos":"1",
    "avgPx":"2566.31",
    "cTime":"1619507758793",
    "ccy":"ETH",
    "deltaBS":"",
    "deltaPA":"",
    "gammaBS":"",
    "gammaPA":"",
    "imr":"",
    "instId":"ETH-USD-SWAP",
    "instType":"SWAP",
    "interest":"0",
    "idxPx":"2566.13",
    "last":"2566.22",
    "usdPx":"",
    "bePx":"2353.949",
    "lever":"10",
    "liab":"",
    "liabCcy":"",
    "liqPx":"2352.8496681818233",
    "markPx":"2353.849",
    "margin":"0.0003896645377994",
    "mgnMode":"isolated",
    "mgnRatio":"11.731726509588816",
    "mmr":"0.0000311811092368",
    "notionalUsd":"2276.2546609009605",
    "optVal":"",
    "pTime":"1619507761462",
    "pos":"1",
    "baseBorrowed": "",
    "baseInterest": "",
    "quoteBorrowed": "",
    "quoteInterest": "",
    "posCcy":"",
    "posId":"307173036051017730",
    "posSide":"long",
    "spotInUseAmt": "",
    "spotInUseCcy": "",
    "bizRefId": "",
    "bizRefType": "",
    "thetaBS":"",
    "thetaPA":"",
    "tradeId":"109844",
    "uTime":"1619507761462",
    "upl":"-0.0000009932766034",
    "uplLastPx":"-0.0000009932766034",
    "uplRatio":"-0.0025490556801078",
    "uplRatioLastPx":"-0.0025490556801078",
    "vegaBS":"",
    "vegaPA":"",
    "realizedPnl":"0.001",
    "pnl":"0.0011",
    "fee":"-0.0001",
    "fundingFee":"0",
    "liqPenalty":"0",
    "closeOrderAlgo":[
        {
            "algoId":"123",
            "slTriggerPx":"123",
            "slTriggerPxType":"mark",
            "tpTriggerPx":"123",
            "tpTriggerPxType":"mark",
            "closeFraction":"0.6"
        },
        {
            "algoId":"123",
            "slTriggerPx":"123",
            "slTriggerPxType":"mark",
            "tpTriggerPx":"123",
            "tpTriggerPxType":"mark",
            "closeFraction":"0.4"
        }
    ]
}]
}

推送数据参数

参数名 类型 描述
arg Object 订阅成功的频道
> channel String 频道名
> uid String 用户标识
> instType String 产品类型
> instFamily String 交易品种
> instId String 产品ID
data Array 订阅的数据
> instType String 产品类型
> mgnMode String 保证金模式, cross:全仓 isolated:逐仓
> posId String 持仓ID
> posSide String 持仓方向
long:开平仓模式开多
short:开平仓模式开空
net:买卖模式(交割/永续/期权pos为正代表开多,pos为负代表开空。币币杠杆posCcy为交易货币时,代表开多;posCcy为计价货币时,代表开空。)
> pos String 持仓数量,逐仓自主划转模式下,转入保证金后会产生pos为0的仓位
> baseBal String 交易币余额,适用于 币币杠杆(逐仓自主划转模式 和 一键借币模式)
> quoteBal String 计价币余额 ,适用于 币币杠杆(逐仓自主划转模式 和 一键借币模式)
> baseBorrowed String 交易币已借,适用于 币币杠杆(逐仓一键借币模式)
> baseInterest String 交易币计息,适用于 币币杠杆(逐仓一键借币模式)
> quoteBorrowed String 计价币已借,适用于 币币杠杆(逐仓一键借币模式)
> quoteInterest String 计价币计息,适用于 币币杠杆(逐仓一键借币模式)
> posCcy String 持仓数量币种,仅适用于币币杠杆
> availPos String 可平仓数量,适用于 币币杠杆,交割/永续(开平仓模式),期权
对于杠杆仓位,平仓时,杠杆还清负债后,余下的部分会视为币币交易,如果想要减少币币交易的数量,可通过"获取最大可用数量"接口获取只减仓的可用数量。
> avgPx String 开仓平均价
> upl String 未实现收益(以标记价格计算)
> uplRatio String 未实现收益率(以标记价格计算
> uplLastPx String 以最新成交价格计算的未实现收益,主要做展示使用,实际值还是 upl
> uplRatioLastPx String 以最新成交价格计算的未实现收益率
> instId String 产品ID,如 BTC-USD-180216
> lever String 杠杆倍数,不适用于期权卖方
> liqPx String 预估强平价
不适用于期权
> markPx String 最新标记价格
> imr String 初始保证金,仅适用于全仓
> margin String 保证金余额,仅适用于逐仓,可增减
> mgnRatio String 保证金率
> mmr String 维持保证金
> liab String 负债额,仅适用于币币杠杆
> liabCcy String 负债币种,仅适用于币币杠杆
> interest String 利息,已经生成未扣利息
> tradeId String 最新成交ID
> notionalUsd String 以美金价值为单位的持仓数量
> optVal String 期权价值,仅适用于期权
> adl String 信号区,分为5档,从1到5,数字越小代表adl强度越弱
> bizRefId String 外部业务id,e.g. 体验券id
> bizRefType String 外部业务类型
> ccy String 占用保证金的币种
> last String 最新成交价
> idxPx String 最新指数价格
> usdPx String 美金价格
> bePx String 盈亏平衡价
> deltaBS String 美金本位持仓仓位delta,仅适用于期权
> deltaPA String 币本位持仓仓位delta,仅适用于期权
> gammaBS String 美金本位持仓仓位gamma,仅适用于期权
> gammaPA String 币本位持仓仓位gamma,仅适用于期权
> thetaBS String 美金本位持仓仓位theta,仅适用于期权
> thetaPA String 币本位持仓仓位theta,仅适用于期权
> vegaBS String 美金本位持仓仓位vega,仅适用于期权
> vegaPA String 币本位持仓仓位vega,仅适用于期权
> spotInUseAmt String 现货对冲占用数量
适用于组合保证金模式
> spotInUseCcy String 现货对冲占用币种,如 BTC
适用于组合保证金模式
> realizedPnl String 已实现收益
> pnl String 平仓订单累计收益额
> fee String 累计手续费金额,正数代表平台返佣 ,负数代表平台扣除
> fundingFee String 累计资金费用
> liqPenalty String 累计爆仓罚金,有值时为负数。
> closeOrderAlgo Array 平仓策略委托订单。调用策略委托下单,且closeFraction=1 时,该数组才会有值。
>> algoId String 策略委托单ID
>> slTriggerPx String 止损触发价
>> slTriggerPxType String 止损触发价类型
last:最新价格
index:指数价格
mark:标记价格
>> tpTriggerPx String 止盈委托价
>> tpTriggerPxType String 止盈触发价类型
last:最新价格
index:指数价格
mark:标记价格
>> closeFraction String 策略委托触发时,平仓的百分比。1 代表100%
> cTime String 持仓创建时间,Unix时间戳的毫秒数格式,如 1597026383085
> uTime String 最近一次持仓更新时间,Unix时间戳的毫秒数格式,如 1597026383085
> pTime String 持仓信息的推送时间,Unix时间戳的毫秒数格式,如 1597026383085

账户余额和持仓频道

获取账户余额和持仓信息,首次订阅按照订阅维度推送数据,此外,当成交、资金划转等事件触发时,推送数据。

该频道适用于尽快获取账户现金余额和仓位资产变化的信息。

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "balance_and_position"
    }]
}

请求参数

参数 类型 是否必须 描述
op String 操作,subscribe unsubscribe
args Array 请求订阅的频道列表
> channel String 频道名,balance_and_position

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "balance_and_position"
    },
    "connId": "a4d3ae55"
}

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"balance_and_position\"}]}",
    "connId": "a4d3ae55"
}

返回参数

参数 类型 是否必须 描述
event String 事件,subscribe unsubscribe error
arg Object 订阅的频道
> channel String 频道名,balance_and_position
code String 错误码
msg String 错误消息
connId String WebSocket连接ID

推送示例

{
    "arg": {
        "channel": "balance_and_position",
        "uid": "77982378738415879"
    },
    "data": [{
        "pTime": "1597026383085",
        "eventType": "snapshot",
        "balData": [{
            "ccy": "BTC",
            "cashBal": "1",
            "uTime": "1597026383085"
        }],
        "posData": [{
            "posId": "1111111111",
            "tradeId": "2",
            "instId": "BTC-USD-191018",
            "instType": "FUTURES",
            "mgnMode": "cross",
            "posSide": "long",
            "pos": "10",
            "ccy": "BTC",
            "posCcy": "",
            "avgPx": "3320",
            "uTime": "1597026383085"
        }],
        "trades": [{
            "instId": "BTC-USD-191018",
            "tradeId": "2",
        }]
    }]
}

推送数据参数

参数名 类型 描述
arg Object 请求订阅的频道
> channel String 频道名
> uid String 用户标识
data Array 订阅的数据
> pTime String 推送时间,Unix时间戳的毫秒数格式,如 1597026383085
> eventType String 事件类型
snapshot:首推快照
delivered:交割
exercised:行权
transferred:划转
filled:成交
liquidation:强平
claw_back:穿仓补偿
adl:ADL自动减仓
funding_fee:资金费
adjust_margin:调整保证金
set_leverage:设置杠杆
interest_deduction:扣息
> balData String 余额数据
>> ccy String 币种
>> cashBal String 币种余额
>> uTime String 币种余额信息的更新时间,Unix时间戳的毫秒数格式,如 1597026383085
> posData String 持仓数据
>> posId String 持仓ID
>> tradeId String 最新成交ID
>> instId String 交易产品ID,如 BTC-USD-180213
>> instType String 交易产品类型
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
>> mgnMode String 保证金模式
isolated, cross
>> avgPx String 开仓平均价
>> ccy String 占用保证金的币种
>> posSide String 持仓方向
longshortnet
>> pos String 持仓数量,逐仓自主划转模式下,转入保证金后会产生pos为0的仓位
>> baseBal String 交易币余额
适用于 币币杠杆(逐仓自主划转模式和逐仓一键借币模式)
>> quoteBal String 计价币余额
适用于 币币杠杆(逐仓自主划转模式和逐仓一键借币模式)
>> posCcy String 持仓数量币种
只适用于币币杠杆仓位。当是交割、永续、期权持仓时,该字段返回“”
>> uTime String 仓位信息的更新时间,Unix时间戳的毫秒数格式,如 1597026383085
> trades Array 成交数据
>> instId String 产品ID,如 BTC-USDT
>> tradeId String 最新成交ID

爆仓风险预警推送频道

此推送频道仅作为风险提示,不建议作为策略交易的风险判断。
在行情剧烈波动的情况下,可能会出现此消息推送的同时仓位已经被强平的可能性。
预警会在某一个逐仓仓位有风险时推送。预警会在所有全仓仓位有风险时推送。

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "liquidation-warning",
        "instType": "ANY"
    }]
}

请求参数

参数 类型 是否必须 描述
op String 操作,subscribe unsubscribe
args Array 请求订阅的频道列表
> channel String 频道名,liquidation-warning
> instType String 产品类型
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
ANY:全部
> instFamily String 交易品种
适用于交割/永续/期权
> instId String 产品ID

成功返回示例:单个

{
    "event": "subscribe",
    "arg": {
        "channel": "liquidation-warning",
        "instType": "FUTURES",
        "instFamily": "BTC-USD",
        "instId": "BTC-USD-200329"
    },
    "connId": "a4d3ae55"
}

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"liquidation-warning\", \"instType\" : \"FUTURES\"}]}",
    "connId": "a4d3ae55"
}

返回参数

参数 类型 是否必须 描述
event String 事件,subscribe unsubscribe error
arg Object 订阅的频道
> channel String 频道名 ,liquidation-warning
> instType String 产品类型
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
ANY: 全部
> instFamily String 交易品种
适用于交割/永续/期权
> instId String 产品ID
code String 错误码
msg String 错误消息
connId String WebSocket连接ID

推送示例:单个

{
    "arg":{
        "channel":"liquidation-warning",
        "uid": "77982378738415879",
        "instType":"FUTURES"
    },
    "data":[
        {
            "adl":"1",
            "availPos":"1",
            "avgPx":"2566.31",
            "cTime":"1619507758793",
            "ccy":"ETH",
            "deltaBS":"",
            "deltaPA":"",
            "gammaBS":"",
            "gammaPA":"",
            "imr":"",
            "instId":"ETH-USD-210430",
            "instType":"FUTURES",
            "interest":"0",
            "last":"2566.22",
            "lever":"10",
            "liab":"",
            "liabCcy":"",
            "liqPx":"2352.8496681818233",
            "markPx":"2353.849",
            "margin":"0.0003896645377994",
            "mgnMode":"isolated",
            "mgnRatio":"11.731726509588816",
            "mmr":"0.0000311811092368",
            "notionalUsd":"2276.2546609009605",
            "optVal":"",
            "pTime":"1619507761462",
            "pos":"1",
            "posCcy":"",
            "posId":"307173036051017730",
            "posSide":"long",
            "thetaBS":"",
            "thetaPA":"",
            "tradeId":"109844",
            "uTime":"1619507761462",
            "upl":"-0.0000009932766034",
            "uplRatio":"-0.0025490556801078",
            "vegaBS":"",
            "vegaPA":""
        }
    ]
}

推送数据参数

参数名 类型 描述
arg Object 订阅成功的频道
> channel String 频道名
> uid String 用户标识
> instType String 产品类型
> instFamily String 交易品种
> instId String 产品ID
data Array 订阅的数据
> instType String 产品类型
> mgnMode String 保证金模式, cross:全仓 isolated:逐仓
> posId String 持仓ID
> posSide String 持仓方向
long:开平仓模式开多
short:开平仓模式开空
net:买卖模式(交割/永续/期权pos为正代表开多,pos为负代表开空。币币杠杆posCcy为交易货币时,代表开多;posCcy为计价货币时,代表开空。)
> pos String 持仓数量
> posCcy String 持仓数量币种,仅适用于币币杠杆
> availPos String 可平仓数量,适用于 币币杠杆,交割/永续(开平仓模式),期权
> avgPx String 开仓平均价
> upl String 未实现收益
> uplRatio String 未实现收益率
> instId String 产品ID,如 BTC-USD-180216
> lever String 杠杆倍数,不适用于期权卖方
> liqPx String 预估强平价
不适用于期权
> markPx String 标记价格
> imr String 初始保证金,仅适用于全仓
> margin String 保证金余额,仅适用于逐仓,可增减
> mgnRatio String 保证金率
> mmr String 维持保证金
> liab String 负债额,仅适用于币币杠杆
> liabCcy String 负债币种,仅适用于币币杠杆
> interest String 利息,已经生成未扣利息
> tradeId String 最新成交ID
> notionalUsd String 以美金价值为单位的持仓数量
> optVal String 期权价值,仅适用于期权
> adl String 信号区,分为5档,从1到5,数字越小代表adl强度越弱
> ccy String 占用保证金的币种
> last String 最新成交价
> deltaBS String 美金本位持仓仓位delta,仅适用于期权
> deltaPA String 币本位持仓仓位delta,仅适用于期权
> gammaBS String 美金本位持仓仓位gamma,仅适用于期权
> gammaPA String 币本位持仓仓位gamma,仅适用于期权
> thetaBS String 美金本位持仓仓位theta,仅适用于期权
> thetaPA String 币本位持仓仓位theta,仅适用于期权
> vegaBS String 美金本位持仓仓位vega,仅适用于期权
> vegaPA String 币本位持仓仓位vega,仅适用于期权
> cTime String 持仓创建时间,Unix时间戳的毫秒数格式,如 1597026383085
> uTime String 最近一次持仓更新时间,Unix时间戳的毫秒数格式,如 1597026383085
> pTime String 持仓信息的推送时间,Unix时间戳的毫秒数格式,如 1597026383085

账户greeks频道

获取账户资产的greeks信息,首次订阅按照订阅维度推送数据,此外,当增加或者减少币种余额、持仓数量等事件触发时,推送数据以及按照订阅维度定时推送数据

请求示例:单个

{
    "op": "subscribe",
    "args": [{
        "channel": "account-greeks",
        "ccy": "BTC"
    }]
}

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "account-greeks"
    }]
}

请求参数

参数 类型 是否必须 描述
op String 操作,subscribe unsubscribe
args Array 请求订阅的频道列表
> channel String 频道名,account-greeks
> ccy String 币种

成功返回示例:单个

{
    "event": "subscribe",
    "arg": {
        "channel": "account-greeks",
        "ccy": "BTC"
    },
  "connId": "a4d3ae55"
}

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "account-greeks"
    },
  "connId": "a4d3ae55"
}

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"account-greeks\", \"ccy\" : \"BTC\"}]}",
  "connId": "a4d3ae55"
}

返回参数

参数 类型 是否必须 描述
event String 事件,subscribe unsubscribe error
arg Object 订阅的频道
> channel String 频道名,account-greeks
> ccy String 币种
code String 错误码
msg String 错误消息
connId String WebSocket连接ID

推送示例:单个

{
  "arg": {
    "channel": "account-greeks",
    "uid": "77982378738415879",
    "ccy": "BTC"
  },
  "data": [
    {           
      "thetaBS": "",
      "thetaPA":"",
      "deltaBS":"",
      "deltaPA":"",
      "gammaBS":"",
      "gammaPA":"",
      "vegaBS":"",    
      "vegaPA":"",
      "ccy":"BTC"
      "ts":"1620282889345"
    }
  ]
}

推送示例

{
  "arg": {
    "channel": "account-greeks",
    "uid": "77982378738415879",
    "ccy": "BTC"
  },
  "data": [
    {           
      "thetaBS": "",
      "thetaPA":"",
      "deltaBS":"",
      "deltaPA":"",
      "gammaBS":"",
      "gammaPA":"",
      "vegaBS":"",    
      "vegaPA":"",
      "ccy":"BTC"
      "ts":"1620282889345"
    },
    {           
      "thetaBS": "",
      "thetaPA":"",
      "deltaBS":"",
      "deltaPA":"",
      "gammaBS":"",
      "gammaPA":"",
      "vegaBS":"",    
      "vegaPA":"",
      "ccy":"USDT"
      "ts":"1620282889345"
    }
  ]
}

推送数据参数

参数名 类型 描述
arg Object 请求订阅的频道
> channel String 频道名
> uid String 用户标识
data Array 订阅的数据
> deltaBS String 美金本位账户资产delta
> deltaPA String 币本位账户资产delta
> gammaBS String 美金本位账户资产gamma,仅适用于期权
> gammaPA String 币本位账户资产gamma,仅适用于期权
> thetaBS String 美金本位账户资产theta,仅适用于期权
> thetaPA String 币本位账户资产theta,仅适用于期权
> vegaBS String 美金本位账户资产vega,仅适用于期权
> vegaPA String 币本位账户资产vega,仅适用于期权
> ccy String 币种
> ts String 获取greeks的时间,Unix时间戳的毫秒数格式,如 1597026383085

撮合交易

交易

交易功能模块下的API接口需要身份验证。

POST / 下单

只有当您的账户有足够的资金才能下单。

该接口支持带单产品的下单,但不支持为带单产品平仓。请参考 跟单 了解更多

限速:60次/2s

跟单交易带单合约的限速:4次/2s

限速规则(期权以外):UserID + Instrument ID

限速规则(只限期权):UserID + Instrument Family

HTTP请求

POST /api/v5/trade/order

请求示例

币币下单:
POST /api/v5/trade/order
body
{
    "instId":"BTC-USDT",
    "tdMode":"cash",
    "clOrdId":"b15",
    "side":"buy",
    "ordType":"limit",
    "px":"2.15",
    "sz":"2"
}
import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 简单交易模式限价单
result = tradeAPI.place_order(
    instId="BTC-USDT",
    tdMode="cash",
    clOrdId="b15",
    side="buy",
    ordType="limit",
    px="2.15",
    sz="2"
)

print(result)

请求参数

参数名 类型 是否必须 描述
instId String 产品ID,如 BTC-USD-190927-5000-C
tdMode String 交易模式
保证金模式:isolated:逐仓 ;cross:全仓
非保证金模式:cash:非保证金
spot_isolated:现货逐仓(仅适用于现货带单)
ccy String 保证金币种,仅适用于单币种保证金模式下的全仓杠杆订单
clOrdId String 客户自定义订单ID
字母(区分大小写)与数字的组合,可以是纯字母、纯数字且长度要在1-32位之间。
tag String 订单标签
字母(区分大小写)与数字的组合,可以是纯字母、纯数字,且长度在1-16位之间。
side String 订单方向
buy:买, sell:卖
posSide String 可选 持仓方向
在开平仓模式下必填,且仅可选择 longshort。 仅适用交割、永续。
ordType String 订单类型
market:市价单
limit:限价单
post_only:只做maker单
fok:全部成交或立即取消
ioc:立即成交并取消剩余
optimal_limit_ioc:市价委托立即成交并取消剩余(仅适用交割、永续)
mmp:做市商保护(仅适用于组合保证金账户模式下的期权订单)
mmp_and_post_only:做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单)
sz String 委托数量
px String 可选 委托价格,仅适用于limitpost_onlyfokiocmmpmmp_and_post_only类型的订单
期权下单时,px/pxUsd/pxVol 只能填一个
pxUsd String 可选 以USD价格进行期权下单
仅适用于期权
期权下单时 px/pxUsd/pxVol 必填一个,且只能填一个
pxVol String 可选 以隐含波动率进行期权下单,例如 1 代表 100%
仅适用于期权
期权下单时 px/pxUsd/pxVol 必填一个,且只能填一个
reduceOnly Boolean 是否只减仓,truefalse,默认false
仅适用于币币杠杆,以及买卖模式下的交割/永续
仅适用于单币种保证金模式跨币种保证金模式
tgtCcy String 市价单委托数量sz的单位,仅适用于币币市价订单
base_ccy: 交易货币 ;quote_ccy:计价货币
买单默认quote_ccy, 卖单默认base_ccy
banAmend Boolean 是否禁止币币市价改单,true 或 false,默认false
为true时,余额不足时,系统不会改单,下单会失败,仅适用于币币市价单
quickMgnType String 一键借币类型,仅适用于杠杆逐仓的一键借币模式:
manual:手动,auto_borrow: 自动借币,auto_repay: 自动还币
默认是manual:手动
stpId String 自成交保护ID。来自同一个母账户配着同一个ID的订单不能自成交
用户自定义1<=x<=999999999的整数
stpMode String 自成交保护模式,需要stpId有值才会生效
默认为 cancel maker
cancel_maker,cancel_taker, cancel_both
Cancel both不支持FOK
attachAlgoOrds Array of object 下单附带止盈止损信息
> attachAlgoClOrdId String 下单附带止盈止损时,客户自定义的策略订单ID
字母(区分大小写)与数字的组合,可以是纯字母、纯数字且长度要在1-32位之间。
订单完全成交,下止盈止损委托单时,该值会传给algoClOrdId
> tpTriggerPx String 可选 止盈触发价,如果填写此参数,必须填写 止盈委托价
> tpOrdPx String 可选 止盈委托价,如果填写此参数,必须填写 止盈触发价
委托价格为-1时,执行市价止盈
> slTriggerPx String 可选 止损触发价,如果填写此参数,必须填写 止损委托价
> slOrdPx String 可选 止损委托价,如果填写此参数,必须填写 止损触发价
委托价格为-1时,执行市价止损
> tpTriggerPxType String 止盈触发价类型
last:最新价格
index:指数价格
mark:标记价格
默认为last
> slTriggerPxType String 止损触发价类型
last:最新价格
index:指数价格
mark:标记价格
默认为last
> sz String 可选 数量。仅适用于“多笔止盈”的止盈订单,且对于“多笔止盈”的止盈订单必填
> amendPxOnTriggerType String 是否启用开仓价止损,仅适用于分批止盈的止损订单,第一笔止盈触发时,止损触发价格是否移动到开仓均价止损
0. 不开启,默认值
1. 开启“开仓价止损”,且止损触发价不能为空

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "clOrdId":"oktswap6",
            "ordId":"12345689",
            "tag":"",
            "sCode":"0",
            "sMsg":""
        }
    ],
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

返回参数

参数名 类型 描述
code String 结果代码,0表示成功
msg String 错误信息,代码为0时,该字段为空
data String 包含结果的对象数组
> ordId String 订单ID
> clOrdId String 客户自定义订单ID
> tag String 订单标签
> sCode String 事件执行结果的code,0代表成功
> sMsg String 事件执行失败或成功时的msg
inTime String REST网关接收请求时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123
返回的时间是请求验证后的时间。
outTime String REST网关发送响应时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123

POST / 批量下单

每次最多可以批量提交20个新订单。请求参数应该按数组格式传递,会依次委托订单。

该接口支持带单产品的下单,但不支持为带单产品平仓。请参考 跟单 了解更多

限速:300个/2s

跟单交易带单合约的限速:4个/2s

限速规则(期权以外):UserID + Instrument ID

限速规则(只限期权):UserID + Instrument Family

HTTP请求

POST /api/v5/trade/batch-orders

请求示例

 币币批量下单:
 POST:/api/v5/trade/batch-orders
 body
 [
    {
        "instId":"BTC-USDT",
        "tdMode":"cash",
        "clOrdId":"b15",
        "side":"buy",
        "ordType":"limit",
        "px":"2.15",
        "sz":"2"
    },
    {
        "instId":"BTC-USDT",
        "tdMode":"cash",
        "clOrdId":"b16",
        "side":"buy",
        "ordType":"limit",
        "px":"2.15",
        "sz":"2"
    }
]
import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 批量下单
place_orders_without_clOrdId = [
    {"instId": "BTC-USDT", "tdMode": "cash", "clOrdId": "b15", "side": "buy", "ordType": "limit", "px": "2.15", "sz": "2"},
    {"instId": "BTC-USDT", "tdMode": "cash", "clOrdId": "b16", "side": "buy", "ordType": "limit", "px": "2.15", "sz": "2"}
]

result = tradeAPI.place_multiple_orders(place_orders_without_clOrdId)
print(result)

请求参数

参数名 类型 是否必须 描述
instId String 产品ID,如 BTC-USD-190927-5000-C
tdMode String 交易模式
保证金模式:isolated:逐仓 ;cross:全仓
非保证金模式:cash:非保证金
spot_isolated:现货逐仓(仅适用于现货带单)
ccy String 保证金币种,仅适用于单币种保证金模式下的全仓杠杆订单
clOrdId String 客户自定义订单ID
字母(区分大小写)与数字的组合,可以是纯字母、纯数字且长度要在1-32位之间。
tag String 订单标签
字母(区分大小写)与数字的组合,可以是纯字母、纯数字且长度要在1-16位之间。
side String 订单方向 buy:买, sell:卖
posSide String 可选 持仓方向
在开平仓模式下必填,且仅可选择 longshort。 仅适用交割、永续。
ordType String 订单类型
market:市价单
limit:限价单
post_only:只做maker单
fok:全部成交或立即取消
ioc:立即成交并取消剩余
optimal_limit_ioc:市价委托立即成交并取消剩余(仅适用交割、永续)
mmp:做市商保护(仅适用于组合保证金账户模式下的期权订单)
mmp_and_post_only:做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单)
sz String 委托数量
px String 可选 委托价格,仅适用于limitpost_onlyfokiocmmpmmp_and_post_only类型的订单
期权下单时,px/pxUsd/pxVol 只能填一个
pxUsd String 可选 以USD价格进行期权下单
仅适用于期权
期权下单时 px/pxUsd/pxVol 必填一个,且只能填一个
pxVol String 可选 以隐含波动率进行期权下单,例如 1 代表 100%
仅适用于期权
期权下单时 px/pxUsd/pxVol 必填一个,且只能填一个
reduceOnly Boolean 是否只减仓,truefalse,默认false
仅适用于币币杠杆,以及买卖模式下的交割/永续
仅适用于单币种保证金模式跨币种保证金模式
tgtCcy String 市价单委托数量sz的单位,仅适用于币币市价订单
base_ccy: 交易货币 ;quote_ccy:计价货币
买单默认quote_ccy, 卖单默认base_ccy
banAmend Boolean 是否禁止币币市价改单,true 或 false,默认false
为true时,余额不足时,系统不会改单,下单会失败,仅适用于币币市价单
stpId String 自成交保护ID。来自同一个母账户配着同一个ID的订单不能自成交
用户自定义1<=x<=999999999的整数
stpMode String 自成交保护模式,需要stpId有值才会生效
默认为 cancel maker
cancel_maker,cancel_taker, cancel_both
Cancel both不支持FOK
quickMgnType String 一键借币类型,仅适用于杠杆逐仓的一键借币模式:
manual:手动,auto_borrow: 自动借币,auto_repay: 自动还币
默认是manual:手动
attachAlgoOrds Array of object 下单附带止盈止损信息
> attachAlgoClOrdId String 下单附带止盈止损时,客户自定义的策略订单ID
字母(区分大小写)与数字的组合,可以是纯字母、纯数字且长度要在1-32位之间。
订单完全成交,下止盈止损委托单时,该值会传给algoClOrdId
> tpTriggerPx String 可选 止盈触发价,如果填写此参数,必须填写 止盈委托价
> tpOrdPx String 可选 止盈委托价,如果填写此参数,必须填写 止盈触发价
委托价格为-1时,执行市价止盈
> slTriggerPx String 可选 止损触发价,如果填写此参数,必须填写 止损委托价
> slOrdPx String 可选 止损委托价,如果填写此参数,必须填写 止损触发价
委托价格为-1时,执行市价止损
> tpTriggerPxType String 止盈触发价类型
last:最新价格
index:指数价格
mark:标记价格
默认为last
> slTriggerPxType String 止损触发价类型
last:最新价格
index:指数价格
mark:标记价格
默认为last
> sz String 可选 数量。仅适用于“多笔止盈”的止盈订单,且对于“多笔止盈”的止盈订单必填
> amendPxOnTriggerType String 是否启用开仓价止损,仅适用于分批止盈的止损订单,第一笔止盈触发时,止损触发价格是否移动到开仓均价止损
0. 不开启,默认值
1. 开启“开仓价止损”,且止损触发价不能为空

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "clOrdId":"oktswap6",
            "ordId":"12345689",
            "tag":"",
            "sCode":"0",
            "sMsg":""
        },
        {
            "clOrdId":"oktswap7",
            "ordId":"12344",
            "tag":"",
            "sCode":"0",
            "sMsg":""
        },
     .......
    ],
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

返回参数

参数名 类型 描述
code String 结果代码,0表示成功
msg String 错误信息,代码为0时,该字段为空
data String 包含结果的对象数组
> ordId String 订单ID
> clOrdId String 客户自定义订单ID
> tag String 订单标签
> sCode String 事件执行结果的code,0代表成功
> sMsg String 事件执行失败或成功时的msg
inTime String REST网关接收请求时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123
返回的时间是请求验证后的时间。
outTime String REST网关发送响应时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123

POST / 撤单

撤销之前下的未完成订单。

限速:60次/2s

限速规则(期权以外):UserID + Instrument ID

限速规则(只限期权):UserID + Instrument Family

HTTP请求

POST /api/v5/trade/cancel-order

请求示例

POST /api/v5/trade/cancel-order
body
{
    "ordId":"590908157585625111",
    "instId":"BTC-USDT"
}

import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 撤单
result = tradeAPI.cancel_order(instId="BTC-USDT", ordId = "590908157585625111")
print(result)

请求参数

参数名 类型 是否必须 描述
instId String 产品ID,如 BTC-USD-190927
ordId String 可选 订单ID, ordIdclOrdId必须传一个,若传两个,以ordId为主
clOrdId String 可选 用户自定义ID

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "clOrdId":"oktswap6",
            "ordId":"12345689",
            "sCode":"0",
            "sMsg":""
        }
    ],
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

返回参数

参数名 类型 描述
code String 结果代码,0表示成功
msg String 错误信息,代码为0时,该字段为空
data String 包含结果的对象数组
> ordId String 订单ID
> clOrdId String 客户自定义订单ID
> sCode String 事件执行结果的code,0代表成功
> sMsg String 事件执行失败时的msg
inTime String REST网关接收请求时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123
返回的时间是请求验证后的时间。
outTime String REST网关发送响应时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123

POST / 批量撤单

撤销未完成的订单,每次最多可以撤销20个订单。请求参数应该按数组格式传递。

限速:300个/2s

限速规则(期权以外):UserID + Instrument ID

限速规则(只限期权):UserID + Instrument Family

HTTP请求

POST /api/v5/trade/cancel-batch-orders

请求示例

POST /api/v5/trade/cancel-batch-orders
body
[
    {
        "instId":"BTC-USDT",
        "ordId":"590908157585625111"
    },
    {
        "instId":"BTC-USDT",
        "ordId":"590908544950571222"
    }
]

import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 按ordId撤单
cancel_orders_with_orderId = [
    {"instId": "BTC-USDT", "ordId": "590908157585625111"},
    {"instId": "BTC-USDT", "ordId": "590908544950571222"},
]

result = tradeAPI.cancel_multiple_orders(cancel_orders_with_orderId)
print(result)

请求参数

参数名 类型 是否必须 描述
instId String 产品ID,如 BTC-USD-190927
ordId String 可选 订单ID, ordIdclOrdId必须传一个,若传两个,以ordId为主
clOrdId String 可选 用户自定义ID

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "clOrdId":"oktswap6",
            "ordId":"12345689",
            "sCode":"0",
            "sMsg":""
        },
        {
            "clOrdId":"oktswap7",
            "ordId":"12344",
            "sCode":"0",
            "sMsg":""
        },
     .......
    ],
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

返回参数

参数名 类型 描述
code String 结果代码,0表示成功
msg String 错误信息,代码为0时,该字段为空
data String 包含结果的对象数组
> ordId String 订单ID
> clOrdId String 客户自定义订单ID
> sCode String 事件执行结果的code,0代表成功
> sMsg String 事件执行失败时的msg
inTime String REST网关接收请求时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123
返回的时间是请求验证后的时间。
outTime String REST网关发送响应时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123

POST / 修改订单

修改当前未成交的挂单

限速:60次/2s

跟单交易带单合约的限速:4个/2s

限速规则:UserID + Instrument ID

HTTP请求

POST /api/v5/trade/amend-order

请求示例

POST /api/v5/trade/amend-order
body
{
    "ordId":"590909145319051111",
    "newSz":"2",
    "instId":"BTC-USDT"
}
import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 修改订单
result = tradeAPI.amend_order(
    instId="BTC-USDT",
    ordId="590909145319051111",
    newSz="2"
)
print(result)

请求参数

参数名 类型 是否必须 描述
instId String 产品ID
cxlOnFail Boolean false:不自动撤单 true:自动撤单 当订单修改失败时,该订单是否需要自动撤销。默认为false
ordId String 可选 订单ID, ordIdclOrdId必须传一个,若传两个,以ordId为主
clOrdId String 可选 用户自定义order ID
reqId String 用户自定义修改事件ID
字母(区分大小写)与数字的组合,可以是纯字母、纯数字且长度要在1-32位之间。
newSz String 可选 修改的新数量,对于部分成交订单,该数量应包含已成交数量。
newPx String 可选 修改后的新价格
修改的新价格期权改单时,newPx/newPxUsd/newPxVol 只能填一个,且必须与下单参数保持一致,如下单用px,改单时需使用newPx
newPxUsd String 可选 以USD价格进行期权改单
仅适用于期权,期权改单时,newPx/newPxUsd/newPxVol 只能填一个
newPxVol String 可选 以隐含波动率进行期权改单,例如 1 代表 100%
仅适用于期权,期权改单时,newPx/newPxUsd/newPxVol 只能填一个
attachAlgoOrds Array of object 下单附带止盈止损信息
> attachAlgoId String 可选 附带止盈止损的订单ID,由系统生成,改单时,可用来标识该笔附带止盈止损订单。下止盈止损委托单时,该值不会传给 algoId
> attachAlgoClOrdId String 可选 下单附带止盈止损时,客户自定义的策略订单ID
> newTpTriggerPx String 可选 止盈触发价
如果止盈触发价或者委托价为0,那代表删除止盈。只适用于交割和永续合约。
> newTpOrdPx String 可选 止盈委托价
委托价格为-1时,执行市价止盈。只适用于交割和永续合约。
> newSlTriggerPx String 可选 止损触发价
如果止损触发价或者委托价为0,那代表删除止损。只适用于交割和永续合约。
> newSlOrdPx String 可选 止损委托价
委托价格为-1时,执行市价止损。 只适用于交割和永续合约。
> newTpTriggerPxType String 可选 止盈触发价类型
last:最新价格
index:指数价格
mark:标记价格
只适用于交割/永续
如果要新增止盈,该参数必填
> newSlTriggerPxType String 可选 止损触发价类型
last:最新价格
index:指数价格
mark:标记价格
只适用于交割/永续
如果要新增止损,该参数必填
> sz String 可选 新的张数。仅适用于“多笔止盈”的止盈订单且必填
> amendPxOnTriggerType String 是否启用开仓价止损,仅适用于分批止盈的止损订单
0. 不开启,默认值
1. 开启“开仓价止损”

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
         "clOrdId":"",
         "ordId":"12344",
         "reqId":"b12344",
         "sCode":"0",
         "sMsg":""
        }
    ],
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

返回参数

参数名 类型 描述
code String 结果代码,0表示成功
msg String 错误信息,代码为0时,该字段为空
data String 包含结果的对象数组
> ordId String 订单ID
> clOrdId String 用户自定义ID
> reqId String 用户自定义修改事件ID
> sCode String 事件执行结果的code,0代表成功
> sMsg String 事件执行失败时的msg
inTime String REST网关接收请求时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123
返回的时间是请求验证后的时间。
outTime String REST网关发送响应时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123

POST / 批量修改订单

修改未完成的订单,一次最多可批量修改20个订单。请求参数应该按数组格式传递。

限速:300个/2s

跟单交易带单合约的限速:4个/2s

限速规则:UserID + Instrument ID

HTTP请求

POST /api/v5/trade/amend-batch-orders

请求示例

POST /api/v5/trade/amend-batch-orders
body
[
    {
        "ordId":"590909308792049444",
        "newSz":"2",
        "instId":"BTC-USDT"
    },
    {
        "ordId":"590909308792049555",
        "newSz":"2",
        "instId":"BTC-USDT"
    }
]
import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 按ordId修改未完成的订单
amend_orders_with_orderId = [
    {"instId": "BTC-USDT", "ordId": "590909308792049444","newSz":"2"},
    {"instId": "BTC-USDT", "ordId": "590909308792049555","newSz":"2"},
]

result = tradeAPI.amend_multiple_orders(amend_orders_with_orderId)
print(result)

请求参数

参数名 类型 是否必须 描述
instId String 产品ID
cxlOnFail Boolean false :不自动撤单 true:自动撤单 当订单修改失败时,该订单是否需要自动撤销,默认为false
ordId String 可选 订单ID, ordIdclOrdId必须传一个,若传两个,以ordId为主
clOrdId String 可选 用户自定义order ID
reqId String 用户自定义修改事件ID
字母(区分大小写)与数字的组合,可以是纯字母、纯数字且长度要在1-32位之间。
newSz String 可选 修改的新数量,对于部分成交订单,该数量应包含已成交数量。
newPx String 可选 修改后的新价格
修改的新价格期权改单时,newPx/newPxUsd/newPxVol 只能填一个,且必须与下单参数保持一致,如下单用px,改单时需使用newPx
newPxUsd String 可选 以USD价格进行期权改单
仅适用于期权,期权改单时,newPx/newPxUsd/newPxVol 只能填一个
newPxVol String 可选 以隐含波动率进行期权改单,例如 1 代表 100%
仅适用于期权,期权改单时,newPx/newPxUsd/newPxVol 只能填一个
attachAlgoOrds Array of object 下单附带止盈止损信息
> attachAlgoId String 可选 附带止盈止损的订单ID,由系统生成,改单时,可用来标识该笔附带止盈止损订单。下止盈止损委托单时,该值不会传给 algoId
> attachAlgoClOrdId String 可选 下单附带止盈止损时,客户自定义的策略订单ID
> newTpTriggerPx String 可选 止盈触发价
如果止盈触发价或者委托价为0,那代表删除止盈。只适用于交割和永续合约。
> newTpOrdPx String 可选 止盈委托价
委托价格为-1时,执行市价止盈。只适用于交割和永续合约。
> newSlTriggerPx String 可选 止损触发价
如果止损触发价或者委托价为0,那代表删除止损。只适用于交割和永续合约。
> newSlOrdPx String 可选 止损委托价
委托价格为-1时,执行市价止损。 只适用于交割和永续合约。
> newTpTriggerPxType String 可选 止盈触发价类型
last:最新价格
index:指数价格
mark:标记价格
只适用于交割/永续
如果要新增止盈,该参数必填
> newSlTriggerPxType String 可选 止损触发价类型
last:最新价格
index:指数价格
mark:标记价格
只适用于交割/永续
如果要新增止损,该参数必填
> sz String 可选 新的张数。仅适用于“多笔止盈”的止盈订单且必填
> amendPxOnTriggerType String 是否启用开仓价止损,仅适用于分批止盈的止损订单
0. 不开启,默认值
1. 开启“开仓价止损”

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "clOrdId":"oktswap6",
            "ordId":"12345689",
            "reqId":"b12344",
            "sCode":"0",
            "sMsg":""
        },
        {
            "clOrdId":"oktswap7",
            "ordId":"12344",
            "reqId":"b12344",
            "sCode":"0",
            "sMsg":""
        },
     .......
    ],
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

返回参数

参数名 类型 描述
code String 结果代码,0表示成功
msg String 错误信息,代码为0时,该字段为空
data String 包含结果的对象数组
> ordId String 订单ID
> clOrdId String 用户自定义ID
> reqId String 用户自定义修改事件ID
> sCode String 事件执行结果的code,0代表成功
> sMsg String 事件执行失败时的msg
inTime String REST网关接收请求时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123
返回的时间是请求验证后的时间。
outTime String REST网关发送响应时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123

POST / 市价仓位全平

市价平掉指定交易产品的持仓

限速:20次/2s

限速规则(期权以外):UserID + Instrument ID

限速规则(只限期权):UserID + Instrument Family

HTTP请求

POST /api/v5/trade/close-position

请求示例

POST /api/v5/trade/close-position
body
{
    "instId":"BTC-USDT-SWAP",
    "mgnMode":"cross"
}
import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 市价全平
result = tradeAPI.close_positions(
    instId="BTC-USDT-SWAP",
    mgnMode="cross"
)
print(result)

请求参数

参数名 类型 是否必须 描述
instId String 产品ID
posSide String 可选 持仓方向
买卖模式下:可不填写此参数,默认值net,如果填写,仅可以填写net
开平仓模式下: 必须填写此参数,且仅可以填写 long:平多 ,short:平空
mgnMode String 保证金模式
cross:全仓 ; isolated:逐仓
ccy String 可选 保证金币种,单币种保证金模式的全仓币币杠杆平仓必填
autoCxl Boolean 当市价全平时,平仓单是否需要自动撤销,默认为false.
false:不自动撤单 true:自动撤单
clOrdId String 客户自定义ID
字母(区分大小写)与数字的组合,可以是纯字母、纯数字且长度要在1-32位之间。
tag String 订单标签
字母(区分大小写)与数字的组合,可以是纯字母、纯数字,且长度在1-16位之间。

返回结果

{
    "code": "0",
    "data": [
        {
            "clOrdId": "",
            "instId": "BTC-USDT-SWAP",
            "posSide": "long",
            "tag": ""
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
instId String 产品ID
posSide String 持仓方向
clOrdId String 客户自定义ID
字母(区分大小写)与数字的组合,可以是纯字母、纯数字且长度要在1-32位之间。
tag String 订单标签
字母(区分大小写)与数字的组合,可以是纯字母、纯数字,且长度在1-16位之间。

GET / 获取订单信息

查订单信息

限速:60次/2s

限速规则(期权以外):UserID + Instrument ID

限速规则(只限期权):UserID + Instrument Family

HTTP请求

GET /api/v5/trade/order

请求示例

GET /api/v5/trade/order?ordId=590910403358593111&instId=BTC-USDT

import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 通过 ordId 查询订单
result = tradeAPI.get_order(
    instId="BTC-USDT",
    ordId="590910403358593111"
)
print(result)

请求参数

参数名 类型 是否必须 描述
instId String 产品ID ,如BTC-USD-190927
ordId String 可选 订单ID , ordIdclOrdId必须传一个,若传两个,以ordId为主
clOrdId String 可选 用户自定义ID
如果clOrdId关联了多个订单,只会返回最近的那笔订单

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "instType":"FUTURES",
            "instId":"BTC-USD-200329",
            "ccy":"",
            "ordId":"123445",
            "clOrdId":"b1",
            "tag":"",
            "px":"999",
            "pxUsd":"",
            "pxVol":"",
            "pxType":"",
            "sz":"3",
            "pnl":"5",
            "ordType":"limit",
            "side":"buy",
            "posSide":"long",
            "tdMode":"isolated",
            "accFillSz":"0",
            "fillPx":"0",
            "tradeId":"0",
            "fillSz":"0",
            "fillTime":"0",
            "source": "",
            "state":"live",
            "avgPx":"0",
            "lever":"20",
            "attachAlgoClOrdId":"",
            "tpTriggerPx":"",
            "tpTriggerPxType":"last",
            "tpOrdPx":"",
            "slTriggerPx":"",
            "slTriggerPxType":"last",
            "slOrdPx":"",
            "attachAlgoOrds": [],
            "stpId":"",
            "stpMode":"",
            "feeCcy":"",
            "fee":"",
            "rebateCcy":"",
            "rebate":"",
            "tgtCcy":"",
            "category":"",
            "reduceOnly": "false",
            "cancelSource": "20",
            "cancelSourceReason": "Cancel all after triggered",
            "quickMgnType": "",
            "algoClOrdId": "",
            "algoId": "",
            "uTime":"1597026383085",
            "cTime":"1597026383085"
        }
    ]
}

返回参数

参数名 类型 描述
instType String 产品类型
SPOT:币币
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
instId String 产品ID
tgtCcy String 币币市价单委托数量sz的单位
base_ccy: 交易货币 ;quote_ccy:计价货币
仅适用于币币市价订单
默认买单为quote_ccy,卖单为base_ccy
ccy String 保证金币种,仅适用于单币种保证金模式下的全仓币币杠杆订单
ordId String 订单ID
clOrdId String 客户自定义订单ID
tag String 订单标签
px String 委托价格,对于期权,以币(如BTC, ETH)为单位
pxUsd String 期权价格,以USD为单位
仅适用于期权,其他业务线返回空字符串""
pxVol String 期权订单的隐含波动率
仅适用于期权,其他业务线返回空字符串""
pxType String 期权的价格类型
px:代表按价格下单,单位为币 (请求参数 px 的数值单位是BTC或ETH)
pxVol:代表按pxVol下单
pxUsd:代表按照pxUsd下单,单位为USD (请求参数px 的数值单位是USD)
sz String 委托数量
pnl String 收益,适用于有成交的平仓订单,其他情况均为0
ordType String 订单类型
market:市价单
limit:限价单
post_only:只做maker单
fok:全部成交或立即取消
ioc:立即成交并取消剩余
optimal_limit_ioc:市价委托立即成交并取消剩余(仅适用交割、永续)
mmp:做市商保护(仅适用于组合保证金账户模式下的期权订单)
mmp_and_post_only:做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单)
op_fok:期权简选(全部成交或立即取消)
side String 订单方向
posSide String 持仓方向
tdMode String 交易模式
accFillSz String 累计成交数量
对于币币杠杆,单位为交易货币,如 BTC-USDT, 单位为 BTC;对于市价单,无论tgtCcybase_ccy,还是quote_ccy,单位均为交易货币;
对于交割、永续以及期权,单位为张。
fillPx String 最新成交价格,如果成交数量为0,该字段为""
tradeId String 最新成交ID
fillSz String 最新成交数量
对于币币杠杆,单位为交易货币,如 BTC-USDT, 单位为 BTC;对于市价单,无论tgtCcybase_ccy,还是quote_ccy,单位均为交易货币;
对于交割、永续以及期权,单位为张。
fillTime String 最新成交时间
avgPx String 成交均价,如果成交数量为0,该字段也为""
state String 订单状态
canceled:撤单成功
live:等待成交
partially_filled:部分成交
filled:完全成交
mmp_canceled:做市商保护机制导致的自动撤单
lever String 杠杆倍数,0.01到125之间的数值,仅适用于 币币杠杆/交割/永续
attachAlgoClOrdId String 下单附带止盈止损时,客户自定义的策略订单ID
tpTriggerPx String 止盈触发价
tpTriggerPxType String 止盈触发价类型
last:最新价格
index:指数价格
mark:标记价格
tpOrdPx String 止盈委托价
slTriggerPx String 止损触发价
slTriggerPxType String 止损触发价类型
last:最新价格
index:指数价格
mark:标记价格
slOrdPx String 止损委托价
attachAlgoOrds Array of object 下单附带止盈止损信息
> attachAlgoId String 附带止盈止损的订单ID,订单完全成交,下止盈止损委托单时,该值不会传给 algoId
> attachAlgoClOrdId String 下单附带止盈止损时,客户自定义的策略订单ID
> tpTriggerPx String 止盈触发价
> tpTriggerPxType String 止盈触发价类型
last:最新价格
index:指数价格
mark:标记价格
> tpOrdPx String 止盈委托价
> slTriggerPx String 止损触发价
> slTriggerPx String 止损触发价类型
last:最新价格
index:指数价格
mark:标记价格
> slOrdPx String 止损委托价
> sz String 张数。仅适用于“多笔止盈”的止盈订单且必填
> amendPxOnTriggerType String 是否启用开仓价止损,仅适用于分批止盈的止损订单
0. 不开启,默认值
1. 开启“开仓价止损”
stpId String 自成交保护ID
如果自成交保护不适用则返回""
stpMode String 自成交保护模式
如果自成交保护不适用则返回""
feeCcy String 交易手续费币种
fee String 手续费与返佣
对于币币和杠杆,为订单交易累计的手续费,平台向用户收取的交易手续费,为负数。如: -0.01
对于交割、永续和期权,为订单交易累计的手续费和返佣
rebateCcy String 返佣金币种
source String 订单来源
6:计划委托策略触发后的生成的普通单
7:止盈止损策略触发后的生成的普通单
13:策略委托单触发后的生成的普通单
24:移动止盈止损策略触发后的生成的普通单
rebate String 返佣金额,仅适用于币币和杠杆,平台向达到指定lv交易等级的用户支付的挂单奖励(返佣),如果没有返佣金,该字段为“”。手续费返佣为正数,如:0.01
category String 订单种类
normal:普通委托
twap:TWAP自动换币
adl:ADL自动减仓
full_liquidation:强制平仓
partial_liquidation:强制减仓
delivery:交割
ddh:对冲减仓类型订单
reduceOnly String 是否只减仓,truefalse
cancelSource String 订单取消来源的原因枚举值代码
cancelSourceReason String 订单取消来源的对应具体原因
quickMgnType String 一键借币类型,仅适用于杠杆逐仓的一键借币模式
manual:手动,auto_borrow: 自动借币,auto_repay: 自动还币
algoClOrdId String 客户自定义策略订单ID。策略订单触发,且策略单有algoClOrdId时有值,否则为"",
algoId String 策略委托单ID,策略订单触发时有值,否则为""
uTime String 订单状态更新时间,Unix时间戳的毫秒数格式,如:1597026383085
cTime String 订单创建时间,Unix时间戳的毫秒数格式, 如 :1597026383085

GET / 获取未成交订单列表

获取当前账户下所有未成交订单信息

限速:60次/2s

限速规则:UserID

HTTP请求

GET /api/v5/trade/orders-pending

请求示例

GET /api/v5/trade/orders-pending?ordType=post_only,fok,ioc&instType=SPOT

import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 查询所有未成交订单
result = tradeAPI.get_order_list(
    instType="SPOT",
    ordType="post_only,fok,ioc"
)
print(result)

请求参数

参数名 类型 是否必须 描述
instType String 产品类型
SPOT:币币
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
uly String 标的指数
instFamily String 交易品种
适用于交割/永续/期权
instId String 产品ID,如BTC-USD-200927
ordType String 订单类型
market:市价单
limit:限价单
post_only:只做maker单
fok:全部成交或立即取消
ioc:立即成交并取消剩余
optimal_limit_ioc:市价委托立即成交并取消剩余(仅适用交割、永续)
mmp:做市商保护(仅适用于组合保证金账户模式下的期权订单)
mmp_and_post_only:做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单)
op_fok:期权简选(全部成交或立即取消)
state String 订单状态
live:等待成交
partially_filled:部分成交
after String 请求此ID之前(更旧的数据)的分页内容,传的值为对应接口的ordId
before String 请求此ID之后(更新的数据)的分页内容,传的值为对应接口的ordId
limit String 返回结果的数量,最大为100,默认100条

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "accFillSz": "0",
            "avgPx": "",
            "cTime": "1618235248028",
            "category": "normal",
            "ccy": "",
            "clOrdId": "",
            "fee": "0",
            "feeCcy": "BTC",
            "fillPx": "",
            "fillSz": "0",
            "fillTime": "",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "lever": "5.6",
            "ordId": "301835739059335168",
            "ordType": "limit",
            "pnl": "0",
            "posSide": "net",
            "px": "59200",
            "pxUsd":"",
            "pxVol":"",
            "pxType":"",
            "rebate": "0",
            "rebateCcy": "USDT",
            "side": "buy",
            "attachAlgoClOrdId": "",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "last", 
            "attachAlgoOrds": [],
            "source": "",
            "state": "live",
            "stpId": "",
            "stpMode": "",
            "sz": "1",
            "tag": "",
            "tdMode": "cross",
            "tgtCcy": "",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "last",
            "tradeId": "",
            "reduceOnly": "false",
            "quickMgnType": "",
            "algoClOrdId": "",
            "algoId": "",
            "uTime": "1618235248028"
        }
    ]
}

返回参数

参数名 类型 描述
instType String 产品类型
instId String 产品ID
tgtCcy String 币币市价单委托数量sz的单位
base_ccy: 交易货币 ;quote_ccy:计价货币
仅适用于币币市价订单
默认买单为quote_ccy,卖单为base_ccy
ccy String 保证金币种,仅适用于单币种保证金模式下的全仓币币杠杆订单
ordId String 订单ID
clOrdId String 客户自定义订单ID
tag String 订单标签
px String 委托价格,对于期权,以币(如BTC, ETH)为单位
pxUsd String 期权价格,以USD为单位
仅适用于期权,其他业务线返回空字符串""
pxVol String 期权订单的隐含波动率
仅适用于期权,其他业务线返回空字符串""
pxType String 期权的价格类型
px:代表按价格下单,单位为币 (请求参数 px 的数值单位是BTC或ETH)
pxVol:代表按pxVol下单
pxUsd:代表按照pxUsd下单,单位为USD (请求参数px 的数值单位是USD)
sz String 委托数量
pnl String 收益,适用于有成交的平仓订单,其他情况均为0
ordType String 订单类型
market:市价单
limit:限价单
post_only:只做maker单
fok:全部成交或立即取消
ioc:立即成交并取消剩余
optimal_limit_ioc:市价委托立即成交并取消剩余(仅适用交割、永续)
mmp:做市商保护(仅适用于组合保证金账户模式下的期权订单)
mmp_and_post_only:做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单)
op_fok:期权简选(全部成交或立即取消)
side String 订单方向
posSide String 持仓方向
tdMode String 交易模式
accFillSz String 累计成交数量
fillPx String 最新成交价格。如果还没成交,系统返回""。
tradeId String 最新成交ID
fillSz String 最新成交数量
fillTime String 最新成交时间
avgPx String 成交均价。如果还没成交,系统返回0
state String 订单状态
live:等待成交
partially_filled:部分成交
lever String 杠杆倍数,0.01到125之间的数值,仅适用于 币币杠杆/交割/永续
attachAlgoClOrdId String 下单附带止盈止损时,客户自定义的策略订单ID
tpTriggerPx String 止盈触发价
tpTriggerPxType String 止盈触发价类型
last:最新价格
index:指数价格
mark:标记价格
slTriggerPx String 止损触发价
slTriggerPxType String 止损触发价类型
last:最新价格
index:指数价格
mark:标记价格
slOrdPx String 止损委托价
tpOrdPx String 止盈委托价
attachAlgoOrds Array of object 下单附带止盈止损信息
> attachAlgoId String 附带止盈止损的订单ID,订单完全成交,下止盈止损委托单时,该值不会传给 algoId
> attachAlgoClOrdId String 下单附带止盈止损时,客户自定义的策略订单ID
> tpTriggerPx String 止盈触发价
> tpTriggerPxType String 止盈触发价类型
last:最新价格
index:指数价格
mark:标记价格
> tpOrdPx String 止盈委托价
> slTriggerPx String 止损触发价
> slTriggerPx String 止损触发价类型
last:最新价格
index:指数价格
mark:标记价格
> slOrdPx String 止损委托价
> sz String 张数。仅适用于“多笔止盈”的止盈订单且必填
> amendPxOnTriggerType String 是否启用开仓价止损,仅适用于分批止盈的止损订单
0. 不开启,默认值
1. 开启“开仓价止损”
stpId String 自成交保护ID
如果自成交保护不适用则返回""
stpMode String 自成交保护模式
如果自成交保护不适用则返回""
feeCcy String 交易手续费币种
fee String 手续费与返佣
对于币币和杠杆,为订单交易累计的手续费,平台向用户收取的交易手续费,为负数。如: -0.01
对于交割、永续和期权,为订单交易累计的手续费和返佣
rebateCcy String 返佣金币种
source String 订单来源
6:计划委托策略触发后的生成的普通单
7:止盈止损策略触发后的生成的普通单
13:策略委托单触发后的生成的普通单
24:移动止盈止损策略触发后的生成的普通单
rebate String 返佣金额,仅适用于币币和杠杆,平台向达到指定lv交易等级的用户支付的挂单奖励(返佣),如果没有返佣金,该字段为“”。手续费返佣为正数,如:0.01
category String 订单种类
normal: 普通委托
reduceOnly String 是否只减仓,truefalse
quickMgnType String 一键借币类型,仅适用于杠杆逐仓的一键借币模式
manual:手动,auto_borrow: 自动借币,auto_repay: 自动还币
algoClOrdId String 客户自定义策略订单ID。策略订单触发,且策略单有algoClOrdId是有值,否则为"",
algoId String 策略委托单ID,策略订单触发时有值,否则为""
uTime String 订单状态更新时间,Unix时间戳的毫秒数格式,如 1597026383085
cTime String 订单创建时间,Unix时间戳的毫秒数格式,如 1597026383085

GET / 获取历史订单记录(近七天)

获取最近7天挂单,且完全成交的订单数据,包括7天以前挂单,但近7天才成交的订单数据。按照订单创建时间倒序排序。

已经撤销的未成交单 只保留2小时

限速:40次/2s

限速规则:UserID

HTTP请求

GET /api/v5/trade/orders-history

请求示例

GET /api/v5/trade/orders-history?ordType=post_only,fok,ioc&instType=SPOT

import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 查询币币历史订单(7天内)
# 已经撤销的未成交单 只保留2小时
result = tradeAPI.get_orders_history(
    instType="SPOT",
    ordType="post_only,fok,ioc"
)
print(result)

请求参数

参数名 类型 是否必须 描述
instType String 产品类型
SPOT:币币
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
uly String 标的指数
instFamily String 交易品种
适用于交割/永续/期权
instId String 产品ID,如BTC-USD-190927
ordType String 订单类型
market:市价单
limit:限价单
post_only:只做maker单
fok:全部成交或立即取消
ioc:立即成交并取消剩余
optimal_limit_ioc:市价委托立即成交并取消剩余(仅适用交割、永续)
mmp:做市商保护(仅适用于组合保证金账户模式下的期权订单)
mmp_and_post_only:做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单)
op_fok:期权简选(全部成交或立即取消)
state String 订单状态
canceled:撤单成功
filled:完全成交
mmp_canceled:做市商保护机制导致的自动撤单
category String 订单种类
twap:TWAP自动换币
adl:ADL自动减仓
full_liquidation:强制平仓
partial_liquidation:强制减仓
delivery:交割
ddh:对冲减仓类型订单
after String 请求此ID之前(更旧的数据)的分页内容,传的值为对应接口的ordId
before String 请求此ID之后(更新的数据)的分页内容,传的值为对应接口的ordId
begin String 筛选的开始时间戳,Unix 时间戳为毫秒数格式,如 1597026383085
end String 筛选的结束时间戳,Unix 时间戳为毫秒数格式,如 1597027383085
limit String 返回结果的数量,最大为100,默认100条

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "instType":"FUTURES",
            "instId":"BTC-USD-200329",
            "ccy":"",
            "ordId":"123445",
            "clOrdId":"b1",
            "tag":"",
            "px":"999",
            "pxUsd":"",
            "pxVol":"",
            "pxType":"",
            "sz":"3",
            "ordType":"limit",
            "side":"buy",
            "posSide":"long",
            "tdMode":"isolated",
            "accFillSz":"0",
            "fillPx":"0",
            "tradeId":"0",
            "fillSz":"0",
            "fillTime":"0",
            "source": "",
            "state":"filled",
            "avgPx":"0",
            "lever":"20",
            "attachAlgoClOrdId": "",
            "tpTriggerPx":"",
            "tpTriggerPxType":"last",
            "tpOrdPx":"",
            "slTriggerPx":"",
            "slTriggerPxType":"last",
            "slOrdPx":"",
            "attachAlgoOrds": [],
            "stpId":"",
            "stpMode":"",
            "feeCcy":"",
            "fee":"",
            "rebateCcy":"",
            "rebate":"",
            "tgtCcy":"",
            "pnl":"",
            "category":"",
            "reduceOnly": "false",
            "cancelSource": "20",
            "cancelSourceReason": "Cancel all after triggered",
            "algoClOrdId": "",
            "algoId": "",
            "uTime":"1597026383085",
            "cTime":"1597026383085"
        }
    ]
}

返回参数

参数名 类型 描述
instType String 产品类型
instId String 产品ID
tgtCcy String 币币市价单委托数量sz的单位
base_ccy: 交易货币 ;quote_ccy:计价货币
仅适用于币币市价订单
默认买单为quote_ccy,卖单为base_ccy
ccy String 保证金币种,仅适用于单币种保证金模式下的全仓币币杠杆订单
ordId String 订单ID
clOrdId String 客户自定义订单ID
tag String 订单标签
px String 委托价格,对于期权,以币(如BTC, ETH)为单位
pxUsd String 期权价格,以USD为单位
仅适用于期权,其他业务线返回空字符串""
pxVol String 期权订单的隐含波动率
仅适用于期权,其他业务线返回空字符串""
pxType String 期权的价格类型
px:代表按价格下单,单位为币 (请求参数 px 的数值单位是BTC或ETH)
pxVol:代表按pxVol下单
pxUsd:代表按照pxUsd下单,单位为USD (请求参数px 的数值单位是USD)
sz String 委托数量
ordType String 订单类型
market:市价单
limit:限价单
post_only:只做maker单
fok:全部成交或立即取消
ioc:立即成交并取消剩余
optimal_limit_ioc:市价委托立即成交并取消剩余(仅适用交割、永续)
mmp:做市商保护(仅适用于组合保证金账户模式下的期权订单)
mmp_and_post_only:做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单)
op_fok:期权简选(全部成交或立即取消)
side String 订单方向
posSide String 持仓方向
tdMode String 交易模式
accFillSz String 累计成交数量
fillPx String 最新成交价格,如果成交数量为0,该字段为""
tradeId String 最新成交ID
fillSz String 最新成交数量
fillTime String 最新成交时间
avgPx String 成交均价,如果成交数量为0,该字段也为""
state String 订单状态
canceled:撤单成功
filled:完全成交
mmp_canceled:做市商保护机制导致的自动撤单
lever String 杠杆倍数,0.01到125之间的数值,仅适用于 币币杠杆/交割/永续
attachAlgoClOrdId String 下单附带止盈止损时,客户自定义的策略订单ID
tpTriggerPx String 止盈触发价
tpTriggerPxType String 止盈触发价类型
last:最新价格
index:指数价格
mark:标记价格
tpOrdPx String 止盈委托价
slTriggerPx String 止损触发价
slTriggerPxType String 止损触发价类型
last:最新价格
index:指数价格
mark:标记价格
slOrdPx String 止损委托价
attachAlgoOrds Array of object 下单附带止盈止损信息
> attachAlgoId String 附带止盈止损的订单ID,订单完全成交,下止盈止损委托单时,该值不会传给 algoId
> attachAlgoClOrdId String 下单附带止盈止损时,客户自定义的策略订单ID
> tpTriggerPx String 止盈触发价
> tpTriggerPxType String 止盈触发价类型
last:最新价格
index:指数价格
mark:标记价格
> tpOrdPx String 止盈委托价
> slTriggerPx String 止损触发价
> slTriggerPx String 止损触发价类型
last:最新价格
index:指数价格
mark:标记价格
> slOrdPx String 止损委托价
> sz String 张数。仅适用于“多笔止盈”的止盈订单且必填
> amendPxOnTriggerType String 是否启用开仓价止损,仅适用于分批止盈的止损订单
0. 不开启,默认值
1. 开启“开仓价止损”
stpId String 自成交保护ID
如果自成交保护不适用则返回""
stpMode String 自成交保护模式
如果自成交保护不适用则返回""
feeCcy String 交易手续费币种
fee String 手续费与返佣
对于币币和杠杆,为订单交易累计的手续费,平台向用户收取的交易手续费,为负数。如: -0.01
对于交割、永续和期权,为订单交易累计的手续费和返佣
rebateCcy String 返佣金币种
source String 订单来源
6:计划委托策略触发后的生成的普通单
7:止盈止损策略触发后的生成的普通单
13:策略委托单触发后的生成的普通单
24:移动止盈止损策略触发后的生成的普通单
rebate String 返佣金额,仅适用于币币和杠杆,平台向达到指定lv交易等级的用户支付的挂单奖励(返佣),如果没有返佣金,该字段为“”。手续费返佣为正数,如:0.01
pnl String 收益,适用于有成交的平仓订单,其他情况均为0
category String 订单种类
normal:普通委托
twap:TWAP自动换币
adl:ADL自动减仓
full_liquidation:强制平仓
partial_liquidation:强制减仓
delivery:交割
ddh:对冲减仓类型订单
reduceOnly String 是否只减仓,truefalse
cancelSource String 订单取消来源的原因枚举值代码
cancelSourceReason String 订单取消来源的对应具体原因
algoClOrdId String 客户自定义策略订单ID。策略订单触发,且策略单有algoClOrdId时有值,否则为"",
algoId String 策略委托单ID,策略订单触发时有值,否则为""
uTime String 订单状态更新时间,Unix时间戳的毫秒数格式,如1597026383085
cTime String 订单创建时间,Unix时间戳的毫秒数格式,如 1597026383085

GET / 获取历史订单记录(近三个月)

获取最近3个月挂单,且完全成交的订单数据,包括3个月以前挂单,但近3个月才成交的订单数据。按照订单创建时间倒序排序。

限速:20次/2s

限速规则:UserID

HTTP请求

GET /api/v5/trade/orders-history-archive

请求示例

GET /api/v5/trade/orders-history-archive?ordType=post_only,fok,ioc&instType=SPOT

import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 查询币币历史订单(3月内)
result = tradeAPI.get_orders_history_archive(
    instType="SPOT",
    ordType="post_only,fok,ioc"
)
print(result)

请求参数

参数名 类型 是否必须 描述
instType String 产品类型
SPOT:币币
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
uly String 标的指数
instFamily String 交易品种
适用于交割/永续/期权
instId String 产品ID,如BTC-USD-200927
ordType String 订单类型
market:市价单
limit:限价单
post_only:只做maker单
fok:全部成交或立即取消
ioc:立即成交并取消剩余
optimal_limit_ioc:市价委托立即成交并取消剩余(仅适用交割、永续)
mmp:做市商保护(仅适用于组合保证金账户模式下的期权订单)
mmp_and_post_only:做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单)
op_fok:期权简选(全部成交或立即取消)
state String 订单状态
canceled:撤单成功
filled:完全成交
mmp_canceled:做市商保护机制导致的自动撤单
category String 订单种类
twap:TWAP自动换币
adl:ADL自动减仓
full_liquidation:强制平仓
partial_liquidation:强制减仓
delivery:交割
ddh:对冲减仓类型订单
after String 请求此ID之前(更旧的数据)的分页内容,传的值为对应接口的ordId
before String 请求此ID之后(更新的数据)的分页内容,传的值为对应接口的ordId
begin String 筛选的开始时间戳,Unix 时间戳为毫秒数格式,如 1597026383085
end String 筛选的结束时间戳,Unix 时间戳为毫秒数格式,如 1597027383085
limit String 返回结果的数量,最大为100,默认100条

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "instType":"FUTURES",
            "instId":"BTC-USD-200329",
            "ccy":"",
            "ordId":"123445",
            "clOrdId":"b1",
            "tag":"",
            "px":"999",
            "pxUsd":"",
            "pxVol":"",
            "pxType":"",
            "sz":"3",
            "ordType":"limit",
            "side":"buy",
            "posSide":"long",
            "tdMode":"isolated",
            "accFillSz":"0",
            "fillPx":"0",
            "tradeId":"0",
            "fillSz":"0",
            "fillTime":"0",
            "source": "",
            "state":"filled",
            "avgPx":"0",
            "lever":"20",
            "attachAlgoClOrdId": "",
            "tpTriggerPx":"",
            "tpTriggerPxType":"last",
            "tpOrdPx":"",
            "slTriggerPx":"",
            "slTriggerPxType":"last",
            "slOrdPx":"",
            "attachAlgoOrds": [],
            "stpId":"",
            "stpMode":"",
            "feeCcy":"",
            "fee":"",
            "rebateCcy":"",
            "rebate":"",
            "tgtCcy":"",
            "pnl":"",
            "category":"",
            "reduceOnly": "false",
            "cancelSource": "20",
            "cancelSourceReason": "Cancel all after triggered",
            "algoClOrdId": "",
            "algoId": "",
            "uTime":"1597026383085",
            "cTime":"1597026383085"
        }
    ]
}

返回参数

参数名 类型 描述
instType String 产品类型
instId String 产品ID
tgtCcy String 币币市价单委托数量sz的单位
base_ccy: 交易货币 ;quote_ccy:计价货币
仅适用于币币市价订单
默认买单为quote_ccy,卖单为base_ccy
ccy String 保证金币种,仅适用于单币种保证金模式下的全仓币币杠杆订单
ordId String 订单ID
clOrdId String 客户自定义订单ID
tag String 订单标签
px String 委托价格,对于期权,以币(如BTC, ETH)为单位
pxUsd String 期权价格,以USD为单位
仅适用于期权,其他业务线返回空字符串""
pxVol String 期权订单的隐含波动率
仅适用于期权,其他业务线返回空字符串""
pxType String 期权的价格类型
px:代表按价格下单,单位为币 (请求参数 px 的数值单位是BTC或ETH)
pxVol:代表按pxVol下单
pxUsd:代表按照pxUsd下单,单位为USD (请求参数px 的数值单位是USD)
sz String 委托数量
ordType String 订单类型
market:市价单
limit:限价单
post_only:只做maker单
fok:全部成交或立即取消
ioc:立即成交并取消剩余
optimal_limit_ioc:市价委托立即成交并取消剩余(仅适用交割、永续)
mmp:做市商保护(仅适用于组合保证金账户模式下的期权订单)
mmp_and_post_only:做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单)
op_fok:期权简选(全部成交或立即取消)
side String 订单方向
posSide String 持仓方向
tdMode String 交易模式
accFillSz String 累计成交数量
fillPx String 最新成交价格,如果成交数量为0,该字段为""
tradeId String 最新成交ID
fillSz String 最新成交数量
fillTime String 最新成交时间
avgPx String 成交均价,如果成交数量为0,该字段也为""
state String 订单状态
canceled:撤单成功
filled:完全成交
mmp_canceled:做市商保护机制导致的自动撤单
lever String 杠杆倍数,0.01到125之间的数值,仅适用于 币币杠杆/交割/永续
attachAlgoClOrdId String 下单附带止盈止损时,客户自定义的策略订单ID
tpTriggerPx String 止盈触发价
tpTriggerPxType String 止盈触发价类型
last:最新价格
index:指数价格
mark:标记价格
tpOrdPx String 止盈委托价
slTriggerPx String 止损触发价
slTriggerPxType String 止损触发价类型
last:最新价格
index:指数价格
mark:标记价格
slOrdPx String 止损委托价
stpId String 自成交保护ID
如果自成交保护不适用则返回""
attachAlgoOrds Array of object 下单附带止盈止损信息
> attachAlgoId String 附带止盈止损的订单ID,订单完全成交,下止盈止损委托单时,该值不会传给 algoId
> attachAlgoClOrdId String 下单附带止盈止损时,客户自定义的策略订单ID
> tpTriggerPx String 止盈触发价
> tpTriggerPxType String 止盈触发价类型
last:最新价格
index:指数价格
mark:标记价格
> tpOrdPx String 止盈委托价
> slTriggerPx String 止损触发价
> slTriggerPx String 止损触发价类型
last:最新价格
index:指数价格
mark:标记价格
> slOrdPx String 止损委托价
> sz String 张数。仅适用于“多笔止盈”的止盈订单且必填
> amendPxOnTriggerType String 是否启用开仓价止损,仅适用于分批止盈的止损订单
0. 不开启,默认值
1. 开启“开仓价止损”
stpMode String 自成交保护模式
如果自成交保护不适用则返回""
feeCcy String 交易手续费币种
fee String 手续费与返佣
对于币币和杠杆,为订单交易累计的手续费,平台向用户收取的交易手续费,为负数。如: -0.01
对于交割、永续和期权,为订单交易累计的手续费和返佣
rebateCcy String 返佣金币种
rebate String 返佣金额,仅适用于币币和杠杆,平台向达到指定lv交易等级的用户支付的挂单奖励(返佣),如果没有返佣金,该字段为“”。手续费返佣为正数,如:0.01
pnl String 收益,适用于有成交的平仓订单,其他情况均为0
source String 订单来源
6:计划委托策略触发后的生成的普通单
7:止盈止损策略触发后的生成的普通单
13:策略委托单触发后的生成的普通单
24:移动止盈止损策略触发后的生成的普通单
category String 订单种类
normal:普通委托
twap:TWAP自动换币
adl:ADL自动减仓
full_liquidation:强制平仓
partial_liquidation:强制减仓
delivery:交割
ddh:对冲减仓类型订单
reduceOnly String 是否只减仓,truefalse
cancelSource String 订单取消来源的原因枚举值代码
cancelSourceReason String 订单取消来源的对应具体原因
algoClOrdId String 客户自定义策略订单ID。策略订单触发,且策略单有algoClOrdId是有值,否则为"",
algoId String 策略委托单ID,策略订单触发时有值,否则为""
uTime String 订单状态更新时间,Unix时间戳的毫秒数格式,如 1597026383085
cTime String 订单创建时间,Unix时间戳的毫秒数格式,如 1597026383085

GET / 获取成交明细(近三天)

获取近3天的订单成交明细信息

限速:60次/2s

限速规则:UserID

HTTP 请求

GET /api/v5/trade/fills

请求示例

GET /api/v5/trade/fills

import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 获取成交明细
result = tradeAPI.get_fills()
print(result)

请求参数

参数名 类型 是否必须 描述
instType String 产品类型
SPOT:币币
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
uly String 标的指数
instFamily String 交易品种
适用于交割/永续/期权
instId String 产品 ID,如BTC-USD-190927
ordId String 订单 ID
after String 请求此 ID 之前(更旧的数据)的分页内容,传的值为对应接口的billId
before String 请求此 ID 之后(更新的数据)的分页内容,传的值为对应接口的billId
begin String 筛选的开始时间戳,Unix 时间戳为毫秒数格式,如 1597026383085
end String 筛选的结束时间戳,Unix 时间戳为毫秒数格式,如 1597027383085
limit String 返回结果的数量,最大为100,默认100条

返回结果

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "instType": "FUTURES",
      "instId": "BTC-USD-200329",
      "tradeId": "123",
      "ordId": "312269865356374016",
      "clOrdId": "b16",
      "billId": "1111",
      "tag": "",
      "fillPx": "999",
      "fillSz": "3",
      "fillIdxPx":"998",
      "fillPnl": "0.01",
      "fillPxVol": "",
      "fillPxUsd": "",
      "fillMarkVol": "",
      "fillFwdPx": "",
      "fillMarkPx": "",
      "side": "buy",
      "posSide": "long",
      "execType": "M",
      "feeCcy": "",
      "fee": "",
      "ts": "1597026383085",
      "fillTime": "1597026383084"
    },
    {
      "instType": "FUTURES",
      "instId": "BTC-USD-200329",
      "tradeId": "123",
      "ordId": "312269865356374016",
      "clOrdId": "b16",
      "billId": "1111",
      "tag": "",
      "fillPx": "999",
      "fillSz": "3",
      "fillIdxPx":"998",
      "fillPnl": "0.02",
      "fillPxVol": "",
      "fillPxUsd": "",
      "fillMarkVol": "",
      "fillFwdPx": "",
      "fillMarkPx": "",
      "side": "buy",
      "posSide": "long",
      "execType": "M",
      "feeCcy": "",
      "fee": "",
      "ts": "1597026383085",
      "fillTime": "1597026383084"
    }
  ]
}

返回参数

参数名 类型 描述
instType String 产品类型
instId String 产品 ID
tradeId String 最新成交 ID
ordId String 订单 ID
clOrdId String 用户自定义订单ID
billId String 账单 ID
tag String 订单标签
fillPx String 最新成交价格
fillSz String 最新成交数量
fillIdxPx String 交易执行时的指数价格
对于交叉现货币对,返回 baseCcy-USDT 的指数价格。 例如LTC-ETH,该字段返回LTC-USDT的指数价格。
fillPnl String 最新成交收益,适用于有成交的平仓订单。其他情况均为0。
fillPxVol String 成交时的隐含波动率,仅适用于期权,其他业务线返回空字符串""
fillPxUsd String 成交时的期权价格,以USD为单位,仅适用于期权,其他业务线返回空字符串""
fillMarkVol String 成交时的标记波动率,仅适用于期权,其他业务线返回空字符串""
fillFwdPx String 成交时的远期价格,仅适用于期权,其他业务线返回空字符串""
fillMarkPx String 成交时的标记价格,仅适用于 交割/永续/期权
side String 订单方向 buy:买 sell:卖
posSide String 持仓方向 long:多 short:空 买卖模式返回 net
execType String 流动性方向 T:taker M:maker
不适用于系统订单比如强平和ADL
feeCcy String 交易手续费币种或者返佣金币种
fee String 手续费金额或者返佣金额,手续费扣除为‘负数’,如-0.01;手续费返佣为‘正数’,如 0.01
ts String 成交明细产生时间,Unix时间戳的毫秒数格式,如1597026383085
fillTime String 成交时间,与订单频道的fillTime相同

GET / 获取成交明细(近三个月)

获取近3个月订单成交明细信息

限速:10 次/2s

限速规则:UserID

HTTP 请求

GET /api/v5/trade/fills-history

请求示例

GET /api/v5/trade/fills-history

import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 查询 币币 成交明细(3月内)
result = tradeAPI.get_fills_history(
    instType="SPOT"
)
print(result)

请求参数

参数名 类型 是否必须 描述
instType String 产品类型
SPOT:币币
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
uly String 标的指数
instFamily String 交易品种
适用于交割/永续/期权
instId String 产品 ID,如BTC-USD-190927
ordId String 订单 ID
after String 请求此 ID 之前(更旧的数据)的分页内容,传的值为对应接口的billId
before String 请求此 ID 之后(更新的数据)的分页内容,传的值为对应接口的billId
begin String 筛选的开始时间戳,Unix 时间戳为毫秒数格式,如 1597026383085
end String 筛选的结束时间戳,Unix 时间戳为毫秒数格式,如 1597027383085
limit String 返回结果的数量,最大为100,默认100条

返回结果

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "instType": "FUTURES",
      "instId": "BTC-USD-200329",
      "tradeId": "123",
      "ordId": "312269865356374016",
      "clOrdId": "b16",
      "billId": "1111",
      "tag": "",
      "fillPx": "999",
      "fillSz": "3",
      "fillIdxPx":"998",
      "fillPnl": "0.01",
      "fillPxVol": "",
      "fillPxUsd": "",
      "fillMarkVol": "",
      "fillFwdPx": "",
      "fillMarkPx": "",
      "side": "buy",
      "posSide": "long",
      "execType": "M",
      "feeCcy": "",
      "fee": "",
      "ts": "1597026383085",
      "fillTime": "1597026383084"

    },
    {
      "instType": "FUTURES",
      "instId": "BTC-USD-200329",
      "tradeId": "123",
      "ordId": "312269865356374016",
      "clOrdId": "b16",
      "billId": "1111",
      "tag": "",
      "fillPx": "999",
      "fillSz": "3",
      "fillIdxPx":"998",
      "fillPnl": "0.02",
      "fillPxVol": "",
      "fillPxUsd": "",
      "fillMarkVol": "",
      "fillFwdPx": "",
      "fillMarkPx": "",
      "side": "buy",
      "posSide": "long",
      "execType": "M",
      "feeCcy": "",
      "fee": "",
      "ts": "1597026383085",
      "fillTime": "1597026383084"
    }
  ]
}

返回参数

参数名 类型 描述
instType String 产品类型
instId String 产品 ID
tradeId String 最新成交 ID
ordId String 订单 ID
clOrdId String 用户自定义订单ID
billId String 账单 ID
tag String 订单标签
fillPx String 最新成交价格
fillSz String 最新成交数量
fillIdxPx String 交易执行时的指数价格
对于交叉现货币对,返回 baseCcy-USDT 的指数价格。 例如LTC-ETH,该字段返回LTC-USDT的指数价格。
fillPnl String 最新成交收益,适用于有成交的平仓订单。其他情况均为0。
fillPxVol String 成交时的隐含波动率,仅适用于期权,其他业务线返回空字符串""
fillPxUsd String 成交时的期权价格,以USD为单位,仅适用于期权,其他业务线返回空字符串""
fillMarkVol String 成交时的标记波动率,仅适用于期权,其他业务线返回空字符串""
fillFwdPx String 成交时的远期价格,仅适用于期权,其他业务线返回空字符串""
fillMarkPx String 成交时的标记价格,仅适用于 交割/永续/期权
side String 订单方向 buy:买 sell:卖
posSide String 持仓方向 long:多 short:空 买卖模式返回 net
execType String 流动性方向 T:taker M:maker
不适用于系统订单比如强平和ADL
feeCcy String 交易手续费币种或者返佣金币种
fee String 手续费金额或者返佣金额 ,手续费扣除 为 ‘负数’,如 -0.01 ; 手续费返佣 为 ‘正数’,如 0.01
ts String 成交明细产生时间,Unix时间戳的毫秒数格式,如1597026383085
fillTime String 成交时间,与订单频道的fillTime相同

POST / 申请成交明细(近两年)

申请近2年的历史成交成交明细信息,不包括最近三个月。

限速:8 次/天

限速规则:UserID

HTTP 请求

POST /api/v5/trade/fills-archive

请求示例

POST /api/v5/trade/fills-archive
body
{
    "year":"2023",
    "quarter":"Q1"
}

请求参数

参数名 类型 是否必须 描述
year String 4位数字的年份,如 2023
quarter String 季度,有效值 Q1 Q2 Q3 Q4

返回结果

{
    "code": "0",
    "data": [
        {
            "ts": "1646892328000"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
ts String 下载链接生成时间,Unix时间戳的毫秒数格式 ,如 1597026383085

GET / 获取成交明细(近两年)

获取近2年的历史成交明细信息

限速:10 次/2s

限速规则:UserID

HTTP 请求

GET /api/v5/trade/fills-archive

请求示例

GET /api/v5/trade/fills-archive

请求参数

参数名 类型 是否必须 描述
year String 4位数字的年份,如 2023
quarter String 季度,有效值 Q1 Q2 Q3 Q4

返回结果

{
    "code": "0",
    "data": [
        {
            "fileHref": "http://xxx",
            "state": "finished",
            "ts": "1646892328000"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
fileHref String 文件链接
ts String 下载链接生成时间,Unix时间戳的毫秒数格式 ,如 1597026383085
state String 下载链接状态
finished:已生成
ongoing:进行中

解压后CSV里的字段说明

参数名 类型 描述
instType String 产品类型
instId String 产品 ID
tradeId String 最新成交 ID
ordId String 订单 ID
clOrdId String 用户自定义订单ID
billId String 账单 ID
tag String 订单标签
fillPx String 最新成交价格
fillSz String 最新成交数量
fillIdxPx String 交易执行时的指数价格
对于交叉现货币对,返回 baseCcy-USDT 的指数价格。 例如LTC-ETH,该字段返回LTC-USDT的指数价格。
fillPnl String 最新成交收益,适用于有成交的平仓订单。其他情况均为0。
fillPxVol String 成交时的隐含波动率,仅适用于期权,其他业务线返回空字符串""
fillPxUsd String 成交时的期权价格,以USD为单位,仅适用于期权,其他业务线返回空字符串""
fillMarkVol String 成交时的标记波动率,仅适用于期权,其他业务线返回空字符串""
fillFwdPx String 成交时的远期价格,仅适用于期权,其他业务线返回空字符串""
fillMarkPx String 成交时的标记价格,仅适用于 交割/永续/期权
side String 订单方向 buy:买 sell:卖
posSide String 持仓方向 long:多 short:空 买卖模式返回 net
execType String 流动性方向 T:taker M:maker
不适用于系统订单比如强平和ADL
feeCcy String 交易手续费币种或者返佣金币种
fee String 手续费金额或者返佣金额 ,手续费扣除 为 ‘负数’,如 -0.01 ; 手续费返佣 为 ‘正数’,如 0.01
ts String 成交明细产生时间,Unix时间戳的毫秒数格式,如1597026383085
fillTime String 成交时间,与订单频道的fillTime相同

GET / 获取一键兑换主流币币种列表

获取小币一键兑换主流币币种列表。仅可兑换余额在 $10 以下小币币种。

限速:1次/2s

限速规则:UserID

HTTP 请求

GET /api/v5/trade/easy-convert-currency-list

请求示例

GET /api/v5/trade/easy-convert-currency-list
import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 获取小币一键兑换主流币币种列表
result = tradeAPI.get_easy_convert_currency_list()
print(result)

请求参数

返回结果

{
    "code": "0",
    "data": [
        {
            "fromData": [
                {
                    "fromAmt": "6.580712708344864",
                    "fromCcy": "ADA"
                },
                {
                    "fromAmt": "2.9970000013055097",
                    "fromCcy": "USDC"
                }
            ],
            "toCcy": [
                "USDT",
                "BTC",
                "ETH",
                "OKB"
            ]
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
fromData Array 当前拥有并可兑换的小币币种列表信息
> fromCcy String 可兑换币种
> fromAmt String 可兑换币种数量
toCcy Array 可转换成的主流币币种列表

POST / 一键兑换主流币交易

进行小币一键兑换主流币交易。仅可兑换余额在 $10 以下小币币种。

限速:1次/2s

限速规则:UserID

HTTP 请求

POST /api/v5/trade/easy-convert

请求示例

POST /api/v5/trade/easy-convert
body
{
    "fromCcy": ["ADA","USDC"], //逗号分隔小币
    "toCcy": "OKB" 
}
import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 进行小币一键兑换主流币交易
result = tradeAPI.easy_convert(
    fromCcy=["ADA", "USDC"],
    toCcy="OKB"
)
print(result)

请求参数

参数名 类型 是否必须 描述
fromCcy Array 小币支付币种
单次最多同时选择5个币种,如有多个币种则用逗号隔开
toCcy String 兑换的主流币
只选择一个币种,且不能和小币支付币种重复

返回结果

{
    "code": "0",
    "data": [
        {
            "fillFromSz": "6.5807127",
            "fillToSz": "0.17171580105126",
            "fromCcy": "ADA",
            "status": "running",
            "toCcy": "OKB",
            "uTime": "1661419684687"
        },
        {
            "fillFromSz": "2.997",
            "fillToSz": "0.1683755161661844",
            "fromCcy": "USDC",
            "status": "running",
            "toCcy": "OKB",
            "uTime": "1661419684687"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
status String 当前兑换进度/状态
running: 进行中
filled: 已完成
failed: 失败
fromCcy String 小币支付币种
toCcy String 兑换的主流币
fillFromSz String 小币偿还币种支付数量
fillToSz String 兑换的主流币成交数量
uTime String 交易时间戳,Unix时间戳为毫秒数格式,如 1597026383085

GET / 获取一键兑换主流币历史记录

查询一键兑换主流币的历史记录与进度状态。

限速:1次/2s

限速规则:UserID

HTTP 请求

GET /api/v5/trade/easy-convert-history

请求示例

GET /api/v5/trade/easy-convert-history
import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 获取一键兑换主流币历史记录
result = tradeAPI.get_easy_convert_history()
print(result)

请求参数

参数名 类型 是否必须 描述
after String 查询在此之前的内容,值为时间戳,Unix时间戳为毫秒数格式,如1597026383085
before String 查询在此之后的内容,值为时间戳,Unix时间戳为毫秒数格式,如1597026383085
limit String 返回的结果集数量,默认为100,最大为100

返回结果

{
    "code": "0",
    "data": [
        {
            "fillFromSz": "0.1761712511667539",
            "fillToSz": "6.7342205900000000",
            "fromCcy": "OKB",
            "status": "filled",
            "toCcy": "ADA",
            "uTime": "1661313307979"
        },
        {
            "fillFromSz": "0.1722106121112177",
            "fillToSz": "2.9971018300000000",
            "fromCcy": "OKB",
            "status": "filled",
            "toCcy": "USDC",
            "uTime": "1661313307979"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
fromCcy String 小币支付币种
fromSz String 对应的小币支付数量
toCcy String 兑换到的主流币
toSz String 兑换到的主流币数量
status String 当前兑换进度/状态
running: 进行中
filled: 已完成
failed: 失败
uTime String 交易时间戳,Unix时间戳为毫秒数格式,如 1597026383085

GET / 获取一键还债币种列表

查询一键还债币种列表。负债币种包括全仓负债和逐仓负债。

限速:1次/2s

限速规则:UserID

HTTP 请求

GET /api/v5/trade/one-click-repay-currency-list

请求示例

GET /api/v5/trade/one-click-repay-currency-list
import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 查询一键还债币种列表
result = tradeAPI.get_oneclick_repay_list()
print(result)

请求参数

参数名 类型 是否必须 描述
debtType String 负债类型
cross: 全仓负债
isolated: 逐仓负债

返回结果

{
    "code": "0",
    "data": [
        {
            "debtData": [
                {
                    "debtAmt": "29.653478",
                    "debtCcy": "LTC"
                },
                {
                    "debtAmt": "237803.6828295906051002",
                    "debtCcy": "USDT"
                }
            ],
            "debtType": "cross",
            "repayData": [
                {
                    "repayAmt": "0.4978335419825104",
                    "repayCcy": "ETH"
                }
            ]
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
debtData Array 负债币种信息
> debtCcy String 负债币种
> debtAmt String 可负债币种数量
包括本金和利息
debtType String 负债类型
cross: 全仓负债
isolated: 逐仓负债
repayData Array 偿还币种信息
> repayCcy String 可偿还负债的币种
> repayAmt String 可偿还负债的币种可用资产数量

POST / 一键还债交易

交易一键偿还小额全仓债务。不支持逐仓负债的偿还。根据资金和交易账户的剩余可用余额为最大偿还数量。

限速:1次/2s

限速规则:UserID

HTTP 请求

POST /api/v5/trade/one-click-repay

请求示例

POST /api/v5/trade/one-click-repay
body
{
    "debtCcy": ["ETH","BTC"], //逗号分隔债务币
    "repayCcy": "USDT" //用USDT偿还ETH和BTC
}
import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 交易一键偿还小额全仓债务,使用USDT偿还ETH和BTC债务
result = tradeAPI.oneclick_repay(
    debtCcy=["ETH", "BTC"],
    repayCcy="USDT"
)
print(result)

请求参数

参数名 类型 是否必须 描述
debtCcy Array 负债币种
单次最多同时选择5个币种,如有多个币种则用逗号隔开
repayCcy String 偿还币种
只选择一个币种,且不能和负债币种重复

返回结果

{
    "code": "0",
    "data": [
        {
            "debtCcy": "ETH", 
            "fillDebtSz": "0.01023052",
            "fillRepaySz": "30", 
            "repayCcy": "USDT", 
            "status": "filled",
            "uTime": "1646188520338"
        },
        {
            "debtCcy": "BTC", 
            "fillFromSz": "3",
            "fillToSz": "60,221.15910001",
            "repayCcy": "USDT",
            "status": "filled",
            "uTime": "1646188520338"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
status String 当前还债进度/状态
running: 进行中
filled: 已完成
failed: 失败
debtCcy String 负债币种
repayCcy String 偿还币种
fillDebtSz String 负债币种成交数量
fillRepaySz String 偿还币种成交数量
uTime String 交易时间戳,Unix时间戳为毫秒数格式,如 1597026383085

GET / 获取一键还债历史记录

查询一键还债的历史记录与进度状态。

限速:1次/2s

限速规则:UserID

HTTP 请求

GET /api/v5/trade/one-click-repay-history

请求示例

GET /api/v5/trade/one-click-repay-history
import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# 获取一键还债历史记录
result = tradeAPI.oneclick_repay_history()
print(result)

请求参数

参数名 类型 是否必须 描述
after String 查询在此之前的内容,值为时间戳,Unix时间戳为毫秒数格式,如1597026383085
before String 查询在此之后的内容,值为时间戳,Unix时间戳为毫秒数格式,如1597026383085
limit String 返回的结果集数量,默认为100,最大为100

返回结果

{
    "code": "0",
    "data": [
        {
            "debtCcy": "USDC",
            "fillDebtSz": "6950.4865447900000000",
            "fillRepaySz": "4.3067975995094930",
            "repayCcy": "ETH",
            "status": "filled",
            "uTime": "1661256148746"
        }
    ],
    "msg": ""
}

返回参数

参数名 类型 描述
debtCcy String 负债币种
debtSz String 对应的负债币种成交数量
repayCcy String 偿还币种
repaySz String 偿还币种实际支付数量
status String 当前还债进度/状态
running: 进行中
filled: 已完成
failed: 失败
uTime String 交易时间戳,Unix时间戳为毫秒数格式,如 1597026383085

POST / 撤销 MMP 订单

撤销同一交易品种下用户所有的 MMP 挂单
仅适用于组合保证金账户模式下的期权订单,且有 MMP 权限。

限速:5次/2s

限速规则:UserID

HTTP请求

POST /api/v5/trade/mass-cancel

请求示例

POST /api/v5/trade/mass-cancel
body
{
    "instType":"OPTION",
    "instFamily":"BTC-USD"
}

请求参数

参数名 类型 是否必须 描述
instType String 交易产品类型
OPTION:期权
instFamily String 交易品种

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "result":true
        }
    ]
}

返回参数

参数名 类型 描述
result Boolean 撤单结果
true:全部撤单成功
false:全部撤单失败

POST / 倒计时全部撤单

在倒计时结束后,取消所有 MMP 的挂单。
仅适用于组合保证金账户模式下的期权订单,且有 MMP 权限。

限速:1次/1s

限速规则:UserID

HTTP请求

POST /api/v5/trade/cancel-all-after

请求示例

POST /api/v5/trade/cancel-all-after
{
   "timeOut":"60"
}

请求参数

参数名 类型 是否必须 描述
timeOut String 取消 MMP 挂单的倒计时,单位为秒。
取值范围为 0, [10, 120]
0 代表不使用该功能。

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "triggerTime":"1587971460",
            "ts":"1587971400"
        }
    ]
}

返回参数

参数名 类型 描述
triggerTime String 触发撤单的时间.
triggerTime=0 代表未使用该功能。
ts String 请求时间

WS / 订单频道

获取订单信息,首次订阅不推送,只有当下单、撤单等事件触发时,推送数据

请求示例:单个

{
    "op": "subscribe",
    "args": [{
        "channel": "orders",
        "instType": "FUTURES",
        "instFamily": "BTC-USD",
        "instId": "BTC-USD-200329"
    }]
}

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "orders",
        "instType": "FUTURES",
        "instFamily": "BTC-USD"
    }]
}

请求参数

参数 类型 是否必须 描述
op String 操作,subscribe unsubscribe
args Array 请求订阅的频道列表
> channel String 频道名, orders
> instType String 产品类型
SPOT:币币
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
ANY:全部
> instFamily String 交易品种
适用于交割/永续/期权
> instId String 产品ID

成功返回示例:单个

{
    "event": "subscribe",
    "arg": {
        "channel": "orders",
        "instType": "FUTURES",
        "instFamily": "BTC-USD",
        "instId": "BTC-USD-200329"
    },
    "connId": "a4d3ae55"
}

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "orders",
        "instType": "FUTURES",
        "instFamily": "BTC-USD"
    },
    "connId": "a4d3ae55"
}

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"orders\", \"instType\" : \"FUTURES\"}]}",
    "connId": "a4d3ae55"
}

返回参数

参数 类型 是否必须 描述
event String 事件,subscribe unsubscribe error
arg Object 订阅的频道
> channel String 频道名
> instType String 产品类型
SPOT:币币
MARGIN:币币杠杆
SWAP:永续合约
FUTURES:交割合约
OPTION:期权
ANY:全部
> instFamily String 交易品种
适用于交割/永续/期权
> instId String 产品ID
code String 错误码
msg String 错误消息
connId String WebSocket连接ID

推送示例:单个

{
    "arg": {
        "channel": "orders",
        "instType": "SPOT",
        "instId": "BTC-USDT",
        "uid": "614488474791936"
    },
    "data": [
        {
            "accFillSz": "0.001",
            "amendResult": "",
            "avgPx": "31527.1",
            "cTime": "1654084334977",
            "category": "normal",
            "ccy": "",
            "clOrdId": "",
            "code": "0",
            "execType": "M",
            "fee": "-0.02522168",
            "feeCcy": "USDT",
            "fillFee": "-0.02522168",
            "fillFeeCcy": "USDT",
            "fillNotionalUsd": "31.50818374",
            "fillPx": "31527.1",
            "fillSz": "0.001",
            "fillPnl": "0.01",
            "fillTime": "1654084353263",
            "fillPxVol": "",
            "fillPxUsd": "",
            "fillMarkVol": "",
            "fillFwdPx": "",
            "fillMarkPx": "",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "lever": "0",
            "msg": "",
            "notionalUsd": "31.50818374",
            "ordId": "452197707845865472",
            "ordType": "limit",
            "pnl": "0",
            "posSide": "",
            "px": "31527.1",
            "pxUsd":"",
            "pxVol":"",
            "pxType":"",
            "rebate": "0",
            "rebateCcy": "BTC",
            "reduceOnly": "false",
            "reqId": "",
            "side": "sell",
            "attachAlgoClOrdId": "",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "last",
            "source": "",
            "state": "filled",
            "stpId": "",
            "stpMode": "",
            "sz": "0.001",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "last",
            "tradeId": "242589207",
            "quickMgnType": "",
            "algoClOrdId": "",
            "attachAlgoOrds": [],
            "algoId": "",
            "amendSource": "",
            "cancelSource": "",
            "uTime": "1654084353264"
        }
    ]
}

推送数据参数

参数名 类型 描述
arg Object 订阅成功的频道
> channel String 频道名
> uid String 用户标识
> instType String 产品类型
> instFamily String 交易品种
> instId String 产品ID
data Array 订阅的数据
> instType String 产品类型
> instId String 产品ID
> ccy String 保证金币种,仅适用于单币种保证金账户下的全仓币币杠杆订单
> ordId String 订单ID
> clOrdId String 由用户设置的订单ID来识别您的订单
> tag String 订单标签
> px String 委托价格,对于期权,以币(如BTC, ETH)为单位
> pxUsd String 期权价格,以USD为单位
仅适用于期权,其他业务线返回空字符串""
> pxVol String 期权订单的隐含波动率
仅适用于期权,其他业务线返回空字符串""
> pxType String 期权的价格类型
px:代表按价格下单,单位为币 (请求参数 px 的数值单位是BTC或ETH)
pxVol:代表按pxVol下单
pxUsd:代表按照pxUsd下单,单位为USD (请求参数px 的数值单位是USD)
> sz String 原始委托数量,币币/币币杠杆,以币为单位;交割/永续/期权 ,以张为单位
> notionalUsd String 委托单预估美元价值
> fillNotionalUsd String 委托单已成交的美元价值
> ordType String 订单类型
market:市价单
limit:限价单
post_only: 只做maker单
fok:全部成交或立即取消单
ioc:立即成交并取消剩余单
optimal_limit_ioc:市价委托立即成交并取消剩余(仅适用交割、永续)
mmp:做市商保护(仅适用于组合保证金账户模式下的期权订单)
mmp_and_post_only:做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单)
op_fok:期权简选(全部成交或立即取消)
> side String 订单方向,buy sell
> posSide String 持仓方向
long:开平仓模式开多
short:开平仓模式开空
net:买卖模式
> tdMode String 交易模式
保证金模式 isolated:逐仓 cross:全仓
非保证金模式 cash:现金
> tgtCcy String 市价单委托数量sz的单位
base_ccy: 交易货币 quote_ccy:计价货币
> fillPx String 最新成交价格
> tradeId String 最新成交ID
> fillSz String 最新成交数量
对于币币杠杆,单位为交易货币,如 BTC-USDT, 单位为 BTC;对于市价单,无论tgtCcybase_ccy,还是quote_ccy,单位均为交易货币;
对于交割、永续以及期权,单位为张。
> fillPnl String 最新成交收益,适用于有成交的平仓订单。其他情况均为0。
> fillTime String 最新成交时间
> fillFee String 最新一笔成交的手续费金额或者返佣金额:
手续费扣除 为 ‘负数’,如 -0.01 ;
手续费返佣 为 ‘正数’,如 0.01
> fillFeeCcy String 最新一笔成交的手续费币种或者返佣币种。
如果fillFee小于0,为手续费币种;如果fillFee大于等于0,为返佣币种
> fillPxVol String 成交时的隐含波动率仅适用于期权,其他业务线返回空字符串""
> fillPxUsd String 成交时的期权价格,以USD为单位仅适用于期权,其他业务线返回空字符串""
> fillMarkVol String 成交时的标记波动率,仅适用于期权,其他业务线返回空字符串""
> fillFwdPx String 成交时的远期价格,仅适用于期权,其他业务线返回空字符串""
> fillMarkPx String 成交时的标记价格,仅适用于 交割/永续/期权
> execType String 最新一笔成交的流动性方向 T:taker M:maker
> accFillSz String 累计成交数量
对于币币杠杆,单位为交易货币,如 BTC-USDT, 单位为 BTC;对于市价单,无论tgtCcybase_ccy,还是quote_ccy,单位均为交易货币;
对于交割、永续以及期权,单位为张。
> fillNotionalUsd String 委托单已成交的美元价值
> avgPx String 成交均价,如果成交数量为0,该字段也为0
> state String 订单状态
canceled:撤单成功
live:等待成交
partially_filled: 部分成交
filled:完全成交
mmp_canceled:做市商保护机制导致的自动撤单
> lever String 杠杆倍数,0.01到125之间的数值,仅适用于 币币杠杆/交割/永续
> attachAlgoClOrdId String 下单附带止盈止损时,客户自定义的策略订单ID
> tpTriggerPx String 止盈触发价
> tpTriggerPxType String 止盈触发价类型
last:最新价格
index:指数价格
mark:标记价格
> tpOrdPx String 止盈委托价,止盈委托价格为-1时,执行市价止盈
> slTriggerPx String 止损触发价
> slTriggerPxType String 止损触发价类型
last:最新价格
index:指数价格
mark:标记价格
> slOrdPx String 止损委托价,止损委托价格为-1时,执行市价止损
> attachAlgoOrds Array of object 下单附带止盈止损信息
>> attachAlgoId String 附带止盈止损的订单ID,订单完全成交,下止盈止损委托单时,该值不会传给 algoId
>> attachAlgoClOrdId String 下单附带止盈止损时,客户自定义的策略订单ID
>> tpTriggerPx String 止盈触发价
>> tpTriggerPxType String 止盈触发价类型
last:最新价格
index:指数价格
mark:标记价格
>> tpOrdPx String 止盈委托价
>> slTriggerPx String 止损触发价
>> slTriggerPx String 止损触发价类型
last:最新价格
index:指数价格
mark:标记价格
>> slOrdPx String 止损委托价
>> sz String 张数。仅适用于“多笔止盈”的止盈订单且必填
>> amendPxOnTriggerType String 是否启用开仓价止损,仅适用于分批止盈的止损订单
0. 不开启,默认值
1. 开启“开仓价止损”
> stpId String 自成交保护ID
如果自成交保护不适用则返回""
> stpMode String 自成交保护模式
如果自成交保护不适用则返回""
> feeCcy String 交易手续费币种
币币/币币杠杆:如果是买的话,收取的就是BTC;如果是卖的话,收取的就是USDT
交割/永续/期权 收取的就是保证金
> fee String 订单交易累计的手续费与返佣
对于币币和杠杆,为订单交易累计的手续费,平台向用户收取的交易手续费,为负数。如: -0.01
对于交割、永续和期权,为订单交易累计的手续费和返佣
> rebateCcy String 返佣金币种 ,如果没有返佣金,该字段为“”
> rebate String 返佣累计金额,仅适用于币币和杠杆,平台向达到指定lv交易等级的用户支付的挂单奖励(返佣),如果没有返佣金,该字段为“”
> pnl String 收益,适用于有成交的平仓订单,其他情况均为0
> source String 订单来源
6:计划委托策略触发后的生成的普通单
7:止盈止损策略触发后的生成的普通单
13:策略委托单触发后的生成的普通单
24:移动止盈止损策略触发后的生成的普通单
> cancelSource String 订单取消的来源
有效值及对应的含义是:
0: 已撤单:系统撤单
1: 用户主动撤单
2: 已撤单:预减仓撤单,用户保证金不足导致挂单被撤回
3: 已撤单:风控撤单,用户保证金不足有爆仓风险,导致挂单被撤回
4: 已撤单:币种借币量达到平台硬顶,系统已撤回该订单
6: 已撤单:触发 ADL 撤单,用户保证金率较低且有爆仓风险,导致挂单被撤回
7: 已撤单:交割合约到期
9: 已撤单:扣除资金费用后可用余额不足,系统已撤回该订单
13: 已撤单:FOK 委托订单未完全成交,导致挂单被完全撤回
14: 已撤单:IOC 委托订单未完全成交,仅部分成交,导致部分挂单被撤回
17: 已撤单:平仓单被撤单,由于仓位已被市价全平
20: 系统倒计时撤单
21: 已撤单:相关仓位被完全平仓,系统已撤销该止盈止损订单
22, 23: 已撤单:只减仓订单仅允许减少仓位数量,系统已撤销该订单
27: 成交滑点超过5%,触发成交差价保护导致系统撤单
31: 当前只挂单订单 (Post only) 将会吃掉挂单深度
32: 自成交保护
33: 当前 taker 订单匹配的订单数量超过最大限制
> amendSource String 订单修改的来源
1: 用户主动改单,改单成功
2: 用户主动改单,并且当前这笔订单被只减仓修改,改单成功
3: 用户主动下单,并且当前这笔订单被只减仓修改,改单成功
4: 用户当前已存在的挂单(非当前操作的订单),被只减仓修改,改单成功
5. 期权 px, pxVol 或 pxUsd 的跟随变动导致的改单,比如 iv=60,usd,px 锚定iv=60 时,usd, px 产生变动时的改单
> category String 订单种类分类
normal:普通委托订单种类
twap:TWAP订单种类
adl:ADL订单种类
full_liquidation:爆仓订单种类
partial_liquidation:减仓订单种类
delivery:交割
ddh:对冲减仓类型订单
> uTime String 订单更新时间,Unix时间戳的毫秒数格式,如 1597026383085
> cTime String 订单创建时间,Unix时间戳的毫秒数格式,如 1597026383085
> reqId String 修改订单时使用的request ID,如果没有修改,该字段为""
> amendResult String 修改订单的结果
-1: 失败
0:成功
1:自动撤单(因为修改成功导致订单自动撤销)
2: 自动改单成功,仅适用于期权pxUsd和pxVol订单的自动改单
通过API修改订单时,如果cxlOnFail设置为true且修改返回结果为失败时,则返回 ""
通过API修改订单时,如果修改返回结果为成功但修改最终失败后,当cxlOnFail设置为false时返回 -1;当cxlOnFail设置为true时则返回1
通过Web/APP修改订单时,如果修改失败后,则返回-1
> reduceOnly String 是否只减仓,truefalse
> quickMgnType String 一键借币类型,仅适用于杠杆逐仓的一键借币模式
manual:手动,auto_borrow: 自动借币,auto_repay: 自动还币
> algoClOrdId String 客户自定义策略订单ID。策略订单触发,且策略单有algoClOrdId时有值,否则为"",
> algoId String 策略委托单ID,策略订单触发时有值,否则为""
> code String 错误码,默认为0
> msg String 错误消息,默认为""

WS / 下单

只有当您的账户有足够的资金才能下单。一旦下单,您的账户资金将在订单生命周期内被冻结。被冻结的资金以及数量取决于订单指定的类型和参数

该接口支持带单产品的下单,但不支持为带单产品平仓。请参考 跟单 了解更多

限速:60次/2s

跟单交易带单合约的限速:4次/2s

限速规则(期权以外):UserID + Instrument ID

限速规则(只限期权):UserID + Instrument Family

请求示例

{
    "id": "1512",
    "op": "order",
    "args": [{
        "side": "buy",
        "instId": "BTC-USDT",
        "tdMode": "isolated",
        "ordType": "market",
        "sz": "100"
    }]
}

请求参数

参数名 类型 是否必须 描述
id String 消息的唯一标识
用户提供,返回参数中会返回以便于找到相应的请求。
字母(区分大小写)与数字的组合,可以是纯字母、纯数字且长度必须要在1-32位之间。
op String 支持的业务操作,如 order
args Array 请求参数
> instId String 产品ID,如 BTC-USD-190927-5000-C
> tdMode String 交易模式
保证金模式 isolated:逐仓 cross: 全仓
非保证金模式 cash:现金
spot_isolated:现货逐仓(仅适用于现货带单)
> ccy String 保证金币种,仅适用于单币种保证金账户下的全仓杠杆订单
> clOrdId String 由用户设置的订单ID
字母(区分大小写)与数字的组合,可以是纯字母、纯数字且长度要在1-32位之间。
> tag String 订单标签
字母(区分大小写)与数字的组合,可以是纯字母、纯数字且长度要在1-16位之间。
> side String 订单方向,buy sell
> posSide String 持仓方向
在买卖模式下,默认 net
在开平仓模式下必填,且仅可选择 longshort,仅适用于交割/永续
> ordType String 订单类型
market:市价单
limit:限价单
post_only:只做maker单
fok:全部成交或立即取消
ioc:立即成交并取消剩余
optimal_limit_ioc:市价委托立即成交并取消剩余(仅适用交割、永续)
mmp:做市商保护(仅适用于组合保证金账户模式下的期权订单)
mmp_and_post_only:做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单)
> sz String 委托数量
> px String 可选 委托价格,仅适用于limitpost_onlyfokiocmmpmmp_and_post_only类型的订单
期权下单时,px/pxUsd/pxVol 只能填一个
> pxUsd String 可选 以USD价格进行期权下单
仅适用于期权
期权下单时 px/pxUsd/pxVol 必填一个,且只能填一个
> pxVol String 可选 以隐含波动率进行期权下单,例如 1 代表 100%
仅适用于期权
期权下单时 px/pxUsd/pxVol 必填一个,且只能填一个
> reduceOnly Boolean 是否只减仓,truefalse,默认false
仅适用于币币杠杆,以及买卖模式下的交割/永续
仅适用于单币种保证金模式跨币种保证金模式
> tgtCcy String 币币市价单委托数量sz的单位
base_ccy: 交易货币 ;quote_ccy:计价货币
仅适用于币币市价订单
默认买单为quote_ccy,卖单为base_ccy
> banAmend Boolean 是否禁止币币市价改单,true 或 false,默认false
为true时,余额不足时,系统不会改单,下单会失败,仅适用于币币市价单
> quickMgnType String 一键借币类型,仅适用于杠杆逐仓的一键借币模式:
manual:手动,auto_borrow: 自动借币,auto_repay: 自动还币
默认是manual:手动
> stpId String 自成交保护ID。来自同一个母账户配着同一个ID的订单不能自成交
用户自定义1<=x<=999999999的整数
> stpMode String 自成交保护模式,需要stpId有值才会生效
默认为 cancel maker
cancel_maker,cancel_taker, cancel_both
Cancel both不支持FOK
expTime String 请求有效截止时间。Unix时间戳的毫秒数格式,如 1597026383085

成功返回示例

{
    "id": "1512",
    "op": "order",
    "data": [{
        "clOrdId": "",
        "ordId": "12345689",
        "tag": "",
        "sCode": "0",
        "sMsg": ""
    }],
    "code": "0",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

失败返回示例

{
    "id": "1512",
    "op": "order",
    "data": [{
        "clOrdId": "",
        "ordId": "",
        "tag": "",
        "sCode": "5XXXX",
        "sMsg": "not exist"
    }],
    "code": "1",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

格式错误返回示例

{
    "id": "1512",
    "op": "order",
    "data": [],
    "code": "60013",
    "msg": "Invalid args",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

返回参数

参数名 类型 描述
id String 消息的唯一标识
op String 业务操作
code String 代码
msg String 消息
data Array 请求成功后返回的数据
> ordId String 订单ID
> clOrdId String 由用户设置的订单ID
> tag String 订单标签
> sCode String 订单状态码,0 代表成功
> sMsg String 订单状态消息
inTime String WebSocket 网关接收请求时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123
outTime String WebSocket 网关发送响应时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123

WS / 批量下单

批量进行下单操作,每次可批量交易不同类型的产品,最多可下单20个

该接口支持带单产品的下单,但不支持为带单产品平仓。请参考 跟单 了解更多

限速:300个/2s

跟单交易带单合约的限速:4个/2s

限速规则(期权以外):UserID + Instrument ID

限速规则(只限期权):UserID + Instrument Family

请求示例

{
    "id": "1513",
    "op": "batch-orders",
    "args": [{
        "side": "buy",
        "instId": "BTC-USDT",
        "tdMode": "isolated",
        "ordType": "market",
        "sz": "100"
    }, {
        "side": "buy",
        "instId": "BTC-USD-200925",
        "tdMode": "isolated",
        "ordType": "limit",
        "sz": "1"
    }]
} 

请求参数

参数名 类型 是否必须 描述
id String 消息的唯一标识
用户提供,返回参数中会返回以便于找到相应的请求。
字母(区分大小写)与数字的组合,可以是纯字母、纯数字且长度必须要在1-32位之间。
op String 支持的业务操作,如 batch-orders
args Array 请求参数
> instId String 产品ID,如 BTC-USDT
> tdMode String 交易模式
保证金模式 cross:全仓 isolated:逐仓
非保证金模式 cash:现金
spot_isolated:现货逐仓(仅适用于现货带单)
> ccy String 保证金币种,仅适用于单币种保证金账户下的全仓杠杆订单
> clOrdId String 用户提供的订单ID
字母(区分大小写)与数字的组合,可以是纯字母、纯数字且长度要在1-32位之间。
> tag String 订单标签
字母(区分大小写)与数字的组合,可以是纯字母、纯数字且长度要在1-16位之间。
> side String 订单方向, buy sell
> posSide String 持仓方向
在买卖模式下,默认 net
在开平仓模式下必填,且仅可选择 longshort,仅适用于交割/永续
> ordType String 订单类型
market: 市价单
limit:限价单
post_only:只做maker单
fok:全部成交或立即取消单
ioc:立即成交并取消剩余单
optimal_limit_ioc:市价委托立即成交并取消剩余(仅适用交割、永续)
mmp:做市商保护(仅适用于组合保证金账户模式下的期权订单)
mmp_and_post_only:做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单)
> sz String 委托数量
> px String 可选 委托价格,仅适用于limitpost_onlyfokiocmmpmmp_and_post_only类型的订单
期权下单时,px/pxUsd/pxVol 只能填一个
> pxUsd String 可选 以USD价格进行期权下单
仅适用于期权
期权下单时 px/pxUsd/pxVol 必填一个,且只能填一个
> pxVol String 可选 以隐含波动率进行期权下单,例如 1 代表 100%
仅适用于期权
期权下单时 px/pxUsd/pxVol 必填一个,且只能填一个
> reduceOnly Boolean 是否只减仓,truefalse,默认false
仅适用于币币杠杆,以及买卖模式下的交割/永续
仅适用于单币种保证金模式跨币种保证金模式
> tgtCcy String 币币市价单委托数量sz的单位
base_ccy: 交易货币 ;quote_ccy:计价货币
仅适用于币币市价订单
默认买单为quote_ccy,卖单为base_ccy
> banAmend Boolean 是否禁止币币市价改单,true 或 false,默认false
为true时,余额不足时,系统不会改单,下单会失败,仅适用于币币市价单
> quickMgnType String 一键借币类型,仅适用于杠杆逐仓的一键借币模式:
manual:手动,auto_borrow: 自动借币,auto_repay: 自动还币
默认是manual:手动
> stpId String 自成交保护ID。来自同一个母账户配着同一个ID的订单不能自成交
用户自定义1<=x<=999999999的整数
> stpMode String 自成交保护模式,需要stpId有值才会生效
默认为 cancel maker
cancel_maker,cancel_taker, cancel_both
Cancel both不支持FOK
expTime String 请求有效截止时间。Unix时间戳的毫秒数格式,如 1597026383085

全部成功返回示例

{
    "id": "1513",
    "op": "batch-orders",
    "data": [{
        "clOrdId": "",
        "ordId": "12345689",
        "tag": "",
        "sCode": "0",
        "sMsg": ""
    }, {
        "clOrdId": "",
        "ordId": "12344",
        "tag": "",
        "sCode": "0",
        "sMsg": ""
    }],
    "code": "0",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

部分成功返回示例

{
    "id": "1513",
    "op": "batch-orders",
    "data": [{
        "clOrdId": "",
        "ordId": "12345689",
        "tag": "",
        "sCode": "0",
        "sMsg": ""
    }, {
        "clOrdId": "",
        "ordId": "",
        "tag": "",
        "sCode": "5XXXX",
        "sMsg": "Insufficient margin"
    }],
    "code": "2",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

全部失败返回示例

{
    "id": "1513",
    "op": "batch-orders",
    "data": [{
        "clOrdId": "oktswap6",
        "ordId": "",
        "tag": "",
        "sCode": "5XXXX",
        "sMsg": "Insufficient margin"
    }, {
        "clOrdId": "oktswap7",
        "ordId": "",
        "tag": "",
        "sCode": "5XXXX",
        "sMsg": "Insufficient margin"
    }],
    "code": "1",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

格式错误返回示例

{
    "id": "1513",
    "op": "batch-orders",
    "data": [],
    "code": "60013",
    "msg": "Invalid args",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

返回参数

参数 类型 描述
id String 消息的唯一标识
op String 业务操作
code String 代码
msg String 消息
data Array 请求成功后返回的数据
> ordId String 订单ID
> clOrdId String 由用户设置的订单ID
> tag String 订单标签
> sCode String 订单状态码,0 代表成功
> sMsg String 事件执行失败或成功时的msg
inTime String WebSocket 网关接收请求时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123
outTime String WebSocket 网关发送响应时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123

WS / 撤单

撤销当前未完成订单

限速:60次/2s

限速规则(期权以外):UserID + Instrument ID

限速规则(只限期权):UserID + Instrument Family

请求示例

{
    "id": "1514",
    "op": "cancel-order",
    "args": [{
        "instId": "BTC-USDT",
        "ordId": "2510789768709120"
    }]
}

请求参数

参数名 类型 是否必须 描述
id String 消息的唯一标识
用户提供,返回参数中会返回以便于找到相应的请求。
字母(区分大小写)与数字的组合,可以是纯字母、纯数字且长度必须要在1-32位之间。
op String 支持的业务操作,如 cancel-order
args Array 请求参数
> instId String 产品ID
> ordId String 可选 订单ID
ordId和clOrdId必须传一个,若传两个,以 ordId 为主
> clOrdId String 可选 用户提供的订单ID
字母(区分大小写)与数字的组合,可以是纯字母、纯数字,且长度要在1-32位之间。

成功返回示例

{
    "id": "1514",
    "op": "cancel-order",
    "data": [{
        "clOrdId": "",
        "ordId": "2510789768709120",
        "sCode": "0",
        "sMsg": ""
    }],
    "code": "0",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

失败返回示例

{
    "id": "1514",
    "op": "cancel-order",
    "data": [{
        "clOrdId": "",
        "ordId": "2510789768709120",
        "sCode": "5XXXX",
        "sMsg": "Order not exist"
    }],
    "code": "1",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

格式错误返回示例

{
    "id": "1514",
    "op": "cancel-order",
    "data": [],
    "code": "60013",
    "msg": "Invalid args",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

返回参数

参数 类型 描述
id String 消息的唯一标识
op String 业务操作
code String 代码
msg String 消息
data Array 请求成功后返回的数据
> ordId String 订单ID
> clOrdId String 由用户设置的订单ID
> sCode String 订单状态码,0 代表成功
> sMsg String 订单状态消息
inTime String WebSocket 网关接收请求时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123
outTime String WebSocket 网关发送响应时的时间戳,Unix时间戳的微秒数格式,如 1597026383085123