概览

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

在 my.okx.com 完成注册的用户，请访问 https://my.okx.com/docs-v5/zh/ 获取 V5 API 文档。

API学习资源与技术支持

教程

学习使用V5 API交易: V5 API使用指南
学习使用Python交易现货: Python 现货交易教程
学习使用Python交易衍生品: Python 衍生品交易教程

Python包

使用Python SDK更简单地上手: Python SDK
轻松上手Python做市商代码 Python 做市商代码示例

客户服务

订阅API更新: https://t.me/OKExAPIChannel
请花1分钟时间帮助我们提升我们的服务: V5 API 满意度调研
如有问题请咨询线上客服

创建我的APIKey

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

生成APIKey

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

APIKey
SecretKey
Passphrase

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

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

读取：查询账单和历史记录等读权限
提现：可以进行提币
交易：可以下单和撤单，转账，调整配置等写权限

REST 请求验证

发起请求

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

OK-ACCESS-KEY字符串类型的APIKey。
OK-ACCESS-SIGN使用HMAC SHA256哈希函数获得哈希值，再使用Base-64编码（请参阅签名）。
OK-ACCESS-TIMESTAMP发起请求的时间（UTC），如：2020-12-08T09:08:57.715Z
OK-ACCESS-PASSPHRASE您在创建API密钥时指定的Passphrase。

所有请求都应该含有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）。它实现了用户端与服务器全双工通信，使得数据可以快速地双向传播。通过一次简单的握手就可以建立用户端和服务器连接，服务器根据业务规则可以主动推送信息给用户端。其优点如下：

用户端和服务器进行数据传输时，请求头信息比较小，大概2个字节。
用户端和服务器皆可以主动地发送数据给对方。
不需要多次创建TCP请求和销毁，节约宽带和服务器的资源。

连接

连接限制：3 次/秒 (基于IP)

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

请求限制：

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

连接限制

子账户维度，订阅每个 WebSocket 频道的最大连接数为 30 个。每个 WebSocket 连接都由唯一的 connId 标识。

受此限制的 WebSocket 频道如下：

若用户通过不同的请求参数在同一个 WebSocket 连接下订阅同一个频道，例如使用 {"channel": "orders", "instType": "ANY"} 和 {"channel": "orders", "instType": "SWAP"}，只算为一次连接。若用户使用相同或不同的 WebSocket 连接订阅上述频道，例如订单频道和账户频道。在该两个频道之间，计数不会累计，因为它们被视作不同的频道。简言之，系统计算每个频道对应的 WebSocket 连接数量。

新链接订阅频道时，平台将对该订阅返回channel-conn-count的消息同步链接数量。

链接数量更新

{
    "event":"channel-conn-count",
    "channel":"orders",
    "connCount": "2",
    "connId":"abcd1234"
}

当超出限制时，一般最新订阅的链接会收到拒绝。用户会先收到平时的订阅成功信息然后收到channel-conn-count-error消息，代表平台终止了这个链接的订阅。在异常场景下平台会终止已订阅的现有链接。

链接数量限制报错

{
    "event": "channel-conn-count-error",
    "channel": "orders",
    "connCount": "20",
    "connId":"a4d3ae55"
}

通过 WebSocket 进行的订单操作，例如下单、修改和取消订单，不会受到此改动影响。

请求示例

{
 "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

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

先将timestamp 、 method 、requestPath 进行字符串拼接，再使用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":"BTC-USDT"
        }
    ]
}

请求参数

参数	类型	是否必须	描述
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": "BTC-USDT"
    },
    "connId": "accb8e21"
}

返回参数

参数	类型	是否必须	描述
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": "BTC-USDT"
    }
  ]
}

请求参数

参数	类型	是否必须	描述
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": "BTC-USDT"
    },
    "connId": "d0b44253"
}

返回参数

参数	类型	是否必须	描述
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

通知

WebSocket有一种消息类型(event=notice)。

用户会在如下场景收到此类信息：

Websocket服务升级断线

在推送服务升级前30秒会推送信息，告知用户WebSocket服务即将升级。用户可以重新建立新的连接避免由于断线造成的影响。

返回示例

{
    "event": "notice",
    "code": "64008",
    "msg": "The connection will soon be closed for a service upgrade. Please reconnect.",
    "connId": "a4d3ae55"
}

目前支持WebSocket公共频道(/ws/v5/public)和私有频道(/ws/v5/private)。

账户模式

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

交易账户交易系统提供四个账户模式，分别为现货模式、现货和合约模式、跨币种保证金模式以及组合保证金模式。

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

实盘交易

实盘API交易地址如下：

REST：https://www.okx.com
WebSocket公共频道：wss://ws.okx.com:8443/ws/v5/public
WebSocket私有频道：wss://ws.okx.com:8443/ws/v5/private
WebSocket业务频道：wss://ws.okx.com:8443/ws/v5/business

AWS 地址如下：

REST：https://aws.okx.com
WebSocket公共频道：wss://wsaws.okx.com:8443/ws/v5/public
WebSocket私有频道：wss://wsaws.okx.com:8443/ws/v5/private
WebSocket业务频道：wss://wsaws.okx.com:8443/ws/v5/business

模拟盘交易

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

模拟盘API交易地址如下：

REST：https://www.okx.com
WebSocket公共频道：wss://wspap.okx.com:8443/ws/v5/public
WebSocket私有频道：wss://wspap.okx.com:8443/ws/v5/private
WebSocket业务频道：wss://wspap.okx.com:8443/ws/v5/business

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

模拟盘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

模拟盘交互式浏览器

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

Parameters 面板中点击Try it out按钮，编辑请求参数。
点击Execute按钮发送请求。Responses 面板中查看请求结果。

立即体验交互式浏览器

基本信息

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

未成交订单（包括 post only，limit和处理中的taker单）的最大挂单数：4,000个
单个交易产品未成交订单的最大挂单数为500个，被计入到 500 笔挂单数量限制的订单类型包括：
- 限价委托 (Limit)
- 市价委托 (Market)
- 只挂单 (Post only)
- 全部成交或立即取消 (FOK)
- 立即成交并取消剩余 (IOC)
- 市价委托立即成交并取消剩余 (optimal limit IOC)
- 止盈止损 (TP/SL)
- 以下类型的订单触发的限价和市价委托：
  - 止盈止损 (TP/SL)
  - 计划委托 (Trigger)
  - 移动止盈止损 (Trailing stop)
  - 套利下单 (Arbitrage)
  - 冰山策略 (Iceberg)
  - 时间加权策略 (TWAP)
  - 定投 (Recurring buy)
价差订单最大挂单数：所有价差订单挂单合计500个
策略委托订单最大挂单数：
- 止盈止损：100个每个Instrument ID
- 计划委托：500个
- 移动止盈止损：50个
- 冰山委托：100个
- 时间加权委托：20个
网格策略最大个数：
- 现货网格：100个
- 合约网格：100个

交易限制规则如下：

当taker订单匹配的maker订单数量超过最大限制1000笔时，taker订单将被取消
- 限价单仅成交与1000笔maker订单相对应的部分，并取消剩余；
- 全部成交或立即取消（FOK）订单将直接被取消。

返回数据规则如下：

当返回数据中，有code，且没有sCode字段时，code和msg代表请求结果或者报错原因；
当返回中有sCode字段时，代表请求结果或者报错原因的是sCode和sMsg，而不是code和msg。

交易品种instFamily参数说明：

与uly没有区别：
- 如："BTC-USD-SWAP"的instFamily和uly均为BTC-USD，"BTC-USDC-SWAP"的instFamily和uly均为为BTC-USDC。
- 若请求参数指定uly为"BTC-USD"，会包含"BTC-USD"币本位合约的数据
- 若请求参数指定instFamily为"BTC-USD"，也只会包含"BTC-USD"币本位合约的数据。
您可以通过"获取交易产品基础信息"接口获取交易产品对应的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 文档并限制请求）。
每个接口的限速都不同。您可以从接口详细信息中找到每个接口的限制。限速定义详述如下：

WebSocket 登录和订阅限速基于连接。
公共未经身份验证的 REST 限速基于 IP 地址。
私有 REST 限速基于 User ID（子帐户具有单独的 User ID）。
WebSocket 订单管理限速基于 User ID（子账户具有单独的 User ID）。

对于与交易相关的 API（下订单、取消订单和修改订单），以下条件适用：

限速在 REST 和 WebSocket 通道之间共享。
下单、修改订单、取消订单的限速相互独立。
限速在 Instrument ID 级别定义（期权除外）
期权的限速是根据 Instrument Family 级别定义的。请参阅获取交易产品基础信息接口以查看交易品种信息。
批量订单接口和单订单接口的限速也是独立的，除了只有一个订单发送到批量订单接口时，该订单将被视为一个订单并采用单订单限速。

子账户限速

子账户维度，每2秒最多允许1000个订单相关请求。仅有新订单及修改订单请求会被计入此限制。此限制涵盖以下所列的所有接口。对于包含多个订单的批量请求，每个订单将被单独计数。如果请求频率超过限制，系统会返回50061错误码。产品ID维度的限速规则保持不变，现有的限速规则与新增的子账户维度限速将并行运行。若用户需要更高的速率限制，可以通过多个子账户进行交易。

基于成交比率的子账户限速

仅适用于用户等级 >= VIP5的用户。
为了激励更高效的交易，交易所将为交易成交比率高的用户提供更高的子账户限速。

交易所将在每天 00:00 UTC，根据过去七天的交易数据计算两个比率。

子账户成交比率：该比率为（子账户的USDT对应交易量）/（每个交易产品的新增和修改请求数 * 交易产品乘数之和）。请注意，在这种情况下，母账户自身也被视为一个“子账户”。
母账户合计成交比率：该比率为（母账户层面的USDT对应交易量）/（所有子账户各个交易产品的新增和修改请求数 * 交易产品乘数之和）。

交易产品乘数允许我们微调每个交易产品对成交比率的影响权重。较小的交易产品乘数（<1）适用于小币对及合约，在交易这些币对、合约时，为达到相同交易量往往需要更多的订单。所有的交易产品都有默认乘数，部分交易产品有独立的乘数。详情请见下表。

业务线	覆盖规则	独立乘数	默认乘数
永续	产品ID	`1` 产品ID： BTC-USDT-SWAP BTC-USD-SWAP ETH-USDT-SWAP ETH-USD-SWAP	`0.2`
交割	交易品种	`0.3` 交易品种： BTC-USDT BTC-USD ETH-USDT ETH-USD	`0.1`
币币	产品ID	`0.5` 产品ID： BTC-USDT ETH-USDT	`0.1`
期权	交易品种		`0.1`

成交比率计算不包括大宗交易，价差交易，做市商保护（MMP），以及法币类型订单对应的订单数量；并且不包括大宗交易，价差交易对应的交易量。仅考虑 sCode = 0 的成功请求。

每日 08:00 UTC，系统将根据UTC时间 00:00 的数据快照，选取子账户成交比率及母账户合计成交比率中的较大值决定子账户的未来限速。详情请见下表。对于独立经纪商，系统只会取子账户的成交比率。

	成交比率[x<=比率<y)	子账户每2秒限速(新订单及修改订单请求)
Tier 1	[0,1)	1,000
Tier 2	[1,2)	1,250
Tier 3	[2,3)	1,500
Tier 4	[3,5)	1,750
Tier 5	[5,10)	2,000
Tier 6	[10,20)	2,500
Tier 7	[20,50)	3,000
Tier 8	>= 50	10,000

若成交比率和预期限速有所改善，则提升将于 08:00 (UTC) 立即生效。但若成交比率下降，需要降低未来限速，系统将给予一天的宽限期，降低后的速率限制将在 T+1 08:00 (UTC) 实施。在 T+1 时，若成交比率提高，则将立即授予更高的限速。若用户的交易手续费等级降级为 VIP4，其限速将降低为最低档位，并有一天的宽限期。

若子账户7日交易量低于1,000,000 USDT，则按照母账户的合计成交比率实施限速。

对于新创建的子账户，创建时将应用最低档位限速，在 T+1 08:00 (UTC)时，将开始应用上述限速规则。

大宗交易、价差交易、做市商保护（MMP）以及币币、币币杠杆订单不受子账户限速限制。

交易所提供 GET / 获取账户限速接口以便用户查询成交比率以及限速数据，数据将于每天 08:00 (UTC) 更新。该接口将返回子账户成交比率，母账户合计成交比率，子账户当前限速以及 T+1 时的预期子账户限速（适用于限速降级）。

成交比率、限速计算样例如下。用户有三个账户，交易产品 BTC-USDT-SWAP 及 XRP-USDT 的乘数分别为1，0.1。

账户 A（母账户）：
1. BTC-USDT-SWAP 交易量为100 USDT，订单数量为10;
2. XRP-USDT 交易量为20 USDT，订单数量为15;
3. 子账户成交比率 = (100+20) / (10 * 1 + 15 * 0.1) = 10.4
账户 B (子账户)：
1. BTC-USDT-SWAP 交易量为200 USDT，订单数量为100;
2. XRP-USDT 交易量为20 USDT，订单数量为30;
3. 子账户成交比率 = (200+20) / (100 * 1 + 30 * 0.1) = 2.13
账户 C (子账户)：
1. BTC-USDT-SWAP 交易量为300 USDT，订单数量为100;
2. XRP-USDT 交易量为20 USDT，订单数量为45;
3. 子账户成交比率 = (300+20) / (100 * 1 + 45 * 0.1) = 3.06
母账户合计成交比率 = (100+20+200+20+300+20) / (10 * 1 + 15 * 0.1 + 100 * 1 + 30 * 0.1 + 100 * 1 + 45 * 0.1) = 3.01
账户限速
1. 账户 A = max(10.4, 3.01) = 10.4 -> 2500订单请求/2秒
2. 账户 B = max(2.13, 3.01) = 3.01 -> 1750订单请求/2秒
3. 账户 C = max(3.06, 3.01) = 3.06 -> 1750订单请求/2秒

最佳实践

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

做市商申请

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

交易等级VIP2及以上
其他交易所达标做市商（需审核）

感兴趣的各方可以使用此表格联系我们：https://okx.typeform.com/contact-sales

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

经纪商申请

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

点击申请
经纪商规则介绍
如有问题请咨询线上客服

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

交易账户

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

REST API

获取交易产品基础信息

获取当前账户可交易产品的信息列表。

限速：20次/2s

限速规则：UserID + InstType

权限：读取

HTTP请求

GET /api/v5/account/instruments

请求示例

GET /api/v5/account/instruments?instType=SPOT

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_instruments(instType="SPOT")
print(result)

请求参数

参数名	类型	是否必须	描述
instType	String	是	产品类型 `SPOT`：币币 `MARGIN`：币币杠杆 `SWAP`：永续合约 `FUTURES`：交割合约 `OPTION`：期权
uly	String	可选	标的指数，仅适用于`交割/永续/期权`，期权必填
instFamily	String	否	交易品种，仅适用于`交割/永续/期权`
instId	String	否	产品ID

返回结果

{
    "code": "0",
    "data": [
        {
            "auctionEndTime": "",
            "baseCcy": "BTC",
            "ctMult": "",
            "ctType": "",
            "ctVal": "",
            "ctValCcy": "",
            "expTime": "",
            "instFamily": "",
            "instId": "BTC-EUR",
            "instType": "SPOT",
            "lever": "",
            "listTime": "1704876947000",
            "lotSz": "0.00000001",
            "maxIcebergSz": "9999999999.0000000000000000",
            "maxLmtAmt": "1000000",
            "maxLmtSz": "9999999999",
            "maxMktAmt": "1000000",
            "maxMktSz": "1000000",
            "maxStopSz": "1000000",
            "maxTriggerSz": "9999999999.0000000000000000",
            "maxTwapSz": "9999999999.0000000000000000",
            "minSz": "0.00001",
            "optType": "",
            "quoteCcy": "EUR",
            "settleCcy": "",
            "state": "live",
            "ruleType": "normal",
            "stk": "",
            "tickSz": "1",
            "uly": ""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instType	String	产品类型
instId	String	产品id，如 `BTC-USDT`
uly	String	标的指数，如 `BTC-USD`，仅适用于`杠杆/交割/永续/期权`
instFamily	String	交易品种，如 `BTC-USD`，仅适用于`杠杆/交割/永续/期权`
baseCcy	String	交易货币币种，如 `BTC-USDT` 中的 `BTC` ，仅适用于`币币/币币杠杆`
quoteCcy	String	计价货币币种，如 `BTC-USDT` 中的`USDT` ，仅适用于`币币/币币杠杆`
settleCcy	String	盈亏结算和保证金币种，如 `BTC` 仅适用于`交割/永续/期权`
ctVal	String	合约面值，仅适用于`交割/永续/期权`
ctMult	String	合约乘数，仅适用于`交割/永续/期权`
ctValCcy	String	合约面值计价币种，仅适用于`交割/永续/期权`
optType	String	期权类型，`C`或`P` 仅适用于`期权`
stk	String	行权价格，仅适用于`期权`
listTime	String	上线时间 Unix时间戳的毫秒数格式，如 `1597026383085`
auctionEndTime	String	集合竞价结束时间，Unix时间戳的毫秒数格式，如 `1597026383085` 仅适用于通过集合竞价方式上线的`币币`，其余情况返回""
expTime	String	产品下线时间适用于`币币/杠杆/交割/永续/期权`，对于 `交割/期权`，为交割/行权日期；亦可以为产品下线时间，有变动就会推送。
lever	String	该`instId`支持的最大杠杆倍数，不适用于`币币`、`期权`
tickSz	String	下单价格精度，如 `0.0001` 对于期权来说，是梯度中的最小下单价格精度，如果想要获取期权价格梯度，请使用"获取期权价格梯度"接口
lotSz	String	下单数量精度合约的数量单位是`张`，现货的数量单位是`交易货币`
minSz	String	最小下单数量合约的数量单位是`张`，现货的数量单位是`交易货币`
ctType	String	合约类型 `linear`：正向合约 `inverse`：反向合约仅适用于`交割/永续`
state	String	产品状态 `live`：交易中 `suspend`：暂停中 `preopen`：预上线，交割和期权合约轮转生成到开始交易；部分交易产品上线前 `test`：测试中（测试产品，不可交易）
ruleType	String	交易规则类型 `normal`：普通交易 `pre_market`：盘前交易
maxLmtSz	String	限价单的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`交易货币`
maxMktSz	String	市价单的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`USDT`
maxLmtAmt	String	限价单的单笔最大美元价值
maxMktAmt	String	市价单的单笔最大美元价值仅适用于`币币/币币杠杆`
maxTwapSz	String	时间加权单的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`交易货币` 单笔最小委托数量为 minSz*2
maxIcebergSz	String	冰山委托的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`交易货币`
maxTriggerSz	String	计划委托委托的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`交易货币`
maxStopSz	String	止盈止损市价委托的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`USDT`

查看账户余额

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

限速：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": "55415.624719833286",
            "borrowFroz": "0",
            "details": [
                {
                    "availBal": "4834.317093622894",
                    "availEq": "4834.3170936228935",
                    "borrowFroz": "0",
                    "cashBal": "4850.435693622894",
                    "ccy": "USDT",
                    "crossLiab": "0",
                    "disEq": "4991.542013297616",
                    "eq": "4992.890093622894",
                    "eqUsd": "4991.542013297616",
                    "smtSyncEq": "0",
                    "spotCopyTradingEq": "0",
                    "fixedBal": "0",
                    "frozenBal": "158.573",
                    "imr": "",
                    "interest": "0",
                    "isoEq": "0",
                    "isoLiab": "0",
                    "isoUpl": "0",
                    "liab": "0",
                    "maxLoan": "0",
                    "mgnRatio": "",
                    "mmr": "",
                    "notionalLever": "",
                    "ordFrozen": "0",
                    "rewardBal": "0",
                    "spotInUseAmt": "",
                    "clSpotInUseAmt": "",
                    "maxSpotInUse": "",
                    "spotIsoBal": "0",
                    "stgyEq": "150",
                    "twap": "0",
                    "uTime": "1705449605015",
                    "upl": "-7.545600000000006",
                    "uplLiab": "0",
                    "spotBal": "",
                    "openAvgPx": "",
                    "accAvgPx": "",
                    "spotUpl": "",
                    "spotUplRatio": "",
                    "totalPnl": "",
                    "totalPnlRatio": ""
                }
            ],
            "imr": "8.57068529",
            "isoEq": "0",
            "mgnRatio": "143682.59776662575",
            "mmr": "0.3428274116",
            "notionalUsd": "85.7068529",
            "ordFroz": "0",
            "totalEq": "55837.43556134779",
            "uTime": "1705474164160",
            "upl": "-7.543562688000006",
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
uTime	String	账户信息的更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
totalEq	String	美金层面权益
isoEq	String	美金层面逐仓仓位权益适用于`现货和合约模式`/`跨币种保证金模式`/`组合保证金模式`
adjEq	String	美金层面有效保证金适用于`现货模式`/`跨币种保证金模式`/`组合保证金模式`
ordFroz	String	美金层面全仓挂单占用保证金仅适用于`现货模式`/`跨币种保证金模式`
imr	String	美金层面占用保证金适用于`现货模式`/`跨币种保证金模式`/`组合保证金模式`
mmr	String	美金层面维持保证金适用于`现货模式`/`跨币种保证金模式`/`组合保证金模式`
borrowFroz	String	账户美金层面潜在借币占用保证金仅适用于`现货模式`/`跨币种保证金模式`/`组合保证金模式`。在其他账户模式下为""。
mgnRatio	String	美金层面保证金率适用于`现货模式`/`跨币种保证金模式`/`组合保证金模式`
notionalUsd	String	以美金价值为单位的持仓数量，即仓位美金价值适用于`现货模式`/`跨币种保证金模式`/`组合保证金模式`
upl	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	币种逐仓负债额适用于`跨币种保证金模式`/`组合保证金模式`
> rewardBal	String	体验金余额
> mgnRatio	String	币种全仓保证金率，衡量账户内某项资产风险的指标适用于`现货和合约模式`且有全仓仓位时
> imr	String	币种维度全仓占用保证金适用于`现货和合约模式`且有全仓仓位时
> mmr	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	现货对冲占用数量适用于`组合保证金模式`
> clSpotInUseAmt	String	用户自定义现货占用数量适用于`组合保证金模式`
> maxSpotInUse	String	系统计算得到的最大可能现货占用数量适用于`组合保证金模式`
> spotIsoBal	String	现货逐仓余额仅适用于现货带单/跟单适用于`现货模式`/`现货和合约模式`
> smtSyncEq	String	合约智能跟单权益默认为0，仅适用于跟单人。
> spotCopyTradingEq	String	现货智能跟单权益默认为0，仅适用于跟单人。
> spotBal	String	现货余额，单位为币种，比如 BTC。详情
> openAvgPx	String	现货开仓成本价单位 USD。详情
> accAvgPx	String	现货累计成本价单位 USD。详情
> spotUpl	String	现货未实现收益，单位 USD。详情
> spotUplRatio	String	现货未实现收益率。详情
> totalPnl	String	现货累计收益，单位 USD。详情
> totalPnlRatio	String	现货累计收益率。详情

更多字段详情，请参考以下产品文档：
现货和合约账户全仓交易规则
 跨币种保证金账户全仓交易规则
 跨币种保证金模式和组合保证金模式对比

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

参数	现货模式	现货和合约模式	跨币种保证金模式	组合保证金模式
uTime	是	是	是	是
totalEq	是	是	是	是
isoEq		是	是	是
adjEq	是		是	是
ordFroz	是		是	是
imr	是		是	是
mmr	是		是	是
borrowFroz	是		是	是
mgnRatio	是		是	是
notionalUsd	是		是	是
upl			是	是
details
> ccy	是	是	是	是
> eq	是	是	是	是
> cashBal	是	是	是	是
> uTime	是	是	是	是
> isoEq		是	是	是
> availEq		是	是	是
> disEq	是	是	是	是
> availBal	是	是	是	是
> frozenBal	是	是	是	是
> ordFrozen	是	是	是	是
> liab	是		是	是
> upl		是	是	是
> uplLiab			是	是
> crossLiab	是		是	是
> isoLiab			是	是
> mgnRatio		是
> interest	是		是	是
> twap	是		是	是
> maxLoan	是		是	是
> eqUsd	是	是	是	是
> borrowFroz	是		是	是
> notionalLever		是
> stgyEq	是	是	是	是
> isoUpl		是	是	是
> spotInUseAmt				是
> spotIsoBal	是	是
> imr		是
> mmr		是
> spotBal	是	是	是	是
> openAvgPx	是	是	是	是
> accAvgPx	是	是	是	是
> spotUpl	是	是	是	是
> spotUplRatio	是	是	是	是
> totalPnl	是	是	是	是
> totalPnlRatio	是	是	是	是

查看持仓信息

获取该账户下拥有实际持仓的信息。账户为买卖模式会显示净持仓（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`：期权 `instType`和`instId`同时传入的时候会校验`instId`与`instType`是否一致。
instId	String	否	交易产品ID，如：`BTC-USDT-SWAP` 支持多个`instId`查询（不超过10个），半角逗号分隔
posId	String	否	持仓ID 支持多个`posId`查询（不超过20个）。存在有效期的属性，自最近一次完全平仓算起，满30天 posId 以及整个仓位会被清除。

返回结果

{
    "code": "0",
    "data": [
        {
            "adl": "1",
            "availPos": "0.00190433573",
            "avgPx": "62961.4",
            "baseBal": "",
            "baseBorrowed": "",
            "baseInterest": "",
            "bePx": "",
            "bizRefId": "",
            "bizRefType": "",
            "cTime": "1724740225685",
            "ccy": "BTC",
            "clSpotInUseAmt": "",
            "closeOrderAlgo": [],
            "deltaBS": "",
            "deltaPA": "",
            "fee": "",
            "fundingFee": "",
            "gammaBS": "",
            "gammaPA": "",
            "idxPx": "62890.5",
            "imr": "",
            "instId": "BTC-USDT",
            "instType": "MARGIN",
            "interest": "0",
            "last": "62892.9",
            "lever": "5",
            "liab": "-99.9998177776581948",
            "liabCcy": "USDT",
            "liqPenalty": "",
            "liqPx": "53615.448336593756",
            "margin": "0.000317654",
            "markPx": "62891.9",
            "maxSpotInUseAmt": "",
            "mgnMode": "isolated",
            "mgnRatio": "9.404143929947395",
            "mmr": "0.0000318005395854",
            "notionalUsd": "119.756628017499",
            "optVal": "",
            "pendingCloseOrdLiabVal": "0",
            "pnl": "",
            "pos": "0.00190433573",
            "posCcy": "BTC",
            "posId": "1752810569801498626",
            "posSide": "net",
            "quoteBal": "",
            "quoteBorrowed": "",
            "quoteInterest": "",
            "realizedPnl": "",
            "spotInUseAmt": "",
            "spotInUseCcy": "",
            "thetaBS": "",
            "thetaPA": "",
            "tradeId": "785524470",
            "uTime": "1724742632153",
            "upl": "-0.0000033452492717",
            "uplLastPx": "-0.0000033199677697",
            "uplRatio": "-0.0105311101755551",
            "uplRatioLastPx": "-0.0104515220008934",
            "usdPx": "",
            "vegaBS": "",
            "vegaPA": ""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
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-USDT-SWAP`
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	期权市值，仅适用于`期权`
pendingCloseOrdLiabVal	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，仅适用于`期权`
spotInUseAmt	String	现货对冲占用数量适用于`组合保证金模式`
spotInUseCcy	String	现货对冲占用币种，如 `BTC` 适用于`组合保证金模式`
clSpotInUseAmt	String	用户自定义现货占用数量适用于`组合保证金模式`
maxSpotInUseAmt	String	系统计算得到的最大可能现货占用数量适用于`组合保证金模式`
realizedPnl	String	已实现收益仅适用于`交割/永续/期权` realizedPnl=pnl+fee+fundingFee+liqPenalty
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，如体验券id
bizRefType	String	外部业务类型

查看历史持仓信息

获取最近3个月有更新的仓位信息，按照仓位更新时间倒序排列。于2024年11月11日中午12:00（UTC+8）开始支持组合保证金账户模式下的历史持仓。

限速：10次/2s

限速规则：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条，uTime 相同的记录均会在当前请求中全部返回

返回结果

{
    "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",
            "posSide": "long",
            "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	已实现收益仅适用于`交割/永续/期权` realizedPnl=pnl+fee+fundingFee+liqPenalty
fee	String	累计手续费金额，正数代表平台返佣，负数代表平台扣除
fundingFee	String	累计资金费用
liqPenalty	String	累计爆仓罚金，有值时为负数。
pnl	String	平仓收益额
pnlRatio	String	平仓收益率
posSide	String	持仓模式方向 `long`：开平仓模式开多 `short`：开平仓模式开空 `net`：买卖模式
lever	String	杠杆倍数
direction	String	持仓方向 `long`：多 `short`：空仅适用于 `币币杠杆/交割/永续/期权`
triggerPx	String	触发标记价格，`type` 为`3`,`4`,`5`时有值，为`1`, `2` 时为空""
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-USDT-SWAP`
> 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`：期权
instId	String	否	产品ID，如 `BTC-USDT`
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`：价差交易 `26`：结构化产品 `27`：闪兑 `28`：小额兑换 `29`：一键还债 `30`：简单交易 `250`：跟单人分润支出 `251`：跟单人分润退还
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`：穿仓补偿 `109`：强平惩罚费 `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`：一键借币的自动还币 `220`：USDT 买期权转入 `221`：USDT 买期权转出 `16`：强制还币 `17`：强制借币还息 `224`：一键还债买入 `225`：一键还债卖出 `236`：小额兑换买入 `237`：小额兑换卖出 `250`：永续分润支出 `251`：永续分润退还 `280`：现货分润支出 `281`：现货分润退还 `284`: 跟单自动转入 `285`: 跟单手动转入 `286`: 跟单自动转出 `287`: 跟单手动转出 `270`：价差交易买 `271`：价差交易卖 `272`：价差交易开多 `273`：价差交易开空 `274`：价差交易平多 `275`：价差交易平空 `290`：系统转出小额资产 `293`：固定借币扣息 `294`：固定借币利息退款 `295`：固定借币逾期利息 `296`：结构化下单转出 `297`：结构化下单转入 `298`：结构化结算转出 `299`：结构化结算转入 `306`：手动借币 `307`：自动借币 `308`：手动还币 `309`：自动还币 `312`：自动折抵 `318`：闪兑买入 `319`：闪兑卖出 `320`：简单交易买入 `321`：简单交易卖出
after	String	否	请求此id之前（更旧的数据）的分页内容，传的值为对应接口的`billId`
before	String	否	请求此id之后（更新的数据）的分页内容，传的值为对应接口的`billId`
begin	String	否	筛选的开始时间戳 `ts`，Unix 时间戳为毫秒数格式，如 1597026383085
end	String	否	筛选的结束时间戳 `ts`，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-USDT`
ordId	String	订单ID 当type为`2`/`5`/`9`时，返回相应订单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	交易执行时的指数价格 d 对于交叉现货币对，返回 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`：期权
instId	String	否	产品ID，如 `BTC-USDT`
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`：价差交易 `26`：结构化产品 `250`：跟单人分润支出 `251`：跟单人分润退还
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`：穿仓补偿 `109`：强平惩罚费 `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`：一键借币的自动还币 `220`：USDT 买期权转入 `221`：USDT 买期权转出 `16`：强制还币 `17`：强制借币还息 `224`：一键还债买入 `225`：一键还债卖出 `236`：小额兑换买入 `237`：小额兑换卖出 `250`：永续分润支出 `251`：永续分润退还 `280`：现货分润支出 `281`：现货分润退还 `284`: 跟单自动转入 `285`: 跟单手动转入 `286`: 跟单自动转出 `287`: 跟单手动转出 `270`：价差交易买 `271`：价差交易卖 `272`：价差交易开多 `273`：价差交易开空 `274`：价差交易平多 `275`：价差交易平空 `290`：系统转出小额资产 `293`：固定借币扣息 `294`：固定借币利息退款 `295`：固定借币逾期利息 `296`：结构化下单转出 `297`：结构化下单转入 `298`：结构化结算转出 `299`：结构化结算转入 `306`：手动借币 `307`：自动借币 `308`：手动还币 `309`：自动还币 `312`：自动折抵 `318`：闪兑买入 `319`：闪兑卖出 `320`：简单交易买入 `321`：简单交易卖出
after	String	否	请求此id之前（更旧的数据）的分页内容，传的值为对应接口的`billId`
before	String	否	请求此id之后（更新的数据）的分页内容，传的值为对应接口的`billId`
begin	String	否	筛选的开始时间戳 `ts`，Unix 时间戳为毫秒数格式，如 `1597026383085`
end	String	否	筛选的结束时间戳 `ts`，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-USDT`
ordId	String	订单ID 当type为`2`/`5`/`9`时，返回相应订单id 无订单时，该字段返回 ""
execType	String	流动性方向 `T`：taker `M`：maker
from	String	转出账户 `6`：资金账户 `18`：交易账户仅适用于`资金划转`，不是`资金划转`时，返回 ""
to	String	转入账户 `6`：资金账户 `18`：交易账户仅适用于`资金划转`，不是`资金划转`时，返回 ""
notes	String	备注
interest	String	利息
tag	String	订单标签
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	成交时的远期价格，仅适用于 `期权`，其他业务线返回空字符串""

申请账单流水（自 2021 年）

申请自 2021 年 2 月 1 日以来的账单数据，不包括当前季度。

限速：12 次/天

限速规则：UserID

权限：读取

HTTP 请求

POST /api/v5/account/bills-history-archive

请求示例

POST /api/v5/account/bills-history-archive
body
{
    "year":"2023",
    "quarter":"Q1"
}

请求参数

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

返回结果

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

返回参数

参数名	类型	描述
result	String	是否已经存在该区间的下载链接 `true`：已存在，可以通过"获取账单流水（自 2021 年）"接口获取 `false`：不存在，正在生成，请 2 个小时后查看下载链接
ts	String	服务端首次收到请求的时间，Unix时间戳的毫秒数格式，如 `1597026383085`

获取账单流水（自 2021 年）

获取自 2021 年 2 月 1 日以来的账单数据

限速：10 次/2s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/account/bills-history-archive

请求示例

GET /api/v5/account/bills-history-archive?year=2023&quarter=Q4

请求参数

参数名	类型	是否必须	描述
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`：进行中 `failed`：生成失败，请重新生成

解压后CSV里的字段说明

参数名	类型	描述
instType	String	产品类型
billId	String	账单ID
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-USDT`
ordId	String	订单ID 无订单时，该字段返回 ""
execType	String	流动性方向 `T`：taker `M`：maker
interest	String	利息
tag	String	订单标签
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": "2",
            "acctStpMode": "cancel_maker",
            "autoLoan": false,
            "ctIsoMode": "automatic",
            "enableSpotBorrow": false,
            "greeksType": "PA",
            "ip": "",
            "type": "0",
            "kycLv": "3",
            "label": "v5 test",
            "level": "Lv1",
            "levelTmp": "",
            "liquidationGear": "-1",
            "mainUid": "44705892343619584",
            "mgnIsoMode": "automatic",
            "opAuth": "1",
            "perm": "read_only,withdraw,trade",
            "posMode": "long_short_mode",
            "roleType": "0",
            "spotBorrowAutoRepay": false,
            "spotOffsetType": "",
            "spotRoleType": "0",
            "spotTraderInsts": [],
            "traderInsts": [],
            "uid": "44705892343619584"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
uid	String	当前请求的账户ID，账户uid和app上的一致
mainUid	String	当前请求的母账户ID 如果 uid = mainUid，代表当前账号为母账户；如果 uid != mainUid，代表当前账户为子账户。
acctLv	String	账户模式 `1`：现货模式 `2`：现货和合约模式 `3`：跨币种保证金模式 `4`：组合保证金模式
acctStpMode	String	账户自成交保护模式 `cancel_maker`：撤销挂单 `cancel_taker`：撤销吃单 `cancel_both`：撤销挂单和吃单用户可通过母账户登录网页修改该配置
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 或 Access token 的权限 `read_only`：读取 `trade`：交易 `withdraw`：提币
liquidationGear	String	强平提醒的保证金率水平 `3` 和 `-1` 代表保证金率达到 300% 时，每隔 1 小时 app 和 ”爆仓风险预警推送频道“会推送通知。`-1` 是初始值，与`-3`有着同样效果 `0` 代表不提醒
enableSpotBorrow	Boolean	`现货模式`下是否支持借币 `true`：支持 `false`：不支持
spotBorrowAutoRepay	Boolean	`现货模式`下是否支持自动还币 `true`：支持 `false`：不支持
type	String	账户类型 `0`：母账户 `1`：普通子账户 `2`：资管子账户 `5`：托管交易子账户 - Copper `9`：资管交易子账户 - Copper `12`：托管交易子账户 - Komainu

设置持仓模式

现货和合约模式和跨币种保证金模式：交割和永续合约支持开平仓模式和买卖模式。买卖模式只会有一个方向的仓位；开平仓模式可以分别持有多、空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种杠杆倍数的设置场景：

在逐仓交易模式下，设置币币杠杆的杠杆倍数（币对层面）；
现货模式账户已开通借币功能，在全仓交易模式下，设置币币杠杆的杠杆倍数（币种层面）；
现货和合约模式账户在全仓交易模式下，设置币币杠杆的杠杆倍数（币对层面）；
跨币种保证金模式账户在全仓交易模式下，设置币币杠杆的杠杆倍数（币种层面）；
组合保证金模式账户在全仓交易模式下，设置币币杠杆的杠杆倍数（币种层面）；
在全仓交易模式下，设置交割的杠杆倍数（指数层面）；
在逐仓交易模式、买卖持仓模式下，设置交割的杠杆倍数（合约层面）；
在逐仓交易模式、开平仓持仓模式下，设置交割的杠杆倍数（合约与持仓方向层面）；
在全仓交易模式下，设置永续的杠杆倍数（合约层面）；
在逐仓交易模式、买卖持仓模式下，设置永续的杠杆倍数（合约层面）；
在逐仓交易模式、开平仓持仓模式下，设置永续的杠杆倍数（合约与持仓方向层面）；

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

限速：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
{
    "ccy":"BTC",
    "lever":"5",
    "mgnMode":"cross"
}


# 3.`现货和合约模式`账户在`全仓`交易模式下，设置`币币杠杆`的杠杆倍数（币对层面）
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT",
    "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
{
    "ccy":"BTC",
    "lever":"5",
    "mgnMode":"cross"
}

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

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

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

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

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

# 11.在`逐仓`交易模式、`开平仓`持仓模式下，设置`永续`的杠杆倍数（合约与头寸层面）
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：币对、合约全仓下，`instId`和`ccy`至少要传一个；如果两个都传，默认使用`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	持仓方向

获取最大可下单数量

获取最大可下单数量，可对应下单时的 "sz" 字段

限速：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`：非保证金 `spot_isolated`：现货逐仓
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`：非保证金 `spot_isolated`：现货逐仓
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",
        "availBuy": "100",
        "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	可选	增加或减少的保证金的币种，仅适用于逐仓一键借币模式下的币币杠杆，且必填

返回结果

{
    "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-SWAP&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-SWAP",
    mgnMode="cross"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	可选	产品ID 支持多个instId查询，半角逗号分隔。instId个数不超过20个。
ccy	String	可选	币种，用于币种维度的杠杆。仅适用于`现货模式`/`跨币种保证金模式`/`组合保证金模式`的全仓币币杠杆。支持多ccy查询，半角逗号分隔。ccy个数不超过20个。
mgnMode	String	是	保证金模式 `isolated`：逐仓 `cross`：全仓

返回结果

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

返回参数

参数名	类型	描述
instId	String	产品ID
ccy	String	币种，用于币种维度的杠杆。仅适用于`现货模式`/`跨币种保证金模式`/`组合保证金模式`的全仓币币杠杆。
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=cross

# 现货模式用户已经开通了借币情况下币种最大可借
GET  /api/v5/account/max-loan?instId=USDT&mgnMode=cross

# 现货和合约模式逐仓账户获取币币杠杆最大可借
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)

请求参数

参数名	类型	是否必须	描述
mgnMode	String	是	仓位类型 `isolated`：逐仓 `cross`：全仓
instId	String	可选	产品 ID，如 `BTC-USDT` 支持多产品ID查询（不超过5个），半角逗号分隔
ccy	String	可选	币种仅适用于`现货模式`下手动借币币种最大可借
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`
ruleType	String	是	交易规则类型 `normal`：普通交易 `pre_market`：盘前交易 ruleType不能与instId/instFamily/uly同时传入

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
            "category": "1", //已废弃
            "delivery": "",
            "exercise": "",
            "instType": "SPOT",
            "level": "lv1",
            "maker": "-0.0008",
            "makerU": "",
            "makerUSDC": "",
            "taker": "-0.001",
            "takerU": "",
            "takerUSDC": "",
            "ruleType": "normal",
            "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 合约费率
ruleType	String	交易规则类型 `normal`：普通交易 `pre_market`：盘前交易
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	否	借币类型 `2`：市场借币默认为`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	类型 `2`：市场借币
ccy	String	借贷币种，如 `BTC`
instId	String	产品ID，如 `BTC-USDT-SWAP` 仅适用于`市场借币`
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`：开仓自动划转
type	String	是	业务线类型 `MARGIN`：币币杠杆 `CONTRACTS`：合约

返回结果

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

返回参数

参数名	类型	描述
isoMode	String	逐仓保证金划转模式 `automatic`：开仓自动划转

查看账户最大可转余额

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

限速：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	借/还币的数量

获取一键借币还币历史

获取最多3个月内的记录

限速：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	借/还币时间

获取借币利率与限额

限速：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	否	借币类型 `2`：市场借币默认为`2`
ccy	String	否	借贷币种，如 `BTC`

返回结果

{
    "code": "0",
    "data": [
        {
            "debt": "0.85893159114900247077000000000000",
            "interest": "0.00000000000000000000000000000000",
            "loanAlloc": "",
            "nextDiscountTime": "1729490400000",
            "nextInterestTime": "1729490400000",
            "records": [
                {
                    "availLoan": "",
                    "avgRate": "",
                    "ccy": "BTC",
                    "interest": "0",
                    "loanQuota": "175.00000000",
                    "posLoan": "",
                    "rate": "0.0000276",
                    "surplusLmt": "175.00000000",
                    "surplusLmtDetails": {},
                    "usedLmt": "0.00000000",
                    "usedLoan": ""
                }
            ]
        }
    ],
    "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	Object	母子账户剩余可借额度详情，母子账户剩余可借额度的值取该数组中的最小值，可以用来判断是什么原因导致可借额度不足仅适用于`尊享借币`
>> allAcctRemainingQuota	String	母子账户剩余额度
>> curAcctRemainingQuota	String	当前账户剩余额度仅适用于为子账户分配限额的场景
>> platRemainingQuota	String	平台剩余额度，当平台剩余额度大于`curAcctRemainingQuota`或者`allAcctRemainingQuota`时，会显示大于某个值，如">1000"
> usedLmt	String	母子账户已借额度如果已配置可用额度，该字段代表当前交易账户的已借额度
> interest	String	已计未扣利息仅适用于`市场借币`
> posLoan	String	当前账户负债占用（锁定额度内）仅适用于`尊享借币`
> availLoan	String	当前账户剩余可用（锁定额度内）仅适用于`尊享借币`
> usedLoan	String	当前账户已借额度仅适用于`尊享借币`
> avgRate	String	币种已借平均(小时)利率，仅适用于`尊享借币`

获取固定借币限额

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/account/fixed-loan/borrowing-limit

请求示例

GET /api/v5/account/fixed-loan/borrowing-limit

请求参数

无

返回结果

{
    "code": "0",
    "data": [
        {
            "availRepay": "1110.9884",
            "borrowed": "60895.1139",
            "details": [
                {
                    "availBorrow": "0.0566",
                    "borrowed": "0",
                    "ccy": "BTC",
                    "minBorrow": "0.1433",
                    "used": "0",
                    "term": "30D"
                },
                {
                    "availBorrow": "0",
                    "borrowed": "0",
                    "ccy": "LTC",
                    "minBorrow": "114.582",
                    "used": "0",
                    "term": "30D"
                },
                {
                    "availBorrow": "10",
                    "borrowed": "0",
                    "ccy": "ETH",
                    "minBorrow": "2.6666",
                    "used": "0",
                    "term": "30D"
                },
                {
                    "availBorrow": "248727.5",
                    "borrowed": "61115",
                    "ccy": "USDT",
                    "minBorrow": "9999.5679",
                    "used": "60000",
                    "term": "30D"
                }
            ],
            "totalAvailBorrow": "289336.6564",
            "totalBorrowLmt": "22843016.1921",
            "ts": "1716368077071",
            "used": "59784.1256"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
totalBorrowLmt	String	（母子账户）借币限额
totalAvailBorrow	String	（母子账户）剩余可借
borrowed	String	（当前账户）已借
used	String	（当前账户）已使用额度
availRepay	String	（当前账户）可还额度
details	Array of object	币种维度借币信息
> ccy	String	币种，如 `BTC`
> used	String	当前币种已使用额度
> borrowed	String	当前币种已借
> availBorrow	String	当前币种剩余可借
> minBorrow	String	当前币种最小借币数量
> term	String	借贷期限如 `30D`：30天
ts	String	数据返回时间，Unix时间戳的毫秒数格式，如 `1597026383085`

获取固定借币询价

限速：2次/s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/account/fixed-loan/borrowing-quote

请求示例

# 新订单询价
GET /api/v5/account/fixed-loan/borrowing-quote?type=normal&ccy=BTC&maxRate=0.1&amt=0.1&term=30D

# 续借询价
GET /api/v5/account/fixed-loan/borrowing-quote?type=reborrow&ordId=2405162053378222

请求参数

参数	类型	是否必须	描述
type	String	是	类型 `normal`：普通 `reborrow`：续借
ccy	String	可选	币种，如 `BTC` 当`type`=`normal`，该字段必填。
amt	String	可选	借币数量当`type`=`normal`，该字段必填。
maxRate	String	可选	借币年利率，小数形式，如 `0.01` 代表 `1%`。当`type`=`normal`，该字段必填。
term	String	可选	借贷期限 `30D`：30天当`type`=`normal`，该字段必填。
ordId	String	可选	订单ID 当`type`=`reborrow`，该字段必填。

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "BTC",
            "estAvailBorrow": "0.0215",
            "estInterest": "0.00017716",
            "estRate": "0.1",
            "penaltyInterest": "",
            "term": "30D",
            "ts": "1714963101596"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	币种，如 `BTC`
term	String	借贷期限 `30D`：30天
estAvailBorrow	String	预估可借
estRate	String	预估可借年利率
estInterest	String	预估利息
penaltyInterest	String	罚息适用于`type`=`reborrow`
ts	String	数据返回时间，Unix时间戳的毫秒数格式，如 `1597026383085`

固定借币下单

对于新的借币订单，属于IOC(立即成交并取消剩余)类型。对于续借订单，属于FOK(全部成交或立即取消)类型。
订单簿信息可以参考获取借贷量。

限速：2次/s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/account/fixed-loan/borrowing-order

请求示例

POST /api/v5/account/fixed-loan/borrowing-order
body
{
    "ccy": "BTC",
    "amt": "0.1",
    "maxRate": "0.01",
    "term": "30D",
    "reborrow": true,
    "reborrowRate": "0.01"
}

请求参数

参数	类型	是否必须	描述
ccy	String	是	币种，如 `BTC`
amt	String	是	借币数量
maxRate	String	是	借币年利率，小数形式，如 `0.01` 代表 `1%`。
term	String	是	借贷期限
reborrow	Boolean	否	是否到期自动续借默认为`false`
reborrowRate	String	否	自动续借利率, 小数形式，如 `0.01` 代表 `1%`。如果`reborrow`为`true`，该字段必填。

返回结果

{
    "code": "0",
    "data": [
        {
            "ordId":"2405162053378222"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ordId	String	订单ID

修改固定借币订单

限速：2次/s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/account/fixed-loan/amend-borrowing-order

请求示例

POST /api/v5/account/fixed-loan/amend-borrowing-order
body
{
    "ordId": "2405162053378222",
    "reborrow": true,
    "renewMaxRate": "0.01"
}

请求参数

参数	类型	是否必须	描述
ordId	String	是	借币订单ID
reborrow	Boolean	否	是否到期自动续借默认为`false`
renewMaxRate	String	否	自动续借年利率, 小数形式，如 `0.01` 代表 `1%`。如果`reborrow`为`true`，该字段必填。

返回结果

{
    "code": "0",
    "data": [
        {
            "ordId":"2405162053378222"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ordId	String	借币订单ID

固定借币手动续借

限速：2次/s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/account/fixed-loan/manual-reborrow

请求示例

POST /api/v5/account/fixed-loan/manual-reborrow
body
{
    "ordId": "2405162053378222",
    "maxRate": "0.01"
}

请求参数

参数	类型	是否必须	描述
ordId	String	是	借币订单ID
maxRate	String	是	手动续借可接受最大年利率, 小数形式，如 `0.01` 代表 `1%`。

返回结果

{
    "code": "0",
    "data": [
        {
            "ordId":"2405162053378222"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ordId	String	订单ID

固定借币手动还币

限速：2次/s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/account/fixed-loan/repay-borrowing-order

请求示例

POST /api/v5/account/fixed-loan/repay-borrowing-order
body
{
    "ordId": "2405162053378222"
}

请求参数

参数	类型	是否必须	描述
ordId	String	是	借币订单ID

返回结果

{
    "code": "0",
    "data": [
        {
            "ordId":"2405162053378222"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ordId	String	订单ID

固定借币转市场借币

限速：2次/s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/account/fixed-loan/convert-to-market-loan

请求示例

POST /api/v5/account/fixed-loan/convert-to-market-loan
body
{
    "ordId": "2409141848234868"
}

请求参数

参数	类型	是否必须	描述
ordId	String	是	借币订单ID

返回结果

{
    "code": "0",
    "data": [
        {
            "ordId":"2409141848234868"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ordId	String	借币订单ID

固定借币减少负债

提供为订单“设置待还币状态/取消待还币状态”功能。

设置待还币状态

• 当订单将变为待还币状态，同时币种的借还币顺序将变更为：还币顺序为先还固定借币，其次为市场化借币。新增负债占用借币限额的顺序为先占用市场化借币额度，其次为固定借币。

• 成功还币后，上述的借还币顺序将恢复为：还币顺序市场化借币优先。新增负债占用顺序固定借币优先。

• 当多个订单处于待还币状态时，系统将优先处理到期日最早的订单。如果到期日相同，则优先处理利率最高的订单。如果利率也相同，则优先处理金额最大的订单。一旦您还清所有订单或取消还币，优先级将恢复为默认状态。

• 您可以通过杠杆平仓、向交易账户转入借币币种来降低负债。若负债降低数量大于或等于当前订单借币数量，将自动还币。

• 已经处于待还币状态的订单无法手动还币，如果需要手动还币需要取消待还币状态。

限速：2次/s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/account/fixed-loan/reduce-liabilities

请求示例

POST /api/v5/account/fixed-loan/reduce-liabilities
body
{    
    "ordId": "2409141802194350",
    "pendingRepay": true
}

请求参数

参数	类型	是否必须	描述
ordId	String	是	借币订单ID
pendingRepay	String	是	`true`：设置订单为待还币状态 `false`：取消订单待还币状态

返回结果

{
    "code": "0",
    "data": [
        {
            "ordId": "2409141802194350",
            "pendingRepay": true
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ordId	String	借币订单ID
pendingRepay	String	`true`：设置订单为待还币状态 `false`：取消订单待还币状态

获取固定借币订单信息

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/account/fixed-loan/borrowing-orders-list

请求示例

GET /api/v5/account/fixed-loan/borrowing-orders-list

请求参数

参数	类型	是否必须	描述
ordId	String	否	订单ID
ccy	String	否	币种，如 `BTC`
state	String	否	状态 `1`：借币中 `2`：借币成功 `3`：已还币 `4`：申请失败 `5`：已逾期 `6`：还币中 `7`：续借中 `8`：待还币 (详情参考固定借币减少负债)
term	String	否	借贷期限如 `30D`：30天
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的`ordId`
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的`ordId`
limit	String	否	返回结果的数量，最大为`100`，默认`100`条

返回结果

{
    "code": "0",
    "data": [
        {
            "accruedInterest": "0.0065753424657534",
            "actualBorrowAmt": "0",
            "cTime": "1720701491000",
            "ccy": "ETH",
            "curRate": "0",
            "deadlinePenaltyInterest": "1723271891000",
            "earlyRepayPenaltyInterest": "",
            "expiryTime": "1723293491000",
            "failedReason": "1",
            "forceRepayTime": "1725885491000",
            "ordId": "2407112038109533",
            "overduePenaltyInterest": "",
            "potentialPenaltyInterest": "",
            "reborrow": false,
            "reborrowRate": "",
            "reqBorrowAmt": "8",
            "settleReason": "",
            "state": "4",
            "term": "30D",
            "uTime": "1720701490000"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	币种，如 `BTC`
ordId	String	订单ID
term	String	借贷期限如 `30D`: 30天
state	String	状态 `1`：借币中 `2`：借币成功 `3`：已还币 `4`：申请失败 `5`：已逾期 `6`：还币中 `7`：续借中 `8`：待还币 (详情参考固定借币减少负债)
failedReason	String	借币失败原因 `1`：当前没有匹配订单 `2`：无法支付预付利息 `-1`：其他原因
settleReason	String	订单结束原因 `1`：订单到期 `2`：提前展期（续借） `3`：提前释放额度
curRate	String	当前订单的借币年利率
accruedInterest	String	应计利息
reqBorrowAmt	String	原始借币数量
actualBorrowAmt	String	实际借币数量
reborrow	Boolean	是否自动续借 `true`：自动续借 `false`：非自动续借
reborrowRate	String	自动续借利率，小时形式，如 `0.01`代表`1%`
expiryTime	String	到期时间，Unix时间戳的毫秒数格式，如 `1597026383085`
forceRepayTime	String	强制还币时间，Unix时间戳的毫秒数格式，如 `1597026383085`
deadlinePenaltyInterest	String	罚息截止时间（在此时间之后提前还币将不会产生罚息），Unix时间戳的毫秒数格式，如 `1597026383085`
potentialPenaltyInterest	String	提前还币带来的潜在罚息
overduePenaltyInterest	String	逾期利息
earlyRepayPenaltyInterest	String	提前还币产生的实际罚息
cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`

手动借/还币

仅适用于现货模式已开通借币的情况。

限速：1次/s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/account/spot-manual-borrow-repay

请求示例

POST /api/v5/account/spot-manual-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.spot_manual_borrow_repay(ccy="USDT", side="borrow", amt= "1")
print(result)

请求参数

参数名	类型	是否必须	描述
ccy	String	是	币种，如 `BTC`
side	String	是	方向 `borrow`：借币 `repay`：还币
amt	String	是	数量

返回结果

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

返回参数

参数名	类型	描述
ccy	String	币种，如 `BTC`
side	String	方向 `borrow`：借币 `repay`：还币
amt	String	实际数量

设置自动还币

仅适用于现货模式已开通借币的情况。

限速：5次/2s

限速规则：UserID

权限：交易

HTTP请求

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

请求示例

POST /api/v5/account/set-auto-repay
body
{
    "autoRepay": true
}

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_auto_repay(autoRepay=True)
print(result)

请求参数

参数名	类型	是否必须	描述
autoRepay	Boolean	是	是否支持`现货模式`下自动还币 `true`：支持 `false`：不支持

返回结果

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

返回参数

参数名	类型	描述
autoRepay	Boolean	是否支持`现货模式`下自动还币 `true`：支持 `false`：不支持

获取借/还币历史

获取现货模式下的借/还币历史。

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

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

请求示例

GET /api/v5/account/spot-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.spot_borrow_repay_history(ccy="USDT", type="auto_borrow")
print(result)

请求参数

参数名	类型	是否必须	描述
ccy	String	否	币种，如 `BTC`
type	String	否	事件类型 `auto_borrow`：自动借币 `auto_repay`：自动还币 `manual_borrow`：手动借币 `manual_repay`：手动还币
after	String	否	请求发生时间`ts`之前（包含）的分页内容，Unix时间戳的毫秒数格式，如 `1597026383085`
before	String	否	请求发生时间`ts`之后（包含）的分页内容，Unix时间戳的毫秒数格式，如 `1597026383085`
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "accBorrowed": "0",
            "amt": "6764.802661157592",
            "ccy": "USDT",
            "ts": "1725330976644",
            "type": "auto_repay"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	币种，如 `BTC`
type	String	事件类型 `auto_borrow`：自动借币 `auto_repay`：自动还币 `manual_borrow`：手动借币 `manual_repay`：手动还币
amt	String	数量
accBorrowed	String	累计借币数量
ts	String	事件发生时间，Unix时间戳的毫秒数格式，如 `1597026383085`

仓位创建器

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

限速：2次/2s

限速规则：UserID

权限：读取

HTTP请求

POST /api/v5/account/position-builder

请求示例

# 真实与虚拟的仓位与资产一起计算
POST /api/v5/account/position-builder
body
{
    "inclRealPosAndEq": false,
    "simPos":[
         {
            "pos":"-10",
            "instId":"BTC-USDT-SWAP"
         },
         {
            "pos":"10",
            "instId":"LTC-USDT-SWAP"
         }
    ],
    "simAsset":[
        {
            "ccy": "USDT",
            "amt": "100"
        }
    ],
    "spotOffsetType":"1",
    "greeksType":"CASH"
}


# 只计算已有真实仓位
POST /api/v5/account/position-builder
body
{
   "inclRealPosAndEq": true
}


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

import okx.Account as Account

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading:0 , demo trading:1

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

result = accountAPI.position_builder(
    inclRealPosAndEq=True,
    simPos=[
        {
            "pos": "10",
            "instId": "BTC-USDT-SWAP"
        },
        {
            "pos": "10",
            "instId": "LTC-USDT-SWAP"
        }
    ]
)
print(result)

请求参数

参数名	类型	是否必须	描述
inclRealPosAndEq	Boolean	否	是否代入已有仓位和资产默认为`true`
spotOffsetType	String	否	现货对冲模式 `1`：现货对冲模式U模式 `2`：现货对冲模式币模式 `3`：衍生品模式默认是`3`
simPos	Array of object	否	模拟仓位列表
> instId	String	否	交易产品ID，如 `BTC-USDT-SWAP` 适用于 `SWAP`/`FUTURES`/`OPTION`
> pos	String	否	持仓量
simAsset	Array of object	否	模拟资产当`inclRealPosAndEq`为`true`，只考虑真实资产，会忽略虚拟资产
> ccy	String	否	币种，如 `BTC`
> amt	String	否	币种数量可以为负，代表减少币种资产
greeksType	String	否	希腊值类型 `BS`：BS模型 `PA`：币本位 `CASH`：美元现金等价默认是 `BS`

返回结果

{
    "code": "0",
    "data": [
        {
            "assets": [
                {
                    "availEq": "2.92259509161",
                    "borrowImr": "0",
                    "borrowMmr": "0",
                    "ccy": "BTC",
                    "spotInUse": "0"
                },
                {
                    "availEq": "1",
                    "borrowImr": "0",
                    "borrowMmr": "0",
                    "ccy": "ETH",
                    "spotInUse": "0"
                },
                {
                    "availEq": "-76819.72721896428",
                    "borrowImr": "9612.484308105535",
                    "borrowMmr": "1920.4931804741072",
                    "ccy": "USDT",
                    "spotInUse": "0"
                },
                {
                    "availEq": "100.000001978",
                    "borrowImr": "0",
                    "borrowMmr": "0",
                    "ccy": "OKB",
                    "spotInUse": "0"
                },
                {
                    "availEq": "1.1618286584225905",
                    "borrowImr": "0",
                    "borrowMmr": "0",
                    "ccy": "USDC",
                    "spotInUse": "0"
                }
            ],
            "borrowMmr": "1919.9362374517698",
            "derivMmr": "61.63384859899599",
            "eq": "50503.83298678435",
            "marginRatio": "24.513003004865656",
            "riskUnitData": [
                {
                    "delta": "0.010000438961223",
                    "gamma": "0",
                    "imr": "79.93948582424999",
                    "indexUsd": "0.99971",
                    "mmr": "61.49191217249999",
                    "mr1": "61.49191217249999",
                    "mr1FinalResult": {
                        "pnl": "-61.49191217249999",
                        "spotShock": "-0.15",
                        "volShock": "up"
                    },
                    "mr1Scenarios": {
                        "volSame": {
                            "0": "0",
                            "-0.05": "-20.497304057499974",
                            "-0.1": "-40.99460811500002",
                            "0.1": "40.99460811500002",
                            "0.15": "61.49191217249999",
                            "0.05": "20.497304057499974",
                            "-0.15": "-61.49191217249999"
                        },
                        "volShockDown": {
                            "0": "0",
                            "-0.05": "-20.497304057499974",
                            "-0.1": "-40.99460811500002",
                            "0.1": "40.99460811500002",
                            "0.15": "61.49191217249999",
                            "0.05": "20.497304057499974",
                            "-0.15": "-61.49191217249999"
                        },
                        "volShockUp": {
                            "0": "0",
                            "-0.05": "-20.497304057499974",
                            "-0.1": "-40.99460811500002",
                            "0.1": "40.99460811500002",
                            "0.15": "61.49191217249999",
                            "0.05": "20.497304057499974",
                            "-0.15": "-61.49191217249999"
                        }
                    },
                    "mr2": "0",
                    "mr3": "0",
                    "mr4": "0",
                    "mr5": "0",
                    "mr6": "61.49191217249999",
                    "mr6FinalResult": {
                        "pnl": "-122.98382434499997",
                        "spotShock": "-0.3"
                    },
                    "mr7": "1.8448113495150003",
                    "portfolios": [
                        {
                            "amt": "10",
                            "delta": "0.010000438961223",
                            "gamma": "0",
                            "instId": "BTC-USDT-SWAP",
                            "instType": "SWAP",
                            "isRealPos": false,
                            "notionalUsd": "409.968",
                            "theta": "0",
                            "vega": "0"
                        }
                    ],
                    "riskUnit": "BTC-USDT",
                    "theta": "0",
                    "vega": "0"
                },
                {
                    "delta": "0.009998760367833",
                    "gamma": "0",
                    "imr": "0.1845173544448",
                    "indexUsd": "0.99971",
                    "mmr": "0.141936426496",
                    "mr1": "0.141936426496",
                    "mr1FinalResult": {
                        "pnl": "-0.141936426496",
                        "spotShock": "-0.2",
                        "volShock": "up"
                    },
                    "mr1Scenarios": {
                        "volSame": {
                            "0": "0",
                            "-0.07": "-0.0496777492736",
                            "-0.2": "-0.141936426496",
                            "0.07": "0.0496777492736",
                            "0.2": "0.141936426496",
                            "0.14": "0.0993554985472",
                            "-0.14": "-0.0993554985472"
                        },
                        "volShockDown": {
                            "0": "0",
                            "-0.07": "-0.0496777492736",
                            "-0.2": "-0.141936426496",
                            "0.07": "0.0496777492736",
                            "0.2": "0.141936426496",
                            "0.14": "0.0993554985472",
                            "-0.14": "-0.0993554985472"
                        },
                        "volShockUp": {
                            "0": "0",
                            "-0.07": "-0.0496777492736",
                            "-0.2": "-0.141936426496",
                            "0.07": "0.0496777492736",
                            "0.2": "0.141936426496",
                            "0.14": "0.0993554985472",
                            "-0.14": "-0.0993554985472"
                        }
                    },
                    "mr2": "0",
                    "mr3": "0",
                    "mr4": "0",
                    "mr5": "0",
                    "mr6": "0.141936426496",
                    "mr6FinalResult": {
                        "pnl": "-0.283872852992",
                        "spotShock": "-0.4"
                    },
                    "mr7": "0.004967159106",
                    "portfolios": [
                        {
                            "amt": "10",
                            "delta": "0.009998760367833",
                            "gamma": "0",
                            "instId": "LTC-USDT-SWAP",
                            "instType": "SWAP",
                            "isRealPos": false,
                            "notionalUsd": "0.7098000000000001",
                            "theta": "0",
                            "vega": "0"
                        }
                    ],
                    "riskUnit": "LTC-USDT",
                    "theta": "0",
                    "vega": "0"
                }
            ],
            "totalImr": "9689.820690834878",
            "totalMmr": "1981.5700860507657",
            "ts": "1705915813386"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
eq	String	账户有效保证金
totalMmr	String	账户维持保证金，单位为`USD`
totalImr	String	账户初始保证金占用，单位为`USD`
borrowMmr	String	账户借币维持保证金，单位为`USD`
derivMmr	String	账户衍生品维持保证金，单位为`USD`
marginRatio	String	账户全仓保证金率
ts	String	账户信息的更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
assets	Array of object	资产信息
> ccy	String	币种，如 `BTC`
> availEq	String	币种权益
> spotInUse	String	现货对冲占用
> borrowMmr	String	借币维持保证金，单位为`USD`
> borrowImr	String	借币初始保证金，单位为`USD`
riskUnitData	Array of object	Risk unit 相关信息
> riskUnit	String	账户内的 risk unit，如 `BTC-USDT`
> indexUsd	String	Risk unit 指数对应的美元价值
> mmr	String	Risk unit 维度的维持保证金，单位为`USD`
> imr	String	Risk unit 维度的初始保证金，单位为`USD`
> mr1	String	现货和波动率变化风险 (适用于所有衍生品，以及在现货对冲模式下的现货)
> mr2	String	时间价值风险 (仅适用于期权)
> mr3	String	波动率跨期风险 (仅适用于期权)
> mr4	String	基差风险 (适用于所有衍生品)
> mr5	String	利率风险 (仅适用于期权)
> mr6	String	极端市场波动风险 (适用于所有衍生品，以及在现货对冲模式下的现货)
> mr7	String	减仓成本 (适用于所有衍生品)
> mr1Scenarios	Object	MR1 的压力测试场景分析
>> volShockDown	Object	波动率向下时，不同价格波动比率下的压力测试盈亏值为 {`change`: `value`, ...} `change`：价格波动比率（百分比），如 `0.01` 代表 `1%` `value`：压力测试下的盈亏，单位为`USD` 如 {"-0.15":"-2333.23", ...}
>> volSame	Object	波动率不变时，不同价格波动比率下的压力测试盈亏值为 {`change`: `value`, ...} `change`：价格波动比率（百分比），如 `0.01` 代表 `1%` `value`：压力测试下的盈亏，单位为`USD` 如 {"-0.15":"-2333.23", ...}
>> volShockUp	Object	波动率向上时，不同价格波动比率下的压力测试盈亏值为 {`change`: `value`, ...} `change`：价格波动比率（百分比），如 `0.01` 代表 `1%` `value`：压力测试下的盈亏，单位为`USD` 如 {"-0.15":"-2333.23", ...}
> mr1FinalResult	Object	MR1 最大亏损场景
>> pnl	String	MR1 最大亏损压测盈亏，单位为 `USD`
>> spotShock	String	MR1 最大亏损的价格波动（百分比），如 `0.01` 代表 `1%`
>> volShock	String	MR1 最大亏损波动率趋势 `down`：波动率向下 `unchange`：波动率不变 `up`：波动率向上
> mr6FinalResult	String	MR6 最大亏损场景
>> pnl	String	MR6 最大亏损压测盈亏，单位为 `USD`
>> spotShock	String	MR6 最大亏损的价格波动（百分比），如 `0.01` 代表 `1%`
> delta	String	(Risk unit 维度) 合约价格随标的价格变动的比例当标的价格变动 x 时，合约价格变动约为此 Delta 数值乘以 x
> gamma	String	(Risk unit 维度) 标的价格对 Delta 值的影响程度当标的价格变动 x% 时，期权 Delta 值的变动约为此 Gamma 数值乘以 x%
> theta	String	(Risk unit 维度) 距离到期日时间缩短 1 天，该合约价格的变化量
> vega	String	(Risk unit 维度) 标的波动率增加 1%，该合约价格的变化量
> portfolios	Array of object	资产组合
>> instId	String	产品ID，如 `BTC-USDT-SWAP`
>> instType	String	产品类型 `SPOT`：现货 `SWAP`：永续合约 `FUTURES`：交割合约 `OPTION`：期权
>> amt	String	`instType`为`SPOT`，代表现货对冲占用 `instType`为`SWAP`/`FUTURES`/`OPTION`，代表仓位数量。
>> notionalUsd	String	美金价值
>> delta	String	`instType`为`SPOT`，代表资产数量。 `instType`为`SWAP`/`FUTURES`/`OPTION`，代表(产品层面) 合约价格随标的价格变动的比例。
>> gamma	String	(产品层面) 标的价格对 Delta 值的影响程度 `instType`为`SPOT`，返回""
>> theta	String	(产品层面) 距离到期日时间缩短 1 天，该合约价格的变化量 `instType`为`SPOT`，返回""
>> vega	String	(产品层面) 标的波动率增加 1%，该合约价格的变化量 `instType`为`SPOT`，返回""
>> isRealPos	Boolean	是否为真实仓位 `instType`为`SWAP`/`FUTURES`/`OPTION`，该字段有效，其他都默认返回`false`

设置现货对冲占用

用户自定义现货对冲占用数量，不代表实际现货对冲占用数量。仅适用于组合保证金模式。

限速：10次/2s

限速规则：UserID

权限：交易

HTTP请求

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

请求示例

# 设置现货对冲占用
POST /api/v5/account/set-riskOffset-amt
{
   "ccy": "BTC",
   "clSpotInUseAmt": "0.5"
}

请求参数

参数名	类型	是否必须	描述
ccy	String	是	币种，如BTC
clSpotInUseAmt	String	是	用户自定义现货对冲数量

返回示例

{
   "code": "0",
   "msg": "",
   "data": [
      {
         "ccy": "BTC",
         "clSpotInUseAmt": "0.5"
      }
   ]
}

返回参数

参数名	类型	描述
ccy	String	币种，如BTC
clSpotInUseAmt	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`之间半角逗号分隔适用于`交割/永续/期权` `uly`与`instFamily`必须传一个,若传两个，以`instFamily`为主
instFamily	String	可选	交易品种，如 `BTC-USDT`，支持多个查询（不超过5个），`instFamily`之间半角逗号分隔适用于`交割/永续/期权` `uly`与`instFamily`必须传一个,若传两个，以`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`：衍生品对冲 `4`：现货对冲(USDC)

返回结果

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

返回参数

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

开通期权交易

限速：5次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/account/activate-option

请求示例

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	是否自动借币

预设置账户模式切换

预设置账户模式切换的必要信息，若由现货和合约模式/跨币种保证金模式切换到组合保证金模式，则可选预设置riskOffsetType；若由组合保证金模式切换到现货和合约模式/跨币种保证金模式，且存在全仓交割、永续仓位，则必须预设置lever，令所有仓位具有相同杠杆倍数。

若用户未按照规定进行设置，在预检查或设置账户模式时将接收到报错或提示信息。

限速：5次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/account/account-level-switch-preset

请求示例

# 1. 现货和合约模式 -> 跨币种
POST /api/v5/account/account-level-switch-preset
{
    "acctLv": "3"
}

# 2. 现货和合约模式/跨币种 -> 组合保证金
POST /api/v5/account/account-level-switch-preset
{
    "acctLv": "4",
    "riskOffsetType": "1"
}

# 3. 跨币种 -> 现货和合约模式
POST /api/v5/account/account-level-switch-preset
{
    "acctLv": "2"
}

# 4. 组合保证金 -> 现货和合约模式/跨币种，且有全仓合约仓位，则必须传入lever
POST /api/v5/account/account-level-switch-preset
{
    "acctLv": "2",
    "lever": "10"
}

# 5. 组合保证金 -> 现货和合约模式/跨币种，没有全仓合约仓位，则不需传入lever，不进行校验
POST /api/v5/account/account-level-switch-preset
{
    "acctLv": "3"
}

请求参数

参数名	类型	是否必须	描述
acctLv	String	是	账户模式 `2`: 现货和合约模式 `3`: 跨币种保证金模式 `4`: 组合保证金模式
lever	String	可选	在`组合保证金模式`向`现货和合约模式/跨币种保证金模式`切换，且用户有全仓仓位时，必须传入
riskOffsetType	String	可选	风险对冲模式 `1`：现货对冲(USDT) `2`：现货对冲(币) `3`：衍生品对冲（未开启现货对冲） `4`：现货对冲(USDC) 适用于`现货和合约模式/跨币种保证金模式`向`组合保证金模式`切换

返回结果 1. 现货和合约模式 -> 跨币种

{
    "acctLv": "3",
    "curAcctLv": "2",
    "lever": "",
    "riskOffsetType": ""
}

返回结果 2. 现货和合约模式/跨币种 -> 组合保证金

{
    "acctLv": "4",
    "curAcctLv": "2",
    "lever": "",
    "riskOffsetType": "1"
}

返回结果 3. 跨币种 -> 现货和合约模式

{
    "acctLv": "2",
    "curAcctLv": "3",
    "lever": "",
    "riskOffsetType": ""
}

返回结果 4. 组合保证金 -> 现货和合约模式/跨币种

{
    "acctLv": "2",
    "curAcctLv": "4",
    "lever": "10",
    "riskOffsetType": ""
}

返回结果 5. 组合保证金 -> 现货和合约模式/跨币种，没有全仓合约仓位，则不需传入lever，不进行校验

{
    "acctLv": "3",
    "curAcctLv": "4",
    "lever": "",
    "riskOffsetType": ""
}

返回参数

参数名	类型	描述
curAcctLv	String	当前账户类型
acctLv	String	切换后的账户类型
lever	String	用户预设置的全仓合约仓位杠杆倍数
riskOffsetType	String	用户预设置的风险对冲模式

预检查账户模式切换

获取账户模式切换预检查相关信息

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/account/set-account-switch-precheck

请求示例

GET /api/v5/account/set-account-switch-precheck?acctLv=3

请求参数

参数名	类型	是否必须	描述
acctLv	String	是	账户模式 `1`: 现货模式 `2`: 现货和合约模式 `3`: 跨币种保证金模式 `4`: 组合保证金模式

返回结果: 现货和合约模式->跨币种，需要现在网页或移动端完成答题

{
    "code": "51070",
    "data": [],
    "msg": "您当前尚未达到升级至该账户模式的要求，请先在官方网站或APP完成账户模式的升级。"
}

返回结果: 现货和合约模式->跨币种，有不兼容信息。sCode 1

{
    "code": "0",
    "data": [
        {
            "acctLv": "3",
            "curAcctLv": "1",
            "mgnAft": null,
            "mgnBf": null,
            "posList": [],
            "posTierCheck": [],
            "riskOffsetType": "",
            "sCode": "1",
            "unmatchedInfoCheck": [
                {
                    "posList": [],
                    "totalAsset": "",
                    "type": "repay_borrowings"
                }
            ]
        }
    ],
    "msg": ""
}

返回结果: 组合保证金->跨币种，未进行杠杆设置，展示用户全部合约全仓仓位。sCode 3

{
    "code": "0",
    "data": [
        {
            "acctLv": "3",
            "curAcctLv": "4",
            "mgnAft": null,
            "mgnBf": null,
            "posList": [
                {
                    "lever": "50",
                    "posId": "2005456500916518912"
                },
                {
                    "lever": "10",
                    "posId": "2005456108363218944"
                },
                {
                    "lever": "100",
                    "posId": "2005456332909477888"
                },
                {
                    "lever": "1",
                    "posId": "2005456415990251520"
                }
            ],
            "posTierCheck": [],
            "riskOffsetType": "",
            "sCode": "3",
            "unmatchedInfoCheck": []
        }
    ],
    "msg": ""
}

返回结果: 组合保证金->跨币种，已进行杠杆设置，将全部杠杆倍数设置为50，通过梯度档位及保证金校验。sCode 0

{
    "code": "0",
    "data": [
        {
            "acctLv": "3",
            "curAcctLv": "4",
            "mgnAft": {
                "acctAvailEq": "106002.2061970689",
                "details": [],
                "mgnRatio": "148.1652396878421"
            },
            "mgnBf": {
                "acctAvailEq": "77308.89735228613",
                "details": [],
                "mgnRatio": "4.460069474634038"
            },
            "posList": [
                {
                    "lever": "50",
                    "posId": "2005456500916518912"
                },
                {
                    "lever": "50",
                    "posId": "2005456108363218944"
                },
                {
                    "lever": "50",
                    "posId": "2005456332909477888"
                },
                {
                    "lever": "50",
                    "posId": "2005456415990251520"
                }
            ],
            "posTierCheck": [],
            "riskOffsetType": "",
            "sCode": "0",
            "unmatchedInfoCheck": []
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
sCode	String	校验码 `0`：通过所有验证 `1`：有不兼容信息 `3`：未进行杠杆设置 `4`：梯度档位或保证金校验未通过
curAcctLv	String	当前账户模式 `1`: 现货模式 `2`: 现货和合约模式 `3`: 跨币种保证金模式 `4`: 组合保证金模式所有情况下均返回
acctLv	String	新账户模式 `1`: 现货模式 `2`: 现货和合约模式 `3`: 跨币种保证金模式 `4`: 组合保证金模式所有情况下均返回
riskOffsetType	String	风险对冲模式 `1`：现货对冲(USDT) `2`：现货对冲(币) `3`：衍生品对冲 `4`：现货对冲(USDC) acctLv为`4`时返回，其余情况下返回"" 若用户有设置，则为用户的设置值；若没有设置，则为默认值
unmatchedInfoCheck	Array of objects	包含不匹配信息对象的列表仅在sCode为`1`，有不兼容信息时返回，其他情况返回[]
>> type	String	不匹配信息类型 `asset_validation`：资产校验 `pending_orders`：撮合挂单 `pending_algos`：策略挂单，冰山、时间加权、定投等 `isolated_margin`：杠杆逐仓一键借币及自主划转 `isolated_contract`：合约逐仓自主划转 `contract_long_short`：合约开平模式 `cross_margin`：杠杆全仓开仓划转 `cross_option_buyer`：期权全仓买方 `isolated_option`：期权逐仓（仅适用于简单账户） `growth_fund`：体验金仓位 `all_positions`：所有仓位 `spot_lead_copy_only_simple_single`：带单和自定义跟单员只能使用现货或现货和合约模式 `stop_spot_custom`：停止现货自定义跟单 `stop_futures_custom`：停止合约自定义跟单 `lead_portfolio`：身为带单员，您不能切换到组合保证金账户模式 `futures_smart_sync`：您存在合约智能跟单，无法切换到现货模式 `vip_fixed_loan`：存在尊享借币 `repay_borrowings`：存在借币 `compliance_restriction`：合规，无法使用保证金交易相关服务 `compliance_kyc2`：合规，无法使用保证金交易相关服务，如果您不是该地区居民，请进行KYC2身份认证
>> totalAsset	String	总资产仅在type为`asset_validation`时返回，其他情况都为""
>> posList	Array of string	不匹配仓位列表，返回持仓ID 在type为仓位相关枚举值时返回，其他情况都为[]
posList	Array of objects	合约全仓仓位列表适用于curAcctLv为`4`，acctLv为`2/3`，且用户具有全仓合约仓位的情况在sCode为`0/3/4`的情况下返回
> posId	String	持仓ID
> lever	String	切换后的全仓仓位杠杆倍数
posTierCheck	Array of objects	未满足梯度档位校验全仓仓位的列表仅在sCode为`4`时返回
> instFamily	String	交易品种
> instType	String	产品类型 `SWAP`：永续合约 `FUTURES`：交割合约 `OPTION`：期权
> pos	String	持仓量
> lever	String	杠杆倍数
> maxSz	String	若acctLv为`2/3`，目标账户模式为单币种、跨币种，则为当前杠杆倍数下的最大持仓张数；若acctLv为`4`，目标账户模式为组合保证金，则为PM全仓最大持仓量上限
mgnBf	Object	切换账户模式前的保证金相关信息在sCode为`0/4`时返回，其他时候为null
> acctAvailEq	String	美金层面可用保证金在curAcctLv为`3/4`时返回，其他情况返回""
> mgnRatio	String	美金层面保证金率在curAcctLv为`3/4`时返回，其他情况返回""
> details	Array of objects	各币种资产详细信息仅在curAcctLv为`2`时返回，其他情况返回[]
>> ccy	String	币种
>> availEq	String	币种维度可用保证金
>> mgnRatio	String	币种维度全仓保证金率
mgnAft	Object	切换账户模式后的保证金相关信息在sCode为`0/4`时返回，其他时候为null
> acctAvailEq	String	美金层面可用保证金在acctLv为`3/4`时返回，其他情况返回""
> mgnRatio	String	美金层面保证金率在acctLv为`3/4`时返回，其他情况返回""
> details	Array of objects	各币种资产详细信息仅在acctLv为`2`时返回，其他情况返回""
>> ccy	String	币种
>> availEq	String	币种维度可用保证金
>> mgnRatio	String	币种维度全仓保证金率

设置账户模式

账户模式的首次设置，需要在网页或手机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 权限。

限速：5次/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": "1000",
      "qtyLimit": "10",
      "timeInterval": "5000"
    }
  ],
  "msg": ""
}

返回参数

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

WebSocket

账户频道

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

该频道的并发连接受到如下规则限制：WebSocket 连接限制

服务地址

/ws/v5/private (需要登录)

请求示例：单个

{
    "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",
        "uid": "44*********584"
    },
    "data": [{
        "adjEq": "55444.12216906034",
        "borrowFroz": "0",
        "details": [{
            "availBal": "4734.371190691436",
            "availEq": "4734.371190691435",
            "borrowFroz": "0",
            "cashBal": "4750.426970691436",
            "ccy": "USDT",
            "coinUsdPrice": "0.99927",
            "crossLiab": "0",
            "disEq": "4889.379316336831",
            "eq": "4892.951170691435",
            "eqUsd": "4889.379316336831",
            "smtSyncEq": "0",
            "spotCopyTradingEq": "0",
            "fixedBal": "0",
            "frozenBal": "158.57998",
            "imr": "",
            "interest": "0",
            "isoEq": "0",
            "isoLiab": "0",
            "isoUpl": "0",
            "liab": "0",
            "maxLoan": "0",
            "mgnRatio": "",
            "mmr": "",
            "notionalLever": "",
            "ordFrozen": "0",
            "rewardBal": "0",
            "spotInUseAmt": "",
            "clSpotInUseAmt": "",
            "maxSpotInUseAmt": "",          
            "spotIsoBal": "0",
            "stgyEq": "150",
            "twap": "0",
            "uTime": "1705564213903",
            "upl": "-7.475800000000003",
            "uplLiab": "0",
            "spotBal": "",
            "openAvgPx": "",
            "accAvgPx": "",
            "spotUpl": "",
            "spotUplRatio": "",
            "totalPnl": "",
            "totalPnlRatio": ""
        }],
        "imr": "8.5737166146",
        "isoEq": "0",
        "mgnRatio": "143705.65988369548",
        "mmr": "0.342948664584",
        "notionalUsd": "85.737166146",
        "ordFroz": "0",
        "totalEq": "55868.06403501676",
        "uTime": "1705564223311",
        "upl": "-7.470342666000003"
    }]
}

推送数据参数

参数名	类型	描述
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	以美金价值为单位的持仓数量，即仓位美金价值适用于`现货模式`/`跨币种保证金模式`/`组合保证金模式`
> upl	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	币种逐仓负债额适用于`跨币种保证金模式`/`组合保证金模式`
>> rewardBal	String	体验金余额
>> mgnRatio	String	币种全仓保证金率，衡量账户内某项资产风险的指标适用于`现货和合约模式`且有全仓仓位时
>> imr	String	币种维度全仓占用保证金适用于`现货和合约模式`且有全仓仓位时
>> mmr	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	现货对冲占用数量适用于`组合保证金模式`
>> clSpotInUseAmt	String	用户自定义现货占用数量适用于`组合保证金模式`
>> maxSpotInUseAmt	String	系统计算得到的最大可能现货占用数量适用于`组合保证金模式`
>> smtSyncEq	String	合约智能跟单权益默认为0，仅适用于跟单人。
>> spotCopyTradingEq	String	现货智能跟单权益默认为0，仅适用于跟单人。
>> spotBal	String	现货余额，单位为币种，比如 BTC。详情
>> openAvgPx	String	现货开仓成本价单位 USD。详情
>> accAvgPx	String	现货累计成本价单位 USD。详情
>> spotUpl	String	现货未实现收益，单位 USD。详情
>> spotUplRatio	String	现货未实现收益率。详情
>> totalPnl	String	现货累计收益，单位 USD。详情
>> totalPnlRatio	String	现货累计收益率。详情

持仓频道

获取持仓信息，首次订阅按照订阅维度推送数据，此外，当下单、撤单等事件触发时，推送数据以及按照订阅维度定时推送数据
该频道的并发连接受到如下规则限制：WebSocket 连接限制

服务地址

/ws/v5/private (需要登录)

请求示例：单个

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

请求示例

{
    "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 如果同时传了 instId 和 instFamily，instId 将被使用
> extraParams	String	否	额外配置
>> updateInterval	int	否	`0`: 仅根据持仓事件推送数据 `2000, 3000, 4000`: 根据持仓事件推送，且根据设置的时间间隔定时推送（ms）若不添加该字段或将其设置为上述合法值以外的其他值，数据将根据事件推送并大约每 5 秒定期推送一次。使用该字段需严格遵守以下格式。 "extraParams": " { \"updateInterval\": \"0\" } "

成功返回示例：单个

{
    "event": "subscribe",
    "arg": {
        "channel": "positions",
        "instType": "FUTURES",
        "instFamily": "BTC-USD"
    },
    "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",
            "pendingCloseOrdLiabVal":"0.1",
            "pos":"1",
            "baseBorrowed": "",
            "baseInterest": "",
            "quoteBorrowed": "",
            "quoteInterest": "",
            "posCcy":"",
            "posId":"307173036051017730",
            "posSide":"long",
            "spotInUseAmt": "",
            "clSpotInUseAmt": "",
            "maxSpotInUseAmt": "",
            "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":"",
    "pendingCloseOrdLiabVal":"0.1",
    "pTime":"1619507761462",
    "pos":"1",
    "baseBorrowed": "",
    "baseInterest": "",
    "quoteBorrowed": "",
    "quoteInterest": "",
    "posCcy":"",
    "posId":"307173036051017730",
    "posSide":"long",
    "spotInUseAmt": "",
    "clSpotInUseAmt": "",
    "maxSpotInUseAmt": "",
    "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":"",
    "pendingCloseOrdLiabVal":"0.1",
    "pTime":"1619507761462",
    "pos":"1",
    "baseBorrowed": "",
    "baseInterest": "",
    "quoteBorrowed": "",
    "quoteInterest": "",
    "posCcy":"",
    "posId":"307173036051017730",
    "posSide":"long",
    "spotInUseAmt": "",
    "clSpotInUseAmt": "",
    "maxSpotInUseAmt": "",
    "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-USDT-SWAP`
> 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	期权价值，仅适用于`期权`
> pendingCloseOrdLiabVal	String	逐仓杠杆负债对应平仓挂单的数量
> adl	String	信号区，分为5档，从1到5，数字越小代表adl强度越弱
> bizRefId	String	外部业务id，如体验券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	现货对冲占用数量适用于`组合保证金模式`
> clSpotInUseAmt	String	用户自定义现货占用数量适用于`组合保证金模式`
> maxSpotInUseAmt	String	系统计算得到的最大可能现货占用数量适用于`组合保证金模式`
> spotInUseCcy	String	现货对冲占用币种，如 `BTC` 适用于`组合保证金模式`
> realizedPnl	String	已实现收益仅适用于`交割/永续/期权` realizedPnl=pnl+fee+fundingFee+liqPenalty
> 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`

账户余额和持仓频道

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

该频道适用于尽快获取账户现金余额和仓位资产变化的信息。
该频道的并发连接受到如下规则限制：WebSocket 连接限制

服务地址

/ws/v5/private (需要登录)

请求示例

{
    "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	持仓方向 `long`，`short`，`net`
>> pos	String	持仓数量，逐仓自主划转模式下，转入保证金后会产生pos为`0`的仓位
>> baseBal	String	交易币余额适用于 `币币杠杆`（逐仓一键借币模式）（已弃用）
>> quoteBal	String	计价币余额适用于 `币币杠杆`（逐仓一键借币模式）（已弃用）
>> posCcy	String	持仓数量币种只适用于币币杠杆仓位。当是交割、永续、期权持仓时，该字段返回“”
>> uTime	String	仓位信息的更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> trades	Array	成交数据
>> instId	String	产品ID，如 `BTC-USDT`
>> tradeId	String	最新成交ID

爆仓风险预警推送频道

此推送频道仅作为风险提示，不建议作为策略交易的风险判断。
在行情剧烈波动的情况下，可能会出现此消息推送的同时仓位已经被强平的可能性。
预警会在某一个逐仓仓位有风险时推送。预警会在所有全仓仓位有风险时推送。
该频道的并发连接受到如下规则限制：WebSocket 连接限制

服务地址

/ws/v5/private (需要登录)

请求示例

{
    "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": "ANY"
  },
  "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":[
        {
            "cTime":"1619507758793",
            "ccy":"ETH",
            "instId":"ETH-USD-210430",
            "instType":"FUTURES",
            "lever":"10",
            "markPx":"2353.849",
            "mgnMode":"isolated",
            "mgnRatio":"11.731726509588816",
            "pTime":"1619507761462",
            "pos":"1",
            "posCcy":"",
            "posId":"307173036051017730",
            "posSide":"long",
            "uTime":"1619507761462",
        }
    ]
}

推送数据参数

参数名	类型	描述
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	持仓数量币种，仅适用于`币币杠杆`
> instId	String	产品ID，如 `BTC-USDT-SWAP`
> lever	String	杠杆倍数，不适用于`期权卖方`
> markPx	String	标记价格
> mgnRatio	String	保证金率
> ccy	String	占用保证金的币种
> cTime	String	持仓创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> uTime	String	最近一次持仓更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> pTime	String	持仓信息的推送时间，Unix时间戳的毫秒数格式，如 `1597026383085`

账户greeks频道

获取账户资产的greeks信息，首次订阅按照订阅维度推送数据，此外，当增加或者减少币种余额、持仓数量等事件触发时，推送数据以及按照订阅维度定时推送数据
该频道的并发连接受到如下规则限制：WebSocket 连接限制

服务地址

/ws/v5/private (需要登录)

请求示例：单个

{
    "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",
        "ccy": "BTC",
        "uid": "614488474791936"
    },
    "data": [
        {
            "ccy": "BTC",
            "deltaBS": "1.1246665401944310",
            "deltaPA": "-0.0074076183688949",
            "gammaBS": "0.0000000000000000",
            "gammaPA": "0.0148152367377899",
            "thetaBS": "2.0356991946421226",
            "thetaPA": "-0.0000000200174309",
            "ts": "1729179082006",
            "vegaBS": "0.0000000000000000",
            "vegaPA": "0.0000000000000000"
        }
    ]
}

推送示例

{
    "arg": {
        "channel": "account-greeks",
        "uid": "614488474791936"
    },
    "data": [
        {
            "ccy": "BTC",
            "deltaBS": "1.1246665403011684",
            "deltaPA": "-0.0074021163991037",
            "gammaBS": "0.0000000000000000",
            "gammaPA": "0.0148042327982075",
            "thetaBS": "2.1342098201092528",
            "thetaPA": "-0.0000000200876441",
            "ts": "1729179001692",
            "vegaBS": "0.0000000000000000",
            "vegaPA": "0.0000000000000000"
        },
        {
            "ccy": "ETH",
            "deltaBS": "0.3810670161698570",
            "deltaPA": "-0.0688347042402955",
            "gammaBS": "-0.0000000000230396",
            "gammaPA": "0.1376693483440320",
            "thetaBS": "0.3314776517141782",
            "thetaPA": "0.0000000001316008",
            "ts": "1729179001692",
            "vegaBS": "-0.0000000045069794",
            "vegaPA": "-0.0000000000017267"
        }
    ]
}

推送数据参数

参数名	类型	描述
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-USDT`
tdMode	String	是	交易模式保证金模式：`isolated`：逐仓；`cross`：全仓非保证金模式：`cash`：非保证金 `spot_isolated`：现货逐仓(仅适用于现货带单) ，现货带单时，`tdMode` 的值需要指定为`spot_isolated`
ccy	String	否	保证金币种，仅适用于`现货和合约模式`下的`全仓杠杆`订单
clOrdId	String	否	客户自定义订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
tag	String	否	订单标签字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。
side	String	是	订单方向 `buy`：买， `sell`：卖
posSide	String	可选	持仓方向在开平仓模式下必填，且仅可选择 `long` 或 `short`。仅适用交割、永续。
ordType	String	是	订单类型 `market`：市价单 `limit`：限价单 `post_only`：只做maker单 `fok`：全部成交或立即取消 `ioc`：立即成交并取消剩余 `optimal_limit_ioc`：市价委托立即成交并取消剩余（仅适用交割、永续） `mmp`：做市商保护(仅适用于组合保证金账户模式下的期权订单) `mmp_and_post_only`：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单)
sz	String	是	委托数量
px	String	可选	委托价格，仅适用于`limit`、`post_only`、`fok`、`ioc`、`mmp`、`mmp_and_post_only`类型的订单期权下单时，px/pxUsd/pxVol 只能填一个
pxUsd	String	可选	以USD价格进行期权下单仅适用于期权期权下单时 px/pxUsd/pxVol 必填一个，且只能填一个
pxVol	String	可选	以隐含波动率进行期权下单，例如 1 代表 100% 仅适用于期权期权下单时 px/pxUsd/pxVol 必填一个，且只能填一个
reduceOnly	Boolean	否	是否只减仓，`true` 或 `false`，默认`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	否	自成交保护模式默认为 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时，执行市价止盈
> tpOrdKind	String	否	止盈订单类型 `condition`: 条件单 `limit`: 限价单默认为`condition`
> 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":"",
            "ts":"1695190491421",
            "sCode":"0",
            "sMsg":""
        }
    ],
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

返回参数

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

ordType
订单类型，创建新订单时必须指定，您指定的订单类型将影响需要哪些订单参数和撮合系统如何执行您的订单，以下是有效的ordType：
普通委托：
limit：限价单，要求指定sz 和 px
market：市价单，币币和币币杠杆，是市价委托吃单；交割合约和永续合约，是自动以最高买/最低卖价格委托，遵循限价机制；期权合约不支持市价委托；由于市价委托无法确定成交价格，为确保有足够的资产买入设定数量的交易币种，会多冻结5%的计价币资产
高级委托：
post_only：限价委托，在下单那一刻只做maker，如果该笔订单的任何部分会吃掉当前挂单深度，则该订单将被全部撤销。
fok：限价委托，全部成交或立即取消，如果无法全部成交该笔订单，则该订单将被全部撤销。
ioc：限价委托，立即成交并取消剩余，立即按照委托价格撮合成交，并取消该订单剩余未完成数量，不会在深度列表上展示委托数量。
optimal_limit_ioc：市价委托，立即成交并取消剩余，仅适用于交割合约和永续合约。

reduceOnly
只减仓，下单时，此参数设置为 true 时，表示此笔订单具有减仓属性，只会减少持仓数量，不会增加新的持仓仓位
对于同一杠杆产品，所有反方向挂单的币数加上当前只减仓下单数量，不能超过仓位资产；负债还完后，如果还有剩余的委托数量，不会反向开仓，而是会进行币币交易。
对于同一交割/永续产品，当前只减仓下单张数，加上价格时间优先于当前只减仓下单的只减仓挂单张数总和，不能超过持仓数量
仅适用于`现货和合约模式`和`跨币种保证金模式`
仅适用于`币币杠杆`，以及买卖模式下的`交割/永续`
注意：交割和永续合约在开平仓模式下，所有的平仓单都有只减仓逻辑，不受该字段传值的影响。

tgtCcy
市价单委托数量`sz`的单位：仅适用于币币市价下单交易。
交易货币：base_ccy
计价货币：quote_ccy
您在使用交易货币买入或者计价货币卖出时，请知晓：
1.如果您输入的数量大于当前可买或者可卖的数量，系统将按照您的最大可买或者可卖数量帮您完成交易，如果您希望按照指定数量成交，那您可以尝试使用限价单，等待市场价格波动到锁定的余额可以买入或卖出您指定的数量。
2.如果您输入的数量不大于当前可买或者可卖的数量，那当市场价格波动过大时，锁定的余额可能没办法买入您输入的交易货币数量或卖出您输入的计价货币数量，为保证您的交易体验，我们基于【能买多少买多少】或者【能卖多少卖多少】的原则，更改下单的数量帮您完成交易。此外，我们将尽量多锁定一点余额来规避更改下单数量的情况。
2.1 交易币买入例子：
以市价下单买入 10个LTC为例，用户可买为11个，此时 10 < 11，挂单成功。当LTC-USDT的市价为200，用户被锁定余额为3,000 USDT，200*10 < 3,000，最终成交10个LTC；若市场波动过大，LTC-USDT的市价为400，此时400*10 > 3,000，当用户被锁定的余额不够买入下单指定的交易货币数量时，系統使用用户被锁定的最大余额3,000 USDT下单买入，最终成交 3,000/400 = 7.5个 LTC。
2.2 计价币卖出例子：
以市价下单卖出 1,000USDT为例，用户可卖为1,200USDT，1,000 < 1,200，挂单成功。LTC-USDT的市价为200，用户被锁定的余额为6个LTC，最终成交5个LTC；若市场波动过大，LTC-USDT的市价为100，100*6 < 1,000，当用户被锁定的余额不够卖出下单指定的计价货币数量时，系統使用用户被锁定的最大余额6个LTC下单，最终成交 6 * 100 = 600 USDT。

对于下单附带止盈止损：
1. 只有当该订单完全成交时，才会生成止盈止损策略订单，否则不会生成止盈止损策略订单。
2. 带单员不支持使用 attachAlgoOrds (Array)，建议使用先前的方法，详情可参考 https://www.okx.com/docs-v5/log_zh/#2022-11-21
3. tgtCcy 为 base_ccy 时的市价买单和 tgtCcy 为 quote_ccy 时的市价卖单，均不支持附带止盈止损
4. tpOrdKind 为 limit，且只有一笔单边止盈时，attachAlgoClOrdId 可以作为 clOrdId 在获取订单信息接口查询。
5. 对于“分批止盈”，包含限价止盈和触发止盈：
* 分批止盈的每笔止盈止损订单仅支持单向止盈止损，slTriggerPx&slOrdPx 与 tpTriggerPx&tpOrdPx 只能填写一组，否则报错 51076
* 同一笔订单上附带分批止盈的止盈触发价类型 (tpTriggerPxType) 必须保持一致，否则报错 51080
* 同一笔订单上附带分批止盈的止盈触发价 (tpTriggerPx) 不能相等，否则报错 51081
* 在附带分批止盈时，止盈订单的数量不能为空，否则报错 51089
* 同一笔订单上分批止盈的止盈数量之和，需要等于订单的委托数量，否则报错 51083
* 同一笔订单上分批止盈的止盈委托不能超过 10 笔，否则报错 51079
* 币币/杠杆不支持开启'开仓价止损'，否则报错 51077
* 同一笔订单上附带分批止盈的止损委托单不能超过 1 笔，否则报错 51084
* 附带止盈止损开启'开仓价止损'时 (amendPxOnTriggerType 设置为 1)，该笔订单上的止盈委托单必须大于等于 2 笔，否则报错 51085
* 同一笔订单上附带分批止盈的止盈类型必须保持一致，否则报错 51091
* 同一笔订单上附带分批止盈的止盈委托价不能相等，否则报错 51092
* 同一笔订单上附带分批止盈，其中限价止盈的止盈委托价 (tpOrdPx) 不能为 -1 (市价)，否则报错 51093
* 币币、杠杆和期权交易不支持限价止盈，否则报错 51094

强制自成交保护
交易系统会以母账户维度实施强制自成交保护，同一母账户下所有账户，包括母账户本身和所有子账户，都无法进行自成交。订单的默认STP模式为`Cancel Maker`，用户亦可以通过下单接口的stpMode参数指定订单的STP模式。
强制自成交保护不会导致延迟。
有三种STP模式。STP模式始终基于taker订单中的配置。
1.Cancel Maker：这是默认的STP模式，系统撤Maker订单以防止自成交。然后，taker订单会基于深度继续和下一个订单成交。
2.Cancel Taker：撤Taker订单以防止自成交。如果用户的Maker订单不是深度里第一个订单，Taker订单会被部分成交，然后撤单。FOK订单会确保完全成交和自成交保护。
3.Cancel Both：撤Taker和Maker订单以防止自成交。如果用户的Maker订单不是深度里第一个订单，Taker订单会被部分成交，然后Taker订单的剩余数量和第一个自我Maker订单被取消。此模式不支持FOK订单。

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-USDT`
tdMode	String	是	交易模式保证金模式：`isolated`：逐仓；`cross`：全仓非保证金模式：`cash`：非保证金 `spot_isolated`：现货逐仓(仅适用于现货带单) ，现货带单时，`tdMode` 的值需要指定为`spot_isolated`
ccy	String	否	保证金币种，仅适用于`现货和合约模式`下的`全仓杠杆`订单
clOrdId	String	否	客户自定义订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
tag	String	否	订单标签字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-16位之间。
side	String	是	订单方向 `buy`：买， `sell`：卖
posSide	String	可选	持仓方向在开平仓模式下必填，且仅可选择 `long` 或 `short`。仅适用交割、永续。
ordType	String	是	订单类型 `market`：市价单 `limit`：限价单 `post_only`：只做maker单 `fok`：全部成交或立即取消 `ioc`：立即成交并取消剩余 `optimal_limit_ioc`：市价委托立即成交并取消剩余（仅适用交割、永续） `mmp`：做市商保护(仅适用于组合保证金账户模式下的期权订单) `mmp_and_post_only`：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单)
sz	String	是	委托数量
px	String	可选	委托价格，仅适用于`limit`、`post_only`、`fok`、`ioc`、`mmp`、`mmp_and_post_only`类型的订单期权下单时，px/pxUsd/pxVol 只能填一个
pxUsd	String	可选	以USD价格进行期权下单仅适用于期权期权下单时 px/pxUsd/pxVol 必填一个，且只能填一个
pxVol	String	可选	以隐含波动率进行期权下单，例如 1 代表 100% 仅适用于期权期权下单时 px/pxUsd/pxVol 必填一个，且只能填一个
reduceOnly	Boolean	否	是否只减仓，`true` 或 `false`，默认`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	否	自成交保护模式默认为 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时，执行市价止盈
> tpOrdKind	String	否	止盈订单类型 `condition`: 条件单 `limit`: 限价单默认为`condition`
> 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":"",
            "ts":"1695190491421",
            "sCode":"0",
            "sMsg":""
        },
        {
            "clOrdId":"oktswap7",
            "ordId":"12344",
            "tag":"",
            "ts":"1695190491421",
            "sCode":"0",
            "sMsg":""
        }
    ],
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

返回参数

参数名	类型	描述
code	String	结果代码，`0`表示成功
msg	String	错误信息，代码为0时，该字段为空
data	String	包含结果的对象数组
> ordId	String	订单ID
> clOrdId	String	客户自定义订单ID
> tag	String	订单标签
> ts	String	系统完成订单请求处理的时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
> 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-USDT`
ordId	String	可选	订单ID， `ordId`和`clOrdId`必须传一个，若传两个，以`ordId`为主
clOrdId	String	可选	用户自定义ID

返回结果

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

返回参数

参数名	类型	描述
code	String	结果代码，`0`表示成功
msg	String	错误信息，代码为0时，该字段为空
data	String	包含结果的对象数组
> ordId	String	订单ID
> clOrdId	String	客户自定义订单ID
> ts	String	系统完成订单请求处理的时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
> 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， `ordId`和`clOrdId`必须传一个，若传两个，以`ordId`为主
clOrdId	String	可选	用户自定义ID

返回结果

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

返回参数

参数名	类型	描述
code	String	结果代码，`0`表示成功
msg	String	错误信息，代码为0时，该字段为空
data	String	包含结果的对象数组
> ordId	String	订单ID
> clOrdId	String	客户自定义订单ID
> ts	String	系统完成订单请求处理的时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
> 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` `false`：不自动撤单 `true`：自动撤单
ordId	String	可选	订单ID `ordId`和`clOrdId`必须传一个，若传两个，以`ordId`为主
clOrdId	String	可选	用户自定义订单ID
reqId	String	否	用户自定义修改事件ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
newSz	String	可选	修改的新数量，必须大于0，对于部分成交订单，该数量应包含已成交数量。
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时，执行市价止盈。
> newTpOrdKind	String	否	止盈订单类型 `condition`: 条件单 `limit`: 限价单
> 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",
         "ts":"1695190491421",
         "reqId":"b12344",
         "sCode":"0",
         "sMsg":""
        }
    ],
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

返回参数

参数名	类型	描述
code	String	结果代码，`0`表示成功
msg	String	错误信息，代码为0时，该字段为空
data	String	包含结果的对象数组
> ordId	String	订单ID
> clOrdId	String	用户自定义ID
> ts	String	系统完成订单请求处理的时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
> 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` `false`：不自动撤单 `true`：自动撤单
ordId	String	可选	订单ID， `ordId`和`clOrdId`必须传一个，若传两个，以`ordId`为主
clOrdId	String	可选	用户自定义order ID
reqId	String	否	用户自定义修改事件ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
newSz	String	可选	修改的新数量，必须大于0，对于部分成交订单，该数量应包含已成交数量。
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时，执行市价止盈。
> newTpOrdKind	String	否	止盈订单类型 `condition`: 条件单 `limit`: 限价单
> 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",
            "ts":"1695190491421",
            "reqId":"b12344",
            "sCode":"0",
            "sMsg":""
        },
        {
            "clOrdId":"oktswap7",
            "ordId":"12344",
            "ts":"1695190491421",
            "reqId":"b12344",
            "sCode":"0",
            "sMsg":""
        }
    ],
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

返回参数

参数名	类型	描述
code	String	结果代码，`0`表示成功
msg	String	错误信息，代码为0时，该字段为空
data	String	包含结果的对象数组
> ordId	String	订单ID
> clOrdId	String	用户自定义ID
> ts	String	系统完成订单请求处理的时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
> 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=1753197687182819328&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="680800019749904384"
)
print(result)

请求参数

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

返回结果

{
    "code": "0",
    "data": [
        {
            "accFillSz": "0.00192834",
            "algoClOrdId": "",
            "algoId": "",
            "attachAlgoClOrdId": "",
            "attachAlgoOrds": [],
            "avgPx": "51858",
            "cTime": "1708587373361",
            "cancelSource": "",
            "cancelSourceReason": "",
            "category": "normal",
            "ccy": "",
            "clOrdId": "",
            "fee": "-0.00000192834",
            "feeCcy": "BTC",
            "fillPx": "51858",
            "fillSz": "0.00192834",
            "fillTime": "1708587373361",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "isTpLimit": "false",
            "lever": "",
            "linkedAlgoOrd": {
                "algoId": ""
            },
            "ordId": "680800019749904384",
            "ordType": "market",
            "pnl": "0",
            "posSide": "net",
            "px": "",
            "pxType": "",
            "pxUsd": "",
            "pxVol": "",
            "quickMgnType": "",
            "rebate": "0",
            "rebateCcy": "USDT",
            "reduceOnly": "false",
            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "source": "",
            "state": "filled",
            "stpId": "",
            "stpMode": "",
            "sz": "100",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "quote_ccy",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "",
            "tradeId": "744876980",
            "uTime": "1708587373362"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
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；对于市价单，无论`tgtCcy`是`base_ccy`，还是`quote_ccy`，单位均为交易货币；对于交割、永续以及期权，单位为张。
fillPx	String	最新成交价格，如果成交数量为0，该字段为""
tradeId	String	最新成交ID
fillSz	String	最新成交数量对于`币币`和`杠杆`，单位为交易货币，如 BTC-USDT, 单位为 BTC；对于市价单，无论`tgtCcy`是`base_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
> tpOrdKind	String	止盈订单类型 `condition`: 条件单 `limit`: 限价单
> tpTriggerPx	String	止盈触发价
> tpTriggerPxType	String	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
> tpOrdPx	String	止盈委托价
> slTriggerPx	String	止损触发价
> slTriggerPxType	String	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
> slOrdPx	String	止损委托价
> sz	String	张数。仅适用于“多笔止盈”的止盈订单
> amendPxOnTriggerType	String	是否启用开仓价止损，仅适用于分批止盈的止损订单 `0`：不开启，默认值 `1`：开启
> failCode	String	委托失败的错误码，默认为"", 委托失败时有值，如 51020
> failReason	String	委托失败的原因，默认为"" 委托失败时有值
linkedAlgoOrd	Object	止损订单信息，仅适用于包含限价止盈单的双向止盈止损订单，触发后生成的普通订单
> algoId	Object	策略订单唯一标识
stpId	String	自成交保护ID 如果自成交保护不适用则返回""（已弃用）
stpMode	String	自成交保护模式
feeCcy	String	交易手续费币种
fee	String	手续费与返佣对于币币和杠杆，为订单交易累计的手续费，平台向用户收取的交易手续费，为负数。如： -0.01 对于交割、永续和期权，为订单交易累计的手续费和返佣
rebateCcy	String	返佣金币种
source	String	订单来源 `6`：计划委托策略触发后的生成的普通单 `7`：止盈止损策略触发后的生成的普通单 `13`：策略委托单触发后的生成的普通单 `25`：移动止盈止损策略触发后的生成的普通单 `34`: 追逐限价委托生成的普通单
rebate	String	返佣金额，仅适用于币币和杠杆，平台向达到指定lv交易等级的用户支付的挂单奖励（返佣），如果没有返佣金，该字段为“”。手续费返佣为正数，如：0.01
category	String	订单种类 `normal`：普通委托 `twap`：TWAP自动换币 `adl`：ADL自动减仓 `full_liquidation`：强制平仓 `partial_liquidation`：强制减仓 `delivery`：交割 `ddh`：对冲减仓类型订单
reduceOnly	String	是否只减仓，`true` 或 `false`
cancelSource	String	订单取消来源的原因枚举值代码
cancelSourceReason	String	订单取消来源的对应具体原因
quickMgnType	String	一键借币类型，仅适用于杠杆逐仓的一键借币模式 `manual`：手动 `auto_borrow`：自动借币 `auto_repay`：自动还币
algoClOrdId	String	客户自定义策略订单ID。策略订单触发，且策略单有`algoClOrdId`时有值，否则为"",
algoId	String	策略委托单ID，策略订单触发时有值，否则为""
isTpLimit	String	是否为限价止盈，true 或 false.
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-USDT`
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",
    "data": [
        {
            "accFillSz": "0",
            "algoClOrdId": "",
            "algoId": "",
            "attachAlgoClOrdId": "",
            "attachAlgoOrds": [],
            "avgPx": "",
            "cTime": "1724733617998",
            "cancelSource": "",
            "cancelSourceReason": "",
            "category": "normal",
            "ccy": "",
            "clOrdId": "",
            "fee": "0",
            "feeCcy": "BTC",
            "fillPx": "",
            "fillSz": "0",
            "fillTime": "",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "isTpLimit": "false",
            "lever": "",
            "linkedAlgoOrd": {
                "algoId": ""
            },
            "ordId": "1752588852617379840",
            "ordType": "post_only",
            "pnl": "0",
            "posSide": "net",
            "px": "13013.5",
            "pxType": "",
            "pxUsd": "",
            "pxVol": "",
            "quickMgnType": "",
            "rebate": "0",
            "rebateCcy": "USDT",
            "reduceOnly": "false",
            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "source": "",
            "state": "live",
            "stpId": "",
            "stpMode": "cancel_maker",
            "sz": "0.001",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "",
            "tradeId": "",
            "uTime": "1724733617998"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
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
> tpOrdKind	String	止盈订单类型 `condition`: 条件单 `limit`: 限价单
> tpTriggerPx	String	止盈触发价
> tpTriggerPxType	String	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
> tpOrdPx	String	止盈委托价
> slTriggerPx	String	止损触发价
> slTriggerPxType	String	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
> slOrdPx	String	止损委托价
> sz	String	张数。仅适用于“多笔止盈”的止盈订单
> failCode	String	委托失败的错误码，默认为"", 委托失败时有值，如 51020
> failReason	String	委托失败的原因，默认为"" 委托失败时有值
> amendPxOnTriggerType	String	是否启用开仓价止损，仅适用于分批止盈的止损订单 `0`：不开启，默认值 `1`：开启
linkedAlgoOrd	Object	止损订单信息，仅适用于包含限价止盈单的双向止盈止损订单，触发后生成的普通订单
> algoId	Object	策略订单唯一标识
stpId	String	自成交保护ID 如果自成交保护不适用则返回""（已弃用）
stpMode	String	自成交保护模式
feeCcy	String	交易手续费币种
fee	String	手续费与返佣对于币币和杠杆，为订单交易累计的手续费，平台向用户收取的交易手续费，为负数。如： -0.01 对于交割、永续和期权，为订单交易累计的手续费和返佣
rebateCcy	String	返佣金币种
source	String	订单来源 `6`：计划委托策略触发后的生成的普通单 `7`：止盈止损策略触发后的生成的普通单 `13`：策略委托单触发后的生成的普通单 `25`：移动止盈止损策略触发后的生成的普通单 `34`: 追逐限价委托生成的普通单
rebate	String	返佣金额，仅适用于币币和杠杆，平台向达到指定lv交易等级的用户支付的挂单奖励（返佣），如果没有返佣金，该字段为“”。手续费返佣为`正数`，如：`0.01`
category	String	订单种类 `normal`：普通委托
reduceOnly	String	是否只减仓，`true` 或 `false`
quickMgnType	String	一键借币类型，仅适用于杠杆逐仓的一键借币模式 `manual`：手动，`auto_borrow`：自动借币，`auto_repay`：自动还币
algoClOrdId	String	客户自定义策略订单ID。策略订单触发，且策略单有`algoClOrdId`是有值，否则为"",
algoId	String	策略委托单ID，策略订单触发时有值，否则为""
isTpLimit	String	是否为限价止盈，true 或 false.
uTime	String	订单状态更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
cancelSource	String	订单取消来源的原因枚举值代码
cancelSourceReason	String	订单取消来源的对应具体原因

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	否	筛选的开始时间戳 `cTime`，Unix 时间戳为毫秒数格式，如 1597026383085
end	String	否	筛选的结束时间戳 `cTime`，Unix 时间戳为毫秒数格式，如 1597027383085
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "accFillSz": "0.00192834",
            "algoClOrdId": "",
            "algoId": "",
            "attachAlgoClOrdId": "",
            "attachAlgoOrds": [],
            "avgPx": "51858",
            "cTime": "1708587373361",
            "cancelSource": "",
            "cancelSourceReason": "",
            "category": "normal",
            "ccy": "",
            "clOrdId": "",
            "fee": "-0.00000192834",
            "feeCcy": "BTC",
            "fillPx": "51858",
            "fillSz": "0.00192834",
            "fillTime": "1708587373361",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "isTpLimit": "false",
            "lever": "",
            "ordId": "680800019749904384",
            "ordType": "market",
            "pnl": "0",
            "posSide": "",
            "px": "",
            "pxType": "",
            "pxUsd": "",
            "pxVol": "",
            "quickMgnType": "",
            "rebate": "0",
            "rebateCcy": "USDT",
            "reduceOnly": "false",
            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "source": "",
            "state": "filled",
            "stpId": "",
            "stpMode": "",
            "sz": "100",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "quote_ccy",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "",
            "tradeId": "744876980",
            "uTime": "1708587373362",
            "linkedAlgoOrd": {
                "algoId": ""
            }
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
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
> tpOrdKind	String	止盈订单类型 `condition`: 条件单 `limit`: 限价单
> tpTriggerPx	String	止盈触发价
> tpTriggerPxType	String	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
> tpOrdPx	String	止盈委托价
> slTriggerPx	String	止损触发价
> slTriggerPxType	String	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
> slOrdPx	String	止损委托价
> sz	String	张数。仅适用于“多笔止盈”的止盈订单
> amendPxOnTriggerType	String	是否启用开仓价止损，仅适用于分批止盈的止损订单 `0`：不开启，默认值 `1`：开启
> failCode	String	委托失败的错误码，默认为"", 委托失败时有值，如 51020
> failReason	String	委托失败的原因，默认为"" 委托失败时有值
linkedAlgoOrd	Object	止损订单信息，仅适用于包含限价止盈单的双向止盈止损订单，触发后生成的普通订单
> algoId	Object	策略订单唯一标识
stpId	String	自成交保护ID 如果自成交保护不适用则返回""（已弃用）
stpMode	String	自成交保护模式
feeCcy	String	交易手续费币种
fee	String	手续费与返佣对于币币和杠杆，为订单交易累计的手续费，平台向用户收取的交易手续费，为负数。如： -0.01 对于交割、永续和期权，为订单交易累计的手续费和返佣
rebateCcy	String	返佣金币种
source	String	订单来源 `6`：计划委托策略触发后的生成的普通单 `7`：止盈止损策略触发后的生成的普通单 `13`：策略委托单触发后的生成的普通单 `25`：移动止盈止损策略触发后的生成的普通单 `34`: 追逐限价委托生成的普通单
rebate	String	返佣金额，仅适用于币币和杠杆，平台向达到指定lv交易等级的用户支付的挂单奖励（返佣），如果没有返佣金，该字段为“”。手续费返佣为`正数`，如：`0.01`
pnl	String	收益，适用于有成交的平仓订单，其他情况均为0
category	String	订单种类 `normal`：普通委托 `twap`：TWAP自动换币 `adl`：ADL自动减仓 `full_liquidation`：强制平仓 `partial_liquidation`：强制减仓 `delivery`：交割 `ddh`：对冲减仓类型订单
reduceOnly	String	是否只减仓，`true` 或 `false`
cancelSource	String	订单取消来源的原因枚举值代码
cancelSourceReason	String	订单取消来源的对应具体原因
algoClOrdId	String	客户自定义策略订单ID。策略订单触发，且策略单有`algoClOrdId`时有值，否则为"",
algoId	String	策略委托单ID，策略订单触发时有值，否则为""
isTpLimit	String	是否为限价止盈，true 或 false.
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-USDT`
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	否	筛选的开始时间戳 `cTime`，Unix 时间戳为毫秒数格式，如 `1597026383085`
end	String	否	筛选的结束时间戳 `cTime`，Unix 时间戳为毫秒数格式，如 `1597027383085`
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "accFillSz": "0.00192834",
            "algoClOrdId": "",
            "algoId": "",
            "attachAlgoClOrdId": "",
            "attachAlgoOrds": [],
            "avgPx": "51858",
            "cTime": "1708587373361",
            "cancelSource": "",
            "cancelSourceReason": "",
            "category": "normal",
            "ccy": "",
            "clOrdId": "",
            "fee": "-0.00000192834",
            "feeCcy": "BTC",
            "fillPx": "51858",
            "fillSz": "0.00192834",
            "fillTime": "1708587373361",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "isTpLimit": "false",
            "lever": "",
            "ordId": "680800019749904384",
            "ordType": "market",
            "pnl": "0",
            "posSide": "",
            "px": "",
            "pxType": "",
            "pxUsd": "",
            "pxVol": "",
            "quickMgnType": "",
            "rebate": "0",
            "rebateCcy": "USDT",
            "reduceOnly": "false",
            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "source": "",
            "state": "filled",
            "stpId": "",
            "stpMode": "",
            "sz": "100",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "quote_ccy",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "",
            "tradeId": "744876980",
            "uTime": "1708587373362",
            "linkedAlgoOrd": {
                "algoId": ""
            }
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
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
> tpOrdKind	String	止盈订单类型 `condition`: 条件单 `limit`: 限价单
> tpTriggerPx	String	止盈触发价
> tpTriggerPxType	String	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
> tpOrdPx	String	止盈委托价
> slTriggerPx	String	止损触发价
> slTriggerPxType	String	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
> slOrdPx	String	止损委托价
> sz	String	张数。仅适用于“多笔止盈”的止盈订单
> amendPxOnTriggerType	String	是否启用开仓价止损，仅适用于分批止盈的止损订单 `0`：不开启，默认值 `1`：开启
> failCode	String	委托失败的错误码，默认为"", 委托失败时有值，如 51020
> failReason	String	委托失败的原因，默认为"" 委托失败时有值
linkedAlgoOrd	Object	止损订单信息，仅适用于包含限价止盈单的双向止盈止损订单，触发后生成的普通订单
> algoId	Object	策略订单唯一标识
stpMode	String	自成交保护模式
feeCcy	String	交易手续费币种
fee	String	手续费与返佣对于币币和杠杆，为订单交易累计的手续费，平台向用户收取的交易手续费，为负数。如： -0.01 对于交割、永续和期权，为订单交易累计的手续费和返佣
rebateCcy	String	返佣金币种
rebate	String	返佣金额，仅适用于币币和杠杆，平台向达到指定lv交易等级的用户支付的挂单奖励（返佣），如果没有返佣金，该字段为“”。手续费返佣为`正数`，如：`0.01`
pnl	String	收益，适用于有成交的平仓订单，其他情况均为0
source	String	订单来源 `6`：计划委托策略触发后的生成的普通单 `7`：止盈止损策略触发后的生成的普通单 `13`：策略委托单触发后的生成的普通单 `25`：移动止盈止损策略触发后的生成的普通单 `34`: 追逐限价委托生成的普通单
category	String	订单种类 `normal`：普通委托 `twap`：TWAP自动换币 `adl`：ADL自动减仓 `full_liquidation`：强制平仓 `partial_liquidation`：强制减仓 `delivery`：交割 `ddh`：对冲减仓类型订单
reduceOnly	String	是否只减仓，`true` 或 `false`
cancelSource	String	订单取消来源的原因枚举值代码
cancelSourceReason	String	订单取消来源的对应具体原因
algoClOrdId	String	客户自定义策略订单ID。策略订单触发，且策略单有`algoClOrdId`是有值，否则为"",
algoId	String	策略委托单ID，策略订单触发时有值，否则为""
isTpLimit	String	是否为限价止盈，true 或 false.
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-USDT`
ordId	String	否	订单 ID
subType	String	否	成交类型 `1`：买入 `2`：卖出 `3`：开多 `4`：开空 `5`：平多 `6`：平空 `100`：强减平多 `101`：强减平空 `102`：强减买入 `103`：强减卖出 `104`：强平平多 `105`：强平平空 `106`：强平买入 `107`：强平卖出 `110`：强平换币转入 `111`：强平换币转出 `118`：系统换币转入 `119`：系统换币转出 `125`：自动减仓平多 `126`：自动减仓平空 `127`：自动减仓买入 `128`：自动减仓卖出 `212`：一键借币的自动借币 `213`：一键借币的自动还币 `204`：大宗交易买 `205`：大宗交易卖 `206`：大宗交易开多 `207`：大宗交易开空 `208`：大宗交易平多 `209`：大宗交易平空 `270`：价差交易买 `271`：价差交易卖 `272`：价差交易开多 `273`：价差交易开空 `274`：价差交易平多 `275`：价差交易平空
after	String	否	请求此 ID 之前（更旧的数据）的分页内容，传的值为对应接口的`billId`
before	String	否	请求此 ID 之后（更新的数据）的分页内容，传的值为对应接口的`billId`
begin	String	否	筛选的开始时间戳 `ts`，Unix 时间戳为毫秒数格式，如 `1597026383085`
end	String	否	筛选的结束时间戳 `ts`，Unix 时间戳为毫秒数格式，如 `1597027383085`
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "side": "buy",
            "fillSz": "0.00192834",
            "fillPx": "51858",
            "fillPxVol": "",
            "fillFwdPx": "",
            "fee": "-0.00000192834",
            "fillPnl": "0",
            "ordId": "680800019749904384",
            "feeRate": "-0.001",
            "instType": "SPOT",
            "fillPxUsd": "",
            "instId": "BTC-USDT",
            "clOrdId": "",
            "posSide": "net",
            "billId": "680800019754098688",
            "subType": "1",
            "fillMarkVol": "",
            "tag": "",
            "fillTime": "1708587373361",
            "execType": "T",
            "fillIdxPx": "",
            "tradeId": "744876980",
            "fillMarkPx": "",
            "feeCcy": "BTC",
            "ts": "1708587373362"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instType	String	产品类型
instId	String	产品 ID
tradeId	String	最新成交 ID
ordId	String	订单 ID
clOrdId	String	用户自定义订单ID
billId	String	账单 ID
subType	String	成交类型
tag	String	订单标签
fillPx	String	最新成交价格，同"账单流水查询"的 px
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`相同
feeRate	String	手续费费率。该字段仅对 `币币`和`杠杆`返回

GET / 获取成交明细（近三个月）

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

限速：10 次/2s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/trade/fills-history

请求示例

GET /api/v5/trade/fills-history?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_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
subType	String	否	成交类型 `1`：买入 `2`：卖出 `3`：开多 `4`：开空 `5`：平多 `6`：平空 `100`：强减平多 `101`：强减平空 `102`：强减买入 `103`：强减卖出 `104`：强平平多 `105`：强平平空 `106`：强平买入 `107`：强平卖出 `110`：强平换币转入 `111`：强平换币转出 `118`：系统换币转入 `119`：系统换币转出 `125`：自动减仓平多 `126`：自动减仓平空 `127`：自动减仓买入 `128`：自动减仓卖出 `212`：一键借币的自动借币 `213`：一键借币的自动还币 `204`：大宗交易买 `205`：大宗交易卖 `206`：大宗交易开多 `207`：大宗交易开空 `208`：大宗交易平多 `209`：大宗交易平空 `270`：价差交易买 `271`：价差交易卖 `272`：价差交易开多 `273`：价差交易开空 `274`：价差交易平多 `275`：价差交易平空
after	String	否	请求此 ID 之前（更旧的数据）的分页内容，传的值为对应接口的 `billId`
before	String	否	请求此 ID 之后（更新的数据）的分页内容，传的值为对应接口的 `billId`
begin	String	否	筛选的开始时间戳 `ts`，Unix 时间戳为毫秒数格式，如 `1597026383085`
end	String	否	筛选的结束时间戳 `ts`，Unix 时间戳为毫秒数格式，如 `1597027383085`
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "side": "buy",
            "fillSz": "0.00192834",
            "fillPx": "51858",
            "fillPxVol": "",
            "fillFwdPx": "",
            "fee": "-0.00000192834",
            "fillPnl": "0",
            "ordId": "680800019749904384",
            "feeRate": "-0.001",
            "instType": "SPOT",
            "fillPxUsd": "",
            "instId": "BTC-USDT",
            "clOrdId": "",
            "posSide": "net",
            "billId": "680800019754098688",
            "subType": "1",
            "fillMarkVol": "",
            "tag": "",
            "fillTime": "1708587373361",
            "execType": "T",
            "fillIdxPx": "",
            "tradeId": "744876980",
            "fillMarkPx": "",
            "feeCcy": "BTC",
            "ts": "1708587373362"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instType	String	产品类型
instId	String	产品 ID
tradeId	String	最新成交 ID
ordId	String	订单 ID
clOrdId	String	用户自定义订单ID
billId	String	账单 ID
subType	String	成交类型
tag	String	订单标签
fillPx	String	最新成交价格，同"账单流水查询"的 px
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`相同
feeRate	String	手续费费率。该字段仅对 `币币`和`杠杆`返回

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)

请求参数

参数名	类型	是否必须	描述
source	String	否	资金来源 `1`：交易账户 `2`：资金账户默认为`1`

返回结果

{
    "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 / 一键兑换主流币交易

进行小币一键兑换主流币交易。

限速：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	是	兑换的主流币只选择一个币种，且不能和小币支付币种重复
source	String	否	资金来源 `1`：交易账户 `2`：资金账户默认为`1`

返回结果

{
    "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 / 获取一键兑换主流币历史记录

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

限速：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",
            "acct": "18",
            "uTime": "1661313307979"
        },
        {
            "fillFromSz": "0.1722106121112177",
            "fillToSz": "2.9971018300000000",
            "fromCcy": "OKB",
            "status": "filled",
            "toCcy": "USDC",
            "acct": "18",
            "uTime": "1661313307979"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
fromCcy	String	小币支付币种
fillFromSz	String	对应的小币支付数量
toCcy	String	兑换到的主流币
fillToSz	String	兑换到的主流币数量
acct	String	兑换到的主流币所在的账户 `6`：资金账户 `18`：交易账户
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 / 获取一键还债历史记录

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

限速：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	负债币种
fillDebtSz	String	对应的负债币种成交数量
repayCcy	String	偿还币种
fillRepaySz	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	是	交易品种
lockInterval	String	否	锁定时长(毫秒) 范围应为[0, 10 000] 默认为 0. 如果想要立即解锁，您可以设置为 "0" 下单时，如果在该锁定期间，会报错 54008，如果在 MMP 触发期间，会报错 51034

返回结果

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

返回参数

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

POST / 倒计时全部撤单

在倒计时结束后，取消所有挂单。适用于所有撮合交易产品（不包括价差交易）。

限速：1次/s

限速规则：UserID + tag

权限：交易

HTTP请求

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

请求示例

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

import okx.Trade as Trade

# API initialization
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_all_after(
    timeOut="10"
)

print(result)

请求参数

参数名	类型	是否必须	描述
timeOut	String	是	取消挂单的倒计时，单位为秒取值范围为 0, [10, 120] 0 代表不使用该功能
tag	String	否	CAA订单标签字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间

返回结果

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

返回参数

参数名	类型	描述
triggerTime	String	触发撤单的时间 triggerTime=0 代表未使用该功能
tag	String	CAA订单标签
ts	String	请求被接收到的时间

GET / 获取账户限速

获取账户限速相关信息

仅有新订单及修改订单请求会被计入此限制。对于包含多个订单的批量请求，每个订单将被单独计数。

更多细节，请见基于成交比率的子账户限速

限速：1次/s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/trade/account-rate-limit

请求示例


# 获取账户限速相关信息
GET /api/v5/trade/account-rate-limit

请求参数

None

返回结果

{
   "code":"0",
   "data":[
      {
         "accRateLimit":"2000",
         "fillRatio":"0.1234",
         "mainFillRatio":"0.1234",
         "nextAccRateLimit":"2000",
         "ts":"123456789000"
      }
   ],
   "msg":""
}

返回参数

参数名	类型	描述
fillRatio	String	监测期内子账户的成交比率适用于交易费等级 >= VIP 5的用户，其余用户返回"" 对于监测期内没有交易量的账户，返回"0"。对于监测期内有交易量，但没有订单操作数的用户，返回"9999"。
mainFillRatio	String	监测期内母账户合计成交比率适用于交易费等级 >= VIP 5的用户，其余用户返回"" 对于监测期内没有交易量的账户，返回"0"
accRateLimit	String	当前子账户交易限速（每两秒）
nextAccRateLimit	String	预计下一周期子账户交易限速（每两秒）适用于交易费等级 >= VIP 5的用户，其余用户返回""
ts	String	数据更新时间对于交易费等级>= VIP 5的用户，数据将于每日16:00（UTC+8）生成对于交易费等级 < VIP 5的用户，返回当前时间戳

POST / 订单预检查

用来预先查看订单下单前后的账户的对比信息，仅适用于跨币种保证金模式和组合保证金模式。

限速：5次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/trade/order-precheck

请求示例

POST /api/v5/trade/order-precheck
body
{
    "instId":"BTC-USDT",
    "tdMode":"cash",
    "clOrdId":"b15",
    "side":"buy",
    "ordType":"limit",
    "px":"2.15",
    "sz":"2"
}

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 `BTC-USDT`
tdMode	String	是	交易模式保证金模式：`isolated`：逐仓；`cross`：全仓非保证金模式：`cash`：非保证金 `spot_isolated`：现货逐仓(仅适用于现货带单) ，现货带单时，`tdMode` 的值需要指定为`spot_isolated`
side	String	是	订单方向 `buy`：买， `sell`：卖
posSide	String	可选	持仓方向在开平仓模式下必填，且仅可选择 `long` 或 `short`。仅适用交割、永续。
ordType	String	是	订单类型 `market`：市价单 `limit`：限价单 `post_only`：只做maker单 `fok`：全部成交或立即取消 `ioc`：立即成交并取消剩余 `optimal_limit_ioc`：市价委托立即成交并取消剩余（仅适用交割、永续）
sz	String	是	委托数量
px	String	可选	委托价格，仅适用于`limit`、`post_only`、`fok`、`ioc`类型的订单
reduceOnly	Boolean	否	是否只减仓，`true` 或 `false`，默认`false` 仅适用于`币币杠杆`，以及买卖模式下的`交割/永续` 仅适用于`现货和合约模式`和`跨币种保证金模式`
tgtCcy	String	否	市价单委托数量`sz`的单位，仅适用于`币币`市价订单 `base_ccy`: 交易货币；`quote_ccy`：计价货币买单默认`quote_ccy`，卖单默认`base_ccy`
attachAlgoOrds	Array of object	否	下单附带止盈止损信息
> attachAlgoClOrdId	String	否	下单附带止盈止损时，客户自定义的策略订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。订单完全成交，下止盈止损委托单时，该值会传给`algoClOrdId`
> tpTriggerPx	String	可选	止盈触发价对于条件止盈单，如果填写此参数，必须填写止盈委托价
> tpOrdPx	String	可选	止盈委托价对于条件止盈单，如果填写此参数，必须填写止盈触发价对于限价止盈单，需填写此参数，不需要填写止盈触发价委托价格为-1时，执行市价止盈
> tpOrdKind	String	否	止盈订单类型 `condition`: 条件单 `limit`: 限价单默认为`condition`
> slTriggerPx	String	可选	止损触发价，如果填写此参数，必须填写止损委托价
> slOrdPx	String	可选	止损委托价，如果填写此参数，必须填写止损触发价委托价格为-1时，执行市价止损
> tpTriggerPxType	String	否	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格默认为`last`
> slTriggerPxType	String	否	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格默认为`last`
> sz	String	可选	数量。仅适用于“多笔止盈”的止盈订单，且对于“多笔止盈”的止盈订单必填

返回结果

{
    "code": "0",
    "data": [
        {
            "adjEq": "41.94347460746277",
            "adjEqChg": "-226.05616481626",
            "availBal": "0",
            "availBalChg": "0",
            "imr": "0",
            "imrChg": "57.74709688430927",
            "liab": "0",
            "liabChg": "0",
            "liabChgCcy": "",
            "liqPx": "6764.8556232031115",
            "liqPxDiff": "-57693.044376796888536773622035980224609375",
            "liqPxDiffRatio": "-0.8950500152315991",
            "mgnRatio": "0",
            "mgnRatioChg": "0",
            "mmr": "0",
            "mmrChg": "0",
            "posBal": "",
            "posBalChg": "",
            "type": ""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
adjEq	String	当前美金层面有效保证金
adjEqChg	String	下单后，美金层面有效保证金的变动数量
imr	String	当前美金层面占用保证金
imrChg	String	下单后，美金层面占用保证金的变动数量
mmr	String	当前美金层面维持保证金
mmrChg	String	下单后，美金层面维持保证金的变动数量
mgnRatio	String	当前美金层面保证金率
mgnRatioChg	String	下单后，美金层面保证金率的变动数量
availBal	String	当前币种可用余额，仅适用于关闭自动借币时
availBalChg	String	下单后，币种可用余额的变动数量，仅适用于关闭自动借币时
liqPx	String	当前预估强平价
liqPxDiff	String	下单后，预估强平价与标记价格的差距
liqPxDiffRatio	String	下单后，预估强平价与标记价格的差距比率
posBal	String	当前杠杆逐仓仓位正资产，仅适用于逐仓杠杆
posBalChg	String	下单后，杠杆逐仓仓位正资产的变动数量，仅适用于逐仓杠杆
liab	String	当前负债如果是全仓，对应全仓负债，如果是逐仓，对应逐仓负债
liabChg	String	下单后，当前负债的变动数量如果是全仓，对应全仓负债，如果是逐仓，对应逐仓负债
liabChgCcy	String	下单后，当前负债变动数量的单位仅适用于全仓，开启自动借币时
type	String	仓位正资产(`posBal`)的单位类型，仅适用于杠杆逐仓，用来确定`posBal`的单位 `1`:下单前后都是交易货币 `2`:下单前是交易货币，下单后是计价货币 `3`:下单前是计价货币，下单后是交易货币 `4`:下单前后都是计价货币

WS / 订单频道

获取订单信息，首次订阅不推送，只有当下单、撤单等事件触发时，推送数据
该频道的并发连接受到如下规则限制：WebSocket 连接限制

服务地址

/ws/v5/private (需要登录)

请求示例：单个

{
    "op": "subscribe",
    "args": [{
        "channel": "orders",
        "instType": "FUTURES",
        "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",
        "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",
            "lastPx": "38892.2",
            "quickMgnType": "",
            "algoClOrdId": "",
            "attachAlgoOrds": [],
            "algoId": "",
            "amendSource": "",
            "cancelSource": "",
            "isTpLimit": "false",
            "uTime": "1654084353264",
            "linkedAlgoOrd": {
                "algoId": ""
            }
        }
    ]
}

推送数据参数

参数名	类型	描述
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；对于市价单，无论`tgtCcy`是`base_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；对于市价单，无论`tgtCcy`是`base_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
>> tpOrdKind	String	止盈订单类型 `condition`: 条件单 `limit`: 限价单
>> tpTriggerPx	String	止盈触发价
>> tpTriggerPxType	String	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
>> tpOrdPx	String	止盈委托价
>> slTriggerPx	String	止损触发价
>> slTriggerPxType	String	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
>> slOrdPx	String	止损委托价
>> sz	String	张数。仅适用于“多笔止盈”的止盈订单
>> amendPxOnTriggerType	String	是否启用开仓价止损，仅适用于分批止盈的止损订单 `0`：不开启，默认值 `1`：开启
> linkedAlgoOrd	Object	止损订单信息，仅适用于包含限价止盈单的双向止盈止损订单，触发后生成的普通订单
>> algoId	Object	策略订单唯一标识
> stpId	String	自成交保护ID 如果自成交保护不适用则返回""（已弃用）
> stpMode	String	自成交保护模式
> feeCcy	String	交易手续费币种 `币币/币币杠杆`：如果是买的话，收取的就是交易币；如果是卖的话，收取的就是计价币。 `交割/永续/期权` 收取的就是保证金
> fee	String	订单交易累计的手续费与返佣对于币币和杠杆，为订单交易累计的手续费，平台向用户收取的交易手续费，为负数。如： -0.01 对于交割、永续和期权，为订单交易累计的手续费和返佣
> rebateCcy	String	返佣金币种，如果没有返佣金，该字段为“”
> rebate	String	返佣累计金额，仅适用于币币和杠杆，平台向达到指定lv交易等级的用户支付的挂单奖励（返佣），如果没有返佣金，该字段为“”
> pnl	String	收益，适用于有成交的平仓订单，其他情况均为0 对于合约全仓爆仓，将包含相应强平惩罚金
> source	String	订单来源 `6`：计划委托策略触发后的生成的普通单 `7`：止盈止损策略触发后的生成的普通单 `13`：策略委托单触发后的生成的普通单 `25`：移动止盈止损策略触发后的生成的普通单 `34`: 追逐限价委托生成的普通单
> cancelSource	String	订单取消的来源有效值及对应的含义是： `0`: 已撤单：系统撤单 `1`: 用户主动撤单 `2`: 已撤单：预减仓撤单，用户保证金不足导致挂单被撤回 `3`: 已撤单：风控撤单，用户保证金不足有爆仓风险，导致挂单被撤回 `4`: 已撤单：币种借币量达到平台硬顶，系统已撤回该订单 `6`: 已撤单：触发 ADL 撤单，用户保证金率较低且有爆仓风险，导致挂单被撤回 `7`: 已撤单：交割合约到期 `9`: 已撤单：扣除资金费用后可用余额不足，系统已撤回该订单 `13`: 已撤单：FOK 委托订单未完全成交，导致挂单被完全撤回 `14`: 已撤单：IOC 委托订单未完全成交，仅部分成交，导致部分挂单被撤回 `15`: 已撤单：该订单委托价不在限价范围内 `17`: 已撤单：平仓单被撤单，由于仓位已被市价全平 `20`: 系统倒计时撤单 `21`: 已撤单：相关仓位被完全平仓，系统已撤销该止盈止损订单 `22`, `23`: 已撤单：只减仓订单仅允许减少仓位数量，系统已撤销该订单 `27`: 成交滑点超过5%，触发成交差价保护导致系统撤单 `31`: 当前只挂单订单 (Post only) 将会吃掉挂单深度 `32`: 自成交保护 `33`: 当前 taker 订单匹配的订单数量超过最大限制 `36`: 关联止损被触发，撤销限价止盈 `37`: 关联止损被撤销，撤销限价止盈 `38`: 您已撤销做市商保护 (MMP) 类型订单 `39`: 因做市商保护 (MMP) 被触发，该类型订单已被撤销 `40`: 初始下单价格与最新的买一或卖一价已达到最大追逐距离，您的订单已被自动取消
> 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`：对冲减仓类型订单
> isTpLimit	String	是否为限价止盈，true 或 false.
> 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	是否只减仓，`true` 或 `false`
> quickMgnType	String	一键借币类型，仅适用于杠杆逐仓的一键借币模式 `manual`：手动，`auto_borrow`：自动借币，`auto_repay`：自动还币
> algoClOrdId	String	客户自定义策略订单ID。策略订单触发，且策略单有`algoClOrdId`时有值，否则为"",
> algoId	String	策略委托单ID，策略订单触发时有值，否则为""
> lastPx	String	最新成交价
> code	String	错误码，默认为0
> msg	String	错误消息，默认为""

WS / 成交频道

获取成交信息。该频道无首推，仅在订单簿成交相关事件触发时推送数据，tradeId > 0。

该频道仅适用于交易等级VIP5及以上的用户。其他用户请使用WS / 订单频道。

服务地址

/ws/v5/private (需要登录)

请求示例：单个

{
    "op": "subscribe",
    "args": [
        {
            "channel": "fills",
            "instId": "BTC-USDT-SWAP"
        }
    ]
}

请求示例

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

请求参数

参数名	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	订阅的频道
> channel	String	是	频道名 `fills`
> instId	String	否	产品ID

成功返回示例：单个

{
  "event": "subscribe",
  "arg": {
    "channel": "fills",
    "instId": "BTC-USDT-SWAP"
  },
  "connId": "a4d3ae55"
}

成功返回示例

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

返回参数

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

推送示例：单个

{
    "arg": {
        "channel": "fills",
        "instId": "BTC-USDT-SWAP",
        "uid": "614488474791111"
    },
    "data":[
        {
            "instId": "BTC-USDT-SWAP",
            "fillSz": "100",
            "fillPx": "70000",
            "side": "buy",
            "ts": "1705449605015",
            "ordId": "680800019749904384",
            "tradeId": "12345",
            "execType": "T",
            "count": "10"
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> uid	String	用户标识
> instId	String	产品ID
data	Array	订阅的数据
> instId	String	产品ID
> fillSz	String	成交数量，若这笔成交有聚合，则成交数量为聚合后的数量
> fillPx	String	成交价格
> side	String	订单方向，`buy` `sell`
> ts	String	成交时间
> ordId	String	订单ID
> tradeId	String	成交ID 若为taker订单且有聚合，则为聚合的多笔交易中最新一笔交易的成交ID
> execType	String	流动性方向 `T`：taker `M`：maker
> count	String	聚合的订单匹配数量

- 该频道仅适用于交易等级VIP5及以上的用户，其他用户接入将收到错误码60029
- 该频道只推送部分订单频道的信息，与大宗交易、价差速递相关的成交，强平、自动减仓等非订单簿事件不会通过该频道推送。用户应同时关注订单频道，对订单做最终确认
- 该频道接收到成交推送时，账户余额、保证金、持仓等信息可能仍未发生变化
- taker订单将根据不同成交价格进行聚合，有聚合时，count字段表示聚合的订单匹配数量，tradeId代表聚合的多笔交易中最新一笔交易的ID；maker订单不会聚合
- 未来，该频道将施加连接数量限制，子账户维度，订阅成交频道的最大连接数为20个。我们建议用户始终低于限制使用该频道，以免限制上线后对策略造成影响

WS / 下单

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

服务地址

/ws/v5/private (需要登录)

限速：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-USDT`
> tdMode	String	是	交易模式保证金模式 `isolated`：逐仓 `cross`：全仓非保证金模式 `cash`：现金 `spot_isolated`：现货逐仓(仅适用于现货带单) ，现货带单时，`tdMode` 的值需要指定为`spot_isolated`
> ccy	String	否	保证金币种，仅适用于`现货和合约模式`下的全仓杠杆订单
> clOrdId	String	否	由用户设置的订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
> tag	String	否	订单标签字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-16位之间。
> side	String	是	订单方向，`buy` `sell`
> posSide	String	否	持仓方向在买卖模式下，默认 `net` 在开平仓模式下必填，且仅可选择 `long` 或 `short`，仅适用于`交割/永续`
> ordType	String	是	订单类型 `market`：市价单 `limit`：限价单 `post_only`：只做maker单 `fok`：全部成交或立即取消 `ioc`：立即成交并取消剩余 `optimal_limit_ioc`：市价委托立即成交并取消剩余（仅适用交割、永续） `mmp`：做市商保护(仅适用于组合保证金账户模式下的期权订单) `mmp_and_post_only`：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单)
> sz	String	是	委托数量
> px	String	可选	委托价格，仅适用于`limit`、`post_only`、`fok`、`ioc`、`mmp`、`mmp_and_post_only`类型的订单期权下单时，px/pxUsd/pxVol 只能填一个
> pxUsd	String	可选	以USD价格进行期权下单仅适用于期权期权下单时 px/pxUsd/pxVol 必填一个，且只能填一个
> pxVol	String	可选	以隐含波动率进行期权下单，例如 1 代表 100% 仅适用于期权期权下单时 px/pxUsd/pxVol 必填一个，且只能填一个
> reduceOnly	Boolean	否	是否只减仓，`true` 或 `false`，默认`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	否	自成交保护模式默认为 cancel maker `cancel_maker`,`cancel_taker`, `cancel_both` Cancel both不支持FOK
expTime	String	否	请求有效截止时间。Unix时间戳的毫秒数格式，如 `1597026383085`

成功返回示例

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

失败返回示例

{
    "id": "1512",
    "op": "order",
    "data": [{
        "clOrdId": "",
        "ordId": "",
        "tag": "",
        "ts":"1695190491421",
        "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	订单标签
> ts	String	系统完成订单请求处理的时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
> sCode	String	订单状态码，0 代表成功
> sMsg	String	订单状态消息
inTime	String	WebSocket 网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 `1597026383085123`
outTime	String	WebSocket 网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 `1597026383085123`

WS / 批量下单

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

服务地址

/ws/v5/private (需要登录)

限速：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`：现货逐仓(仅适用于现货带单) ，现货带单时，`tdMode` 的值需要指定为`spot_isolated`
> ccy	String	否	保证金币种，仅适用于`现货和合约模式`下的全仓杠杆订单
> clOrdId	String	否	用户提供的订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
> tag	String	否	订单标签字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-16位之间。
> side	String	是	订单方向， `buy` `sell`
> posSide	String	否	持仓方向在买卖模式下，默认 `net` 在开平仓模式下必填，且仅可选择 `long` 或 `short`，仅适用于`交割/永续`
> ordType	String	是	订单类型 `market`：市价单 `limit`：限价单 `post_only`：只做maker单 `fok`：全部成交或立即取消单 `ioc`：立即成交并取消剩余单 `optimal_limit_ioc`：市价委托立即成交并取消剩余（仅适用交割、永续） `mmp`：做市商保护(仅适用于组合保证金账户模式下的期权订单) `mmp_and_post_only`：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单)
> sz	String	是	委托数量
> px	String	可选	委托价格，仅适用于`limit`、`post_only`、`fok`、`ioc`、`mmp`、`mmp_and_post_only`类型的订单期权下单时，px/pxUsd/pxVol 只能填一个
> pxUsd	String	可选	以USD价格进行期权下单仅适用于期权期权下单时 px/pxUsd/pxVol 必填一个，且只能填一个
> pxVol	String	可选	以隐含波动率进行期权下单，例如 1 代表 100% 仅适用于期权期权下单时 px/pxUsd/pxVol 必填一个，且只能填一个
> reduceOnly	Boolean	否	是否只减仓，`true` 或 `false`，默认`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	否	自成交保护模式默认为 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": "",
        "ts":"1695190491421",
        "sCode": "0",
        "sMsg": ""
    }, {
        "clOrdId": "",
        "ordId": "12344",
        "tag": "",
        "ts":"1695190491421",
        "sCode": "0",
        "sMsg": ""
    }],
    "code": "0",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

部分成功返回示例

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

全部失败返回示例

{
    "id": "1513",
    "op": "batch-orders",
    "data": [{
        "clOrdId": "oktswap6",
        "ordId": "",
        "tag": "",
        "ts":"1695190491421",
        "sCode": "5XXXX",
        "sMsg": "Insufficient margin"
    }, {
        "clOrdId": "oktswap7",
        "ordId": "",
        "tag": "",
        "ts":"1695190491421",
        "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	订单标签
> ts	String	系统完成订单请求处理的时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
> sCode	String	订单状态码，0 代表成功
> sMsg	String	事件执行失败或成功时的msg
inTime	String	WebSocket 网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 `1597026383085123`
outTime	String	WebSocket 网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 `1597026383085123`

WS / 撤单

撤销当前未完成订单

服务地址

/ws/v5/private (需要登录)

限速：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",
        "ts": "1695190491421",
        "sCode": "0",
        "sMsg": ""
    }],
    "code": "0",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

失败返回示例

{
    "id": "1514",
    "op": "cancel-order",
    "data": [{
        "clOrdId": "",
        "ordId": "2510789768709120",
        "ts": "1695190491421",
        "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
> ts	String	系统完成订单请求处理的时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
> sCode	String	订单状态码，0 代表成功
> sMsg	String	订单状态消息
inTime	String	WebSocket 网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 `1597026383085123`
outTime	String	WebSocket 网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 `1597026383085123`

WS / 批量撤单

批量进行撤单操作，每次可批量撤销不同类型的产品，最多撤销20个

服务地址

/ws/v5/private (需要登录)

限速：300个/2s

限速规则（期权以外）：UserID + Instrument ID

限速规则（只限期权）：UserID + Instrument Family

请求示例

{
    "id": "1515",
    "op": "batch-cancel-orders",
    "args": [{
        "instId": "BTC-USDT",
        "ordId": "2517748157541376"
    }, {
        "instId": "LTC-USDT",
        "ordId": "2517748155771904"
    }]
}

请求参数

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

全部成功返回示例

{
    "id": "1515",
    "op": "batch-cancel-orders",
    "data": [{
        "clOrdId": "oktswap6",
        "ordId": "2517748157541376",
        "ts": "1695190491421",
        "sCode": "0",
        "sMsg": ""
    }, {
        "clOrdId": "oktswap7",
        "ordId": "2517748155771904",
        "ts": "1695190491421",
        "sCode": "0",
        "sMsg": ""
    }],
    "code": "0",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

部分成功的返回示例

{
    "id": "1515",
    "op": "batch-cancel-orders",
    "data": [{
        "clOrdId": "oktswap6",
        "ordId": "2517748157541376",
        "ts": "1695190491421",
        "sCode": "0",
        "sMsg": ""
    }, {
        "clOrdId": "oktswap7",
        "ordId": "2517748155771904",
        "ts": "1695190491421",
        "sCode": "5XXXX",
        "sMsg": "order not exist"
    }],
    "code": "2",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

全部失败的返回示例

{
    "id": "1515",
    "op": "batch-cancel-orders",
    "data": [{
        "clOrdId": "oktswap6",
        "ordId": "2517748157541376",
        "ts": "1695190491421",
        "sCode": "5XXXX",
        "sMsg": "order not exist"
    }, {
        "clOrdId": "oktswap7",
        "ordId": "2517748155771904",
        "ts": "1695190491421",
        "sCode": "5XXXX",
        "sMsg": "order not exist"
    }],
    "code": "1",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

格式错误示例

{
    "id": "1515",
    "op": "batch-cancel-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
> ts	String	系统完成订单请求处理的时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
> sCode	String	订单状态码，0 代表成功
> sMsg	String	订单状态消息
inTime	String	WebSocket 网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 `1597026383085123`
outTime	String	WebSocket 网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 `1597026383085123`

WS / 改单

修改当前未成交的订单

服务地址

/ws/v5/private (需要登录)

限速：60次/2s

跟单交易带单产品的限速：4次/2s

限速规则（期权以外）：UserID + Instrument ID

限速规则（只限期权）：UserID + Instrument Family

该接口限速同时受到子账户限速及基于成交比率的子账户限速限速规则的影响。

请求示例

{
    "id": "1512",
    "op": "amend-order",
    "args": [{
        "instId": "BTC-USDT",
        "ordId": "2510789768709120",
        "newSz": "2"
    }]
}

请求参数

参数名	类型	是否必须	描述
id	String	是	消息的唯一标识用户提供，返回参数中会返回以便于找到相应的请求。字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	支持的业务操作，如 `amend-order`
args	Array	是	请求参数
> instId	String	是	产品ID
> cxlOnFail	Boolean	否	当订单修改失败时，该订单是否需要自动撤销。默认为`false` `false`：不自动撤单 `true`：自动撤单
> ordId	String	可选	订单ID ordId和clOrdId必须传一个，若传两个，以 ordId 为主
> clOrdId	String	可选	用户提供的订单ID
> reqId	String	否	用户提供的reqId 如果提供，那在返回参数中返回reqId，方便找到相应的修改请求。字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
> newSz	String	可选	请求修改的新数量，必须大于0。`newSz`和`newPx`不可同时为空。对于部分成交订单，该数量应包含已成交数量。
> newPx	String	可选	修改后的新价格修改的新价格期权改单时，newPx/newPxUsd/newPxVol 只能填一个，且必须与下单参数保持一致，如下单用px，改单时需使用newPx
> newPxUsd	String	可选	以USD价格进行期权改单仅适用于期权，期权改单时，newPx/newPxUsd/newPxVol 只能填一个
> newPxVol	String	可选	以隐含波动率进行期权改单，例如 1 代表 100% 仅适用于期权，期权改单时，newPx/newPxUsd/newPxVol 只能填一个
expTime	String	否	请求有效截止时间。Unix时间戳的毫秒数格式，如 `1597026383085`

成功返回示例

{
    "id": "1512",
    "op": "amend-order",
    "data": [{
        "clOrdId": "",
        "ordId": "2510789768709120",
        "ts": "1695190491421",
        "reqId": "b12344",
        "sCode": "0",
        "sMsg": ""
    }],
    "code": "0",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

失败返回示例

{
    "id": "1512",
    "op": "amend-order",
    "data": [{
        "clOrdId": "",
        "ordId": "2510789768709120",
        "ts": "1695190491421",
        "reqId": "b12344",
        "sCode": "5XXXX",
        "sMsg": "order not exist"
    }],
    "code": "1",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

格式错误返回示例

{
    "id": "1512",
    "op": "amend-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
> ts	String	系统完成订单请求处理的时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
> reqId	String	用户提供的reqId 如果用户在请求中提供reqId，则返回相应reqId
> sCode	String	订单状态码，0 代表成功
> sMsg	String	订单状态消息
inTime	String	WebSocket 网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 `1597026383085123`
outTime	String	WebSocket 网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 `1597026383085123`

WS / 批量改单

批量进行改单操作，每次可批量修改不同类型的产品，最多改20个

服务地址

/ws/v5/private (需要登录)

限速：300个/2s

跟单交易带单产品的限速：4个/2s

限速规则（期权以外）：UserID + Instrument ID

限速规则（只限期权）：UserID + Instrument Family

该接口限速同时受到子账户限速及基于成交比率的子账户限速限速规则的影响。

请求示例

{
    "id": "1513",
    "op": "batch-amend-orders",
    "args": [{
        "instId": "BTC-USDT",
        "ordId": "12345689",
        "newSz": "2"
    }, {
        "instId": "BTC-USDT",
        "ordId": "12344",
        "newSz": "2"
    }]
}

请求参数

参数名	类型	是否必须	描述
id	String	是	消息的唯一标识用户提供，返回参数中会返回以便于找到相应的请求。字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	支持的业务操作，如 `batch-amend-orders`
args	Array	是	请求参数
> instId	String	是	产品ID
> cxlOnFail	Boolean	否	当订单修改失败时，该订单是否需要自动撤销。默认为`false` `false`：不自动撤单 `true`：自动撤单
> ordId	String	可选	订单ID ordId 和 clOrdId 必须传一个，若传两个，以order id 为主
> clOrdId	String	可选	用户提供的订单ID
> reqId	String	否	用户提供的请求ID 如果提供，那在返回参数中返回reqId，方便找到相应的修改请求。字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
> newSz	String	可选	修改后的新数量，必须大于0。`newSz`和`newPx`不可同时为空。对于部分成交订单，该数量应包含已成交数量。
> newPx	String	可选	修改后的新价格修改的新价格期权改单时，newPx/newPxUsd/newPxVol 只能填一个，且必须与下单参数保持一致，如下单用px，改单时需使用newPx
> newPxUsd	String	可选	以USD价格进行期权改单仅适用于期权，期权改单时，newPx/newPxUsd/newPxVol 只能填一个
> newPxVol	String	可选	以隐含波动率进行期权改单，例如 1 代表 100% 仅适用于期权，期权改单时，newPx/newPxUsd/newPxVol 只能填一个
expTime	String	否	请求有效截止时间。Unix时间戳的毫秒数格式，如 `1597026383085`

全部成功返回示例

{
    "id": "1513",
    "op": "batch-amend-orders",
    "data": [{
        "clOrdId": "oktswap6",
        "ordId": "12345689",
        "ts": "1695190491421",
        "reqId": "b12344",
        "sCode": "0",
        "sMsg": ""
    }, {
        "clOrdId": "oktswap7",
        "ordId": "12344",
        "ts": "1695190491421",
        "reqId": "b12344",
        "sCode": "0",
        "sMsg": ""
    }],
    "code": "0",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

全部失败返回示例

{
    "id": "1513",
    "op": "batch-amend-orders",
    "data": [{
        "clOrdId": "",
        "ordId": "12345689",
        "ts": "1695190491421",
        "reqId": "b12344",
        "sCode": "5XXXX",
        "sMsg": "order not exist"
    }, {
        "clOrdId": "oktswap7",
        "ordId": "",
        "ts": "1695190491421",
        "reqId": "b12344",
        "sCode": "5XXXX",
        "sMsg": "order not exist"
    }],
    "code": "1",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

部分成功返回示例

{
    "id": "1513",
    "op": "batch-amend-orders",
    "data": [{
        "clOrdId": "",
        "ordId": "12345689",
        "ts": "1695190491421",
        "reqId": "b12344",
        "sCode": "0",
        "sMsg": ""
    }, {
        "clOrdId": "oktswap7",
        "ordId": "",
        "ts": "1695190491421",
        "reqId": "b12344",
        "sCode": "5XXXX",
        "sMsg": "order not exist"
    }],
    "code": "2",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

格式错误返回示例

{
    "id": "1513",
    "op": "batch-amend-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
> ts	String	系统完成订单请求处理的时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
> reqId	String	用户提供的请求ID 如果用户在请求中提供reqId，则返回相应reqId
> sCode	String	订单状态码，0 代表成功
> sMsg	String	订单状态消息
inTime	String	WebSocket 网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 `1597026383085123`
outTime	String	WebSocket 网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 `1597026383085123`

WS / 撤销 MMP 订单

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

服务地址

/ws/v5/private (需要登录)

限速：5次/2s

限速规则：UserID

请求示例

{
    "id": "1512",
    "op": "mass-cancel",
    "args": [{
        "instType":"OPTION",
        "instFamily":"BTC-USD"
    }]
}

请求参数

参数名	类型	是否必须	描述
id	String	是	消息的唯一标识用户提供，返回参数中会返回以便于找到相应的请求。字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	支持的业务操作，如 `mass-cancel`
args	Array	是	请求参数
> instType	String	是	交易产品类型 `OPTION`:期权
> instFamily	String	是	交易品种
> lockInterval	String	否	锁定时长(毫秒) 范围应为[0, 10 000] 默认为 0. 如果想要立即解锁，您可以设置为 "0" 下单时，如果在该锁定期间，会报错 54008，如果在 MMP 触发期间，会报错 51034

成功返回示例

{
    "id": "1512",
    "op": "mass-cancel",
    "data": [
        {
            "result": true
        }
    ],
    "code": "0",
    "msg": ""
}

格式错误返回示例

{
    "id": "1512",
    "op": "mass-cancel",
    "data": [],
    "code": "60013",
    "msg": "Invalid args"
}

返回参数

参数名	类型	描述
id	String	消息的唯一标识
op	String	业务操作
code	String	代码
msg	String	消息
data	Array	请求成功后返回的数据
> result	Boolean	撤单结果 `true`：全部撤单成功 `false`：全部撤单失败

策略交易

POST / 策略委托下单

提供单向止盈止损委托、双向止盈止损委托、追逐限价委托、计划委托、时间加权委托、移动止盈止损委托

限速：20次/2s

跟单交易带单产品的限速：1次/2s

限速规则（期权以外）：UserID + Instrument ID

限速规则（只限期权）：UserID + Instrument Family

权限：交易

HTTP请求

POST /api/v5/trade/order-algo

请求示例

# 止盈止损策略下单
POST /api/v5/trade/order-algo
body
{
    "instId":"BTC-USDT",
    "tdMode":"cross",
    "side":"buy",
    "ordType":"conditional",
    "sz":"2",
    "tpTriggerPx":"15",
    "tpOrdPx":"18"
}

# 计划委托策略下单
POST /api/v5/trade/order-algo
body
{
    "instId": "BTC-USDT-SWAP",
    "side": "buy",
    "tdMode": "cross",
    "posSide": "net",
    "sz": "1",
    "ordType": "trigger",
    "triggerPx": "25920",
    "triggerPxType": "last",
    "orderPx": "-1",
    "attachAlgoOrds": [{
        "attachAlgoClOrdId": "",
        "slTriggerPx": "100",
        "slOrdPx": "600",
        "tpTriggerPx": "25921",
        "tpOrdPx": "2001"
    }]
}

# 移动止盈止损策略下单
POST /api/v5/trade/order-algo
body
{
    "instId": "BTC-USDT-SWAP",
    "tdMode": "cross",
    "side": "buy",
    "ordType": "move_order_stop",
    "sz": "10",
    "posSide": "net",
    "callbackRatio": "0.05",
    "reduceOnly": true
}

# 时间加权策略下单
POST /api/v5/trade/order-algo
body
{
    "instId": "BTC-USDT-SWAP",
    "tdMode": "cross",
    "side": "buy",
    "ordType": "twap",
    "sz": "10",
    "posSide": "net",
    "szLimit": "10",
    "pxLimit": "100",
    "timeInterval": "10",
    "pxSpread": "10"
}

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_algo_order(
    instId="BTC-USDT",
    tdMode="cross",
    side="buy",
    ordType="conditional",
    sz="2",
    tpTriggerPx="15",
    tpOrdPx="18"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 `BTC-USDT`
tdMode	String	是	交易模式保证金模式 `isolated`：逐仓，`cross：`全仓非保证金模式 `cash`：非保证金 `spot_isolated`：现货逐仓(仅适用于现货带单)
ccy	String	否	保证金币种仅适用于`现货和合约模式`下的全仓杠杆订单
side	String	是	订单方向 `buy`：买 `sell`：卖
posSide	String	可选	持仓方向在开平仓模式下必填，且仅可选择 `long` 或 `short`
ordType	String	是	订单类型 `conditional`：单向止盈止损 `oco`：双向止盈止损 `chase`: 追逐限价委托，仅适用于交割和永续 `trigger`：计划委托 `move_order_stop`：移动止盈止损 `twap`：时间加权委托
sz	String	可选	委托数量 `sz`和`closeFraction`必填且只能填其一
tag	String	否	订单标签字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间
tgtCcy	String	否	委托数量的类型 `base_ccy`: 交易货币；`quote_ccy`：计价货币仅适用于`币币`单向止盈止损市价买单默认买为`计价货币`，卖为`交易货币`
algoClOrdId	String	否	客户自定义策略订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
closeFraction	String	可选	策略委托触发时，平仓的百分比。1 代表100% 现在系统只支持全部平仓，唯一接受参数为`1` 对于同一个仓位，仅支持一笔全部平仓的止盈止损挂单仅适用于`交割`或`永续` 当`posSide` = `net`时，`reduceOnly`必须为`true` 仅适用于止盈止损 `ordType` = `conditional` 或 `oco` 仅适用于止盈止损市价订单不支持组合保证金模式 `sz`和`closeFraction`必填且只能填其一

止盈止损

了解更多止盈止损

参数名	类型	是否必须	描述
tpTriggerPx	String	否	止盈触发价，如果填写此参数，必须填写`止盈委托价`
tpTriggerPxType	String	否	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格默认为`last`
tpOrdPx	String	否	止盈委托价，如果填写此参数，必须填写`止盈触发价` 委托价格为-1时，执行市价止盈
tpOrdKind	String	否	止盈订单类型 `condition`: 条件单 `limit`: 限价单默认为`condition`
slTriggerPx	String	否	止损触发价，如果填写此参数，必须填写`止损委托价`
slTriggerPxType	String	否	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格默认为`last`
slOrdPx	String	否	止损委托价，如果填写此参数，必须填写`止损触发价` 委托价格为`-1`时，执行市价止损
cxlOnClosePos	Boolean	否	决定用户所下的止盈止损订单是否与该交易产品对应的仓位关联。若关联，仓位被全平时，该止盈止损订单会被同时撤销；若不关联，仓位被撤销时，该止盈止损订单不受影响。有效值： `true`：下单与仓位关联的止盈止损订单 `false`：下单与仓位不关联的止盈止损订单默认值为`false`。若传入`true`，用户必须同时传入 reduceOnly = true，说明当下单与仓位关联的止盈止损订单时，必须为只减仓。适用于`现货和合约模式`、`跨币种保证金模式`。
reduceOnly	Boolean	否	是否只减仓，`true` 或 `false`，默认`false` 仅适用于`币币杠杆`，以及买卖模式下的`交割/永续` 仅适用于`现货和合约模式`和`跨币种保证金模式`
quickMgnType	String	否	一键借币类型，仅适用于杠杆逐仓的一键借币模式 `manual`：手动 `auto_borrow`：自动借币 `auto_repay`：自动还币默认是`manual`：手动（已弃用）

追逐限价委托

参数名	类型	是否必须	描述
chaseType	String	否	追逐类型。 `distance`: 买一/卖一价的距离，默认值。 `ratio`: 比例。
chaseVal	String	否	追逐值。当`chaseType`为`distance`时，是到买一/卖一价的距离。对于 USDT 本位合约，单位为 USDT；对于 USDC 合约，单位为 USDC；对于币本位合约，单位为 USD 。当`chaseType`为`ratio`时，为比率，0.1 代表 10%。默认值为 0。
maxChaseType	String	可选	最大追逐值的类型。 `distance`: 买一/卖一价的距离 `ratio`: 比例。0.1 代表 10%。 maxChaseTyep 和 maxChaseVal 需要同时填写或者不填写。
maxChaseVal	String	可选	最大追逐值。当`chaseType`为`distance`时，是到买一/卖一价的的最大距离当`chaseType`为`ratio`时，指的比率，0.1 代表 10%。
reduceOnly	Boolean	否	是否只减仓，`true` 或 `false`，默认`false` 仅适用于`币币杠杆`，以及买卖模式下的`交割/永续` 仅适用于`现货和合约模式`和`跨币种保证金模式`

计划委托

了解更多计划委托

参数名	类型	是否必须	描述
triggerPx	String	是	计划委托触发价格
orderPx	String	是	委托价格委托价格为`-1`时，执行市价委托
triggerPxType	String	否	计划委托触发价格类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格默认为`last`
quickMgnType	String	否	一键借币类型，仅适用于杠杆逐仓的一键借币模式 `manual`：手动 `auto_borrow`：自动借币 `auto_repay`：自动还币默认是`manual`（已弃用）
attachAlgoOrds	Array of object	否	附带止盈止损信息适用于`现货和合约模式/跨币种保证金模式/组合保证金模式`
> attachAlgoClOrdId	String	否	下单附带止盈止损时，客户自定义的策略订单ID，字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。订单完全成交，下止盈止损委托单时，该值会传给algoClOrdId。
> tpTriggerPx	String	否	止盈触发价，如果填写此参数，必须填写`止盈委托价`
> tpTriggerPxType	String	否	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格默认为`last`
> tpOrdPx	String	否	止盈委托价，如果填写此参数，必须填写`止盈触发价` 委托价格为`-1`时，执行市价止盈
> slTriggerPx	String	否	止损触发价，如果填写此参数，必须填写`止损委托价`
> slTriggerPxType	String	否	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格默认为`last`
> slOrdPx	String	否	止损委托价，如果填写此参数，必须填写`止损触发价` 委托价格为`-1`时，执行市价止损

移动止盈止损

了解更多移动止盈止损

参数名	类型	是否必须	描述
callbackRatio	String	可选	回调幅度的比例，如 "0.05"代表"5%" `callbackRatio`和`callbackSpread`只能传入一个
callbackSpread	String	可选	回调幅度的价距
activePx	String	否	激活价格激活价格是移动止盈止损的激活条件，当市场最新成交价达到或超过激活价格，委托被激活。激活后系统开始计算止盈止损的实际触发价格。如果不填写激活价格，即下单后就被激活。
quickMgnType	String	否	一键借币类型，仅适用于杠杆逐仓的一键借币模式： `manual`：手动 `auto_borrow`：自动借币 `auto_repay`：自动还币默认是`manual`（已弃用）
reduceOnly	Boolean	否	是否只减仓，`true` 或 `false`，默认`false` 该参数仅在 `交割/永续` 的买卖模式下有效，开平模式忽略此参数

时间加权

了解更多时间加权委托

参数名	类型	是否必须	描述
pxVar	String	可选	吃单价优于盘口的比例，取值范围在 [0.0001,0.01] 之间，如 "0.01"代表"1%" 以买入为例，市价低于限制价时，策略开始用买一价向上取一定比例的委托价来委托小额买单。当前这个参数就用来确定向上的比例。 `pxVar`和`pxSpread`只能传入一个
pxSpread	String	可选	吃单单价优于盘口的价距，取值范围不小于0（无上限）以买入为例，市价低于限制价时，策略开始用买一价向上取一定价距的委托价来委托小额买单。当前这个参数就用来确定向上的价距。
szLimit	String	是	单笔数量以买入为例，市价低于 “限制价” 时，策略开始用买一价向上取一定价距 / 比例的委托价来委托 “一定数量” 的买单。当前这个参数用来确定其中的 “一定数量”。
pxLimit	String	是	吃单限制价，取值范围不小于0（无上限）以买入为例，市价低于 “限制价” 时，策略开始用买一价向上取一定价距 / 比例的委托价来委托小额买单。当前这个参数就是其中的 “限制价”。
timeInterval	String	是	下单间隔，单位为秒。以买入为例，市价低于 “限制价” 时，策略开始按 “时间周期” 用买一价向上取一定价距 / 比例的委托价来委托小额买单。当前这个参数就是其中的 “时间周期”。

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "algoId":"12345689",
            "clOrdId": "",
            "algoClOrdId": "",
            "sCode":"0",
            "sMsg":"",
            "tag":""
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	策略委托单ID
clOrdId	String	~~客户自定义订单ID~~（已废弃）
algoClOrdId	String	客户自定义策略订单ID
sCode	String	事件执行结果的code，0代表成功
sMsg	String	事件执行失败时的msg
tag	String	订单标签

POST / 撤销策略委托订单

撤销策略委托订单，每次最多可以撤销10个策略委托单

限速：20次/2s

限速规则（期权以外）：UserID + Instrument ID

限速规则（只限期权）：UserID + Instrument Family

权限：交易

HTTP请求

POST /api/v5/trade/cancel-algos

请求示例

POST /api/v5/trade/cancel-algos
body
[
    {
        "algoId":"590919993110396111",
        "instId":"BTC-USDT"
    },
    {
        "algoId":"590920138287841222",
        "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)

# 支持止盈止损，计划委托 类型的策略撤单
algo_orders = [
    {"instId": "BTC-USDT", "algoId": "590919993110396111"},
    {"instId": "BTC-USDT", "algoId": "590920138287841222"}
]

result = tradeAPI.cancel_algo_order(algo_orders)
print(result)

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略委托单ID
instId	String	是	产品ID 如 `BTC-USDT`

返回结果

{
    "code": "0",
    "data": [
        {
            "algoClOrdId": "",
            "algoId": "1836489397437468672",
            "clOrdId": "",
            "sCode": "0",
            "sMsg": "",
            "tag": ""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略委托单ID
sCode	String	事件执行结果的code，0代表成功
sMsg	String	事件执行失败时的msg
clOrdId	String	~~客户自定义订单ID~~（已废弃）
algoClOrdId	String	~~客户自定义策略订单ID~~（已废弃）
tag	String	~~订单标签~~（已废弃）

POST / 修改策略委托订单

修改策略委托订单（仅支持止盈止损和计划委托订单，不包含、冰山委托、时间加权、移动止盈止损等订单）

限速：20次/2s

限速规则：UserID + Instrument ID

权限：交易

HTTP请求

POST /api/v5/trade/amend-algos

请求示例

POST /api/v5/trade/amend-algos
body
{
    "algoId":"2510789768709120",
    "newSz":"2",
    "instId":"BTC-USDT"
}

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID
algoId	String	可选	策略委托单ID `algoId`和`algoClOrdId`必须传一个，若传两个，以`algoId`为主
algoClOrdId	String	可选	客户自定义策略订单ID `algoId`和`algoClOrdId`必须传一个，若传两个，以`algoId`为主
cxlOnFail	Boolean	否	当订单修改失败时，该订单是否需要自动撤销。默认为`false` `false`：不自动撤单 `true`：自动撤单
reqId	String	否	用户自定义修改事件ID，字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间
newSz	String	可选	修改的新数量，必须大于0。

止盈止损

参数名	类型	是否必须	描述
newTpTriggerPx	String	可选	止盈触发价如果止盈触发价或者委托价为0，那代表删除止盈
newTpOrdPx	String	可选	止盈委托价委托价格为-1时，执行市价止盈
newSlTriggerPx	String	可选	止损触发价如果止损触发价或者委托价为0，那代表删除止损
newSlOrdPx	String	可选	止损委托价委托价格为-1时，执行市价止损
newTpTriggerPxType	String	可选	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
newSlTriggerPxType	String	可选	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格

计划委托

参数名	类型	是否必须	描述
newTriggerPx	String	是	修改后的触发价格
newOrdPx	String	是	修改后的委托价格委托价格为`-1`时，执行市价委托
newTriggerPxType	String	否	修改后的计划委托触发价格类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格默认为`last`
attachAlgoOrds	Array of object	否	修改附带止盈止损信息适用于`现货和合约模式/跨币种保证金模式/组合保证金模式`
> newTpTriggerPx	String	否	止盈触发价，如果填写此参数，必须填写`止盈委托价`
> newTpTriggerPxType	String	否	修改后的止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格默认为`last`
> newTpOrdPx	String	否	止盈委托价，如果填写此参数，必须填写`止盈触发价` 委托价格为`-1`时，执行市价止盈
> newSlTriggerPx	String	否	止损触发价，如果填写此参数，必须填写`止损委托价`
> newSlTriggerPxType	String	否	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格默认为`last`
> newSlOrdPx	String	否	止损委托价，如果填写此参数，必须填写`止损触发价` 委托价格为`-1`时，执行市价止损

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "algoClOrdId":"algo_01",
            "algoId":"2510789768709120",
            "reqId":"po103ux",
            "sCode":"0",
            "sMsg":""
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	订单ID
algoClOrdId	String	客户自定义策略订单ID
reqId	String	用户自定义修改事件ID，字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间
sCode	String	事件执行结果的code，0代表成功
sMsg	String	事件执行失败时的msg

POST / 撤销高级策略委托订单

该接口即将下线，建议使用撤销策略委托订单
撤销、时间加权、移动止盈止损委托订单，每次最多可以撤销10个策略委托单

限速：20次/2s

限速规则（期权以外）：UserID + Instrument ID

限速规则（只限期权）：UserID + Instrument Family

权限：交易

HTTP请求

POST /api/v5/trade/cancel-advance-algos

请求示例

POST /api/v5/trade/cancel-advance-algos
body
[
    {
        "algoId":"590920768125665111",
        "instId":"BTC-USDT"
    },
    {
        "algoId":"590920799650058222",
        "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)

# 支持 冰山委托，时间加权委托，移动止盈止损 类型的策略撤单
algo_orders_advance = [
    {"instId": "BTC-USDT", "algoId": "590920768125665111"},
    {"instId": "BTC-USDT", "algoId": "590920799650058222"}
]

result = tradeAPI.cancel_advance_algos(algo_orders_advance)
print(result)

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略委托单ID
instId	String	是	产品ID 如 `BTC-USDT`

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "algoId":"1234",
            "sCode":"0",
            "sMsg":""
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	订单ID
sCode	String	事件执行结果的code，0代表成功
sMsg	String	事件执行失败时的msg

GET / 获取策略委托单信息

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/trade/order-algo

请求示例

GET /api/v5/trade/order-algo?algoId=1753184812254216192

请求参数

参数名	类型	是否必须	描述
algoId	String	可选	策略委托单ID `algoId`和`algoClOrdId`必须传一个，若传两个，以`algoId`为主
algoClOrdId	String	可选	客户自定义策略订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。

返回结果

{
    "code": "0",
    "data": [
        {
            "activePx": "",
            "actualPx": "",
            "actualSide": "",
            "actualSz": "0",
            "algoClOrdId": "",
            "algoId": "1753184812254216192",
            "amendPxOnTriggerType": "0",
            "attachAlgoOrds": [],
            "cTime": "1724751378980",
            "callbackRatio": "",
            "callbackSpread": "",
            "ccy": "",
            "chaseType": "",
            "chaseVal": "",
            "clOrdId": "",
            "closeFraction": "",
            "failCode": "0",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "isTradeBorrowMode": "",
            "last": "62916.5",
            "lever": "",
            "linkedOrd": {
                "ordId": ""
            },
            "maxChaseType": "",
            "maxChaseVal": "",
            "moveTriggerPx": "",
            "ordId": "",
            "ordIdList": [],
            "ordPx": "",
            "ordType": "conditional",
            "posSide": "net",
            "pxLimit": "",
            "pxSpread": "",
            "pxVar": "",
            "quickMgnType": "",
            "reduceOnly": "false",
            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "state": "live",
            "sz": "10",
            "szLimit": "",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "quote_ccy",
            "timeInterval": "",
            "tpOrdPx": "-1",
            "tpTriggerPx": "10000",
            "tpTriggerPxType": "last",
            "triggerPx": "",
            "triggerPxType": "",
            "triggerTime": "",
            "uTime": "1724751378980"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instType	String	产品类型
instId	String	产品ID
ccy	String	保证金币种，仅适用于`现货和合约模式`下的全仓杠杆订单
ordId	String	最新一笔订单ID，即将废弃。
ordIdList	Array	订单ID列表，当止盈止损存在市价拆单时，会有多个。
algoId	String	策略委托单ID
clOrdId	String	客户自定义订单ID
sz	String	委托数量
closeFraction	String	策略委托触发时，平仓的百分比。1 代表100%
ordType	String	订单类型
side	String	订单方向
posSide	String	持仓方向
tdMode	String	交易模式
tgtCcy	String	币币市价单委托数量`sz`的单位 `base_ccy`: 交易货币；`quote_ccy`：计价货币仅适用于`币币`市价订单默认买单为`quote_ccy`，卖单为`base_ccy`
state	String	订单状态 `live`：待生效 `pause`：暂停生效 `partially_effective`:部分生效 `effective`：已生效 `canceled`：已撤销 `order_failed`：委托失败 `partially_failed`：部分委托失败
lever	String	杠杆倍数，0.01到125之间的数值，仅适用于 `币币杠杆/交割/永续`
tpTriggerPx	String	止盈触发价
tpTriggerPxType	String	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
tpOrdPx	String	止盈委托价
slTriggerPx	String	止损触发价
slTriggerPxType	String	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
slOrdPx	String	止损委托价
triggerPx	String	计划委托触发价格
triggerPxType	String	计划委托触发价格类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
ordPx	String	计划委托单的委托价格
actualSz	String	实际委托量
actualPx	String	实际委托价
actualSide	String	实际触发方向 `tp`：止盈 `sl`：止损仅适用于`单向止盈止损委托`和`双向止盈止损委托`
triggerTime	String	策略委托触发时间，Unix时间戳的毫秒数格式，如 `1597026383085`
pxVar	String	价格比例仅适用于`冰山委托`和`时间加权委托`
pxSpread	String	价距仅适用于`冰山委托`和`时间加权委托`
szLimit	String	单笔数量仅适用于`冰山委托`和`时间加权委托`
pxLimit	String	挂单限制价仅适用于`冰山委托`和`时间加权委托`
tag	String	订单标签
timeInterval	String	下单间隔仅适用于`时间加权委托`
callbackRatio	String	回调幅度的比例仅适用于`移动止盈止损`
callbackSpread	String	回调幅度的价距仅适用于`移动止盈止损`
activePx	String	移动止盈止损激活价格仅适用于`移动止盈止损`
moveTriggerPx	String	移动止盈止损触发价格仅适用于`移动止盈止损`
reduceOnly	String	是否只减仓 `true`或`false`
quickMgnType	String	一键借币类型，仅适用于杠杆逐仓的一键借币模式 `manual`：手动，`auto_borrow`：自动借币，`auto_repay`：自动还币
last	String	下单时的最新成交价
failCode	String	代表策略触发失败的原因，已撤销和已生效时为""，委托失败时有值，如 51008；仅适用于单向止盈止损委托、双向止盈止损委托、移动止盈止损委托、计划委托。
algoClOrdId	String	客户自定义策略订单ID
amendPxOnTriggerType	String	是否启用开仓价止损仅适用于分批止盈的止损订单 `0`：不开启，默认值 `1`：开启
attachAlgoOrds	Array of object	附带止盈止损信息适用于`现货和合约模式/跨币种保证金模式/组合保证金模式`
> attachAlgoClOrdId	String	下单附带止盈止损时，客户自定义的策略订单ID，字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。订单完全成交，下止盈止损委托单时，该值会传给algoClOrdId。
> tpTriggerPx	String	止盈触发价，如果填写此参数，必须填写`止盈委托价`
> tpTriggerPxType	String	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
> tpOrdPx	String	止盈委托价，如果填写此参数，必须填写`止盈触发价` 委托价格为`-1`时，执行市价止盈
> slTriggerPx	String	止损触发价，如果填写此参数，必须填写`止损委托价`
> slTriggerPxType	String	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
> slOrdPx	String	止损委托价，如果填写此参数，必须填写`止损触发价` 委托价格为`-1`时，执行市价止损
linkedOrd	Object	止盈订单信息，仅适用于止损单，且该止损订单来自包含限价止盈单的双向止盈止损订单
> ordId	String	订单 ID
cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	订单更新时间，Unix时间戳的毫秒数格式，如 1597026383085
isTradeBorrowMode	String	是否自动借币 true：自动借币 false：不自动借币仅适用于计划委托、移动止盈止损和时间加权策略
chaseType	String	追逐类型。仅适用于`追逐限价委托`。
chaseVal	String	追逐值。仅适用于`追逐限价委托`。
maxChaseType	String	最大追逐值的类型。仅适用于`追逐限价委托`。
maxChaseVal	String	最大追逐值。仅适用于`追逐限价委托`。

GET / 获取未完成策略委托单列表

获取当前账户下未触发的策略委托单列表

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/trade/orders-algo-pending

请求示例

GET /api/v5/trade/orders-algo-pending?ordType=conditional

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.order_algos_list(
    ordType="conditional"
)
print(result)

请求参数

参数名	类型	是否必须	描述
algoId	String	否	策略委托单ID
instType	String	否	产品类型 `SPOT`：币币 `SWAP`：永续合约 `FUTURES`：交割合约 `MARGIN`：杠杆
instId	String	否	产品ID，如 `BTC-USDT`
ordType	String	是	订单类型 `conditional`：单向止盈止损 `oco`：双向止盈止损 `chase`: 追逐限价委托，仅适用于交割和永续 `trigger`：计划委托 `move_order_stop`：移动止盈止损 `twap`：时间加权委托支持 `conditional` 和 `oco` 同时查询，半角逗号分隔，对于其他类型，一次请求仅支持查询一个
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的`algoId`
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的`algoId`
limit	String	否	返回结果的数量，最大为100，默认100条
algoClOrdId	String	否	客户自定义策略订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。

返回结果

{
    "code": "0",
    "data": [
        {
            "activePx": "",
            "actualPx": "",
            "actualSide": "",
            "actualSz": "0",
            "algoClOrdId": "",
            "algoId": "1753184812254216192",
            "amendPxOnTriggerType": "0",
            "attachAlgoOrds": [],
            "cTime": "1724751378980",
            "callbackRatio": "",
            "callbackSpread": "",
            "ccy": "",
            "chaseType": "",
            "chaseVal": "",
            "clOrdId": "",
            "closeFraction": "",
            "failCode": "0",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "isTradeBorrowMode": "",
            "last": "62916.5",
            "lever": "",
            "linkedOrd": {
                "ordId": ""
            },
            "maxChaseType": "",
            "maxChaseVal": "",
            "moveTriggerPx": "",
            "ordId": "",
            "ordIdList": [],
            "ordPx": "",
            "ordType": "conditional",
            "posSide": "net",
            "pxLimit": "",
            "pxSpread": "",
            "pxVar": "",
            "quickMgnType": "",
            "reduceOnly": "false",
            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "state": "live",
            "sz": "10",
            "szLimit": "",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "quote_ccy",
            "timeInterval": "",
            "tpOrdPx": "-1",
            "tpTriggerPx": "10000",
            "tpTriggerPxType": "last",
            "triggerPx": "",
            "triggerPxType": "",
            "triggerTime": "",
            "uTime": "1724751378980"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instType	String	产品类型
instId	String	产品ID
ccy	String	保证金币种，仅适用于`现货和合约模式`下的全仓杠杆订单
ordId	String	最新一笔订单ID，即将废弃。
ordIdList	Array	订单ID列表，当止盈止损存在市价拆单时，会有多个。
algoId	String	策略委托单ID
clOrdId	String	客户自定义订单ID
sz	String	委托数量
closeFraction	String	策略委托触发时，平仓的百分比。1 代表100%
ordType	String	订单类型
side	String	订单方向
posSide	String	持仓方向
tdMode	String	交易模式
tgtCcy	String	币币市价单委托数量`sz`的单位 `base_ccy`：交易货币 `quote_ccy`：计价货币仅适用于`币币`市价订单默认买单为`quote_ccy`，卖单为`base_ccy`
state	String	订单状态 `live`：待生效 `pause`：暂停生效
lever	String	杠杆倍数，0.01到125之间的数值仅适用于 `币币杠杆`/`交割`/`永续`
tpTriggerPx	String	止盈触发价
tpTriggerPxType	String	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
tpOrdPx	String	止盈委托价
slTriggerPx	String	止损触发价
slTriggerPxType	String	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
slOrdPx	String	止损委托价
triggerPx	String	计划委托触发价格
triggerPxType	String	计划委托触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
ordPx	String	计划委托单的委托价格
actualSz	String	实际委托量
actualPx	String	实际委托价
actualSide	String	实际触发方向 `tp`：止盈 `sl`：止损仅适用于`单向止盈止损委托`和`双向止盈止损委托`
triggerTime	String	策略委托触发时间，Unix时间戳的毫秒数格式，如 `1597026383085`
pxVar	String	价格比例仅适用于`冰山委托`和`时间加权委托`
pxSpread	String	价距仅适用于`冰山委托`和`时间加权委托`
szLimit	String	单笔数量仅适用于`冰山委托`和`时间加权委托`
tag	String	订单标签
pxLimit	String	挂单限制价仅适用于`冰山委托`和`时间加权委托`
timeInterval	String	下单间隔仅适用于`时间加权委托`
callbackRatio	String	回调幅度的比例仅适用于`移动止盈止损`
callbackSpread	String	回调幅度的价距仅适用于`移动止盈止损`
activePx	String	移动止盈止损激活价格仅适用于`移动止盈止损`
moveTriggerPx	String	移动止盈止损触发价格仅适用于`移动止盈止损`
reduceOnly	String	是否只减仓 `true` 或 `false`
quickMgnType	String	一键借币类型，仅适用于杠杆逐仓的一键借币模式 `manual`：手动 `auto_borrow`：自动借币 `auto_repay`：自动还币
last	String	下单时的最新成交价
failCode	String	代表策略触发失败的原因，委托失败时有值，如 51008，对于该接口一直为""。
algoClOrdId	String	客户自定义策略订单ID
amendPxOnTriggerType	String	是否启用开仓价止损，仅适用于分批止盈的止损订单 `0`：不开启，默认值 `1`：开启
attachAlgoOrds	Array of object	附带止盈止损信息适用于`现货和合约模式/跨币种保证金模式/组合保证金模式`
> attachAlgoClOrdId	String	下单附带止盈止损时，客户自定义的策略订单ID，字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。订单完全成交，下止盈止损委托单时，该值会传给algoClOrdId。
> tpTriggerPx	String	止盈触发价，如果填写此参数，必须填写`止盈委托价`
> tpTriggerPxType	String	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
> tpOrdPx	String	止盈委托价，如果填写此参数，必须填写`止盈触发价` 委托价格为`-1`时，执行市价止盈
> slTriggerPx	String	止损触发价，如果填写此参数，必须填写`止损委托价`
> slTriggerPxType	String	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
> slOrdPx	String	止损委托价，如果填写此参数，必须填写`止损触发价` 委托价格为`-1`时，执行市价止损
linkedOrd	Object	止盈订单信息，仅适用于止损单，且该止损订单来自包含限价止盈单的双向止盈止损订单
> ordId	String	订单 ID
cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	订单更新时间，Unix时间戳的毫秒数格式，如 1597026383085
isTradeBorrowMode	String	是否自动借币 true：自动借币 false：不自动借币仅适用于计划委托、移动止盈止损和时间加权策略
chaseType	String	追逐类型。仅适用于`追逐限价委托`。
chaseVal	String	追逐值。仅适用于`追逐限价委托`。
maxChaseType	String	最大追逐值的类型。仅适用于`追逐限价委托`。
maxChaseVal	String	最大追逐值。仅适用于`追逐限价委托`。

GET / 获取历史策略委托单列表

获取最近3个月当前账户下所有策略委托单列表

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

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

请求示例

GET /api/v5/trade/orders-algo-history?ordType=conditional&state=effective

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.order_algos_history(
    state="effective",
    ordType="conditional"
)
print(result)

请求参数

参数名	类型	是否必须	描述
ordType	String	是	订单类型 `conditional`：单向止盈止损 `oco`：双向止盈止损 `chase`: 追逐限价委托，仅适用于交割和永续 `trigger`：计划委托 `move_order_stop`：移动止盈止损 `twap`：时间加权委托支持 `conditional` 和 `oco` 同时查询，半角逗号分隔，对于其他类型，一次请求仅支持查询一个
state	String	可选	订单状态 `effective`：已生效 `canceled`：已经撤销 `order_failed`：委托失败 `state`和`algoId`必填且只能填其一
algoId	String	可选	策略委托单ID
instType	String	否	产品类型 `SPOT`：币币 `SWAP`：永续合约 `FUTURES`：交割合约 `MARGIN`：杠杆
instId	String	否	产品ID，`BTC-USDT`
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的`algoId`
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的`algoId`
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "activePx": "",
            "actualPx": "",
            "actualSide": "tp",
            "actualSz": "100",
            "algoClOrdId": "",
            "algoId": "1880721064716505088",
            "amendPxOnTriggerType": "0",
            "attachAlgoOrds": [],
            "cTime": "1728552255493",
            "callbackRatio": "",
            "callbackSpread": "",
            "ccy": "",
            "chaseType": "",
            "chaseVal": "",
            "clOrdId": "",
            "closeFraction": "1",
            "failCode": "1",
            "instId": "BTC-USDT-SWAP",
            "instType": "SWAP",
            "isTradeBorrowMode": "",
            "last": "60777.5",
            "lever": "10",
            "linkedOrd": {
                "ordId": ""
            },
            "maxChaseType": "",
            "maxChaseVal": "",
            "moveTriggerPx": "",
            "ordId": "1884789786215137280",
            "ordIdList": [
                "1884789786215137280"
            ],
            "ordPx": "",
            "ordType": "oco",
            "posSide": "long",
            "pxLimit": "",
            "pxSpread": "",
            "pxVar": "",
            "quickMgnType": "",
            "reduceOnly": "true",
            "side": "sell",
            "slOrdPx": "-1",
            "slTriggerPx": "57000",
            "slTriggerPxType": "mark",
            "state": "effective",
            "sz": "100",
            "szLimit": "",
            "tag": "",
            "tdMode": "isolated",
            "tgtCcy": "",
            "timeInterval": "",
            "tpOrdPx": "-1",
            "tpTriggerPx": "63000",
            "tpTriggerPxType": "last",
            "triggerPx": "",
            "triggerPxType": "",
            "triggerTime": "1728673513447",
            "uTime": "1728673513447"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instType	String	产品类型
instId	String	产品ID
ccy	String	保证金币种，仅适用于`现货和合约模式`下的全仓杠杆订单
ordId	String	最新一笔订单ID，即将废弃。
ordIdList	Array	订单ID列表，当止盈止损存在市价拆单时，会有多个。
algoId	String	策略委托单ID
clOrdId	String	客户自定义订单ID
sz	String	委托数量
closeFraction	String	策略委托触发时，平仓的百分比。1 代表100%
ordType	String	订单类型
side	String	订单方向
posSide	String	持仓方向
tdMode	String	交易模式
tgtCcy	String	币币市价单委托数量`sz`的单位 `base_ccy`: 交易货币；`quote_ccy`：计价货币仅适用于`币币`市价订单默认买单为`quote_ccy`，卖单为`base_ccy`
state	String	订单状态 `effective`：已生效 `canceled`：已撤销 `order_failed`：委托失败 `partially_failed`：部分委托失败
lever	String	杠杆倍数，0.01到125之间的数值仅适用于 `币币杠杆`/`交割`/永续`
tpTriggerPx	String	止盈触发价
tpTriggerPxType	String	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
tpOrdPx	String	止盈委托价
slTriggerPx	String	止损触发价
slTriggerPxType	String	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
slOrdPx	String	止损委托价
triggerPx	String	计划委托触发价格
triggerPxType	String	计划委托委托价格类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
ordPx	String	计划委托委托价格
actualSz	String	实际委托量
actualPx	String	实际委托价
actualSide	String	实际触发方向 `tp`：止盈 `sl`：止损仅适用于`单向止盈止损委托`和`双向止盈止损委托`
triggerTime	String	策略委托触发时间，Unix时间戳的毫秒数格式，如 `1597026383085`
pxVar	String	价格比例仅适用于`冰山委托`和`时间加权委托`
pxSpread	String	价距仅适用于`冰山委托`和`时间加权委托`
szLimit	String	单笔数量仅适用于`冰山委托`和`时间加权委托`
pxLimit	String	挂单限制价仅适用于`冰山委托`和`时间加权委托`
tag	String	订单标签
timeInterval	String	下单间隔仅适用于`时间加权委托`
callbackRatio	String	回调幅度的比例仅适用于`移动止盈止损`
callbackSpread	String	回调幅度的价距仅适用于`移动止盈止损`
activePx	String	移动止盈止损激活价格仅适用于`移动止盈止损`
moveTriggerPx	String	移动止盈止损触发价格仅适用于`移动止盈止损`
reduceOnly	String	是否只减仓 `true`或`false`
quickMgnType	String	一键借币类型，仅适用于杠杆逐仓的一键借币模式 `manual`：手动，`auto_borrow`：自动借币，`auto_repay`：自动还币
last	String	下单时的最新成交价
failCode	String	代表策略触发失败的原因，已撤销和已生效时为""，委托失败时有值，如 51008；仅适用于单向止盈止损委托、双向止盈止损委托、移动止盈止损委托、计划委托。
algoClOrdId	String	客户自定义策略订单ID
amendPxOnTriggerType	String	是否启用开仓价止损，仅适用于分批止盈的止损订单 `0`：不开启，默认值 `1`：开启
attachAlgoOrds	Array of object	附带止盈止损信息适用于`现货和合约模式/跨币种保证金模式/组合保证金模式`
> attachAlgoClOrdId	String	下单附带止盈止损时，客户自定义的策略订单ID，字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。订单完全成交，下止盈止损委托单时，该值会传给algoClOrdId。
> tpTriggerPx	String	止盈触发价，如果填写此参数，必须填写`止盈委托价`
> tpTriggerPxType	String	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
> tpOrdPx	String	止盈委托价，如果填写此参数，必须填写`止盈触发价` 委托价格为`-1`时，执行市价止盈
> slTriggerPx	String	止损触发价，如果填写此参数，必须填写`止损委托价`
> slTriggerPxType	String	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
> slOrdPx	String	止损委托价，如果填写此参数，必须填写`止损触发价` 委托价格为`-1`时，执行市价止损
linkedOrd	Object	止盈订单信息，仅适用于止损单，且该止损订单来自包含限价止盈单的双向止盈止损订单
> ordId	String	订单 ID
cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	订单更新时间，Unix时间戳的毫秒数格式，如 1597026383085
isTradeBorrowMode	String	是否自动借币 true：自动借币 false：不自动借币仅适用于计划委托、移动止盈止损和时间加权策略
chaseType	String	追逐类型。仅适用于`追逐限价委托`。
chaseVal	String	追逐值。仅适用于`追逐限价委托`。
maxChaseType	String	最大追逐值的类型。仅适用于`追逐限价委托`。
maxChaseVal	String	最大追逐值。仅适用于`追逐限价委托`。

WS / 策略委托订单频道

获取策略委托订单，首次订阅不推送，只有当下单、撤单等事件触发时，推送数据

服务地址

/ws/v5/business (需要登录)

请求示例：单个

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

请求示例

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

请求参数

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

成功返回示例：单个

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

成功返回示例

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

失败返回示例

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

返回参数

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

推送示例：单个

{
    "arg": {
        "channel": "orders-algo",
        "uid": "77982378738415879",
        "instType": "FUTURES",
        "instId": "BTC-USD-200329"
    },
    "data": [{
        "actualPx": "0",
        "actualSide": "",
        "actualSz": "0",
        "algoClOrdId": "",
        "algoId": "581878926302093312",
        "attachAlgoOrds": [],
        "amendResult": "",
        "cTime": "1685002746818",
        "uTime": "1708679675245",
        "ccy": "",
        "clOrdId": "",
        "closeFraction": "",
        "failCode": "",
        "instId": "BTC-USDC",
        "instType": "SPOT",
        "last": "26174.8",
        "lever": "0",
        "notionalUsd": "11.0",
        "ordId": "",
        "ordIdList": [],
        "ordPx": "",
        "ordType": "conditional",
        "posSide": "",
        "quickMgnType": "",
        "reduceOnly": "false",
        "reqId": "",
        "side": "buy",
        "slOrdPx": "",
        "slTriggerPx": "",
        "slTriggerPxType": "",
        "state": "live",
        "sz": "11",
        "tag": "",
        "tdMode": "cross",
        "tgtCcy": "quote_ccy",
        "tpOrdPx": "-1",
        "tpTriggerPx": "1",
        "tpTriggerPxType": "last",
        "triggerPx": "",
        "triggerTime": "",
        "amendPxOnTriggerType": "0",
        "linkedOrd":{
            "ordId":"98192973880283"
        },
        "isTradeBorrowMode": ""
    }]
}

推送数据参数

参数名	类型	描述
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，与策略委托订单关联的订单ID，即将废弃。
> ordIdList	Array	订单ID列表，当止盈止损存在市价拆单时，会有多个。
> algoId	String	策略委托单ID
> clOrdId	String	客户自定义订单ID
> sz	String	委托数量，`币币/币币杠杆` 以币为单位；`交割/永续/期权` 以张为单位
> ordType	String	订单类型 `conditional`：单向止盈止损 `oco`：双向止盈止损 `trigger`：计划委托
> side	String	订单方向，`buy` `sell`
> posSide	String	持仓方向 `long`：开平仓模式开多 `short`：开平仓模式开空 `net`：买卖模式
> tdMode	String	交易模式保证金模式 `cross`：全仓 `isolated`：逐仓非保证金模式 `cash`：现金
> tgtCcy	String	币币市价单委托数量`sz`的单位 `base_ccy`：交易货币 `quote_ccy`：计价货币仅适用于`币币`市价订单默认买单为`quote_ccy`，卖单为`base_ccy`
> lever	String	杠杆倍数，0.01到125之间的数值，仅适用于 `币币杠杆/交割/永续`
> state	String	订单状态 `live`：待生效 `effective`：已生效 `canceled`：已撤销 `order_failed`：委托失败 `partially_failed`：部分委托失败 `partially_effective`: 部分生效
> tpTriggerPx	String	止盈触发价
> tpTriggerPxType	String	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
> tpOrdPx	String	止盈委托价，委托价格为`-1`时，执行市价止盈
> slTriggerPx	String	止损触发价
> slTriggerPxType	String	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
> slOrdPx	String	止损委托价委托价格为`-1`时，执行市价止损
> triggerPx	String	计划委托单的触发价格
> triggerPxType	String	计划委托单的触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
> ordPx	String	计划委托单的委托价格
> last	String	下单时的最新成交价
> actualSz	String	实际委托量
> actualPx	String	实际委价
> tag	String	订单标签
> notionalUsd	String	委托单预估美元价值
> actualSide	String	实际触发方向 `sl`：止损 `tp`：止盈仅适用于`单向止盈止损委托`和`双向止盈止损委托`
> triggerTime	String	策略委托触发时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> reduceOnly	String	是否只减仓，`true` 或 `false`
> failCode	String	代表策略触发失败的原因，已撤销和已生效时为""，委托失败时有值，如 51008；仅适用于单向止盈止损委托、双向止盈止损委托、移动止盈止损委托、计划委托。
> algoClOrdId	String	客户自定义策略订单ID
> reqId	String	修改订单时使用的request ID，如果没有修改，该字段为""
> amendResult	String	修改订单的结果 `-1`：失败 `0`：成功
> amendPxOnTriggerType	String	是否启用开仓价止损，仅适用于分批止盈的止损订单 `0`：不开启，默认值 `1`：开启
> attachAlgoOrds	Array of object	附带止盈止损信息适用于`现货和合约模式/跨币种保证金模式/组合保证金模式`
>> attachAlgoClOrdId	String	下单附带止盈止损时，客户自定义的策略订单ID，字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。订单完全成交，下止盈止损委托单时，该值会传给algoClOrdId。
>> tpTriggerPx	String	止盈触发价，如果填写此参数，必须填写`止盈委托价`
>> tpTriggerPxType	String	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
>> tpOrdPx	String	止盈委托价，如果填写此参数，必须填写`止盈触发价` 委托价格为`-1`时，执行市价止盈
>> slTriggerPx	String	止损触发价，如果填写此参数，必须填写`止损委托价`
>> slTriggerPxType	String	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格
>> slOrdPx	String	止损委托价，如果填写此参数，必须填写`止损触发价` 委托价格为`-1`时，执行市价止损
> linkedOrd	Object	止盈订单信息，仅适用于止损单，且该止损订单来自包含限价止盈单的双向止盈止损订单
>> ordId	String	订单 ID
> cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> uTime	String	订单更新时间，Unix时间戳的毫秒数格式，如 1597026383085
> isTradeBorrowMode	String	是否自动借币 true：自动借币 false：不自动借币仅适用于计划委托、移动止盈止损和时间加权策略
> chaseType	String	追逐类型。仅适用于`追逐限价委托`。
> chaseVal	String	追逐值。仅适用于`追逐限价委托`。
> maxChaseType	String	最大追逐值的类型。仅适用于`追逐限价委托`。
> maxChaseVal	String	最大追逐值。仅适用于`追逐限价委托`。

WS / 高级策略委托订单频道

获取高级策略委托订单（冰山、时间加权、移动止盈止损），首次订阅推送，当下单、撤单等事件触发时，推送数据

服务地址

/ws/v5/business (需要登录)

请求示例：单个

{
    "op": "subscribe",
    "args": [{
        "channel": "algo-advance",
        "instType": "SPOT",
        "instId": "BTC-USDT"
    }]
}

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "algo-advance",
        "instType": "SPOT",
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，`subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `algo-advance`
> instType	String	是	产品类型 `SPOT`：币币 `MARGIN`：币币杠杆 `SWAP`：永续合约 `FUTURES`：交割合约 `ANY`：全部
> instId	String	否	产品ID
> algoId	String	否	策略ID

成功返回示例：单个

{
    "event": "subscribe",
    "arg": {
        "channel": "algo-advance",
        "instType": "SPOT",
        "instId": "BTC-USDT"
    },
    "connId": "a4d3ae55"
}

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "algo-advance",
        "instType": "SPOT"
    },
    "connId": "a4d3ae55"
}

失败返回示例

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

返回参数

参数	类型	是否必须	描述
event	String	是	事件 `subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名
> instType	String	是	产品类型 `SPOT`：币币 `MARGIN`：币币杠杆 `SWAP`：永续合约 `FUTURES`：交割合约 `ANY`：全部
> instId	String	否	产品ID
> algoId	String	否	策略ID
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket连接ID

推送示例：单个

{
    "arg":{
        "channel":"algo-advance",
        "uid": "77982378738415879",
        "instType":"SPOT",
        "instId":"BTC-USDT"
    },
    "data":[
        {
            "actualPx":"",
            "actualSide":"",
            "actualSz":"0",
            "algoId":"355056228680335360",
            "cTime":"1630924001545",
            "ccy":"",
            "clOrdId": "",
            "count":"1",
            "instId":"BTC-USDT",
            "instType":"SPOT",
            "lever":"0",
            "notionalUsd":"",
            "ordPx":"",
            "ordType":"iceberg",
            "pTime":"1630924295204",
            "posSide":"net",
            "pxLimit":"10",
            "pxSpread":"1",
            "pxVar":"",
            "side":"buy",
            "slOrdPx":"",
            "slTriggerPx":"",
            "state":"pause",
            "sz":"0.1",
            "szLimit":"0.1",
            "tag": "adadadadad",
            "tdMode":"cash",
            "timeInterval":"",
            "tpOrdPx":"",
            "tpTriggerPx":"",
            "triggerPx":"",
            "triggerTime":"",
            "callbackRatio":"",
            "callbackSpread":"",
            "activePx":"",
            "moveTriggerPx":"",
            "failCode": "",
            "algoClOrdId": "",
            "reduceOnly": "",
            "isTradeBorrowMode": true
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> uid	String	用户标识
> instType	String	产品类型
> instId	String	产品ID
> algoId	String	策略ID
data	Array	订阅的数据
> instType	String	产品类型
> instId	String	产品ID
> ccy	String	保证金币种，仅`现货和合约模式`下的全仓币币杠杆需要选择保证金币种
> ordId	String	订单ID，与策略委托订单关联的订单ID
> algoId	String	策略委托单ID
> clOrdId	String	客户自定义订单ID
> sz	String	委托数量，`币币/币币杠杆` 以币为单位；`交割/永续/期权` 以张为单位
> ordType	String	订单类型 `iceberg`：冰山委托 `twap`：时间加权委托 `move_order_stop`：移动止盈止损
> side	String	订单方向，`buy` `sell`
> posSide	String	持仓方向 `long`：开平仓模式开多 `short`：开平仓模式开空 `net`：买卖模式
> tdMode	String	交易模式保证金模式 `cross`：全仓 `isolated`：逐仓非保证金模式 `cash`：现金
> tgtCcy	String	币币市价单委托数量`sz`的单位 `base_ccy`: 交易货币；`quote_ccy`：计价货币仅适用于`币币`市价订单默认买单为`quote_ccy`，卖单为`base_ccy`
> lever	String	杠杆倍数，0.01到125之间的数值，仅适用于 `币币杠杆/交割/永续`
> state	String	订单状态 `live`：待生效 `effective`：已生效 `partially_effective`：部分生效 `canceled`：已撤销 `order_failed`：委托失败 `pause`: 暂停生效
> tpTriggerPx	String	止盈触发价
> tpOrdPx	String	止盈委托价，委托价格为`-1`时，执行市价止盈
> slTriggerPx	String	止损触发价
> slOrdPx	String	止损委托价委托价格为`-1`时，执行市价止损
> triggerPx	String	计划委托单的触发价格
> ordPx	String	计划委托单的委托价格
> actualSz	String	实际委托量
> actualPx	String	实际委价
> tag	String	订单标签字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。
> notionalUsd	String	委托单预估美元价值
> actualSide	String	实际触发方向，`sl`：止损 `tp`：止盈
> triggerTime	String	策略委托触发时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> pxVar	String	价格比例仅适用于`冰山委托`和`时间加权委托`
> pxSpread	String	价距仅适用于`冰山委托`和`时间加权委托`
> szLimit	String	单笔数量仅适用于`冰山委托`和`时间加权委托`
> pxLimit	String	挂单限制价仅适用于`冰山委托`和`时间加权委托`
> timeInterval	String	下单间隔仅适用于`时间加权委托`
> count	String	策略订单计数仅适用于`冰山委托`和`时间加权委托`
> callbackRatio	String	回调幅度的比例仅适用于`移动止盈止损`
> callbackSpread	String	回调幅度的价距仅适用于`移动止盈止损`
> activePx	String	移动止盈止损激活价格仅适用于`移动止盈止损`
> failCode	String	代表策略触发失败的原因，已撤销和已生效时为""，委托失败时有值，如 51008；仅适用于单向止盈止损委托、双向止盈止损委托、移动止盈止损委托、计划委托。
> algoClOrdId	String	客户自定义策略订单ID
> moveTriggerPx	String	移动止盈止损触发价格仅适用于`移动止盈止损`
> reduceOnly	String	是否只减仓，`true` 或 `false`
> pTime	String	订单信息的推送时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> isTradeBorrowMode	Boolean	是否自动借币 true：自动借币 false：不自动借币仅适用于计划委托、移动止盈止损和时间加权策略

网格交易

网格是一种在指定价格区间自动进行低买高卖的交易策略。用户设定参数后，系统分割小网格自动挂单，随着市场波动，策略低买高卖赚取波段收益。
网格交易功能模块下的API接口需要身份验证。

POST / 网格策略委托下单

限速：20次/2s

限速规则：UserID + Instrument ID

权限：交易

HTTP请求

POST /api/v5/tradingBot/grid/order-algo

请求示例

# 现货网格下单
POST /api/v5/tradingBot/grid/order-algo
body
{
    "instId": "BTC-USDT",
    "algoOrdType": "grid",
    "maxPx": "5000",
    "minPx": "400",
    "gridNum": "10",
    "runType": "1",
    "quoteSz": "25",
    "triggerParams":[
      {
         "triggerAction":"stop",
         "triggerStrategy":"price",  
         "triggerPx":"1000"
      }
    ]
}

# 合约网格下单
POST /api/v5/tradingBot/grid/order-algo
body
{
    "instId": "BTC-USDT-SWAP",
    "algoOrdType": "contract_grid",
    "maxPx": "5000",
    "minPx": "400",
    "gridNum": "10",
    "runType": "1",
    "sz": "200", 
    "direction": "long",
    "lever": "2",
    "triggerParams":[
      {
         "triggerAction":"start", 
         "triggerStrategy":"rsi", 
         "timeframe":"30m",
         "thold":"10",
         "triggerCond":"cross",
         "timePeriod":"14"
      },
      {
         "triggerAction":"stop",
         "triggerStrategy":"price",
         "triggerPx":"1000",
         "stopType":"2"
      }
   ]
}

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如`BTC-USDT`
algoOrdType	String	是	策略订单类型 `grid`：现货网格委托 `contract_grid`：合约网格委托
maxPx	String	是	区间最高价格
minPx	String	是	区间最低价格
gridNum	String	是	网格数量
runType	String	否	网格类型 `1`：等差，`2`：等比默认为等差
tpTriggerPx	String	否	止盈触发价适用于`现货网格`/`合约网格`
slTriggerPx	String	否	止损触发价适用于`现货网格`/`合约网格`
algoClOrdId	String	否	用户自定义策略ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
tag	String	否	订单标签
profitSharingRatio	String	否	带单员分润比例，仅支持固定比例分润 `0`,`0.1`,`0.2`,`0.3`
triggerParams	Array of object	否	信号触发参数适用于`现货网格`/`合约网格`
> triggerAction	String	是	触发行为 `start`：网格启动 `stop`：网格停止
> triggerStrategy	String	是	触发策略 `instant`：立即触发 `price`：价格触发 `rsi`：rsi指标触发默认为`instant`
> delaySeconds	String	否	延迟触发时间，单位为秒，默认为`0`
> timeframe	String	否	K线种类 `3m`, `5m`, `15m`, `30m` (`m`代表分钟) `1H`, `4H` (`H`代表小时) `1D` (`D`代表天) 该字段只在`triggerStrategy`为`rsi`时有效
> thold	String	否	阈值取值[1,100]的整数该字段只在`triggerStrategy`为`rsi`时有效
> triggerCond	String	否	触发条件 `cross_up`：上穿 `cross_down`：下穿 `above`：上方 `below`：下方 `cross`：交叉该字段只在`triggerStrategy`为`rsi`时有效
> timePeriod	String	否	周期 `14` 该字段只在`triggerStrategy`为`rsi`下有效
> triggerPx	String	否	触发价格该字段只在`triggerStrategy`为`price`下有效
> stopType	String	否	策略停止类型现货 `1`：卖出交易币，`2`：不卖出交易币合约网格 `1`：停止平仓，`2`：停止不平仓该字段只在`triggerAction`为`stop`时有效

现货网格

参数名	类型	是否必须	描述
quoteSz	String	可选	计价币投入数量 `quoteSz`和`baseSz`至少指定一个
baseSz	String	可选	交易币投入数量 `quoteSz`和`baseSz`至少指定一个

合约网格

参数名	类型	是否必须	描述
sz	String	是	投入保证金,单位为`USDT`
direction	String	是	合约网格类型 `long`：做多，`short`：做空，`neutral`：中性
lever	String	是	杠杆倍数
basePos	Boolean	否	是否开底仓默认为`false` 中性合约网格忽略该参数
tpRatio	String	否	止盈比率，0.1 代表 10%
slRatio	String	否	止损比率，0.1 代表 10%

返回结果

{
    "code": "0",
    "data": [
        {
            "algoClOrdId": "",
            "algoId": "447053782921515008",
            "sCode": "0",
            "sMsg": "",
            "tag": ""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
algoClOrdId	String	用户自定义策略ID
sCode	String	事件执行结果的code，0代表成功
sMsg	String	事件执行失败时的msg
tag	String	订单标签

POST / 修改网格策略订单

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/grid/amend-order-algo

请求示例

POST /api/v5/tradingBot/grid/amend-order-algo
body
{
    "algoId":"448965992920907776",
    "instId":"BTC-USDT-SWAP",
    "slTriggerPx":"1200",
    "tpTriggerPx":""
}

POST /api/v5/tradingBot/grid/amend-order-algo
body 
{
   "algoId":"578963447615062016",
   "instId":"BTC-USDT",
   "triggerParams":[
       {
           "triggerAction":"stop",  
           "triggerStrategy":"price",   
           "triggerPx":"1000"
       }
   ]
}

POST /api/v5/tradingBot/grid/amend-order-algo
body 
{
   "algoId":"578963447615062016",
   "instId":"BTC-USDT-SWAP",
   "triggerParams":[
       {
           "triggerAction":"stop",  
           "triggerStrategy":"instant",   
           "stopType":"1"
       }
   ]
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID
instId	String	是	产品ID，如`BTC-USDT-SWAP`
slTriggerPx	String	可选	新的止损触发价当值为""则代表取消止损触发价 `slTriggerPx`、`tpTriggerPx`至少要传一个值
tpTriggerPx	String	可选	新的止盈触发价当值为""则代表取消止盈触发价
triggerParams	Array of object	否	信号触发参数
tpRatio	String	否	止盈比率，0.1 代表 10%，仅适用于合约网格当值为""则代表取消止盈比率
slRatio	String	否	止损比率，0.1 代表 10%，仅适用于合约网格当值为""则代表取消止损比率
> triggerAction	String	是	触发行为 `start`：网格启动 `stop`：网格停止
> triggerStrategy	String	是	触发策略 `instant`：立即触发 `price`：价格触发 `rsi`：rsi指标触发
> triggerPx	String	否	触发价格该字段只在`triggerStrategy`为`price`下有效
> stopType	String	否	策略停止类型现货 `1`：卖出交易币，`2`：不卖出交易币合约网格 `1`：停止平仓，`2`：停止不平仓该字段只在`triggerAction`为`stop`时有效

返回结果

{
    "code": "0",
    "data": [
        {
            "algoClOrdId": "",
            "algoId": "448965992920907776",
            "sCode": "0",
            "sMsg": "",
            "tag": ""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
algoClOrdId	String	用户自定义策略ID
sCode	String	事件执行结果的code，0代表成功
sMsg	String	事件执行失败时的msg
tag	String	订单标签

POST / 网格策略停止

每次最多可以撤销10个网格策略。

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/grid/stop-order-algo

请求示例

POST /api/v5/tradingBot/grid/stop-order-algo
body
[
    {
        "algoId":"448965992920907776",
        "instId":"BTC-USDT",
        "stopType":"1",
        "algoOrdType":"grid"
    }
]

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID
instId	String	是	产品ID，如`BTC-USDT`
algoOrdType	String	是	策略订单类型 `grid`：现货网格委托 `contract_grid`：合约网格委托
stopType	String	是	网格策略停止类型现货网格 `1`：卖出交易币，`2`：不卖出交易币合约网格 `1`：市价全平 `2`：停止不平仓

返回结果

{
    "code": "0",
    "data": [
        {
            "algoClOrdId": "",
            "algoId": "448965992920907776",
            "sCode": "0",
            "sMsg": "",
            "tag": ""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
algoClOrdId	String	用户自定义策略ID
sCode	String	事件执行结果的code，0代表成功
sMsg	String	事件执行失败时的msg
tag	String	订单标签

POST / 合约网格平仓

只有处于已停止未平仓状态合约网格可使用该接口

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/grid/close-position

请求示例

POST /api/v5/tradingBot/grid/close-position
body
{
    "algoId":"448965992920907776",
    "mktClose":true
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID
mktClose	Boolean	是	是否市价全平 `true`：市价全平，`false`：部分平仓
sz	String	可选	平仓数量,单位为张部分平仓时必传
px	String	可选	平仓价格部分平仓时必传

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "algoClOrdId": "",
            "algoId":"448965992920907776",
            "ordId":"",
            "tag": ""
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
ordId	String	平仓单ID 市价全平时，该字段为""
algoClOrdId	String	用户自定义策略ID
tag	String	订单标签

POST / 撤销合约网格平仓单

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/grid/cancel-close-order

请求示例

POST /api/v5/tradingBot/grid/cancel-close-order
body
{
    "algoId":"448965992920907776",
    "ordId":"570627699870375936"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID
ordId	String	是	平仓单ID

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "algoClOrdId": "",
            "algoId": "448965992920907776",
            "ordId": "570627699870375936",
            "tag": ""
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
ordId	String	平仓单ID
algoClOrdId	String	用户自定义策略ID
tag	String	订单标签

POST / 网格策略立即触发

限速：20次/2s

限速规则：UserID + Instrument ID

权限：交易

HTTP请求

POST /api/v5/tradingBot/grid/order-instant-trigger

请求示例

POST /api/v5/tradingBot/grid/order-instant-trigger
body
{
    "algoId":"561564133246894080"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID

返回结果

{
    "code": "0",
    "data": [
        {
            "algoClOrdId": "",
            "algoId": "561564133246894080"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
algoClOrdId	String	用户自定义策略ID

GET / 获取未完成网格策略委托单列表

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/tradingBot/grid/orders-algo-pending

请求示例

GET /api/v5/tradingBot/grid/orders-algo-pending?algoOrdType=grid

请求参数

参数名	类型	是否必须	描述
algoOrdType	String	是	策略订单类型 `grid`：现货网格委托 `contract_grid`：合约网格委托
algoId	String	否	策略订单ID
instId	String	否	产品ID，如`BTC-USDT`
instType	String	否	产品类型 `SPOT`：币币 `MARGIN`：杠杆 `FUTURES`：交割合约 `SWAP`：永续合约
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的`algoId`
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的`algoId`
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "activeOrdNum": "",
            "actualLever": "",
            "algoClOrdId": "",
            "algoId": "56802********64032",
            "algoOrdType": "grid",
            "arbitrageNum": "0",
            "availEq": "",
            "basePos": false,
            "baseSz": "0",
            "cTime": "1681700496249",
            "cancelType": "0",
            "direction": "",
            "floatProfit": "0",
            "gridNum": "10",
            "gridProfit": "0",
            "instFamily": "",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "investment": "25",
            "lever": "",
            "liqPx": "",
            "maxPx": "5000",
            "minPx": "400",
            "ordFrozen": "",
            "pnlRatio": "0",
            "quoteSz": "25",
            "rebateTrans": [
                {
                    "rebate": "0",
                    "rebateCcy": "BTC"
                },
                {
                    "rebate": "0",
                    "rebateCcy": "USDT"
                }
            ],
            "runType": "1",
            "slTriggerPx": "",
            "state": "running",
            "stopType": "",
            "sz": "",
            "tag": "",
            "totalPnl": "0",
            "tpTriggerPx": "",
            "triggerParams": [
                {
                    "triggerAction": "start",
                    "delaySeconds": "0",
                    "triggerStrategy": "instant",
                    "triggerType": "auto",
                    "triggerTime": ""
                },
                {
                    "triggerAction": "stop",
                    "delaySeconds": "0",
                    "triggerStrategy": "instant",
                    "stopType": "1",
                    "triggerPx": "1000",
                    "triggerType": "manual",
                    "triggerTime": ""
                }
            ],
            "uTime": "1682062564350",
            "uly": "BTC-USDT",
            "profitSharingRatio": "",
            "copyType": "0",
            "fee": "",
            "fundingFee": ""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
algoClOrdId	String	用户自定义策略ID
instType	String	产品类型
instId	String	产品ID
cTime	String	策略订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	策略订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
algoOrdType	String	策略订单类型 `grid`：现货网格委托 `contract_grid`：合约网格委托
state	String	订单状态 `starting`：启动中 `running`：运行中 `stopping`：终止中 `pending_signal`：等待触发 `no_close_position`：已停止未平仓（仅适用于合约网格）
rebateTrans	Array of object	返佣划转信息
> rebate	String	返佣数量
> rebateCcy	String	返佣币种
triggerParams	Array of object	信号触发参数
> triggerAction	String	触发行为 `start`：网格启动 `stop`：网格停止
> triggerStrategy	String	触发策略 `instant`：立即触发 `price`：价格触发 `rsi`：rsi指标触发
> delaySeconds	String	延迟触发时间，单位为秒
> triggerTime	String	triggerAction实际触发时间，Unix时间戳的毫秒数格式, 如 `1597026383085`
> triggerType	String	triggerAction的实际触发类型 `manual`：手动触发 `auto`: 自动触发
> timeframe	String	K线种类 `3m`, `5m`, `15m`, `30m` (`m`代表分钟) `1H`, `4H` (`H`代表小时) `1D` (`D`代表天) 该字段只在`triggerStrategy`为`rsi`时有效
> thold	String	阈值取值[1,100]的整数该字段只在`triggerStrategy`为`rsi`时有效
> triggerCond	String	触发条件 `cross_up`：上穿 `cross_down`：下穿 `above`：上方 `below`：下方 `cross`：交叉该字段只在`triggerStrategy`为`rsi`时有效
> timePeriod	String	周期 `14` 该字段只在`triggerStrategy`为`rsi`下有效
> triggerPx	String	触发价格该字段只在`triggerStrategy`为`price`下有效
> stopType	String	策略停止类型现货 `1`：卖出交易币，`2`：不卖出交易币合约网格 `1`：停止平仓，`2`：停止不平仓该字段只在`triggerAction`为`stop`时有效
maxPx	String	区间最高价格
minPx	String	区间最低价格
gridNum	String	网格数量
runType	String	网格类型 `1`：等差，`2`：等比
tpTriggerPx	String	止盈触发价
slTriggerPx	String	止损触发价
arbitrageNum	String	网格套利次数
totalPnl	String	总收益
pnlRatio	String	收益率
investment	String	累计投入金额现货网格如果投入了交易币则折算为计价币
gridProfit	String	网格利润
floatProfit	String	浮动盈亏
cancelType	String	网格策略停止原因 `0`：无 `1`：手动停止 `2`：止盈停止 `3`：止损停止 `4`：风控停止 `5`：交割停止 `6`: 信号停止
stopType	String	网格策略实际停止类型现货网格 `1`：卖出交易币，`2`：不卖出交易币合约网格 `1`：停止平仓，`2`：停止不平仓
quoteSz	String	计价币投入数量适用于`现货网格
baseSz	String	交易币投入数量适用于`现货网格`
direction	String	合约网格类型 `long`：做多，`short`：做空，`neutral`：中性仅适用于`合约网格`
basePos	Boolean	是否开底仓适用于`合约网格`
sz	String	投入保证金，单位为`USDT` 适用于`合约网格`
lever	String	杠杆倍数适用于`合约网格`
actualLever	String	实际杠杆倍数适用于`合约网格`
liqPx	String	预估强平价格适用于`合约网格`
uly	String	标的指数适用于`合约网格`
instFamily	String	交易品种适用于`交割/永续/期权`，如 `BTC-USD` 适用于`合约网格`
ordFrozen	String	挂单占用适用于`合约网格`
availEq	String	可用保证金适用于`合约网格`
tag	String	订单标签
profitSharingRatio	String	分润比例取值范围[0,0.3] 如果是普通订单（既不是带单也不是跟单），该字段返回""
copyType	String	分润订单类型 `0`：普通订单 `1`：普通跟单 `2`：分润跟单 `3`：带单
fee	String	累计手续费金额，仅适用于合约网格，其他网格策略为""
fundingFee	String	累计资金费用，仅适用于合约网格，其他网格策略为""

GET / 获取历史网格策略委托单列表

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/tradingBot/grid/orders-algo-history

请求示例

GET /api/v5/tradingBot/grid/orders-algo-history?algoOrdType=grid

请求参数

参数名	类型	是否必须	描述
algoOrdType	String	是	策略订单类型 `grid`：现货网格委托 `contract_grid`：合约网格委托
algoId	String	否	策略订单ID
instId	String	否	产品ID，如`BTC-USDT`
instType	String	否	产品类型 `SPOT`：币币 `MARGIN`：杠杆 `FUTURES`：交割合约 `SWAP`：永续合约
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的`algoId`
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的`algoId`
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "actualLever": "",
            "algoClOrdId": "",
            "algoId": "565849588675117056",
            "algoOrdType": "grid",
            "arbitrageNum": "0",
            "availEq": "",
            "basePos": false,
            "baseSz": "0",
            "cTime": "1681181054927",
            "cancelType": "1",
            "direction": "",
            "floatProfit": "0",
            "gridNum": "10",
            "gridProfit": "0",
            "instFamily": "",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "investment": "25",
            "lever": "0",
            "liqPx": "",
            "maxPx": "5000",
            "minPx": "400",
            "ordFrozen": "",
            "pnlRatio": "0",
            "quoteSz": "25",
            "rebateTrans": [
                {
                    "rebate": "0",
                    "rebateCcy": "BTC"
                },
                {
                    "rebate": "0",
                    "rebateCcy": "USDT"
                }
            ],
            "runType": "1",
            "slTriggerPx": "0",
            "state": "stopped",
            "stopResult": "0",
            "stopType": "1",
            "sz": "",
            "tag": "",
            "totalPnl": "0",
            "tpTriggerPx": "0",
            "triggerParams": [
                {
                    "triggerAction": "start",
                    "delaySeconds": "0",
                    "triggerStrategy": "instant",
                    "triggerType": "auto",
                    "triggerTime": ""
                },
                {
                    "triggerAction": "stop",
                    "delaySeconds": "0",
                    "triggerStrategy": "instant",
                    "stopType": "1",
                    "triggerPx": "1000",
                    "triggerType": "manual",
                    "triggerTime": "1681181186484"
                }
            ],
            "uTime": "1681181186496",
            "uly": "BTC-USDT",
            "profitSharingRatio": "",
            "copyType": "0",
            "fee": "",
            "fundingFee": ""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
algoClOrdId	String	用户自定义策略ID
instType	String	产品类型
instId	String	产品ID
cTime	String	策略订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	策略订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
algoOrdType	String	策略订单类型 `grid`：现货网格委托 `contract_grid`：合约网格委托
state	String	订单状态 `stopped`：已停止
rebateTrans	Array of object	返佣划转信息
> rebate	String	返佣数量
> rebateCcy	String	返佣币种
triggerParams	Array of object	信号触发参数
> triggerAction	String	触发行为 `start`：网格启动 `stop`：网格停止
> triggerStrategy	String	触发策略 `instant`：立即触发 `price`：价格触发 `rsi`：rsi指标触发
> delaySeconds	String	延迟触发时间，单位为秒
> triggerTime	String	triggerAction实际触发时间，Unix时间戳的毫秒数格式, 如 `1597026383085`
> triggerType	String	triggerAction的实际触发类型 `manual`：手动触发 `auto`: 自动触发
> timeframe	String	K线种类 `3m`, `5m`, `15m`, `30m` (`m`代表分钟) `1H`, `4H` (`H`代表小时) `1D` (`D`代表天) 该字段只在`triggerStrategy`为`rsi`时有效
> thold	String	阈值取值[1,100]的整数该字段只在`triggerStrategy`为`rsi`时有效
> triggerCond	String	触发条件 `cross_up`：上穿 `cross_down`：下穿 `above`：上方 `below`：下方 `cross`：交叉该字段只在`triggerStrategy`为`rsi`时有效
> timePeriod	String	周期 `14` 该字段只在`triggerStrategy`为`rsi`下有效
> triggerPx	String	触发价格该字段只在`triggerStrategy`为`price`下有效
> stopType	String	策略停止类型现货 `1`：卖出交易币，`2`：不卖出交易币合约网格 `1`：停止平仓，`2`：停止不平仓该字段只在`triggerAction`为`stop`时有效
maxPx	String	区间最高价格
minPx	String	区间最低价格
gridNum	String	网格数量
runType	String	网格类型 `1`：等差，`2`：等比
tpTriggerPx	String	止盈触发价
slTriggerPx	String	止损触发价
arbitrageNum	String	网格套利次数
totalPnl	String	总收益
pnlRatio	String	收益率
investment	String	累计投入金额现货网格如果投入了交易币则折算为计价币
gridProfit	String	网格利润
floatProfit	String	浮动盈亏
cancelType	String	网格策略停止原因 `0`：无 `1`：手动停止 `2`：止盈停止 `3`：止损停止 `4`：风控停止 `5`：交割停止 `6`: 信号停止
stopType	String	网格策略实际停止类型现货网格 `1`：卖出交易币，`2`：不卖出交易币合约网格 `1`：停止平仓，`2`：停止不平仓
quoteSz	String	计价币投入数量适用于`现货网格`
baseSz	String	交易币投入数量适用于`现货网格`
direction	String	合约网格类型 `long`：做多，`short`：做空，`neutral`：中性仅适用于`合约网格`
basePos	Boolean	是否开底仓适用于`合约网格`
sz	String	投入保证金，单位为`USDT` 适用于`合约网格`
lever	String	杠杆倍数适用于`合约网格`
actualLever	String	实际杠杆倍数适用于`合约网格`
liqPx	String	预估强平价格适用于`合约网格`
uly	String	标的指数适用于`合约网格`
instFamily	String	交易品种适用于`交割/永续/期权`，如 `BTC-USD` 适用于`合约网格`
ordFrozen	String	挂单占用适用于`合约网格`
availEq	String	可用保证金适用于`合约网格`
tag	String	订单标签
profitSharingRatio	String	分润比例取值范围[0,0.3] 如果是普通订单（既不是带单也不是跟单），该字段返回""
copyType	String	分润订单类型 `0`：普通订单 `1`：普通跟单 `2`：分润跟单 `3`：带单
fee	String	累计手续费金额，仅适用于合约网格，其他网格策略为""
fundingFee	String	累计资金费用，仅适用于合约网格，其他网格策略为""

GET / 获取网格策略委托订单详情

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/tradingBot/grid/orders-algo-details

请求示例

GET /api/v5/tradingBot/grid/orders-algo-details?algoId=448965992920907776&algoOrdType=grid

请求参数

参数名	类型	是否必须	描述
algoOrdType	String	是	策略订单类型 `grid`：现货网格委托 `contract_grid`：合约网格委托
algoId	String	是	策略订单ID

返回结果

{
    "code": "0",
    "data": [
        {
            "actualLever": "",
            "activeOrdNum": "0",
            "algoClOrdId": "",
            "algoId": "448965992920907776",
            "algoOrdType": "grid",
            "annualizedRate": "0",
            "arbitrageNum": "0",
            "availEq": "",
            "basePos": false,
            "baseSz": "0",
            "cTime": "1681181054927",
            "cancelType": "1",
            "curBaseSz": "0",
            "curQuoteSz": "0",
            "direction": "",
            "eq": "",
            "floatProfit": "0",
            "gridNum": "10",
            "gridProfit": "0",
            "instFamily": "",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "investment": "25",
            "lever": "0",
            "liqPx": "",
            "maxPx": "5000",
            "minPx": "400",
            "ordFrozen": "",
            "perMaxProfitRate": "1.14570215",
            "perMinProfitRate": "0.0991200440528634356837",
            "pnlRatio": "0",
            "profit": "0.00000000",
            "quoteSz": "25",
            "rebateTrans": [
                {
                    "rebate": "0",
                    "rebateCcy": "BTC"
                },
                {
                    "rebate": "0",
                    "rebateCcy": "USDT"
                }
            ],
            "runType": "1",
            "runPx": "30089.7",
            "singleAmt": "0.00101214",
            "slTriggerPx": "0",
            "state": "stopped",
            "stopResult": "0",
            "stopType": "1",
            "sz": "",
            "tag": "",
            "totalAnnualizedRate": "0",
            "totalPnl": "0",
            "tpTriggerPx": "0",
            "tradeNum": "0",
            "triggerParams": [
                {
                    "triggerAction": "start",
                    "delaySeconds": "0",
                    "triggerStrategy": "instant",
                    "triggerType": "auto",
                    "triggerTime": ""
                },
                {
                    "triggerAction": "stop",
                    "delaySeconds": "0",
                    "triggerStrategy": "instant",
                    "stopType": "1",
                    "triggerType": "manual",
                    "triggerTime": "1681181186484"
                }
            ],
            "uTime": "1681181186496",
            "uly": "",
            "profitSharingRatio": "",
            "copyType": "0",
            "tpRatio": "",
            "slRatio": "",
            "fee": "",
            "fundingFee": ""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
algoClOrdId	String	用户自定义策略ID
instType	String	产品类型
instId	String	产品ID
cTime	String	策略订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	策略订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
algoOrdType	String	策略订单类型 `grid`：现货网格委托 `contract_grid`：合约网格委托
state	String	订单状态 `starting`：启动中 `running`：运行中 `stopping`：终止中 `no_close_position`：已停止未平仓（仅适用于合约网格） `stopped`：已停止
rebateTrans	Array of object	返佣划转信息
> rebate	String	返佣数量
> rebateCcy	String	返佣币种
triggerParams	Array of object	信号触发参数
> triggerAction	String	触发行为 `start`：网格启动 `stop`：网格停止
> triggerStrategy	String	触发策略 `instant`：立即触发 `price`：价格触发 `rsi`：rsi指标触发
> delaySeconds	String	延迟触发时间，单位为秒
> triggerTime	String	triggerAction实际触发时间，Unix时间戳的毫秒数格式, 如 `1597026383085`
> triggerType	String	triggerAction的实际触发类型 `manual`：手动触发 `auto`: 自动触发
> timeframe	String	K线种类 `3m`, `5m`, `15m`, `30m` (`m`代表分钟) `1H`, `4H` (`H`代表小时) `1D` (`D`代表天) 该字段只在`triggerStrategy`为`rsi`时有效
> thold	String	阈值取值[1,100]的整数该字段只在`triggerStrategy`为`rsi`时有效
> triggerCond	String	触发条件 `cross_up`：上穿 `cross_down`：下穿 `above`：上方 `below`：下方 `cross`：交叉该字段只在`triggerStrategy`为`rsi`时有效
> timePeriod	String	周期 `14` 该字段只在`triggerStrategy`为`rsi`下有效
> triggerPx	String	触发价格该字段只在`triggerStrategy`为`price`下有效
> stopType	String	策略停止类型现货 `1`：卖出交易币，`2`：不卖出交易币合约网格 `1`：停止平仓，`2`：停止不平仓该字段只在`triggerAction`为`stop`时有效
maxPx	String	区间最高价格
minPx	String	区间最低价格
gridNum	String	网格数量
runType	String	网格类型 `1`：等差，`2`：等比
tpTriggerPx	String	止盈触发价
slTriggerPx	String	止损触发价
tradeNum	String	挂单成交次数
arbitrageNum	String	网格套利次数
singleAmt	String	单网格买卖量
perMinProfitRate	String	预期单网格最低利润率
perMaxProfitRate	String	预期单网格最高利润率
runPx	String	启动时价格
totalPnl	String	总收益
pnlRatio	String	收益率
investment	String	累计投入金额现货网格如果投入了交易币则折算为计价币
gridProfit	String	网格利润
floatProfit	String	浮动盈亏
totalAnnualizedRate	String	总年化
annualizedRate	String	网格年化
cancelType	String	网格策略停止原因 `0`：无 `1`：手动停止 `2`：止盈停止 `3`：止损停止 `4`：风控停止 `5`：交割停止 `6`: 信号停止
stopType	String	网格策略停止类型现货网格 `1`：卖出交易币，`2`：不卖出交易币合约网格 `1`：市价全平，`2`：停止不平仓
activeOrdNum	String	子订单挂单数量
quoteSz	String	计价币投入数量仅适用于`现货网格`
baseSz	String	交易币投入数量仅适用于`现货网格`
curQuoteSz	String	当前持有的计价币资产仅适用于`现货网格`
curBaseSz	String	当前持有的交易币资产仅适用于`现货网格`
profit	String	当前可提取利润,单位是计价币仅适用于`现货网格`
stopResult	String	策略停止结果 `0`：默认，`1`：市价卖币成功 `-1`：市价卖币失败仅适用于`现货网格`
direction	String	合约网格类型 `long`：做多，`short`：做空，`neutral`：中性仅适用于`合约网格`
basePos	Boolean	是否开底仓仅适用于`合约网格`
sz	String	投入保证金，单位为`USDT` 仅适用于`合约网格`
lever	String	杠杆倍数仅适用于`合约网格`
actualLever	String	实际杠杆倍数仅适用于`合约网格`
liqPx	String	预估强平价格仅适用于`合约网格`
uly	String	标的指数仅适用于`合约网格`
instFamily	String	交易品种适用于`交割/永续/期权`，如 `BTC-USD` 适用于`合约网格`
ordFrozen	String	挂单占用适用于`合约网格`
availEq	String	可用保证金适用于`合约网格`
eq	String	策略账户总权益仅适用于`合约网格`
tag	String	订单标签
profitSharingRatio	String	分润比例取值范围[0,0.3] 如果是普通订单（既不是带单也不是跟单），该字段返回""
copyType	String	分润订单类型 `0`：普通订单 `1`：普通跟单 `2`：分润跟单 `3`：带单
tpRatio	String	止盈比率，0.1 代表 10%
slRatio	String	止损比率，0.1 代表 10%
fee	String	累计手续费金额，仅适用于合约网格，其他网格策略为""
fundingFee	String	累计资金费用，仅适用于合约网格，其他网格策略为""

GET / 获取网格策略委托子订单信息

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/tradingBot/grid/sub-orders

请求示例

GET /api/v5/tradingBot/grid/sub-orders?algoId=123456&type=live&algoOrdType=grid

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID
algoOrdType	String	是	策略订单类型 `grid`：现货网格委托 `contract_grid`：合约网格委托
type	String	是	子订单状态 `live`：未成交 `filled`：已成交
groupId	String	否	组ID
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的`ordId`
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的`ordId`
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "accFillSz": "0",
            "algoClOrdId": "",
            "algoId": "448965992920907776",
            "algoOrdType": "grid",
            "avgPx": "0",
            "cTime": "1653347949771",
            "ccy": "",
            "ctVal": "",
            "fee": "0",
            "feeCcy": "USDC",
            "groupId": "3",
            "instId": "BTC-USDC",
            "instType": "SPOT",
            "lever": "0",
            "ordId": "449109084439187456",
            "ordType": "limit",
            "pnl": "0",
            "posSide": "net",
            "px": "30404.3",
            "rebate": "0",
            "rebateCcy": "USDT",
            "side": "sell",
            "state": "live",    
            "sz": "0.00059213",
            "tag": "",
            "tdMode": "cash",
            "uTime": "1653347949831"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
algoClOrdId	String	用户自定义策略ID
instType	String	产品类型
instId	String	产品ID
algoOrdType	String	策略订单类型 `grid`：现货网格委托 `contract_grid`：合约网格委托
groupId	String	组ID
ordId	String	子订单ID
cTime	String	子订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	子订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
tdMode	String	子订单交易模式 `cross`：全仓 `isolated`：逐仓 `cash`：非保证金
ccy	String	保证金币种仅适用于`现货和合约模式`模式下的`全仓杠杆`订单
ordType	String	子订单类型 `market`：市价单 `limit`：限价单 `ioc`：立即成交并取消剩余
sz	String	子订单委托数量
state	String	子订单状态 `canceled`：撤单成功 `live`：等待成交 `partially_filled`：部分成交 `filled`：完全成交 `cancelling`：撤单中
side	String	子订单订单方向 `buy`：买 `sell`：卖
px	String	子订单委托价格
fee	String	子订单手续费数量
feeCcy	String	子订单手续费币种
rebate	String	子订单返佣数量
rebateCcy	String	子订单返佣币种
avgPx	String	子订单平均成交价格
accFillSz	String	子订单累计成交数量
posSide	String	子订单持仓方向 `net`：买卖模式
pnl	String	子订单收益
ctVal	String	合约面值仅支持`FUTURES/SWAP`
lever	String	杠杆倍数
tag	String	订单标签

GET / 获取网格策略委托持仓

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/tradingBot/grid/positions

请求示例

GET /api/v5/tradingBot/grid/positions?algoId=448965992920907776&algoOrdType=contract_grid

请求参数

参数名	类型	是否必须	描述
algoOrdType	String	是	订单类型 `contract_grid`：合约网格委托
algoId	String	是	策略订单ID

返回结果

{
    "code": "0",
    "data": [
        {
            "adl": "1",
            "algoClOrdId": "",
            "algoId": "449327675342323712",
            "avgPx": "29215.0142857142857149",
            "cTime": "1653400065917",
            "ccy": "USDT",
            "imr": "2045.386",
            "instId": "BTC-USDT-SWAP",
            "instType": "SWAP",
            "last": "29206.7",
            "lever": "5",
            "liqPx": "661.1684795867162",
            "markPx": "29213.9",
            "mgnMode": "cross",
            "mgnRatio": "217.19370606167573",
            "mmr": "40.907720000000005",
            "notionalUsd": "10216.70307",
            "pos": "35",
            "posSide": "net",
            "uTime": "1653400066938",
            "upl": "1.674999999999818",
            "uplRatio": "0.0008190504784478"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
algoClOrdId	String	用户自定义策略ID
instType	String	产品类型
instId	String	产品ID，如 `BTC-USDT-SWAP`
cTime	String	策略订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	策略订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
avgPx	String	开仓均价
ccy	String	保证金币种
lever	String	杠杆倍数
liqPx	String	预估强平价
posSide	String	持仓方向 `net`：买卖模式
pos	String	持仓数量
mgnMode	String	保证金模式 `cross`：全仓 `isolated`：逐仓
mgnRatio	String	保证金率
imr	String	初始保证金
mmr	String	维持保证金
upl	String	未实现收益
uplRatio	String	未实现收益率
last	String	最新成交价
notionalUsd	String	仓位美金价值
adl	String	信号区分为5档，从1到5，数字越小代表adl强度越弱
markPx	String	标记价格

POST / 现货网格提取利润

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/grid/withdraw-income

请求示例

POST /api/v5/tradingBot/grid/withdraw-income
body
{
    "algoId":"448965992920907776"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "algoClOrdId": "",
            "algoId":"448965992920907776",
            "profit":"100"
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
algoClOrdId	String	用户自定义策略ID
profit	String	提取的利润

POST / 调整保证金计算

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/grid/compute-margin-balance

请求示例

POST /api/v5/tradingBot/grid/compute-margin-balance
body {
   "algoId":"123456",
   "type":"add",
   "amt":"10"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID
type	String	是	调整保证金类型 `add`：增加，`reduce`：减少
amt	String	否	调整保证金数量

返回结果

{
    "code": "0",
    "data": [
        {
            "lever": "0.3877200981166066",
            "maxAmt": "1.8309562403342999"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
maxAmt	String	最多可调整的保证金数量
lever	String	调整保证金后的杠杠倍数

POST / 调整保证金

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/grid/margin-balance

请求示例

POST /api/v5/tradingBot/grid/margin-balance
body {
   "algoId":"123456",
   "type":"add",
   "amt":"10"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID
type	String	是	调整保证金类型 `add`：增加，`reduce`：减少
amt	String	可选	调整保证金数量 `amt`和`percent`必须传一个
percent	String	可选	调整保证金百分比

返回结果

{
    "code": "0",
    "data": [
        {
            "algoClOrdId": "",
            "algoId": "123456"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
algoClOrdId	String	用户自定义策略ID

POST / 加仓

该接口用于加仓，仅适用于合约网格。

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/grid/adjust-investment

请求示例

POST /api/v5/tradingBot/grid/adjust-investment
body
{
    "algoId":"448965992920907776",
    "amt":"12"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID
amt	String	是	加仓数量

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "algoId":"448965992920907776"
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID

GET / 网格策略智能回测（公共）

公共接口无须鉴权

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/tradingBot/grid/ai-param

请求示例

GET /api/v5/tradingBot/grid/ai-param?instId=BTC-USDT&algoOrdType=grid

请求参数

参数名	类型	是否必须	描述
algoOrdType	String	是	策略订单类型 `grid`：现货网格委托 `contract_grid`：合约网格委托
instId	String	是	产品ID，如`BTC-USDT`
direction	String	可选	合约网格类型 `long`：做多，`short`：做空，`neutral`：中性合约网格必填
duration	String	否	回测周期 `7D`：7天，`30D`：30天，`180D`：180天默认`现货网格`为`7D` 合约网格只支持`7D`

返回结果

{
    "code": "0",
    "data": [
        {
            "algoOrdType": "grid",
            "annualizedRate": "1.5849",
            "ccy": "USDT",
            "direction": "",
            "duration": "7D",
            "gridNum": "5",
            "instId": "BTC-USDT",
            "lever": "0",
            "maxPx": "21373.3",
            "minInvestment": "0.89557758",
            "minPx": "15544.2",
            "perGridProfitRatio": "4.566226200302574",
            "perMaxProfitRate": "0.0733865364573281",
            "perMinProfitRate": "0.0561101403446263",
            "runType": "1",
            "sourceCcy": ""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品ID
algoOrdType	String	策略订单类型 `grid`：现货网格委托 `contract_grid`：合约网格委托
duration	String	回测周期 `7D`：7天，`30D`：30天，`180D`：180天
gridNum	String	网格数量
maxPx	String	区间最高价格
minPx	String	区间最低价格
perMaxProfitRate	String	单网格最高利润率
perMinProfitRate	String	单网格最低利润率
perGridProfitRatio	String	单网格利润率
annualizedRate	String	网格年化收益率
minInvestment	String	最小投资数量
ccy	String	投资币种
runType	String	网格类型 `1`：等差，`2`：等比
direction	String	合约网格类型仅适用于`合约网格`
lever	String	杠杆倍数仅适用于`合约网格`
sourceCcy	String	来源币种

POST / 计算最小投资数量（公共）

公共接口无须鉴权

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

POST /api/v5/tradingBot/grid/min-investment

请求示例

POST /api/v5/tradingBot/grid/min-investment
body
{
    "instId": "ETH-USDT",
    "algoOrdType":"grid",
    "gridNum": "50",
    "maxPx":"5000",
    "minPx":"3000",
    "runType":"1",
    "investmentData":[
        {
            "amt":"0.01",
            "ccy":"ETH"
        },
        {
            "amt":"100",
            "ccy":"USDT"
        }
    ]
}

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如`BTC-USDT`
algoOrdType	String	是	策略订单类型 `grid`：现货网格委托 `contract_grid`：合约网格委托
gridNum	String	是	网格数量
maxPx	String	是	区间最高价格
minPx	String	是	区间最低价格
runType	String	是	网格类型 `1`：等差，`2`：等比
direction	String	可选	合约网格类型 `long`：做多，`short`：做空，`neutral`：中性适用于合约网格
lever	String	可选	杠杆倍数适用于合约网格
basePos	Boolean	否	是否开底仓默认为`false`
investmentType	String	否	投资类型, 仅适用于现货网格 `quote`: 计价货币 `base`: 交易货币 `dual`: 计价货币和交易货币
triggerStrategy	String	否	触发策略, `instant`: 立即触发 `price`: 价格触发 `rsi`: rsi 触发
investmentData	Array of object	否	投资信息
> amt	String	是	投资数量
> ccy	String	是	投资币种

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
           "minInvestmentData": [  
               {
                   "amt":"0.1",
                   "ccy":"ETH"
               },
               {
                   "amt":"100",
                   "ccy":"USDT"
               }
           ],
           "singleAmt":"10"
       }
    ]
}

返回参数

参数名	类型	描述
minInvestmentData	Array of object	最小投入信息
> amt	String	最小投入数量
> ccy	String	最小投入币种
singleAmt	String	单网格买卖量现货网格单位为计价币合约网格单位为张

GET / RSI回测（公共）

公共接口无须鉴权

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/tradingBot/public/rsi-back-testing

请求示例

GET /api/v5/tradingBot/public/rsi-back-testing?instId=BTC-USDT&thold=30&timeframe=3m&timePeriod=14

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如`BTC-USDT` 适用于`币币`
timeframe	String	是	K线种类 `3m`, `5m`, `15m`, `30m` (`m`代表分钟) `1H`, `4H` (`H`代表小时) `1D` (`D`代表天)
thold	String	是	阈值取值[1,100]的整数
timePeriod	String	是	周期 `14`
triggerCond	String	否	触发条件 `cross_up`：上穿 `cross_down`：下穿 `above`：上方 `below`：下方 `cross`：交叉默认是`cross_down`
duration	String	否	回测周期 `1M`：1个月默认`1M`

返回结果

{
    "code": "0",
    "data": [
        {
            "triggerNum": "164"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
triggerNum	String	触发次数

GET / 最大网格数量（公共）

公共接口无须鉴权

可通过该接口获取最大网格数量，最小网格数量总是 2。

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/tradingBot/grid/grid-quantity

请求示例

GET /api/v5/tradingBot/grid/grid-quantity?instId=BTC-USDT-SWAP&runType=1&algoOrdType=contract_grid&maxPx=70000&minPx=50000&lever=5

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如`BTC-USDT`
runType	String	是	网格类型 `1`: 等差 `2`: 等比
algoOrdType	String	是	策略订单类型 `grid`：现货网格委托 `contract_grid`：合约网格委托
maxPx	String	是	区间最高价格
minPx	String	是	区间最低价格
lever	String	可选	杠杆倍数, 合约网格时必填

返回结果

{
    "code": "0",
    "data": [
        {
            "maxGridQty": "285"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
maxGridQty	String	最大网格数量

WS / 现货网格策略委托订单频道

支持现货网格策略订单的定时推送和事件推送

服务地址

/ws/v5/business (需要登录)

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "grid-orders-spot",
        "instType": "ANY"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，`subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `grid-orders-spot`
> instType	String	是	产品类型 `SPOT`：币币 `ANY`：全部
> instId	String	否	产品ID
> algoId	String	否	策略ID

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "grid-orders-spot",
        "instType": "ANY"
    },
    "connId": "a4d3ae55"
}

失败返回示例

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

返回参数

参数	类型	是否必须	描述
event	String	是	事件 `subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名
> instType	String	是	产品类型
> instId	String	否	产品ID
> algoId	String	否	策略ID
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket连接ID

推送示例

{
    "arg": {
        "channel": "grid-orders-spot",
        "instType": "ANY",
        "uid": "4470****9584"
    },
    "data": [{
        "algoClOrdId": "",
        "algoId": "568028283477164032",
        "activeOrdNum":"10",
        "algoOrdType": "grid",
        "annualizedRate": "0",
        "arbitrageNum": "0",
        "baseSz": "0",
        "cTime": "1681700496249",
        "cancelType": "0",
        "curBaseSz": "0",
        "curQuoteSz": "25",
        "floatProfit": "0",
        "gridNum": "10",
        "gridProfit": "0",
        "instId": "BTC-USDT",
        "instType": "SPOT",
        "investment": "25",
        "maxPx": "5000",
        "minPx": "400",
        "pTime": "1682416738467",
        "perMaxProfitRate": "1.14570215",
        "perMinProfitRate": "0.0991200440528634356837",
        "pnlRatio": "0",
        "profit": "0",
        "quoteSz": "25",
        "rebateTrans": [{
            "rebate": "0",
            "rebateCcy": "BTC"
        }, {
            "rebate": "0",
            "rebateCcy": "USDT"
        }],
        "runPx": "30031.7",
        "runType": "1",
        "triggerParams": [{
            "triggerAction": "start",
            "triggerStrategy": "instant",
            "delaySeconds": "0",
            "triggerType": "auto",
            "triggerTime": ""
        }, {
            "triggerAction": "stop",
            "triggerStrategy": "instant",
            "delaySeconds": "0",
            "stopType": "1",
            "triggerType": "manual",
            "triggerTime": ""
        }],
        "singleAmt": "0.00101214",
        "slTriggerPx": "",
        "state": "running",
        "stopResult": "0",
        "stopType": "2",
        "tag": "",
        "totalAnnualizedRate": "0",
        "totalPnl": "0",
        "tpTriggerPx": "",
        "tradeNum": "0",
        "uTime": "1682406665527",
        "profitSharingRatio": "",
        "copyType": "0"
    }]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instType	String	产品类型
> uid	String	用户ID
data	Array	订阅的数据
> algoId	String	策略订单ID
> algoClOrdId	String	用户自定义策略ID
> instType	String	产品类型
> instId	String	产品ID
> cTime	String	策略订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> uTime	String	策略订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> algoOrdType	String	策略订单类型 `grid`：现货网格
> state	String	订单状态 `starting`：启动中 `running`：运行中 `stopping`：终止中 `stopped`：已停止
> rebateTrans	Array of object	返佣划转信息
>> rebate	String	返佣数量
>> rebateCcy	String	返佣币种
> triggerParams	Array of object	信号触发参数
>> triggerAction	String	触发行为 `start`：网格启动 `stop`：网格停止
>> triggerStrategy	String	触发策略 `instant`：立即触发 `price`：价格触发 `rsi`：rsi指标触发
>> delaySeconds	String	延迟触发时间，单位为秒
>> triggerTime	String	triggerAction实际触发时间，Unix时间戳的毫秒数格式, 如 `1597026383085`
>> triggerType	String	triggerAction的实际触发类型 `manual`：手动触发 `auto`: 自动触发
>> timeframe	String	K线种类 `3M`, `5M`, `15M`, `30M` (`M`代表分钟) `1H`, `4H` (`H`代表小时) `1D` (`D`代表天) 该字段只在`triggerStrategy`为`rsi`时有效
>> thold	String	阈值取值[1,100]的整数该字段只在`triggerStrategy`为`rsi`时有效
>> triggerCond	String	触发条件 `cross_up`：上穿 `cross_down`：下穿 `above`：上方 `below`：下方 `cross`：交叉该字段只在`triggerStrategy`为`rsi`时有效
>> timePeriod	String	周期 `14` 该字段只在`triggerStrategy`为`rsi`下有效
>> triggerPx	String	触发价格该字段只在`triggerStrategy`为`price`下有效
>> stopType	String	策略停止类型现货 `1`：卖出交易币，`2`：不卖出交易币合约网格 `1`：停止平仓，`2`：停止不平仓该字段只在`triggerAction`为`stop`时有效
> maxPx	String	区间最高价格
> minPx	String	区间最低价格
> gridNum	String	网格数量
> runType	String	网格类型 `1`：等差，`2`：等比
> tpTriggerPx	String	止盈触发价
> slTriggerPx	String	止损触发价
> tradeNum	String	挂单成交次数
> arbitrageNum	String	网格套利次数
> singleAmt	String	单网格买卖量
> perMinProfitRate	String	预期单网格最低利润率
> perMaxProfitRate	String	预期单网格最高利润率
> runPx	String	启动时价格
> totalPnl	String	总收益
> pnlRatio	String	收益率
> investment	String	投入金额现货网格如果投入了交易币则折算为计价币
> gridProfit	String	网格利润
> floatProfit	String	浮动盈亏
> totalAnnualizedRate	String	总年化
> annualizedRate	String	网格年化
> cancelType	String	网格策略停止原因 `0`：无 `1`：手动停止 `2`：止盈停止 `3`：止损停止 `4`：风控停止 `5`：交割停止 `6`: 信号停止
> stopType	String	网格策略停止类型现货网格 `1`：卖出交易币，`2`：不卖出交易币合约网格 `1`：市价全平，`2`：停止不平仓
> quoteSz	String	计价币投入数量仅适用于`现货网格`
> baseSz	String	交易币投入数量仅适用于`现货网格`
> curQuoteSz	String	当前持有的计价币资产仅适用于`现货网格`
> curBaseSz	String	当前持有的交易币资产仅适用于`现货网格`
> profit	String	当前可提取利润,单位是计价币仅适用于`现货网格`
> stopResult	String	现货网格策略停止结果 `0`：默认，`1`：市价卖币成功 `-1`：市价卖币失败仅适用于`现货网格`
> activeOrdNum	String	子订单挂单数量
> tag	String	订单标签
> profitSharingRatio	String	分润比例取值范围[0,0.3] 如果是普通订单（既不是带单也不是跟单），该字段返回""
> copyType	String	分润订单类型 `0`：普通订单 `1`：普通跟单 `2`：分润跟单 `3`：带单
> pTime	String	网格策略的推送时间，Unix时间戳的毫秒数格式，如 `1597026383085`

WS / 合约网格策略委托订单频道

支持合约网格策略订单的定时推送和事件推送

服务地址

/ws/v5/business (需要登录)

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "grid-orders-contract",
        "instType": "ANY"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，`subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `grid-orders-contract`
> instType	String	是	产品类型 `SWAP`：永续 `FUTURE`：交割 `ANY`：全部
> instId	String	否	产品ID
> algoId	String	否	策略ID

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "grid-orders-contract",
        "instType": "ANY"
    },
    "connId": "a4d3ae55"
}

失败返回示例

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

返回参数

参数	类型	是否必须	描述
event	String	是	事件 `subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名
> instType	String	是	产品类型
> instId	String	否	产品ID
> algoId	String	否	策略ID
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket连接ID

推送示例

{
    "arg": {
        "channel": "grid-orders-contract",
        "instType": "ANY",
        "uid": "4470****9584"
    },
    "data": [{
        "actualLever": "2.3481494635276649",
        "activeOrdNum": "10",
        "algoClOrdId": "",
        "algoId": "571039869070475264",
        "algoOrdType": "contract_grid",
        "annualizedRate": "0",
        "arbitrageNum": "0",
        "availEq": "52.3015392887089673",
        "basePos": true,
        "cTime": "1682418514204",
        "cancelType": "0",
        "direction": "long",
        "eq": "108.7945652387089673",
        "floatProfit": "8.7945652387089673",
        "gridNum": "10",
        "gridProfit": "0",
        "instId": "BTC-USDT-SWAP",
        "instType": "SWAP",
        "investment": "100",
        "lever": "5",
        "liqPx": "16370.482143120824",
        "maxPx": "36437.3",
        "minPx": "26931.9",
        "ordFrozen": "5.38638",
        "pTime": "1682492574068",
        "perMaxProfitRate": "0.1687494513302446",
        "perMinProfitRate": "0.1263869357706788",
        "pnlRatio": "0.0879456523870897",
        "rebateTrans": [{
            "rebate": "0",
            "rebateCcy": "USDT"
        }],
        "runPx": "27306.9",
        "runType": "1",
        "singleAmt": "1",
        "slTriggerPx": "",
        "state": "running",
        "stopType": "0",
        "sz": "100",
        "tag": "",
        "totalAnnualizedRate": "38.52019574554529",
        "totalPnl": "8.7945652387089673",
        "tpTriggerPx": "",
        "tradeNum": "9",
        "triggerParams": [{
            "triggerAction": "start",
            "delaySeconds": "0",
            "triggerStrategy": "price",
            "triggerPx": "1",
            "triggerType": "manual",
            "triggerTime": "1682418561497"
        }, {
            "triggerAction": "stop",
            "delaySeconds": "0",
            "triggerStrategy": "instant",
            "stopType": "1",
            "triggerType": "manual",
            "triggerTime": "0"
        }],
        "uTime": "1682492552257",
        "profitSharingRatio": "",
        "copyType": "0",
        "tpRatio": "",
        "slRatio": "",
        "fee": "",
        "fundingFee": ""
    }]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instType	String	产品类型
> uid	String	用户ID
data	Array	订阅的数据
> algoId	String	策略订单ID
> algoClOrdId	String	用户自定义策略ID
> instType	String	产品类型
> instId	String	产品ID
> cTime	String	策略订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> uTime	String	策略订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> algoOrdType	String	策略订单类型 `contract_grid`：合约网格
> state	String	订单状态 `starting`：启动中 `running`：运行中 `stopping`：终止中 `no_close_position`：已停止未平仓（仅适用于合约网格） `stopped`：已停止
> rebateTrans	Array of object	返佣划转信息
>> rebate	String	返佣数量
>> rebateCcy	String	返佣币种
> triggerParams	Array of object	信号触发参数
>> triggerAction	String	触发行为 `start`：网格启动 `stop`：网格停止
>> triggerStrategy	String	触发策略 `instant`：立即触发 `price`：价格触发 `rsi`：rsi指标触发
>> delaySeconds	String	延迟触发时间，单位为秒
>> triggerTime	String	triggerAction实际触发时间，Unix时间戳的毫秒数格式, 如 `1597026383085`
>> triggerType	String	triggerAction的实际触发类型 `manual`：手动触发 `auto`: 自动触发
>> timeframe	String	K线种类 `3m`, `5m`, `15m`, `30m` (`m`代表分钟) `1H`, `4H` (`H`代表小时) `1D` (`D`代表天) 该字段只在`triggerStrategy`为`rsi`时有效
>> thold	String	阈值取值[1,100]的整数该字段只在`triggerStrategy`为`rsi`时有效
>> triggerCond	String	触发条件 `cross_up`：上穿 `cross_down`：下穿 `above`：上方 `below`：下方 `cross`：交叉该字段只在`triggerStrategy`为`rsi`时有效
>> timePeriod	String	周期 `14` 该字段只在`triggerStrategy`为`rsi`下有效
>> triggerPx	String	触发价格该字段只在`triggerStrategy`为`price`下有效
>> stopType	String	策略停止类型现货网格 `1`：卖出交易币，`2`：不卖出交易币合约网格 `1`：停止平仓，`2`：停止不平仓该字段只在`triggerAction`为`stop`时有效
> maxPx	String	区间最高价格
> minPx	String	区间最低价格
> gridNum	String	网格数量
> runType	String	网格类型 `1`：等差，`2`：等比
> tpTriggerPx	String	止盈触发价
> slTriggerPx	String	止损触发价
> tradeNum	String	挂单成交次数
> arbitrageNum	String	网格套利次数
> singleAmt	String	单网格买卖量
> perMinProfitRate	String	预期单网格最低利润率
> perMaxProfitRate	String	预期单网格最高利润率
> runPx	String	启动时价格
> totalPnl	String	总收益
> pnlRatio	String	收益率
> investment	String	累计投入金额现货网格如果投入了交易币则折算为计价币
> gridProfit	String	网格利润
> floatProfit	String	浮动盈亏
> totalAnnualizedRate	String	总年化
> annualizedRate	String	网格年化
> cancelType	String	网格策略停止原因 `0`：无 `1`：手动停止 `2`：止盈停止 `3`：止损停止 `4`：风控停止 `5`：交割停止 `6`: 信号停止
> stopType	String	网格策略停止类型现货网格 `1`：卖出交易币，`2`：不卖出交易币合约网格 `1`：市价全平，`2`：停止不平仓
> direction	String	合约网格类型 `long`：做多，`short`：做空，`neutral`：中性仅适用于`合约网格`
> basePos	Boolean	是否开底仓仅适用于`合约网格`
> sz	String	投入保证金，单位为`USDT` 仅适用于`合约网格`
> lever	String	杠杆倍数仅适用于`合约网格`
> actualLever	String	实际杠杆倍数仅适用于`合约网格`
> liqPx	String	预估强平价格仅适用于`合约网格`
> eq	String	策略账户总权益仅适用于`合约网格`
> ordFrozen	String	挂单占用适用于`合约网格`
> availEq	String	可用保证金适用于`合约网格`
> activeOrdNum	String	子订单挂单数量
> tag	String	订单标签
> profitSharingRatio	String	分润比例取值范围[0,0.3] 如果是普通订单（既不是带单也不是跟单），该字段返回""
> copyType	String	分润订单类型 `0`：普通订单 `1`：普通跟单 `2`：分润跟单 `3`：带单
> tpRatio	String	止盈比率，0.1 代表 10%
> slRatio	String	止损比率，0.1 代表 10%
> fee	String	累计手续费金额，仅适用于合约网格，其他网格策略为""
> fundingFee	String	累计资金费用，仅适用于合约网格，其他网格策略为""
> pTime	String	网格策略的推送时间，Unix时间戳的毫秒数格式，如 `1597026383085`

WS / 合约网格持仓频道

支持网格策略持仓的首次订阅推送，定时推送和事件推送
请忽略空数据

服务地址

/ws/v5/business (需要登录)

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "grid-positions",
        "algoId": "449327675342323712"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，`subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `grid-positions`
> algoId	String	是	策略ID

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "grid-positions",
        "algoId": "449327675342323712"
    },
    "connId": "a4d3ae55"
}

失败返回示例

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

返回参数

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

推送示例

{
    "arg": {
        "channel": "grid-positions",
        "uid": "4470****9584",
        "algoId": "449327675342323712"
    },
    "data": [{
        "adl": "1",
        "algoClOrdId": "",
        "algoId": "449327675342323712",
        "avgPx": "29181.4638888888888895",
        "cTime": "1653400065917",
        "ccy": "USDT",
        "imr": "2089.2690000000002",
        "instId": "BTC-USDT-SWAP",
        "instType": "SWAP",
        "last": "29852.7",
        "lever": "5",
        "liqPx": "604.7617536513744",
        "markPx": "29849.7",
        "mgnMode": "cross",
        "mgnRatio": "217.71740878394456",
        "mmr": "41.78538",
        "notionalUsd": "10435.794191550001",
        "pTime": "1653536068723",
        "pos": "35",
        "posSide": "net",
        "uTime": "1653445498682",
        "upl": "232.83263888888962",
        "uplRatio": "0.1139826489932205"
    }]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> uid	String	用户标识
> algoId	String	策略订单ID
data	Array	订阅的数据
> algoId	String	策略订单ID
> algoClOrdId	String	用户自定义策略ID
> instType	String	产品类型
> instId	String	产品ID
> cTime	String	策略订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> uTime	String	策略订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> avgPx	String	开仓均价
> ccy	String	保证金币种
> lever	String	杠杆倍数
> liqPx	String	预估强平价
> posSide	String	持仓方向 `net`：买卖模式
> pos	String	持仓数量
> mgnMode	String	保证金模式 `cross`：全仓 `isolated`：逐仓
> mgnRatio	String	保证金率
> imr	String	初始保证金
> mmr	String	维持保证金
> upl	String	未实现收益
> uplRatio	String	未实现收益率
> last	String	最新成交价
> notionalUsd	String	仓位美金价值
> adl	String	信号区分为5档，从1到5，数字越小代表adl强度越弱
> markPx	String	标记价格
> pTime	String	订单信息的推送时间，Unix时间戳的毫秒数格式，如 `1597026383085`

WS / 网格策略子订单频道

支持网格策略子订单的事件推送
请忽略空数据

服务地址

/ws/v5/business (需要登录)

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "grid-sub-orders",
        "algoId": "449327675342323712"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，`subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `grid-sub-orders`
> algoId	String	是	策略ID

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "grid-sub-orders",
        "algoId": "449327675342323712"
    },
    "connId": "a4d3ae55"
}

失败返回示例

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

返回参数

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

推送示例

{
    "arg": {
        "channel": "grid-sub-orders",
        "uid": "44705892343619584",
        "algoId": "449327675342323712"
    },
    "data": [{
        "accFillSz": "0",
        "algoClOrdId": "",
        "algoId": "449327675342323712",
        "algoOrdType": "contract_grid",
        "avgPx": "0",
        "cTime": "1653445498664",
        "ctVal": "0.01",
        "fee": "0",
        "feeCcy": "USDT",
        "groupId": "-1",
        "instId": "BTC-USDT-SWAP",
        "instType": "SWAP",
        "lever": "5",
        "ordId": "449518234142904321",
        "ordType": "limit",
        "pTime": "1653486524502",
        "pnl": "",
        "posSide": "net",
        "px": "28007.2",
        "rebate": "0",
        "rebateCcy": "USDT",
        "side": "buy",
        "state": "live",
        "sz": "1",
        "tag":"",
        "tdMode": "cross",
        "uTime": "1653445498674"
    }]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> uid	String	用户标识
> algoId	String	策略订单ID
data	Array	订阅的数据
> algoId	String	策略订单ID
> algoClOrdId	String	用户自定义策略ID
> instType	String	产品类型
> instId	String	产品ID
> algoOrdType	String	策略订单类型 `grid`：现货网格委托 `contract_grid`：合约网格委托
> groupId	String	组ID
> ordId	String	子订单ID
> cTime	String	子订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> uTime	String	子订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> tag	String	订单标签
> tdMode	String	子订单交易模式 `cross`：全仓 `isolated`：逐仓 `cash`：非保证金
> ordType	String	子订单类型 `market`：市价单 `limit`：限价单 `ioc`：立即成交并取消剩余
> sz	String	子订单委托数量
> state	String	子订单状态 `canceled`：撤单成功 `live`：等待成交 `partially_filled`：部分成交 `filled`：完全成交 `cancelling`：撤单中
> side	String	子订单订单方向 `buy`：买 `sell`：卖
> px	String	子订单委托价格
> fee	String	子订单手续费数量
> feeCcy	String	子订单手续费币种
> rebate	String	子订单返佣数量
> rebateCcy	String	子订单返佣币种
> avgPx	String	子订单平均成交价格
> accFillSz	String	子订单累计成交数量
> posSide	String	子订单持仓方向 `net`：买卖模式
> pnl	String	子订单收益
> ctVal	String	合约面值
> lever	String	杠杆倍数
> pTime	String	订单信息的推送时间，Unix时间戳的毫秒数格式，如 `1597026383085`

信号交易

信号策略允许您将定制的数字货币交易策略展示在欧易平台。您可以完全控制自己设计的算法，而策略将会以高性能、高可靠性实时执行您的交易。了解更多

POST / 创建信号

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/signal/create-signal

请求示例

POST /api/v5/tradingBot/signal/create-signal
body
{
  "signalChanName": "long short",
  "signalDesc": "this is the first version"
}

请求参数

参数名	类型	是否必须	描述
signalChanName	String	是	信号名称
signalChanDesc	String	否	信号描述

返回结果

{
    "code": "0",
    "data": [
       {
           "signalChanId" :"572112109",
           "signalToken":"dojuckew331lkx"
       }

    ],
    "msg": ""
}

返回参数

参数名	类型	描述
signalChanId	String	信号ID
signalChanToken	String	信号单的用户身份标识

GET / 查询所有信号

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/tradingBot/signal/signals

请求示例

GET /api/v5/tradingBot/signal/signals

请求参数

参数名	类型	是否必须	描述
signalSourceType	String	是	信号来源类型 `1`：自己创建的 `2`：订阅他人 `3`：免费信号
signalChanId	String	否	信号ID
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的signalChanId
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的signalChanId
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "signalChanId": "623833708424069120",
            "signalChanName": "test",
            "signalChanDesc": "test",
            "signalChanToken": "test",
            "signalSourceType": "1"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
signalChanId	String	信号ID
signalChanName	String	信号名称
signalChanDesc	String	信号描述
signalChanToken	String	信号单的用户身份标识
signalSourceType	String	信号来源类型 `1`：自己创建的 `2`：订阅他人 `3`：免费信号

POST / 创建信号策略

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/signal/order-algo

请求示例

# 创建信号策略
POST /api/v5/tradingBot/signal/order-algo
body
{
  "signalChanId": "627921182788161536",
  "instIds": [
    "BTC-USDT-SWAP",
    "ETH-USDT-SWAP",
    "LTC-USDT-SWAP"
  ],
  "lever": "10",
  "investAmt": "100",
  "subOrdType": "9",
  "entrySettingParam": {
    "allowMultipleEntry": true,
    "entryType": "1",
    "amt": "",
    "ratio": ""
  },
  "exitSettingParam": {
    "tpSlType": "2",
    "tpPct": "",
    "slPct": ""
  }
}

请求参数

参数名	类型	是否必须	描述
signalChanId	String	是	信号ID
includeAll	Boolean	否	是否包含所有USDT 本位永续合约，默认false。 `true`: 包含 `false` : 不包含
instIds	String	否	该信号支持的产品ID列表，多个instId 用逗号分隔。当 includeAll 为true 时，忽略此参数
lever	String	是	杠杆倍数仅适用于合约信号
investAmt	String	是	投入金额
subOrdType	String	是	1：限价 2：市价 9：由tradingView信号指定
ratio	String	否	限价单的委托价格距离买一/卖一价的百分比。当委托类型为限价时，该字段有效。
entrySettingParam	String	否	进场参数设定
> allowMultipleEntry	String	否	是否允许多次进场，默认允许。 `true`：允许 `false`：不允许
> entryType	String	否	用户自定义策略ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
> amt	String	否	订单标签
> ratio	Array of object	否	信号触发参数适用于`现货网格`/`合约网格`
exitSettingParam	String	否	触发行为 `start`：网格启动 `stop`：网格停止
> tpSlType	String	是	触发策略 `instant`：立即触发 `price`：价格触发 `rsi`：rsi指标触发默认为`instant`
> tpPct	String	否	延迟触发时间，单位为秒，默认为`0`
> slPct	String	否	K线种类 `3m`, `5m`, `15m`, `30m` (`m`代表分钟) `1H`, `4H` (`H`代表小时) `1D` (`D`代表天) 该字段只在`triggerStrategy`为`rsi`时有效

返回结果

{
    "code": "0",
    "data": [
        {
            "algoClOrdId": "",
            "algoId": "447053782921515008",
            "sCode": "0",
            "sMsg": ""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略ID
algoClOrdId	String	用户自定义策略ID
sCode	String	事件执行结果的code，0代表成功
sMsg	String	事件执行失败时的msg

POST / 停止信号策略

每次最多可以撤销10个信号策略。

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/signal/stop-order-algo

请求示例

POST /api/v5/tradingBot/signal/stop-order-algo
body
[
    {
        "algoId":"448965992920907776"
    }
]

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略ID

返回结果

{
    "code": "0",
    "data": [
        {
            "algoId": "448965992920907776",
            "sCode": "0",
            "sMsg": "",
            "algoClOrdId": ""

        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略ID
sCode	String	事件执行结果的code，0代表成功
sMsg	String	事件执行失败时的msg
algoClOrdId	String	客户自定义订单ID

POST / 调整保证金

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/signal/margin-balance

请求示例

POST /api/v5/tradingBot/signal/margin-balance
body
{
   "algoId":"123456",
   "type":"add",
   "amt":"10"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略ID
type	String	是	调整保证金类型 `add`：增加，`reduce`：减少
amt	String	是	调整保证金数量
allowReinvest	Boolean	否	是否允许复投调整后的保证金，默认false。true 或者 false `false`:新投入的资金仅作为保证金用于避免爆仓 `true`:新投入的资金将可用于进行复投。仅适用于进场设定为“TradingView 信号”或“初始投资比例”的策略

返回结果

{
    "code": "0",
    "data": [
        {
            "algoId": "123456"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略ID

POST / 修改止盈止损

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/signal/amendTPSL

请求示例

POST /api/v5/tradingBot/signal/amendTPSL
body
{
    "algoId": "637039348240277504",
    "exitSettingParam": {
        "tpSlType": "pnl",
        "tpPct": "0.01",
        "slPct": "0.01"
    }
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略ID
exitSettingParam	String	是	离场参数设定
> tpSlType	String	是	止盈止损类型
> tpPct	String	否	止盈百分比
> slPct	String	否	止损百分比

返回结果

{
    "code": "0",
    "data": [
        {
            "algoId": "637039348240277504"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略ID

POST / 设置币对

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/signal/set-instruments

请求示例

POST /api/v5/tradingBot/signal/set-instruments
body
{
    "algoId": "637039348240277504",
    "instIds": [
        "SHIB-USDT-SWAP",
        "ETH-USDT-SWAP"
    ]
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略ID
instIds	Array	是	产品Id 列表，当 includeAll 为 true 时，忽略此参数。
includeAll	Boolean	是	是否包含所有USDT 本位永续合约，默认false `true`: 包含 `false` : 不包含

返回结果

{
    "code": "0",
    "data": [
        {
            "algoId": "637039348240277504"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略ID

GET / 获取信号策略详情

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/tradingBot/signal/orders-algo-details

请求示例

GET /api/v5/tradingBot/signal/orders-algo-details?algoId=623833708424069120&algoOrdType=contract

请求参数

参数名	类型	是否必须	描述
algoOrdType	String	是	策略类型 `contract`：合约信号
algoId	String	是	策略ID

返回结果

{
    "code": "0",
    "data": [
        {
            "algoId": "623833708424069120",
            "algoOrdType": "contract",
            "availBal": "1.6561369013122267",
            "cTime": "1695005546360",
            "cancelType": "0",
            "entrySettingParam": {
                "allowMultipleEntry": true,
                "amt": "0",
                "entryType": "1",
                "ratio": ""
            },
            "exitSettingParam": {
                "slPct": "",
                "tpPct": "",
                "tpSlType": "price"
            },
            "floatPnl": "0.1279999999999927",
            "frozenBal": "25.16816",
            "instIds": [
                "BTC-USDT-SWAP",
                "ETH-USDT-SWAP"
            ],
            "instType": "SWAP",
            "investAmt": "100",
            "lever": "10",
            "ratio": "",
            "realizedPnl": "-73.303703098687766",
            "signalChanId": "623827579484770304",
            "signalChanName": "我的信号",
            "signalSourceType": "1",
            "state": "running",
            "subOrdType": "9",
            "totalEq": "26.824296901312227",
            "totalPnl": "-73.1757030986877733",
            "totalPnlRatio": "-0.7317570309868777",
            "uTime": "1697029422313"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略ID
algoClOrdId	String	用户自定义策略ID
instType	String	产品类型
instIds	Array of string	该信号支持的产品ID列表
cTime	String	策略创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	策略更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
algoOrdType	String	策略类型 `contract`：合约信号
state	String	订单状态 `starting`：启动中 `running`：运行中 `stopping`：终止中 `stopped`：已停止
cancelType	String	策略停止原因 `0`：无 `1`：手动停止
totalPnl	String	总收益
totalPnlRatio	String	总收益率
totalEq	String	当前策略总权益
floatPnl	String	浮动盈亏
realizedPnl	String	已实现盈亏
frozenBal	String	占用保证金
availBal	String	可用保证金
lever	String	杠杆倍数仅适用于`合约信号`
investAmt	String	投入金额
subOrdType	String	委托类型 `1`：限价 `2`：市价 `9`：tradingView信号
ratio	String	限价单的委托价格距离买一/卖一价的百分比当委托类型为限价时，该字段有效，无效则返回""。
entrySettingParam	Object	进场参数设定
> allowMultipleEntry	Boolean	是否允许多次进场 `true`：允许 `false`：不允许
> entryType	String	单次委托类型 `1`：单次委托量具体数值将从 TradingView 信号中传入 `2`：单次委托量为固定数量的保证金 `3`：单次委托量为固定的合约张数 `4`：单次委托量基于在收到触发信号时策略中可用保证金的百分比 `5`：单次委托量基于在创建策略时设置的初始投入保证金的百分比
> amt	String	单笔委托量在单次委托类型是固定保证金 / 合约张数下该字段有效，无效的时候返回""
> ratio	String	单笔委托数量百分比在单次委托类型是占用保证金比例 / 初始投资比例下该字段有效，无效的时候返回""
exitSettingParam	Object	离场参数设定
> tpSlType	String	止盈止损类型，该参数用户确定设置止盈止损的触发价格计算的方式 `pnl`：基于平均持仓成本和预期收益率 `price`：基于相对于平均持仓成本的涨跌幅
> tpPct	String	止盈百分比
> slPct	String	止损百分比
signalChanId	String	信号ID
signalChanName	String	信号名称
signalSourceType	String	信号来源类型 `1`：自己创建的 `2`：订阅他人 `3`：免费信号

GET / 获取活跃信号策略

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/tradingBot/signal/orders-algo-pending

请求示例

GET /api/v5/tradingBot/signal/orders-algo-pending?algoOrdType=contract

请求参数

参数名	类型	是否必须	描述
algoOrdType	String	是	策略类型 `contract`：合约信号
algoId	String	否	策略ID
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的algoId
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的algoId
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "algoId": "623833708424069120",
            "algoOrdType": "contract",
            "availBal": "1.6561369013122267",
            "cTime": "1695005546360",
            "cancelType": "0",
            "entrySettingParam": {
                "allowMultipleEntry": true,
                "amt": "0",
                "entryType": "1",
                "ratio": ""
            },
            "exitSettingParam": {
                "slPct": "",
                "tpPct": "",
                "tpSlType": "price"
            },
            "floatPnl": "0.1279999999999927",
            "frozenBal": "25.16816",
            "instIds": [
                "BTC-USDT-SWAP",
                "ETH-USDT-SWAP"
            ],
            "instType": "SWAP",
            "investAmt": "100",
            "lever": "10",
            "ratio": "",
            "realizedPnl": "-73.303703098687766",
            "signalChanId": "623827579484770304",
            "signalChanName": "我的信号",
            "signalSourceType": "1",
            "state": "running",
            "subOrdType": "9",
            "totalEq": "26.824296901312227",
            "totalPnl": "-73.1757030986877733",
            "totalPnlRatio": "-0.7317570309868777",
            "uTime": "1697029422313"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略ID
algoClOrdId	String	用户自定义策略ID
instType	String	产品类型
instIds	Array of string	该信号支持的产品ID列表
cTime	String	策略创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	策略更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
algoOrdType	String	策略类型 `contract`：合约信号
state	String	订单状态 `starting`：启动中 `running`：运行中 `stopping`：终止中 `stopped`：已停止
cancelType	String	策略停止原因 `0`：无 `1`：手动停止
totalPnl	String	总收益
totalPnlRatio	String	总收益率
totalEq	String	当前策略总权益
floatPnl	String	浮动盈亏
realizedPnl	String	已实现盈亏
frozenBal	String	占用保证金
availBal	String	可用保证金
lever	String	杠杆倍数仅适用于`合约信号`
investAmt	String	投入金额
subOrdType	String	委托类型 `1`：限价 `2`：市价 `9`：tradingView信号
ratio	String	限价单的委托价格距离买一/卖一价的百分比当委托类型为限价时，该字段有效，无效则返回""。
entrySettingParam	Object	进场参数设定
> allowMultipleEntry	Boolean	是否允许多次进场 `true`：允许 `false`：不允许
> entryType	String	单次委托类型 `1`：单次委托量具体数值将从 TradingView 信号中传入 `2`：单次委托量为固定数量的保证金 `3`：单次委托量为固定的合约张数 `4`：单次委托量基于在收到触发信号时策略中可用保证金的百分比 `5`：单次委托量基于在创建策略时设置的初始投入保证金的百分比
> amt	String	单笔委托量在单次委托类型是固定保证金 / 合约张数下该字段有效，无效的时候返回""
> ratio	String	单笔委托数量百分比在单次委托类型是占用保证金比例 / 初始投资比例下该字段有效，无效的时候返回""
exitSettingParam	Object	离场参数设定
> tpSlType	String	止盈止损类型，该参数用户确定设置止盈止损的触发价格计算的方式 `pnl`：基于平均持仓成本和预期收益率 `price`：基于相对于平均持仓成本的涨跌幅
> tpPct	String	止盈百分比
> slPct	String	止损百分比
signalChanId	String	信号ID
signalChanName	String	信号名称
signalSourceType	String	信号来源类型 `1`：自己创建的 `2`：订阅他人 `3`：免费信号

GET / 获取历史信号策略

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/tradingBot/signal/orders-algo-history

请求示例

GET /api/v5/tradingBot/signal/orders-algo-history?algoId=623833708424069120&algoOrdType=contract

请求参数

参数名	类型	是否必须	描述
algoOrdType	String	是	策略类型 `contract`：合约信号
algoId	String	是	策略ID
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的algoId
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的algoId
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "algoId": "623833708424069120",
            "algoOrdType": "contract",
            "availBal": "1.6561369013122267",
            "cTime": "1695005546360",
            "cancelType": "1",
            "entrySettingParam": {
                "allowMultipleEntry": true,
                "amt": "0",
                "entryType": "1",
                "ratio": ""
            },
            "exitSettingParam": {
                "slPct": "",
                "tpPct": "",
                "tpSlType": "price"
            },
            "floatPnl": "0.1279999999999927",
            "frozenBal": "25.16816",
            "instIds": [
                "BTC-USDT-SWAP",
                "ETH-USDT-SWAP"
            ],
            "instType": "SWAP",
            "investAmt": "100",
            "lever": "10",
            "ratio": "",
            "realizedPnl": "-73.303703098687766",
            "signalChanId": "623827579484770304",
            "signalChanName": "我的信号",
            "signalSourceType": "1",
            "state": "stopped",
            "subOrdType": "9",
            "totalEq": "26.824296901312227",
            "totalPnl": "-73.1757030986877733",
            "totalPnlRatio": "-0.7317570309868777",
            "uTime": "1697029422313"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略ID
algoClOrdId	String	用户自定义策略ID
instType	String	产品类型
instIds	Array of string	该信号支持的产品ID列表
cTime	String	策略创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	策略更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
algoOrdType	String	策略类型 `contract`：合约信号
state	String	订单状态 `stopped`：已停止
cancelType	String	策略停止原因 1`：手动停止
totalPnl	String	总收益
totalPnlRatio	String	总收益率
totalEq	String	当前策略总权益
floatPnl	String	浮动盈亏
realizedPnl	String	已实现盈亏
frozenBal	String	占用保证金
availBal	String	可用保证金
lever	String	杠杆倍数仅适用于`合约信号`
investAmt	String	投入金额
subOrdType	String	委托类型 `1`：限价 `2`：市价 `9`：tradingView信号
ratio	String	限价单的委托价格距离买一/卖一价的百分比当委托类型为限价时，该字段有效，无效则返回""。
entrySettingParam	Object	进场参数设定
> allowMultipleEntry	Boolean	是否允许多次进场 `true`：允许 `false`：不允许
> entryType	String	单次委托类型 `1`：单次委托量具体数值将从 TradingView 信号中传入 `2`：单次委托量为固定数量的保证金 `3`：单次委托量为固定的合约张数 `4`：单次委托量基于在收到触发信号时策略中可用保证金的百分比 `5`：单次委托量基于在创建策略时设置的初始投入保证金的百分比
> amt	String	单笔委托量在单次委托类型是固定保证金 / 合约张数下该字段有效，无效的时候返回""
> ratio	String	单笔委托数量百分比在单次委托类型是占用保证金比例 / 初始投资比例下该字段有效，无效的时候返回""
exitSettingParam	Object	离场参数设定
> tpSlType	String	止盈止损类型，该参数用户确定设置止盈止损的触发价格计算的方式 `pnl`：基于平均持仓成本和预期收益率 `price`：基于相对于平均持仓成本的涨跌幅
> tpPct	String	止盈百分比
> slPct	String	止损百分比
signalChanId	String	信号ID
signalChanName	String	信号名称
signalSourceType	String	信号来源类型 `1`：自己创建的 `2`：订阅他人 `3`：免费信号

GET / 获取信号策略持仓

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/tradingBot/signal/positions

请求示例

GET /api/v5/tradingBot/signal/positions?algoId=623833708424069120&algoOrdType=contract

请求参数

参数名	类型	是否必须	描述
algoOrdType	String	是	订单类型 `contract`：合约信号
algoId	String	是	策略ID

返回结果

{
    "code": "0",
    "data": [
        {
            "adl": "1",
            "algoClOrdId": "",
            "algoId": "623833708424069120",
            "avgPx": "1597.74",
            "cTime": "1697502301460",
            "ccy": "USDT",
            "imr": "23.76495",
            "instId": "ETH-USDT-SWAP",
            "instType": "SWAP",
            "last": "1584.34",
            "lever": "10",
            "liqPx": "1438.7380360728976",
            "markPx": "1584.33",
            "mgnMode": "cross",
            "mgnRatio": "11.719278420807477",
            "mmr": "1.9011959999999997",
            "notionalUsd": "237.75168928499997",
            "pos": "15",
            "posSide": "net",
            "uTime": "1697502301460",
            "upl": "-2.0115000000000123",
            "uplRatio": "-0.0839310526118142"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略ID
algoClOrdId	String	用户自定义策略ID，将来扩展使用。
instType	String	产品类型
instId	String	产品ID，如 `BTC-USDT-SWAP`
cTime	String	策略创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	策略更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
avgPx	String	开仓均价
ccy	String	保证金币种
lever	String	杠杆倍数
liqPx	String	预估强平价
posSide	String	持仓方向 `net`：买卖模式
pos	String	持仓数量
mgnMode	String	保证金模式 `cross`：全仓 `isolated`：逐仓
mgnRatio	String	保证金率
imr	String	初始保证金
mmr	String	维持保证金
upl	String	未实现收益
uplRatio	String	未实现收益率
last	String	最新成交价
notionalUsd	String	仓位美金价值
adl	String	信号区分为5档，从1到5，数字越小代表adl强度越弱
markPx	String	标记价格

GET /查看历史持仓信息

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

限速：1次/10s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/tradingBot/signal/positions-history

请求示例

GET /api/v5/tradingBot/signal/positions-history?algoId=1234

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略ID
instId	String	否	交易产品ID，如：`BTC-USD-SWAP`
after	String	否	查询仓位更新 (uTime) 之前的内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
before	String	否	查询仓位更新 (uTime) 之后的内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
limit	String	否	分页返回结果的数量，最大为100，默认100条

返回结果

{
  "code": "0",
  "data": [
    {
      "cTime": "1704724451471",
      "closeAvgPx": "200",
      "direction": "net",
      "instId": "ETH-USDT-SWAP",
      "lever": "5.0",
      "mgnMode": "cross",
      "openAvgPx": "220",
      "pnl": "-2.021",
      "pnlRatio": "-0.4593181818181818",
      "uTime": "1704724456322",
      "uly": "ETH-USDT"
    }
  ],
  "msg": ""
}

返回参数

参数名	类型	描述
instId	String	交易产品ID
mgnMode	String	保证金模式 `cross`：全仓，`isolated`：逐仓"
cTime	String	仓位创建时间
uTime	String	仓位更新时间
openAvgPx	String	开仓均价
closeAvgPx	String	平仓均价
pnl	String	平仓收益额
pnlRatio	String	平仓收益率
lever	String	杠杆倍数
direction	String	持仓方向 `long`：多 `short`：空
uly	String	标的指数

POST / 市价仓位全平

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

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/signal/close-position

请求示例

POST /api/v5/tradingBot/signal/close-position
body
{
    "instId":"BTC-USDT-SWAP",
    "algoId":"448965992920907776"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略ID
instId	String	是	产品ID

返回结果

{
    "code": "0",
    "data": [
        {
            "algoId": "448965992920907776"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略ID

POST / 下单

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

限速：20次/2s

权限：交易

HTTP请求

POST /api/v5/tradingBot/signal/sub-order

请求示例

POST /api/v5/tradingBot/signal/sub-order
body
{
    "algoId":"1222",
    "instId":"BTC-USDT-SWAP",
    "side":"buy",
    "ordType":"limit",
    "px":"2.15",
    "sz":"2"
}

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 `BTC-USDT-SWAP`
algoId	String	是	策略订单ID
side	String	是	订单方向 `buy`：买， `sell`：卖
ordType	String	是	订单类型 `market`：市价单 `limit`：限价单
sz	String	是	委托数量
px	String	可选	委托价格，仅适用于`limit`
reduceOnly	Boolean	否	是否只减仓，`true` 或 `false`，默认`false` 仅适用于`现货和合约模式`和`跨币种保证金模式`

返回结果

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

返回参数

参数名	类型	描述
code	String	结果代码，`0`表示成功
msg	String	错误信息，代码为0时，该字段为空
data	String	包含结果的对象数组

POST / 撤单

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

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/signal/cancel-sub-order

请求示例

POST /api/v5/tradingBot/signal/cancel-sub-order
body
{
    "algoId":"91664",
    "signalOrdId":"590908157585625111",
    "instId":"BTC-USDT-SWAP"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略ID
instId	String	是	产品ID，如 BTC-USDT-SWAP
signalOrdId	String	是	订单ID

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "signalOrdId":"590908157585625111",
            "sCode":"0",
            "sMsg":""
        }
    ]
}

返回参数

参数名	类型	描述
code	String	结果代码，`0`表示成功
msg	String	错误信息，代码为0时，该字段为空
data	String	包含结果的对象数组
> signalOrdId	String	订单ID
> sCode	String	事件执行结果的code，0代表成功
> sMsg	String	事件执行失败时的msg

GET / 获取信号策略子订单信息

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/tradingBot/signal/sub-orders

请求示例

# 查询已成交历史子订单
GET /api/v5/tradingBot/signal/sub-orders?algoId=623833708424069120&algoOrdType=contract&state=filled

# 查询指定子订单
GET /api/v5/tradingBot/signal/sub-orders?algoId=623833708424069120&algoOrdType=contract&signalOrdId=O632302662327996418

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略ID
algoOrdType	String	是	策略类型 `contract`：合约信号
state	String	可选	子订单状态 `live`：未成交 `partially_filled`：部分成交 `filled`：已成交 `canceled`：已取消 state 和 signalOrdId 必须传一个，若传两个，以 state 为主
signalOrdId	String	可选	子订单ID
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的`ordId`
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的`ordId`
begin	String	否	请求`cTime`在此时间戳之后(包含)的数据，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
end	String	否	请求`cTime`在此时间戳之前(包含)的数据，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
limit	String	否	返回结果的数量，最大为100，默认100条
type	String	否	子订单类型 `live`：未成交 `filled`：已成交 `即将废弃`
clOrdId	String	否	子订单自定义订单ID `即将废弃`

返回结果

{
    "code": "0",
    "data": [
        {
            "accFillSz": "18",
            "algoClOrdId": "",
            "algoId": "623833708424069120",
            "algoOrdType": "contract",
            "avgPx": "1572.81",
            "cTime": "1697024702320",
            "ccy": "",
            "clOrdId": "O632302662327996418",
            "ctVal": "0.01",
            "fee": "-0.1415529",
            "feeCcy": "USDT",
            "instId": "ETH-USDT-SWAP",
            "instType": "SWAP",
            "lever": "10",
            "ordId": "632302662351958016",
            "ordType": "market",
            "pnl": "-2.6784",
            "posSide": "net",
            "px": "",
            "side": "buy",
            "state": "filled",
            "sz": "18",
            "tag": "",
            "tdMode": "cross",
            "uTime": "1697024702322"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略ID
algoClOrdId	String	用户自定义策略ID，将来扩展使用。
instType	String	产品类型
instId	String	交易产品ID
algoOrdType	String	策略类型 `contract`：合约信号
ordId	String	子订单ID
clOrdId	String	子订单自定义ID，等同于`signalOrdId`
cTime	String	子订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	子订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
tdMode	String	子订单交易模式 `cross`：全仓 `isolated`：逐仓 `cash`：非保证金
ccy	String	保证金币种仅适用于`现货和合约模式`下的`全仓杠杆`订单
ordType	String	子订单类型 `market`：市价单 `limit`：限价单 `ioc`：立即成交并取消剩余
sz	String	子订单委托数量
state	String	子订单状态 `canceled`：撤单成功 `live`：等待成交 `partially_filled`：部分成交 `filled`：完全成交 `cancelling`：撤单中
side	String	子订单订单方向 `buy`：买 `sell`：卖
px	String	子订单委托价格
fee	String	子订单手续费数量
feeCcy	String	子订单手续费币种
avgPx	String	子订单平均成交价格
accFillSz	String	子订单累计成交数量
posSide	String	子订单持仓方向 `net`：买卖模式
pnl	String	子订单收益
ctVal	String	合约面值仅支持`FUTURES/SWAP`
lever	String	杠杆倍数
tag	String	订单标签

GET / 获取信号策略历史事件

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/tradingBot/signal/event-history

请求示例

GET /api/v5/tradingBot/signal/event-history?algoId=623833708424069120

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略ID
after	String	否	请求`eventCtime`在此时间之前（更旧的数据）的分页内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
before	String	否	请求`eventCtime`此时间之后（更新的数据）的分页内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "alertMsg": "{\"marketPosition\":\"short\",\"prevMarketPosition\":\"long\",\"action\":\"sell\",\"instrument\":\"ETHUSDT.P\",\"timestamp\":\"2023-10-16T10:50:00.000Z\",\"maxLag\":\"60\",\"investmentType\":\"base\",\"amount\":\"2\"}",
            "algoId": "623833708424069120",
            "eventCtime": "1697453400959",
            "eventProcessMsg": "Processed reverse entry signal and placed ETH-USDT-SWAP order with all available balance",
            "eventStatus": "success",
            "eventType": "signal_processing",
            "eventUtime": "",
            "triggeredOrdData": [
                {
                    "clOrdId": "O634100754731765763"
                },
                {
                    "clOrdId": "O634100754752737282"
                }
            ]
        }
     ],
     "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略ID
eventType	String	事件类型 `system_action`：系统行为 `user_action`：用户行为 `signal_processing`：信号下单
eventCtime	String	事件发生时间，Unix时间戳的毫秒数格式，如 `1597026383085`
eventUtime	String	事件更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
eventProcessMsg	String	事件处理信息
eventStatus	String	事件处理状态 `success`：成功 `failure`：失败
triggeredOrdData	Array of object	信号触发的子订单的信息
> clOrdId	String	子订单自定义ID

定投

定投是以固定的时间周期，投入固定的金额买入选定币种的策略。在市场波动较为剧烈时，运用适当的定投策略，以同样的投资额度可以在低点购入更多的筹码，可以使用户获得更加可观的收益。了解更多
定投功能模块下的API接口需要身份验证。

POST / 定投策略委托下单

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/recurring/order-algo

请求示例

POST /api/v5/tradingBot/recurring/order-algo
body
{
  "stgyName": "BTC|ETH recurring buy monthly",     
  "amt":"100",
  "recurringList":[    
    {
         "ccy":"BTC",
         "ratio":"0.2"
    },
    {
         "ccy":"ETH",
         "ratio":"0.8"
    }
  ],
  "period":"monthly",
  "recurringDay":"1",
  "recurringTime":"0",
  "timeZone":"8",   // 东8区
  "tdMode":"cross",
  "investmentCcy":"USDT"
}

请求参数

参数名	类型	是否必须	描述
stgyName	String	是	策略自定义名称，不超过40个字符
recurringList	Array of object	是	定投信息
> ccy	String	是	定投币种，如 `BTC`
> ratio	String	是	定投币种资产占比，如 "0.2"代表占比20%
period	String	是	周期类型 `monthly`：月 `weekly`：周 `daily`：日 `hourly`：小时
recurringDay	String	可选	投资日当周期类型为`monthly`，则取值范围是 [1,28] 的整数当周期类型为`weekly`，则取值范围是 [1,7] 的整数当周期类型为`daily`/`hourly`，该参数可不填。
recurringHour	String	可选	小时级别定投的间隔 `1`/`4`/`8`/`12` 如：`1`代表每隔`1`个小时定投当周期类型选择`hourly`，该字段必填。
recurringTime	String	是	投资时间，取值范围是 [0,23] 的整数当周期类型选择`hourly`代表首次定投发生的时间
timeZone	String	是	时区（UTC），取值范围是 [-12,14] 的整数如 `8`表示UTC+8（东8区），北京时间
amt	String	是	每期投入数量
investmentCcy	String	是	投入数量单位，只能是`USDT`/`USDC`
tdMode	String	是	交易模式 `跨币种保证金模式`/`组合保证金模式`下选择 `cross`：全仓 `现货模式`/`现货和合约模式`下选择 `cash`：非保证金
algoClOrdId	String	否	客户自定义订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
tag	String	否	订单标签字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "algoId":"560472804207104000",
            "algoClOrdId":"",
            "sCode":"0",
            "sMsg":"",
            "tag":""
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
algoClOrdId	String	客户自定义订单ID
sCode	String	事件执行结果的code，0代表成功
sMsg	String	事件执行失败时的msg
tag	String	订单标签

POST / 修改定投策略订单

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/recurring/amend-order-algo

请求示例

POST /api/v5/tradingBot/recurring/amend-order-algo
body
{
    "algoId":"448965992920907776",
    "stgyName":"stg1"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID
stgyName	String	是	调整后的策略自定义名称

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "algoId":"448965992920907776",
            "algoClOrdId":"",
            "sCode":"0",
            "sMsg":""
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
algoClOrdId	String	客户自定义订单ID
sCode	String	事件执行结果的code，0代表成功
sMsg	String	事件执行失败时的msg

POST / 定投策略停止

每次最多可以撤销10个定投策略订单。

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/tradingBot/recurring/stop-order-algo

请求示例

POST /api/v5/tradingBot/recurring/stop-order-algo
body
[
    {
        "algoId":"560472804207104000"
    }
]

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID

返回结果

{
    "code": "0",
    "data": [
        {
            "algoClOrdId": "",
            "algoId": "1839309556514557952",
            "sCode": "0",
            "sMsg": "",
            "tag": ""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
algoClOrdId	String	客户自定义订单ID
sCode	String	事件执行结果的code，0代表成功
sMsg	String	事件执行失败时的msg
tag	String	~~订单标签~~（已废弃）

GET / 获取未完成定投策略委托单列表

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/tradingBot/recurring/orders-algo-pending

请求示例

GET /api/v5/tradingBot/recurring/orders-algo-pending

请求参数

参数名	类型	是否必须	描述
algoId	String	否	策略订单ID
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的`algoId`
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的`algoId`
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "algoClOrdId": "",
            "algoId": "644497312047435776",
            "algoOrdType": "recurring",
            "amt": "100",
            "cTime": "1699932133373",
            "cycles": "6",
            "instType": "SPOT",
            "investmentAmt": "0",
            "investmentCcy": "USDC",
            "mktCap": "0",
            "period": "hourly",
            "pnlRatio": "0",
            "recurringDay": "",
            "recurringHour": "1",
            "recurringList": [
                {
                    "ccy": "BTC",
                    "ratio": "0.2"
                },
                {
                    "ccy": "ETH",
                    "ratio": "0.8"
                }
            ],
            "recurringTime": "12",
            "state": "running",
            "stgyName": "stg1",
            "tag": "",
            "timeZone": "8",
            "totalAnnRate": "0",
            "totalPnl": "0",
            "uTime": "1699952473152"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
algoClOrdId	String	客户自定义订单ID
instType	String	产品类型 `SPOT`：现货
cTime	String	策略订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	策略订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
algoOrdType	String	策略订单类型 `recurring`：定投
state	String	订单状态 `running`：运行中 `stopping`：终止中 `pause`: 已暂停
stgyName	String	策略自定义名称，不超过40个字符
recurringList	Array of object	定投信息
> ccy	String	定投币种，如 `BTC`
> ratio	String	定投币种资产占比，如 "0.2"代表占比20%
period	String	周期类型 `monthly`：月 `weekly`：周 `daily`：日 `hourly`：小时
recurringDay	String	投资日当周期类型为`monthly`，则取值范围是 [1,28] 的整数当周期类型为`weekly`，则取值范围是 [1,7] 的整数
recurringHour	String	小时级别定投的间隔 `1`/`4`/`8`/`12` 如：`1`代表每隔`1`个小时定投
recurringTime	String	投资时间，取值范围是 [0,23] 的整数
timeZone	String	时区（UTC），取值范围是 [-12,14] 的整数如 `8`表示UTC+8（东8区），北京时间
amt	String	每期投入数量
investmentAmt	String	累计投入数量
investmentCcy	String	投入数量单位，只能是`USDT`/`USDC`
totalPnl	String	总收益
totalAnnRate	String	总年化
pnlRatio	String	收益率
mktCap	String	当前总市值，单位为`USDT`
cycles	String	定投累计轮数
tag	String	订单标签

GET / 获取历史定投策略委托单列表

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/tradingBot/recurring/orders-algo-history

请求示例

GET /api/v5/tradingBot/recurring/orders-algo-history

请求参数

参数名	类型	是否必须	描述
algoId	String	否	策略订单ID
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的`algoId`
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的`algoId`
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "algoClOrdId": "",
            "algoId": "644496098429767680",
            "algoOrdType": "recurring",
            "amt": "100",
            "cTime": "1699931844050",
            "cycles": "0",
            "instType": "SPOT",
            "investmentAmt": "0",
            "investmentCcy": "USDC",
            "mktCap": "0",
            "period": "hourly",
            "pnlRatio": "0",
            "recurringDay": "",
            "recurringHour": "1",
            "recurringList": [
                {
                    "ccy": "BTC",
                    "ratio": "0.2"
                },
                {
                    "ccy": "ETH",
                    "ratio": "0.8"
                }
            ],
            "recurringTime": "0",
            "state": "stopped",
            "stgyName": "stg1",
            "tag": "",
            "timeZone": "8",
            "totalAnnRate": "0",
            "totalPnl": "0",
            "uTime": "1699932177659"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
algoClOrdId	String	客户自定义订单ID
instType	String	产品类型 `SPOT`：现货
cTime	String	策略订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	策略订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
algoOrdType	String	策略订单类型 `recurring`：定投
state	String	订单状态 `stopped`：已停止
stgyName	String	策略自定义名称，不超过40个字符
recurringList	Array of object	定投信息
> ccy	String	定投币种，如 `BTC`
> ratio	String	定投币种资产占比，如 "0.2"代表占比20%
period	String	周期类型 `monthly`：月 `weekly`：周 `daily`：日 `hourly`：小时
recurringDay	String	投资日当周期类型为`monthly`，则取值范围是 [1,28] 的整数当周期类型为`weekly`，则取值范围是 [1,7] 的整数
recurringHour	String	小时级别定投的间隔 `1`/`4`/`8`/`12` 如：`1`代表每隔`1`个小时定投
recurringTime	String	投资时间，取值范围是 [0,23] 的整数
timeZone	String	时区（UTC），取值范围是 [-12,14] 的整数如 `8`表示UTC+8（东8区），北京时间
amt	String	每期投入数量
investmentAmt	String	累计投入数量
investmentCcy	String	投入数量单位，只能是`USDT`/`USDC`
totalPnl	String	总收益
totalAnnRate	String	总年化
pnlRatio	String	收益率
mktCap	String	当前总市值，单位为`USDT`
cycles	String	定投累计轮数
tag	String	订单标签

GET / 获取定投策略委托订单详情

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/tradingBot/recurring/orders-algo-details

请求示例

GET /api/v5/tradingBot/recurring/orders-algo-details?algoId=644497312047435776

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID

返回结果

{
    "code": "0",
    "data": [
        {
            "algoClOrdId": "",
            "algoId": "644497312047435776",
            "algoOrdType": "recurring",
            "amt": "100",
            "cTime": "1699932133373",
            "cycles": "6",
            "instType": "SPOT",
            "investmentAmt": "0",
            "investmentCcy": "USDC",
            "mktCap": "0",
            "nextInvestTime": "1699956005500",
            "period": "hourly",
            "pnlRatio": "0",
            "recurringDay": "",
            "recurringHour": "1",
            "recurringList": [
                {
                    "avgPx": "0",
                    "ccy": "BTC",
                    "profit": "0",
                    "px": "36683.2",
                    "ratio": "0.2",
                    "totalAmt": "0"
                },
                {
                    "avgPx": "0",
                    "ccy": "ETH",
                    "profit": "0",
                    "px": "2058.36",
                    "ratio": "0.8",
                    "totalAmt": "0"
                }
            ],
            "recurringTime": "12",
            "state": "running",
            "stgyName": "stg1",
            "tag": "",
            "timeZone": "8",
            "totalAnnRate": "0",
            "totalPnl": "0",
            "uTime": "1699952485451"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
algoClOrdId	String	客户自定义订单ID
instType	String	产品类型 `SPOT`：现货
cTime	String	策略订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	策略订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
algoOrdType	String	策略订单类型 `recurring`：定投
state	String	订单状态 `running`：运行中 `stopping`：终止中 `stopped`：已停止 `pause`: 已暂停
stgyName	String	策略自定义名称，不超过40个字符
recurringList	Array of object	定投信息
> ccy	String	定投币种，如 `BTC`
> ratio	String	定投币种资产占比，如 "0.2"代表占比20%
> totalAmt	String	累计购入定投币种的数量
> profit	String	定投收益，单位为`investmentCcy`
> avgPx	String	定投均价，计价单位为`investmentCcy`
> px	String	当前价格，计价单位为`investmentCcy`
period	String	周期类型 `monthly`：月 `weekly`：周 `daily`：日 `hourly`：小时
recurringDay	String	投资日当周期类型为`monthly`，则取值范围是 [1,28] 的整数当周期类型为`weekly`，则取值范围是 [1,7] 的整数
recurringHour	String	小时级别定投的间隔 `1`/`4`/`8`/`12` 如：`1`代表每隔`1`个小时定投
recurringTime	String	投资时间，取值范围是 [0,23] 的整数
timeZone	String	时区（UTC），取值范围是 [-12,14] 的整数如 `8`表示UTC+8（东8区），北京时间
amt	String	每期投入数量
investmentAmt	String	累计投入数量
investmentCcy	String	投入数量单位，只能是`USDT`/`USDC`
nextInvestTime	String	下一次定投发生的时间，Unix时间戳的毫秒数格式，如 `1597026383085`
totalPnl	String	总收益
totalAnnRate	String	总年化
pnlRatio	String	收益率
mktCap	String	当前总市值，单位为`USDT`
cycles	String	定投累计轮数
tag	String	订单标签

GET / 获取定投策略子订单信息

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/tradingBot/recurring/sub-orders

请求示例

GET /api/v5/tradingBot/recurring/sub-orders?algoId=560516615079727104

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID
ordId	String	否	子订单ID
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的`ordId`
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的`ordId`
limit	String	否	返回结果的数量，最大为300，默认300条

返回结果

{
    "code": "0",
    "data": [
        {
            "accFillSz": "0.045315",
            "algoClOrdId": "",
            "algoId": "560516615079727104",
            "algoOrdType": "recurring",
            "avgPx": "1765.4",
            "cTime": "1679911222200",
            "fee": "-0.0000317205",
            "feeCcy": "ETH",
            "instId": "ETH-USDC",
            "instType": "SPOT",
            "ordId": "560523524230717440",
            "ordType": "market",
            "px": "-1",
            "side": "buy",
            "state": "filled",
            "sz": "80",
            "tag": "",
            "tdMode": "",
            "uTime": "1679911222207"
        },
        {
            "accFillSz": "0.00071526",
            "algoClOrdId": "",
            "algoId": "560516615079727104",
            "algoOrdType": "recurring",
            "avgPx": "27961.6",
            "cTime": "1679911222189",
            "fee": "-0.000000500682",
            "feeCcy": "BTC",
            "instId": "BTC-USDC",
            "instType": "SPOT",
            "ordId": "560523524184580096",
            "ordType": "market",
            "px": "-1",
            "side": "buy",
            "state": "filled",
            "sz": "20",
            "tag": "",
            "tdMode": "",
            "uTime": "1679911222194"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
instType	String	产品类型
instId	String	产品ID
algoOrdType	String	策略订单类型 `recurring`：定投
ordId	String	子订单ID
cTime	String	子订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	子订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
tdMode	String	子订单交易模式 `cross`：全仓 `cash`：非保证金
ordType	String	子订单类型 `market`：市价单
sz	String	子订单委托数量
state	String	子订单状态 `canceled`：撤单成功 `live`：等待成交 `partially_filled`：部分成交 `filled`：完全成交 `cancelling`：撤单中
side	String	子订单订单方向 `buy`：买 `sell`：卖
px	String	子订单委托价格市价委托时为"-1"
fee	String	子订单手续费数量
feeCcy	String	子订单手续费币种
avgPx	String	子订单平均成交价格
accFillSz	String	子订单累计成交数量
tag	String	订单标签

WS / 定投策略委托订单频道

支持定投策略订单的定时推送和事件推送

服务地址

/ws/v5/business (需要登录)

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "algo-recurring-buy",
        "instType": "SPOT"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，`subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `algo-recurring-buy`
> instType	String	是	产品类型 `SPOT`：币币 `ANY`：全部
> algoId	String	否	策略ID

成功返回示例

{
        "event": "subscribe",
        "arg": {
                "channel": "algo-recurring-buy",
                "instType": "SPOT"
        },
        "connId": "a4d3ae55"
}

失败返回示例

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

返回参数

参数	类型	是否必须	描述
event	String	是	事件，`subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名
> instType	String	是	产品类型
> algoId	String	否	策略ID
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket连接ID

推送示例

{
    "arg": {
        "channel": "algo-recurring-buy",
        "instType": "SPOT",
        "uid": "447*******584"
    },
    "data": [{
        "algoClOrdId": "",
        "algoId": "644497312047435776",
        "algoOrdType": "recurring",
        "amt": "100",
        "cTime": "1699932133373",
        "cycles": "0",
        "instType": "SPOT",
        "investmentAmt": "0",
        "investmentCcy": "USDC",
        "mktCap": "0",
        "nextInvestTime": "1699934415300",
        "pTime": "1699933314691",
        "period": "hourly",
        "pnlRatio": "0",
        "recurringDay": "",
        "recurringHour": "1",
        "recurringList": [{
            "avgPx": "0",
            "ccy": "BTC",
            "profit": "0",
            "px": "36482",
            "ratio": "0.2",
            "totalAmt": "0"
        }, {
            "avgPx": "0",
            "ccy": "ETH",
            "profit": "0",
            "px": "2057.54",
            "ratio": "0.8",
            "totalAmt": "0"
        }],
        "recurringTime": "12",
        "state": "running",
        "stgyName": "stg1",
        "tag": "",
        "timeZone": "8",
        "totalAnnRate": "0",
        "totalPnl": "0",
        "uTime": "1699932136249"
    }]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instType	String	产品类型
> algoId	String	策略ID
> uid	String	用户ID
data	Array	订阅的数据
> algoId	String	策略订单ID
> algoClOrdId	String	客户自定义订单ID
> instType	String	产品类型 `SPOT`：现货
> cTime	String	策略订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> uTime	String	策略订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> algoOrdType	String	策略订单类型 `recurring`：定投
> state	String	订单状态 `running`：运行中 `stopping`：终止中 `stopped`：已停止 `pause`: 已暂停
> stgyName	String	策略自定义名称，不超过40个字符
> recurringList	Array of object	定投信息
>> ccy	String	定投币种，如 `BTC`
>> ratio	String	定投币种资产占比，如 "0.2"代表占比20%
>> totalAmt	String	累计购入定投币种的数量
>> profit	String	定投收益，单位为`investmentCcy`
>> avgPx	String	定投均价，计价单位为`investmentCcy`
>> px	String	当前价格，计价单位为`investmentCcy`
> period	String	周期类型 `monthly`：月 `weekly`：周 `daily`：日 `hourly`：小时
> recurringDay	String	投资日当周期类型为`monthly`，则取值范围是 [1,28] 的整数当周期类型为`weekly`，则取值范围是 [1,7] 的整数
> recurringHour	String	小时级别定投的间隔 `1`/`4`/`8`/`12` 如：`1`代表每隔`1`个小时定投
> recurringTime	String	投资时间，取值范围是 [0,23] 的整数
> timeZone	String	时区（UTC），取值范围是 [-12,14] 的整数如 `8`表示UTC+8（东8区），北京时间
> amt	String	每期投入数量
> investmentAmt	String	累计投入数量
> investmentCcy	String	投入数量单位，只能是`USDT`/`USDC`
> nextInvestTime	String	下一次定投发生的时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> totalPnl	String	总收益
> totalAnnRate	String	总年化
> pnlRatio	String	收益率
> mktCap	String	当前总市值，单位为`USDT`
> cycles	String	定投累计轮数
> tag	String	订单标签
> pTime	String	策略订单的推送时间，Unix时间戳的毫秒数格式，如 `1597026383085`

跟单

带单 API 交易工作流程如下：

1. 申请成为带单交易员

申请流程可以参考如何申请成为交易员；
可通过查看账户配置接口的roleType 或者 spotRoleType 是否为 1，判断当前账户是否为带单交易员。

2. 带单合约

获取带单产品接口，用于查看平台哪些合约支持带单，以及您开启了哪些合约的带单。对于您未开启带单的合约，依旧可以正常交易，只是不会触发跟单；
交易员修改带单合约接口，初始带单合约在申请带单交易员时进行设置，该接口用于修改您的带单合约。非带单合约修改为带单合约时，该次请求中所有的非带单合约合约不能有持仓或者挂单。

3. 开仓

需要通过下单接口和频道进行开仓，包括：下单接口、批量下单接口、下单频道、批量下单频道。现货带单时，tdMode 的值需要指定为spot_isolated
在买卖模式下，委托的方向必须与现有持仓和挂单保持一致，如果对应产品没有持仓和挂单，可根据自己的需求选择委托方向；
开平仓模式下，可根据自己的需求选择开多或开空。

4. 平仓

可以通过下单接口和频道进行平仓，支持自定义价格和数量，包括：下单接口、批量下单接口、下单频道、批量下单频道，也可以通过市价仓位全平接口或者平仓带单接口进行平仓；
市价仓位全平接口，平掉当前产品下指定的仓位（如：开平模式下，全仓模式下的多仓或空仓），可能包含多个带单；
平仓带单接口，一次仅平仓某一个带单仓位。带单ID（subPosId）为必填参数，需要通过获取当前带单接口获取。

5. 止盈止损

可以通过带单仓位止盈止损接口或者策略委托下单接口设置止盈止损；
带单仓位止盈止损接口，一次仅为一个带单仓位设置。带单ID（subPosId）为必填参数，需要通过获取当前带单接口获取。
策略委托下单接口，为当前产品下指定的仓位（如：开平模式下，全仓模式下的多仓或空仓）设置，可能包含多个带单；

GET / 获取当前带单

获取当前未平仓的带单仓位。

按照开仓时间倒序排列。

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/current-subpositions

请求示例

GET /api/v5/copytrading/current-subpositions?instId=BTC-USDT-SWAP

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约默认返回所有业务线的信息
instId	String	否	产品ID ，如`BTC-USDT-SWAP`
after	String	否	请求此id之前（更旧的数据）的分页内容，传的值为对应接口的`subPosId`
before	String	否	请求此id之后（更新的数据）的分页内容，传的值为对应接口的`subPosId`
limit	String	否	分页返回的结果集数量，最大为500，不填默认返回500条

返回结果

{
    "code": "0",
    "data": [
        {
            "algoId": "",
            "ccy": "USDT",
            "instId": "BTC-USDT-SWAP",
            "instType": "SWAP",
            "lever": "3",
            "margin": "12.6417",
            "markPx": "38205.8",
            "mgnMode": "isolated",
            "openAvgPx": "37925.1",
            "openOrdId": "",
            "openTime": "1701231120479",
            "posSide": "net",
            "slOrdPx": "",
            "slTriggerPx": "",
            "subPos": "1",
            "subPosId": "649945658862370816",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "uniqueCode": "25CD5A80241D6FE6",
            "upl": "0.2807",
            "uplRatio": "0.0222042921442527",
            "availSubPos": "1"
        },
        {
            "algoId": "",
            "ccy": "USDT",
            "instId": "BTC-USDT-SWAP",
            "instType": "SWAP",
            "lever": "3",
            "margin": "12.6263333333333333",
            "markPx": "38205.8",
            "mgnMode": "isolated",
            "openAvgPx": "37879",
            "openOrdId": "",
            "openTime": "1701225074786",
            "posSide": "net",
            "slOrdPx": "",
            "slTriggerPx": "",
            "subPos": "1",
            "subPosId": "649920301388038144",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "uniqueCode": "25CD5A80241D6FE6",
            "upl": "0.3268",
            "uplRatio": "0.0258824150584758",
            "availSubPos": "1"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品ID
subPosId	String	带单仓位ID
posSide	String	持仓方向 long：开平仓模式开多 short：开平仓模式开空 net：买卖模式（subPos为正代表开多，subPos为负代表开空）
mgnMode	String	保证金模式，`isolated`：逐仓；`cross`：全仓
lever	String	杠杆倍数
openOrdId	String	交易员开仓订单号，仅适用于带单仓位
openAvgPx	String	开仓均价
openTime	String	开仓时间
subPos	String	持仓张数
tpTriggerPx	String	止盈触发价
slTriggerPx	String	止损触发价
algoId	String	止盈止损委托单ID
instType	String	产品类型 SPOT：币币 SWAP：永续合约
tpOrdPx	String	止盈委托价，市价时为-1
slOrdPx	String	止损委托价，市价时为-1
margin	String	保证金
upl	String	未实现收益
uplRatio	String	未实现收益率
markPx	String	最新标记价格，仅适用于合约
uniqueCode	String	交易员唯一标识代码
ccy	String	保证金币种
availSubPos	String	可平张数/币数

GET / 获取历史带单

获取最近三个月的已经平仓的带单仓位，按照subPosId倒序排序。

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/subpositions-history

请求示例

GET /api/v5/copytrading/subpositions-history?instId=BTC-USDT-SWAP

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约默认返回所有业务线的信息
instId	String	否	产品ID ，如`BTC-USDT-SWAP`
after	String	否	请求此id之前（更旧的数据）的分页内容，传的值为对应接口的`subPosId`
before	String	否	请求此id之后（更新的数据）的分页内容，传的值为对应接口的`subPosId`
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "closeAvgPx": "37617.5",
            "closeTime": "1701188587950",
            "instId": "BTC-USDT-SWAP",
            "instType": "SWAP",
            "lever": "3",
            "margin": "37.41",
            "markPx": "38203.4",
            "mgnMode": "isolated",
            "openAvgPx": "37410",
            "openOrdId": "",
            "openTime": "1701184638702",
            "pnl": "0.6225",
            "pnlRatio": "0.0166399358460306",
            "posSide": "net",
            "profitSharingAmt": "0.0407967",
            "subPos": "3",
            "closeSubPos": "2",
            "type": "1",
            "subPosId": "649750700213698561",
            "uniqueCode": "25CD5A80241D6FE6"
        },
        {
            "ccy": "USDT",
            "closeAvgPx": "37617.5",
            "closeTime": "1701188587950",
            "instId": "BTC-USDT-SWAP",
            "instType": "SWAP",
            "lever": "3",
            "margin": "24.94",
            "markPx": "38203.4",
            "mgnMode": "isolated",
            "openAvgPx": "37410",
            "openOrdId": "",
            "openTime": "1701184635381",
            "pnl": "0.415",
            "pnlRatio": "0.0166399358460306",
            "posSide": "net",
            "profitSharingAmt": "0.0271978",
            "subPos": "2",
            "closeSubPos": "2",
            "type": "2",
            "subPosId": "649750686292803585",
            "uniqueCode": "25CD5A80241D6FE6"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品ID
subPosId	String	带单仓位ID
posSide	String	持仓方向 long：开平仓模式开多 short：开平仓模式开空 net：买卖模式（subPos为正代表开多，subPos为负代表开空）
mgnMode	String	保证金模式，`isolated`：逐仓；`cross`：全仓
lever	String	杠杆倍数
openOrdId	String	交易员开仓订单号，仅适用于带单仓位
openAvgPx	String	开仓均价
openTime	String	开仓时间
subPos	String	持仓张数
closeTime	String	平仓时间(最近一次平仓的时间)
closeAvgPx	String	平仓均价
pnl	String	收益额
pnlRatio	String	收益率
instType	String	产品类型 SPOT：币币 SWAP：永续合约
margin	String	保证金
ccy	String	币种
markPx	String	最新标记价格，仅适用于合约
uniqueCode	String	交易员唯一标识代码
profitSharingAmt	String	跟单分润额，仅适用于跟单，已经废弃。
closeSubPos	String	已平仓量
type	String	平仓类型 `1`：部分平仓; `2`：完全平仓;

POST / 带单或跟单仓位止盈止损

为当前未平仓的带单仓位设置止盈止损。

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/copytrading/algo-order

请求示例

POST /api/v5/copytrading/algo-order
body
{
    "subPosId": "518541406042591232",
    "tpTriggerPx": "10000"
}

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约，默认值
subPosId	String	是	带单或者跟单仓位ID
tpTriggerPx	String	可选	止盈触发价，tpTriggerPx 和 slTriggerPx 至少需要填写一个如果止盈触发价为0，那代表删除止盈。
slTriggerPx	String	可选	止损触发价，如果止损触发价为0，那代表删除止损
tpOrdPx	String	否	止盈委托价委托价格为-1时，执行市价止盈，默认为市价止盈仅适用于现货交易员
slOrdPx	String	否	止损委托价委托价格为-1时，执行市价止损，默认为市价止损仅适用于现货交易员
tpTriggerPxType	String	否	止盈触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格默认为last
slTriggerPxType	String	否	止损触发价类型 `last`：最新价格 `index`：指数价格 `mark`：标记价格默认为last
tag	String	否	订单标签字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。
subPosType	String	否	数据的类型 `lead`: 带单，默认值 `copy`: 跟单

返回结果

{
    "code": "0",
    "data": [
        {
            "subPosId": "518560559046594560",
            "tag":""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
subPosId	String	带单或者跟单仓位ID
tag	String	订单标签

POST / 平仓带单

一次仅可平仓一个带单仓位。
subPosId 为必填参数，需要通过交易员获取当前带单接口获取。

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/copytrading/close-subposition

请求示例

POST /api/v5/copytrading/close-subposition
body
{
    "subPosId": "518541406042591232"
}

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约，默认值
subPosId	String	是	带单仓位ID
tag	String	否	订单标签字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。
ordType	String	否	订单类型 `market`：市价单 `limit`：限价单默认为市价单
px	String	否	委托价格，仅适用于`limit`类型的订单，且仅适用于现货交易员委托价格为 0 代表撤销挂单已经设置了限价单，仍为该条目设置价格时，视为改单。

返回结果

{
    "code": "0",
    "data": [
        {
            "subPosId": "518560559046594560",
            "tag":""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
subPosId	String	带单仓位ID
tag	String	订单标签

GET / 获取带单产品

获取平台支持带单的产品，以及获取带单员正在带单的产品

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/instruments

请求示例

GET /api/v5/copytrading/instruments

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约，默认值

返回结果

{
    "code": "0",
    "data": [
        {
            "enabled": true,
            "instId": "BTC-USDT-SWAP"
        },
        {
            "enabled": true,
            "instId": "ETH-USDT-SWAP"
        },
        {
            "enabled": false,
            "instId": "ADA-USDT-SWAP"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品ID
enabled	Boolean	是否设置了带单 `true` 或 `false`

POST / 交易员修改带单产品

交易员修改带单产品的设置。初始带单产品在申请带单交易员时进行设置。
非带单产品修改为带单产品时，该次请求中所有的非带单产品不能有持仓或者挂单。

限速：5次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/copytrading/set-instruments

请求示例

POST /api/v5/copytrading/set-instruments
body
{
    "instId": "BTC-USDT-SWAP,ETH-USDT-SWAP"
}

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约，默认值
instId	String	是	产品ID，如 BTC-USDT-SWAP，多个产品用半角逗号隔开

返回结果

{
    "code": "0",
    "data": [
        {
            "enabled": true,
            "instId": "BTC-USDT-SWAP"
        },
        {
            "enabled": true,
            "instId": "ETH-USDT-SWAP"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品id，如 BTC-USDT-SWAP
enabled	Boolean	`true` 或 `false` `true` 代表设置成功 `false` 代表设置失败

交易员获取最近三个月的分润明细。

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/profit-sharing-details

请求示例

GET /api/v5/copytrading/profit-sharing-details?limit=2

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约默认返回所有业务线的信息
after	String	否	请求此id之前（更旧的数据）的分页内容，传的值为对应接口的`profitSharingId`
before	String	否	请求此id之后（更新的数据）的分页内容，传的值为对应接口的`profitSharingId`
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "nickName": "Potato",
            "profitSharingAmt": "0.00536",
            "profitSharingId": "148",
            "portLink": "",
            "ts": "1723392000000",
            "instType": "SWAP"
        },
        {
            "ccy": "USDT",
            "nickName": "Apple",
            "profitSharingAmt": "0.00336",
            "profitSharingId": "20",
            "portLink": "",
            "ts": "1723392000000",
            "instType": "SWAP"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	分润币种
profitSharingAmt	String	分润额，没有分润时，默认返回0
nickName	String	跟单人的昵称
profitSharingId	String	分润ID
instType	String	产品类型 SPOT：币币 SWAP：永续合约
portLink	String	跟单员头像的链接地址
ts	String	分润时间

交易员获取自入驻平台以来，累计获得的总分润金额。

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/total-profit-sharing

请求示例

GET /api/v5/copytrading/total-profit-sharing

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约默认返回所有业务线的信息

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "totalProfitSharingAmt": "0.6584928",
            "instType": "SWAP"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	分润币种
totalProfitSharingAmt	String	历史分润汇总
instType	String	产品类型 SPOT：币币 SWAP：永续合约

交易员获取预计在下一个周期分到的分润金额明细。
当有跟单仓位平仓时，待分润明细会进行更新。

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/unrealized-profit-sharing-details

请求示例

GET /api/v5/copytrading/unrealized-profit-sharing-details

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约默认返回所有业务线的信息

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "nickName": "Potato",
            "portLink": "",
            "ts": "1669901824779",
            "unrealizedProfitSharingAmt": "0.455472",
            "instType": "SWAP"
        },
        {
            "ccy": "USDT",
            "nickName": "Apple",
            "portLink": "",
            "ts": "1669460210113",
            "unrealizedProfitSharingAmt": "0.033608",
            "instType": "SWAP"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	分润币种，如：`USDT`
unrealizedProfitSharingAmt	String	待分润额
nickName	String	跟单人昵称
instType	String	产品类型 SPOT：币币 SWAP：永续合约
portLink	String	跟单员头像的链接地址
ts	String	数据更新时间

交易员获取待分润汇总。

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/total-unrealized-profit-sharing

请求示例

GET /api/v5/copytrading/total-unrealized-profit-sharing

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值

返回结果

{
    "code": "0",
    "data": [
        {
            "profitSharingTs": "1705852800000",
            "totalUnrealizedProfitSharingAmt": "0.114402985553185"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
profitSharingTs	String	当前周期待分润总额的结算时间，Unix时间戳的毫秒数格式，如 `1597026383085`
totalUnrealizedProfitSharingAmt	String	待分润总额

POST / 带单申请

仅支持白名单中的 ND 子账号，进行带单申请，后端无须审核，自动通过
如果想要添加白名单，请联系 BD 处理
其他账号，比如 ND母账号以及普通母账号和普通子账号，仍然需要在页面上进行手动申请

限速：5次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/copytrading/apply-lead-trading

请求示例

POST /api/v5/copytrading/apply-lead-trading
body
{
    "instType": "SWAP",
    "instId": "BTC-USDT-SWAP"
}

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
instId	String	是	首次设置的带单产品ID 如 BTC-USDT-SWAP，多个产品用半角逗号隔开。

返回结果

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

返回参数

参数名	类型	描述
result	Boolean	设置结果 `true`：设置成功

POST / 停止带单

ND broker 子账户停止带单时调用

限速：5次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/copytrading/stop-lead-trading

请求示例

POST /api/v5/copytrading/stop-lead-trading
body
{
    "instType": "SWAP"
}

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值

返回结果

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

返回参数

参数名	类型	描述
result	Boolean	设置结果 `true`：设置成功

修改分润比例

限速：5次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/copytrading/amend-profit-sharing-ratio

请求示例

POST /api/v5/copytrading/amend-profit-sharing-ratio
body
{
    "instType": "SWAP",
    "profitSharingRatio": "0.1"
}

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
profitSharingRatio	String	是	分润比例。0.1 代表10%

返回结果

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

返回参数

参数名	类型	描述
result	Boolean	设置结果 `true`：设置成功

GET / 查看账户配置信息

获取跟单交易和带单交易相关的账户配置信息

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/config

请求示例

GET /api/v5/copytrading/config

请求参数

无

返回结果

{
    "code": "0",
    "data": [
        {
            "details": [
                {
                    "copyTraderNum": "1",
                    "instType": "SWAP",
                    "maxCopyTraderNum": "100",
                    "profitSharingRatio": "0",
                    "roleType": "1"
                },
                {
                    "copyTraderNum": "",
                    "instType": "SPOT",
                    "maxCopyTraderNum": "",
                    "profitSharingRatio": "",
                    "roleType": "0"
                }
            ],
            "nickName": "155***9957",
            "portLink": "",
            "uniqueCode": "5506D3681454A304"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
uniqueCode	String	交易员唯一标识代码
nickName	String	昵称
portLink	String	头像的链接地址
details	String	详情
> instType	String	产品类型 `SPOT`: 币币 `SWAP`: 永续合约
> roleType	String	用户角色 `0`：普通用户 `1`：带单者 `2`：跟单者
> profitSharingRatio	String	分润比例，仅适用于带单员，0.1 代表 10%，否则为""
> maxCopyTraderNum	String	最大跟单人数，仅适用于带单员
> copyTraderNum	String	当前跟单人数，仅适用于带单员

POST / 首次跟单设置

跟随某一交易员的首次设置，停止跟单后需先进行首次设置；

限速：5次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/copytrading/first-copy-settings

请求示例

POST /api/v5/copytrading/first-copy-settings
body
{
    "instType": "SWAP",
    "uniqueCode": "25CD5A80241D6FE6",
    "copyMgnMode": "cross",
    "copyInstIdType": "copy",
    "copyMode": "ratio_copy",
    "copyRatio": "1",
    "copyTotalAmt": "500",
    "subPosCloseType": "copy_close"
}

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。数字加字母组合长度为16位，如：213E8C92DC61EFAC
copyMgnMode	String	是	跟单时的保证金模式 `cross`: 全仓； `isolated`: 逐仓； `copy`: 跟随带单员
copyInstIdType	String	是	跟单合约设置的类型 `custom`: 用户自定义，instId 必填； `copy`: 跟随交易员，自动同步交易员的合约变更
instId	String	可选	产品 ID 可传入多条，以逗号区分
copyMode	String	否	跟单模式 `fixed_amount`: 固定金额跟单，`copyAmt`必填； `ratio_copy`: 比例跟单，`copyRatio`必填默认是`fixed_amount`
copyTotalAmt	String	是	跟单该交易员投入的最大跟单金额，单位为USDT。超过该金额后将不再触发跟单行为
copyAmt	String	可选	单笔跟随金额，单位为USDT
copyRatio	String	可选	跟单比例
tpRatio	String	否	单笔止盈百分比，0.1 代表10%
slRatio	String	否	单笔止损百分比，0.1 代表10%
slTotalAmt	String	否	跟单止损总金额，单位为USDT 净损失达到该金额时，将自动解除跟单关系
subPosCloseType	String	是	剩余仓位处理方式 `market_close`: 立即市价全平 `copy_close`：跟随交易员平仓 `manual_close`: 手动处理默认为 `copy_close`
tag	String	否	订单标签字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。

返回结果

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

返回参数

参数名	类型	描述
result	Boolean	设置结果 `true`：设置成功

POST / 修改跟单设置

跟随某一交易员，完成首次设置后，修改设置时，需要使用该接口

限速：5次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/copytrading/amend-copy-settings

请求示例

POST /api/v5/copytrading/amend-copy-settings
body
{
    "instType": "SWAP",
    "uniqueCode": "25CD5A80241D6FE6",
    "copyMgnMode": "cross",
    "copyInstIdType": "copy",
    "copyMode": "ratio_copy",
    "copyRatio": "1",
    "copyTotalAmt": "500",
    "subPosCloseType": "copy_close"
}

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。数字加字母组合长度为16位，如：213E8C92DC61EFAC
copyMgnMode	String	是	跟单时的保证金模式 `cross`: 全仓； `isolated`: 逐仓； `copy`: 跟随带单员
copyInstIdType	String	是	跟单合约设置的类型 `custom`: 用户自定义，instId 必填； `copy`: 跟随交易员，自动同步交易员的合约变更
instId	String	可选	产品 ID 可传入多条，以逗号区分
copyMode	String	否	跟单模式 `fixed_amount`: 固定金额跟单，`copyAmt`必填； `ratio_copy`: 比例跟单，`copyRatio`必填默认是`fixed_amount`
copyTotalAmt	String	是	跟单该交易员投入的最大跟单金额，单位为USDT。超过该金额后将不再触发跟单行为
copyAmt	String	可选	单笔跟随金额，单位为USDT
copyRatio	String	可选	跟单比例
tpRatio	String	否	单笔止盈百分比，0.1 代表10%
slRatio	String	否	单笔止损百分比，0.1 代表10%
slTotalAmt	String	否	跟单止损总金额，单位为USDT 净损失达到该金额时，将自动解除跟单关系
subPosCloseType	String	是	剩余仓位处理方式 `market_close`: 立即市价全平 `copy_close`：跟随交易员平仓 `manual_close`: 手动处理默认为 `copy_close`
tag	String	否	订单标签字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。

返回结果

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

返回参数

参数名	类型	描述
result	Boolean	设置结果 `true`：设置成功

POST / 停止跟单

该接口用来停止跟单

限速：5次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/copytrading/stop-copy-trading

请求示例

POST /api/v5/copytrading/stop-copy-trading
body
{
    "instType": "SWAP",
    "uniqueCode": "25CD5A80241D6FE6",
    "subPosCloseType": "manual_close"
}

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。数字加字母组合长度为16位，如：213E8C92DC61EFAC
subPosCloseType	String	可选	剩余仓位处理方式，有相关的跟单条目时必填 `market_close`: 立即市价全平 `copy_close`：跟随交易员平仓 `manual_close`: 手动处理

返回结果

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

返回参数

参数名	类型	描述
result	Boolean	设置结果 `true`：设置成功

GET / 获取跟单设置

获取针对某个交易员的跟单设置

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/copy-settings

请求示例

GET /api/v5/copytrading/copy-settings?instType=SWAP&uniqueCode=25CD5A80241D6FE6

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。数字加字母组合长度为16位，如：213E8C92DC61EFAC

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "copyAmt": "",
            "copyInstIdType": "copy",
            "copyMgnMode": "isolated",
            "copyMode": "ratio_copy",
            "copyRatio": "1",
            "copyState": "1",
            "copyTotalAmt": "500",
            "instIds": [
                {
                    "enabled": "1",
                    "instId": "ADA-USDT-SWAP"
                },
                {
                    "enabled": "1",
                    "instId": "YFII-USDT-SWAP"
                }
            ],
            "slRatio": "",
            "slTotalAmt": "",
            "subPosCloseType": "copy_close",
            "tpRatio": "",
            "tag": ""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
copyMode	String	跟单模式 `fixed_amount`: 固定金额跟单 `ratio_copy`: 比例跟单
copyAmt	String	单笔跟随金额，单位为 USDT
copyRatio	String	跟单比例
copyTotalAmt	String	跟单该交易员投入的最大跟单金额，单位为USDT
tpRatio	String	单笔止盈百分比，0.1 代表10%
slRatio	String	单笔止损百分比，0.1 代表10%
copyInstIdType	String	跟单合约设置的类型 `custom`: 用户自定义 `copy`: 跟随交易员，自动同步交易员的合约变更
instIds	Array	可跟单的合约列表，会返回交易员所有带单合约
> instId	String	产品 ID
> enabled	String	是否在跟单 `0`: 没有在跟单 `1`: 在跟单
slTotalAmt	String	跟单止损总金额，单位为 USDT
subPosCloseType	String	剩余仓位处理方式 `market_close`: 立即市价全平 `copy_close`：跟随交易员平仓 `manual_close`: 手动处理
copyMgnMode	String	跟单时的保证金模式 `cross`: 全仓； `isolated`: 逐仓； `copy`: 跟随带单员
ccy	String	保证金币种
copyState	String	当前跟单状态 `0`: 没在跟单 `1`：在跟单
tag	String	订单标签

GET / 获取我的交易员

获取当前跟随的交易员

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/current-lead-traders

请求示例

GET /api/v5/copytrading/current-lead-traders?instType=SWAP

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值

返回结果

{
    "code": "0",
    "data": [
        {
            "beginCopyTime": "1701224821936",
            "ccy": "USDT",
            "copyTotalAmt": "500",
            "copyTotalPnl": "0",
            "leadMode": "public",
            "margin": "1.89395",
            "nickName": "Trader9527",
            "portLink": "",
            "profitSharingRatio": "0.08",
            "todayPnl": "0",
            "uniqueCode": "25CD5A80241D6FE6",
            "upl": "0"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
portLink	String	头像
nickName	String	昵称
margin	String	跟单交易占用的保证金
copyTotalAmt	String	跟单员设置的跟单总金额
copyTotalPnl	String	跟单总收益 (USDT)
uniqueCode	String	带单员唯一标识代码
ccy	String	保证金币种
profitSharingRatio	String	分润比例，0.1 代表 10%
beginCopyTime	String	跟单开始时间，Unix时间戳的毫秒数格式，如 `1597026383085`
upl	String	未实现盈亏
todayPnl	String	今日已实现收益
leadMode	String	带单模式 `public`: 公开模式 `private`: 私域模式

GET / 获取跟单配置信息

公共接口，获取跟单设置时的参数配置信息

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/copytrading/public-config

请求示例

GET /api/v5/copytrading/public-config?instType=SWAP

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值

返回结果

{
    "code": "0",
    "data": [
        {
            "maxCopyAmt": "1000",
            "maxCopyRatio": "100",
            "maxCopyTotalAmt": "30000",
            "maxSlRatio": "0.75",
            "maxTpRatio": "1.5",
            "minCopyAmt": "20",
            "minCopyRatio": "0.01"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
maxCopyAmt	String	固定金额跟单时，单笔最大跟随金额
minCopyAmt	String	固定金额跟单时，单笔最小跟随金额
maxCopyTotalAmt	String	最大跟单金额（针对单个带单员），最小跟单金额同`minCopyAmt`
minCopyRatio	String	比例跟单的单笔最小比率
maxCopyRatio	String	比例跟单的单笔最大比率
maxTpRatio	String	单笔最大止盈比率，最小为 0
maxSlRatio	String	单笔最大止损比率，最小为 0

GET / 获取交易员排名

公共接口，获取交易员排名信息。

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/copytrading/public-lead-traders

请求示例

GET /api/v5/copytrading/public-lead-traders?instType=SWAP

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
sortType	String	否	排名类型 `overview`: 综合排序，默认值 `pnl`: 按照交易员收益额排序 `aum`: 按照带单规模排序 `win_ratio`: 胜率 `pnl_ratio`: 收益率 `current_copy_trader_pnl`: 当前跟单人的收益额
state	String	否	交易员的状态 `0`: 所有交易员，默认值，包括有空缺和没有空缺 `1`: 有空缺的交易员
minLeadDays	String	否	最短带单时长 `1`: 7 天 `2`: 30 天 `3`: 90 天 `4`: 180天
minAssets	String	否	交易员资产范围的最小值，单位为 USDT
maxAssets	String	否	交易员资产范围的最大值，单位为 USDT
minAum	String	否	带单规模的最小值，单位为 USDT
maxAum	String	否	带单规模的最大值，单位为 USDT
dataVer	String	否	排名数据的版本，14 位数字，如：20231010182400，主要在分页时使用每10分钟生成一版，仅保留最新的5个版本默认使用最近的版本；不存在时不会报错，会使用最近的版本。
page	String	否	查询页数
limit	String	否	分页返回的结果集数量，最大为 20，不填默认返回 10 条

返回结果

{
    "code": "0",
    "data": [
        {
            "dataVer": "20231129213200",
            "ranks": [
                {
                    "accCopyTraderNum": "3536",
                    "aum": "1509265.3238761567721365",
                    "ccy": "USDT",
                    "copyState": "0",
                    "copyTraderNum": "999",
                    "leadDays": "156",
                    "maxCopyTraderNum": "1000",
                    "nickName": "Crypto to the moon",
                    "pnl": "48805.1105999999972258",
                    "pnlRatio": "1.6898",
                    "pnlRatios": [
                        {
                            "beginTs": "1701187200000",
                            "pnlRatio": "1.6744"
                        },
                        {
                            "beginTs": "1700755200000",
                            "pnlRatio": "1.649"
                        }
                    ],
                    "portLink": "https://static.okx.com/cdn/okex/users/headimages/20230624/f49a683aaf5949ea88b01bbc771fb9fc",
                    "traderInsts": [
                        "ICP-USDT-SWAP",
                        "MINA-USDT-SWAP"

                    ],
                    "uniqueCode": "540D011FDACCB47A",
                    "winRatio": "0.6957"
                }
            ],
            "totalPage": "1"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
dataVer	String	排名数据的版本
totalPage	String	总的页数
ranks	Array	交易员排名信息
> aum	String	带单规模，单位为USDT
> copyState	String	当前跟单状态 `0`: 没在跟单 `1`：在跟单
> maxCopyTraderNum	String	最大跟单人数
> copyTraderNum	String	跟单人数
> accCopyTraderNum	String	累计跟单人数
> portLink	String	头像
> nickName	String	昵称
> ccy	String	保证金币种
> uniqueCode	String	交易员唯一标识码
> winRatio	String	胜率，0.1 代表 10%
> leadDays	String	带单天数
> traderInsts	Array	交易员带单的合约列表
> pnl	String	近90日交易员收益，单位为 USDT
> pnlRatio	String	近90日交易员收益率，0.1 代表 10%
> pnlRatios	Array	收益率数据
>> beginTs	String	当天收益率的开始时间
>> pnlRatio	String	当天收益率

GET / 获取交易员收益周表现

公共接口，获取交易员最近12周的收益表现，按时间倒序返回

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/copytrading/public-weekly-pnl

请求示例

GET /api/v5/copytrading/public-weekly-pnl?instType=SWAP&uniqueCode=D9ADEAB33AE9EABD

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。数字加字母组合长度为16位，如：213E8C92DC61EFAC

返回结果

{
    "code": "0",
    "data": [
        {
            "beginTs": "1701014400000",
            "pnl": "-2.8428",
            "pnlRatio": "-0.0106"
        },
        {
            "beginTs": "1700409600000",
            "pnl": "81.8446",
            "pnlRatio": "0.3036"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
beginTs	String	当周收益率的开始时间
pnl	String	当周收益额
pnlRatio	String	当周收益率

GET / 获取交易员收益日表现

公共接口，获取交易员每日的收益表现，按时间倒序返回

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/copytrading/public-pnl

请求示例

GET /api/v5/copytrading/public-pnl?instType=SWAP&uniqueCode=D9ADEAB33AE9EABD&lastDays=1

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。数字加字母组合长度为16位，如：213E8C92DC61EFAC
lastDays	String	是	最近天数 `1`: 近 7 天 `2`: 近 30 天 `3`: 近 90 天， `4`: 近 365 天

返回结果

{
    "code": "0",
    "data": [
        {
            "beginTs": "1701100800000",
            "pnl": "97.3309",
            "pnlRatio": "0.3672"
        },
        {
            "beginTs": "1701014400000",
            "pnl": "96.7755",
            "pnlRatio": "0.3651"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
beginTs	String	当天收益率的开始时间
pnl	String	当天收益额
pnlRatio	String	当天收益率

GET / 获取交易员带单情况

公共接口，获取交易员带单情况。

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/copytrading/public-stats

请求示例

GET /api/v5/copytrading/public-stats?instType=SWAP&uniqueCode=D9ADEAB33AE9EABD&lastDays=1

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。数字加字母组合长度为16位，如：213E8C92DC61EFAC
lastDays	String	是	最近天数 `1`: 近 7 天 `2`: 近 30 天 `3`: 近 90 天， `4`: 近 365 天

返回结果

{
    "code": "0",
    "data": [
        {
            "avgSubPosNotional": "213.1038",
            "ccy": "USDT",
            "curCopyTraderPnl": "96.8071",
            "investAmt": "265.095252476476294",
            "lossDays": "1",
            "profitDays": "2",
            "winRatio": "0.6667"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
winRatio	String	胜率
profitDays	String	盈利天数
lossDays	String	亏损天数
curCopyTraderPnl	String	当前跟随者收益 (USDT)
avgSubPosNotional	String	平均仓位价值 (USDT)
investAmt	String	带单本金 (USDT)
ccy	String	保证金币种

GET / 获取交易员币种偏好

公共接口，获取交易员币种偏好，返回结果按 ratio 从大到小排序

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/copytrading/public-preference-currency

请求示例

GET /api/v5/copytrading/public-preference-currency?instType=SWAP&uniqueCode=CB4594A3BB5D3538

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。数字加字母组合长度为16位，如：213E8C92DC61EFAC

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "ETH",
            "ratio": "0.8881"
        },
        {
            "ccy": "BTC",
            "ratio": "0.0666"
        },
        {
            "ccy": "YFII",
            "ratio": "0.0453"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	币种
ratio	String	占比，0.1 代表 10%

GET / 获取交易员当前带单

公共接口，获取交易员当前带单。

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/copytrading/public-current-subpositions

请求示例

GET /api/v5/copytrading/public-current-subpositions?instType=SWAP&uniqueCode=D9ADEAB33AE9EABD

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值
uniqueCode	String	是	交易员唯一标识码
after	String	否	请求此id之前（更旧的数据）的分页内容，传的值为对应接口的`subPosId`
before	String	否	请求此id之后（更新的数据）的分页内容，传的值为对应接口的`subPosId`
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "instId": "ETH-USDT-SWAP",
            "instType": "SWAP",
            "lever": "5",
            "margin": "16.23304",
            "markPx": "2027.31",
            "mgnMode": "isolated",
            "openAvgPx": "2029.13",
            "openTime": "1701144639417",
            "posSide": "short",
            "subPos": "4",
            "subPosId": "649582930998104064",
            "uniqueCode": "D9ADEAB33AE9EABD",
            "upl": "0.0728",
            "uplRatio": "0.0044846806266725"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品ID
subPosId	String	带单仓位ID
posSide	String	持仓方向 long：开平仓模式开多 short：开平仓模式开空 net：买卖模式（subPos为正代表开多，subPos为负代表开空）
mgnMode	String	保证金模式，`isolated`：逐仓；`cross`：全仓
lever	String	杠杆倍数
openAvgPx	String	开仓均价
openTime	String	开仓时间
subPos	String	持仓张数
instType	String	产品类型 SPOT：币币 SWAP：永续合约
margin	String	保证金
upl	String	未实现收益
uplRatio	String	未实现收益率
markPx	String	最新标记价格，仅适用于合约
uniqueCode	String	交易员唯一标识代码
ccy	String	币种

GET / 获取交易员历史带单

公共接口，获取交易员最近三个月的已经平仓的带单仓位，按照subPosId倒序排序。

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/copytrading/public-subpositions-history

请求示例

GET /api/v5/copytrading/public-subpositions-history?instType=SWAP&uniqueCode=9A8534AB09862774

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值
uniqueCode	String	是	交易员唯一标识码数字加字母组合长度为16位，如：213E8C92DC61EFAC
after	String	否	请求此id之前（更旧的数据）的分页内容，传的值为对应接口的`subPosId`
before	String	否	请求此id之后（更新的数据）的分页内容，传的值为对应接口的`subPosId`
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "closeAvgPx": "28385.9",
            "closeTime": "1697709137162",
            "instId": "BTC-USDT-SWAP",
            "instType": "SWAP",
            "lever": "20",
            "margin": "4.245285",
            "mgnMode": "isolated",
            "openAvgPx": "28301.9",
            "openTime": "1697698048031",
            "pnl": "0.252",
            "pnlRatio": "0.05935997229868",
            "posSide": "long",
            "subPos": "3",
            "subPosId": "635126416883355648",
            "uniqueCode": "9A8534AB09862774"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品ID
subPosId	String	带单仓位ID
posSide	String	持仓方向 long：开平仓模式开多 short：开平仓模式开空 net：买卖模式（subPos为正代表开多，subPos为负代表开空）
mgnMode	String	保证金模式，`isolated`：逐仓；`cross`：全仓
lever	String	杠杆倍数
openAvgPx	String	开仓均价
openTime	String	开仓时间
subPos	String	持仓张数
closeTime	String	平仓时间(最近一次平仓的时间)
closeAvgPx	String	平仓均价
pnl	String	收益额
pnlRatio	String	收益率
instType	String	产品类型 SPOT：币币 SWAP：永续合约
margin	String	保证金
ccy	String	币种
uniqueCode	String	交易员唯一标识代码

GET / 获取跟单人信息

公共接口，获取交易员的跟单人信息，按收益从高到低返回

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/copytrading/public-copy-traders

请求示例

GET /api/v5/copytrading/public-copy-traders?instType=SWAP&uniqueCode=D9ADEAB33AE9EABD

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。数字加字母组合长度为16位，如：213E8C92DC61EFAC
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "copyTotalPnl": "2060.12242",
            "copyTraderNumChg": "1",
            "copyTraderNumChgRatio": "0.5",
            "copyTraders": [
                {
                    "beginCopyTime": "1686125051000",
                    "nickName": "bre***@gmail.com",
                    "pnl": "1076.77388",
                    "portLink": ""
                },
                {
                    "beginCopyTime": "1698133811000",
                    "nickName": "MrYanDao505",
                    "pnl": "983.34854",
                    "portLink": "https://static.okx.com/cdn/okex/users/headimages/20231010/fd31f45e99fe41f7bb219c0b53ae0ada"
                }
            ]
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
copyTotalPnl	String	跟单员总收益
ccy	String	总收益币种名称
copyTraderNumChg	String	近 7 日变化的跟单人数
copyTraderNumChgRatio	String	近 7 日跟单人数变化的比率
copyTraders	String	跟单员信息
> beginCopyTime	String	跟单开始时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> nickName	String	昵称
> portLink	String	跟单员头像的链接地址
> pnl	String	跟单收益

GET / 获取交易员排名（私有）

私有接口，获取交易员排名信息。
当 ND 子账户请求时，该接口会返回同一独立经纪商的 ND 子账户带单交易员信息，对应的公共接口则不会返回。

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/lead-traders

请求示例

GET /api/v5/copytrading/lead-traders?instType=SWAP

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
sortType	String	否	排名类型 `overview`: 综合排序，默认值 `pnl`: 按照交易员收益额排序 `aum`: 按照带单规模排序 `win_ratio`: 胜率 `pnl_ratio`: 收益率 `current_copy_trader_pnl`: 当前跟单人的收益额
state	String	否	交易员的状态 `0`: 所有交易员，默认值，包括有空缺和没有空缺 `1`: 有空缺的交易员
minLeadDays	String	否	最短带单时长 `1`: 7 天 `2`: 30 天 `3`: 90 天 `4`: 180天
minAssets	String	否	交易员资产范围的最小值，单位为 USDT
maxAssets	String	否	交易员资产范围的最大值，单位为 USDT
minAum	String	否	带单规模的最小值，单位为 USDT
maxAum	String	否	带单规模的最大值，单位为 USDT
dataVer	String	否	排名数据的版本，14 位数字，如：20231010182400，主要在分页时使用每10分钟生成一版，仅保留最新的5个版本默认使用最近的版本；不存在时不会报错，会使用最近的版本。
page	String	否	查询页数
limit	String	否	分页返回的结果集数量，最大为 20，不填默认返回 10 条

返回结果

{
    "code": "0",
    "data": [
        {
            "dataVer": "20231129213200",
            "ranks": [
                {
                    "chanType": "OKX",
                    "accCopyTraderNum": "3536",
                    "aum": "1509265.3238761567721365",
                    "ccy": "USDT",
                    "copyState": "0",
                    "copyTraderNum": "999",
                    "leadDays": "156",
                    "maxCopyTraderNum": "1000",
                    "nickName": "Crypto to the moon",
                    "pnl": "48805.1105999999972258",
                    "pnlRatio": "1.6898",
                    "pnlRatios": [
                        {
                            "beginTs": "1701187200000",
                            "pnlRatio": "1.6744"
                        },
                        {
                            "beginTs": "1700755200000",
                            "pnlRatio": "1.649"
                        }
                    ],
                    "portLink": "https://static.okx.com/cdn/okex/users/headimages/20230624/f49a683aaf5949ea88b01bbc771fb9fc",
                    "traderInsts": [
                        "ICP-USDT-SWAP",
                        "MINA-USDT-SWAP"

                    ],
                    "uniqueCode": "540D011FDACCB47A",
                    "winRatio": "0.6957"
                }
            ],
            "totalPage": "1"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
dataVer	String	排名数据的版本
totalPage	String	总的页数
ranks	Array	交易员排名信息
> chanType	String	渠道类型 `OKX`: `OKX 平台` `ND`: ND broker
> aum	String	带单规模，单位为USDT
> copyState	String	当前跟单状态 `0`: 没在跟单 `1`：在跟单
> maxCopyTraderNum	String	最大跟单人数
> copyTraderNum	String	跟单人数
> accCopyTraderNum	String	累计跟单人数
> portLink	String	头像
> nickName	String	昵称
> ccy	String	保证金币种
> uniqueCode	String	交易员唯一标识码
> winRatio	String	胜率，0.1 代表 10%
> leadDays	String	带单天数
> traderInsts	Array	交易员带单的合约列表
> pnl	String	近90日交易员收益，单位为 USDT
> pnlRatio	String	近90日交易员收益率，0.1 代表 10%
> pnlRatios	Array	收益率数据
>> beginTs	String	当天收益率的开始时间
>> pnlRatio	String	当天收益率

GET / 获取交易员收益周表现（私有）

私有接口，获取交易员最近12周的收益表现，按时间倒序返回
当 ND 子账户请求时，uniqueCode 支持传同一独立经纪商下的 ND 带单员唯一标识码，对应的公共接口则不支持。

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/weekly-pnl

请求示例

GET /api/v5/copytrading/weekly-pnl?instType=SWAP&uniqueCode=D9ADEAB33AE9EABD

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。数字加字母组合长度为16位，如：213E8C92DC61EFAC

返回结果

{
    "code": "0",
    "data": [
        {
            "beginTs": "1701014400000",
            "pnl": "-2.8428",
            "pnlRatio": "-0.0106"
        },
        {
            "beginTs": "1700409600000",
            "pnl": "81.8446",
            "pnlRatio": "0.3036"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
beginTs	String	当周收益率的开始时间
pnl	String	当周收益额
pnlRatio	String	当周收益率

GET / 获取交易员收益日表现（私有）

私有接口，获取交易员每日的收益表现，按时间倒序返回
当 ND 子账户请求时，uniqueCode 支持传同一独立经纪商下的 ND 带单员唯一标识码，对应的公共接口则不支持。

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/pnl

请求示例

GET /api/v5/copytrading/pnl?instType=SWAP&uniqueCode=D9ADEAB33AE9EABD&lastDays=1

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。数字加字母组合长度为16位，如：213E8C92DC61EFAC
lastDays	String	是	最近天数 `1`: 近 7 天 `2`: 近 30 天 `3`: 近 90 天， `4`: 近 365 天

返回结果

{
    "code": "0",
    "data": [
        {
            "beginTs": "1701100800000",
            "pnl": "97.3309",
            "pnlRatio": "0.3672"
        },
        {
            "beginTs": "1701014400000",
            "pnl": "96.7755",
            "pnlRatio": "0.3651"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
beginTs	String	当天收益率的开始时间
pnl	String	当天收益额
pnlRatio	String	当天收益率

GET / 获取交易员带单情况（私有）

私有接口，获取交易员带单情况。
当 ND 子账户请求时，uniqueCode 支持传同一独立经纪商下的 ND 带单员唯一标识码，对应的公共接口则不支持。

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/stats

请求示例

GET /api/v5/copytrading/stats?instType=SWAP&uniqueCode=D9ADEAB33AE9EABD&lastDays=1

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。数字加字母组合长度为16位，如：213E8C92DC61EFAC
lastDays	String	是	最近天数 `1`: 近 7 天 `2`: 近 30 天 `3`: 近 90 天， `4`: 近 365 天

返回结果

{
    "code": "0",
    "data": [
        {
            "avgSubPosNotional": "213.1038",
            "ccy": "USDT",
            "curCopyTraderPnl": "96.8071",
            "investAmt": "265.095252476476294",
            "lossDays": "1",
            "profitDays": "2",
            "winRatio": "0.6667"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
winRatio	String	胜率
profitDays	String	盈利天数
lossDays	String	亏损天数
curCopyTraderPnl	String	当前跟随者收益 (USDT)
avgSubPosNotional	String	平均仓位价值 (USDT)
investAmt	String	带单本金 (USDT)
ccy	String	保证金币种

GET / 获取交易员币种偏好（私有）

私有接口，获取交易员币种偏好，返回结果按 ratio 从大到小排序
当 ND 子账户请求时，uniqueCode 支持传同一独立经纪商下的 ND 带单员唯一标识码，对应的公共接口则不支持。

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/preference-currency

请求示例

GET /api/v5/copytrading/preference-currency?instType=SWAP&uniqueCode=CB4594A3BB5D3538

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。数字加字母组合长度为16位，如：213E8C92DC61EFAC

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "ETH",
            "ratio": "0.8881"
        },
        {
            "ccy": "BTC",
            "ratio": "0.0666"
        },
        {
            "ccy": "YFII",
            "ratio": "0.0453"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	币种
ratio	String	占比，0.1 代表 10%

GET / 获取交易员当前带单（私有）

私有接口，获取交易员当前带单。
当 ND 子账户请求时，uniqueCode 支持传同一独立经纪商下的 ND 带单员唯一标识码，对应的公共接口则不支持。

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/performance-current-subpositions

请求示例

GET /api/v5/copytrading/performance-current-subpositions?instType=SWAP&uniqueCode=D9ADEAB33AE9EABD

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值
uniqueCode	String	是	交易员唯一标识码
after	String	否	请求此id之前（更旧的数据）的分页内容，传的值为对应接口的`subPosId`
before	String	否	请求此id之后（更新的数据）的分页内容，传的值为对应接口的`subPosId`
limit	String	否	分页返回的结果集数量，最大为500，不填默认返回100条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "instId": "ETH-USDT-SWAP",
            "instType": "SWAP",
            "lever": "5",
            "margin": "16.23304",
            "markPx": "2027.31",
            "mgnMode": "isolated",
            "openAvgPx": "2029.13",
            "openTime": "1701144639417",
            "posSide": "short",
            "subPos": "4",
            "subPosId": "649582930998104064",
            "uniqueCode": "D9ADEAB33AE9EABD",
            "upl": "0.0728",
            "uplRatio": "0.0044846806266725"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品ID
subPosId	String	带单仓位ID
posSide	String	持仓方向 long：开平仓模式开多 short：开平仓模式开空 net：买卖模式（subPos为正代表开多，subPos为负代表开空）
mgnMode	String	保证金模式，`isolated`：逐仓；`cross`：全仓
lever	String	杠杆倍数
openAvgPx	String	开仓均价
openTime	String	开仓时间
subPos	String	持仓张数
instType	String	产品类型 SPOT：币币 SWAP：永续合约
margin	String	保证金
upl	String	未实现收益
uplRatio	String	未实现收益率
markPx	String	最新标记价格，仅适用于合约
uniqueCode	String	交易员唯一标识代码
ccy	String	币种

GET / 获取交易员历史带单（私有）

私有接口，获取交易员最近三个月的已经平仓的带单仓位，按照subPosId倒序排序。
当 ND 子账户请求时，uniqueCode 支持传同一独立经纪商下的 ND 带单员唯一标识码，对应的公共接口则不支持。

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/performance-subpositions-history

请求示例

GET /api/v5/copytrading/performance-subpositions-history?instType=SWAP&uniqueCode=9A8534AB09862774

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值
uniqueCode	String	是	交易员唯一标识码数字加字母组合长度为16位，如：213E8C92DC61EFAC
after	String	否	请求此id之前（更旧的数据）的分页内容，传的值为对应接口的`subPosId`
before	String	否	请求此id之后（更新的数据）的分页内容，传的值为对应接口的`subPosId`
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "closeAvgPx": "28385.9",
            "closeTime": "1697709137162",
            "instId": "BTC-USDT-SWAP",
            "instType": "SWAP",
            "lever": "20",
            "margin": "4.245285",
            "mgnMode": "isolated",
            "openAvgPx": "28301.9",
            "openTime": "1697698048031",
            "pnl": "0.252",
            "pnlRatio": "0.05935997229868",
            "posSide": "long",
            "subPos": "3",
            "subPosId": "635126416883355648",
            "uniqueCode": "9A8534AB09862774"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品ID
subPosId	String	带单仓位ID
posSide	String	持仓方向 long：开平仓模式开多 short：开平仓模式开空 net：买卖模式（subPos为正代表开多，subPos为负代表开空）
mgnMode	String	保证金模式，`isolated`：逐仓；`cross`：全仓
lever	String	杠杆倍数
openAvgPx	String	开仓均价
openTime	String	开仓时间
subPos	String	持仓张数
closeTime	String	平仓时间(最近一次平仓的时间)
closeAvgPx	String	平仓均价
pnl	String	收益额
pnlRatio	String	收益率
instType	String	产品类型 SPOT：币币 SWAP：永续合约
margin	String	保证金
ccy	String	币种
uniqueCode	String	交易员唯一标识代码

GET / 获取跟单人信息（私有）

私有接口，获取交易员的跟单人信息，按收益从高到低返回
当 ND 子账户请求时，uniqueCode 支持传同一独立经纪商下的 ND 带单员唯一标识码，对应的公共接口则不支持。

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/copytrading/copy-traders

请求示例

GET /api/v5/copytrading/copy-traders?instType=SWAP&uniqueCode=D9ADEAB33AE9EABD

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 `SWAP`：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。数字加字母组合长度为16位，如：213E8C92DC61EFAC
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "copyTotalPnl": "2060.12242",
            "copyTraderNumChg": "1",
            "copyTraderNumChgRatio": "0.5",
            "copyTraders": [
                {
                    "beginCopyTime": "1686125051000",
                    "nickName": "bre***@gmail.com",
                    "pnl": "1076.77388",
                    "portLink": ""
                },
                {
                    "beginCopyTime": "1698133811000",
                    "nickName": "MrYanDao505",
                    "pnl": "983.34854",
                    "portLink": "https://static.okx.com/cdn/okex/users/headimages/20231010/fd31f45e99fe41f7bb219c0b53ae0ada"
                }
            ]
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
copyTotalPnl	String	跟单员总收益
ccy	String	总收益币种名称
copyTraderNumChg	String	近 7 日变化的跟单人数
copyTraderNumChgRatio	String	近 7 日跟单人数变化的比率
copyTraders	String	跟单员信息
> beginCopyTime	String	跟单开始时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> nickName	String	昵称
> portLink	String	跟单员头像的链接地址
> pnl	String	跟单收益

WS / 跟单消息通知频道

跟单员获取跟单消息的推送通知

服务地址

/ws/v5/business (需要登录)

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "copytrading-notification",
        "instType": "SWAP"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `copytrading-notification`
> instType	String	是	产品类型 `SWAP`：永续合约
> instId	String	否	产品ID

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "copytrading-notification",
        "instType": "SWAP"
    },
    "connId": "aa993428"
}

失败返回示例

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

返回参数

参数	类型	是否必须	描述
event	String	是	事件 `subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名
> instType	String	是	产品类型 `SWAP`：永续合约
> instId	String	否	产品ID
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket 连接ID

推送示例：

{
    "arg": {
        "channel": "copytrading-notification",
        "instType": "SWAP",
        "uid": "116488283046944768"
    },
    "data": [
        {
            "avgPx": "",
            "ccy": "USDT",
            "copyTotalAmt": "10",
            "infoType": "8",
            "instId": "ETH-USDT-SWAP",
            "instType": "SWAP",
            "lever": "",
            "maxLeadTraderNum": "",
            "minNotional": "",
            "posSide": "",
            "rmThold": "",
            "side": "",
            "slTotalAmt": "",
            "slippageRatio": "",
            "subPosId": "",
            "uniqueCode": "716DDB411E9673F9"
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> uid	String	用户标识
> instType	String	产品类型
data	Array	订阅的数据
> instType	String	产品类型
> infoType	String	消息类型 `1`: 跟单开仓成功（取完全成交） `2`: 跟单平仓成功（取完全成交） `3`: 触发自定义的跟单止损总金额 `4`: 交易员取消跟单者 `5`. 跟单开仓失败-账户资产不足 `6`. 跟单开仓失败-固定金额-跟开张数不足1张 `7`. 跟单开仓失败-比例跟单，跟开张数不足1张 `8`. 跟单开仓失败-超过自定义的跟单总金额 `9`. 跟单开仓失败-触发差价保护 `12`. 跟单平仓失败
> subPosId	String	跟单仓位 ID
> uniqueCode	String	交易员唯一标识码
> instId	String	产品 ID
> lever	String	杠杠倍数
> avgPx	String	跟单成交均价
> ccy	String	币种
> side	String	订单方向，`buy` `sell`
> posSide	String	持仓方向 `long`：开平仓模式开多 `short`：开平仓模式开空 `net`：买卖模式
> slTotalAmt	String	跟单止损总金额
> rmThold	String	跟单员的余额低于该值时，交易员可移除该跟单员
> minNotional	String	单张合约对应的价值，单位为 USDT
> copyTotalAmt	String	跟单员设置的跟单总金额
> slippageRatio	String	滑点率
> maxLeadTraderNum	String	交易员单日带单次数上限

WS / 带单消息通知频道

带单失败时的消息通知

服务地址

/ws/v5/business (需要登录)

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "copytrading-lead-notification",
        "instType": "SWAP"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `copytrading-lead-notification`
> instType	String	是	产品类型 `SWAP`：永续合约
> instId	String	否	产品ID

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "copytrading-lead-notification",
        "instType": "SWAP"
    },
    "connId": "aa993428"
}

失败返回示例

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

返回参数

参数	类型	是否必须	描述
event	String	是	事件 `subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名
> instType	String	是	产品类型 `SWAP`：永续合约
> instId	String	否	产品ID
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket 连接ID

推送示例：

{
    "arg": {
        "channel": "copytrading-lead-notification",
        "instType": "SWAP",
        "uid": "525627088439549953"
    },
    "data": [
        {
            "infoType": "2",
            "instId": "",
            "instType": "SWAP",
            "maxLeadTraderNum": "3",
            "minLeadEq": "",
            "posSide": "",
            "side": "",
            "subPosId": "667695035433385984",
            "uniqueCode": "3AF72F63E3EAD701"
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> uid	String	用户标识
> instType	String	产品类型
data	Array	订阅的数据
> instType	String	产品类型
> infoType	String	消息类型 `1`: 带单失败，触发最大仓位限制 `2`: 带单失败，触发带单次数限制 `3`: 带单失败，交易账户 USDT 低于最小权益
> subPosId	String	带单仓位 ID
> uniqueCode	String	交易员唯一标识码
> instId	String	产品 ID
> side	String	订单方向，`buy` `sell`
> posSide	String	持仓方向 `long`：开平仓模式开多 `short`：开平仓模式开空 `net`：买卖模式
> maxLeadTraderNum	String	当前交易员单日最大带单次数
> minLeadEq	String	带单最小 USDT 权益

行情数据

行情数据功能模块下的API接口不需要身份验证。

GET / 获取所有产品行情信息

获取产品行情信息

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/tickers

请求示例

GET /api/v5/market/tickers?instType=SWAP

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取所有产品行情信息
result = marketDataAPI.get_tickers(
    instType="SWAP"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instType	String	是	产品类型 `SPOT`：币币 `SWAP`：永续合约 `FUTURES`：交割合约 `OPTION`：期权
uly	String	否	标的指数适用于`交割/永续/期权`，如 `BTC-USD`
instFamily	String	否	交易品种适用于`交割/永续/期权`，如 `BTC-USD`

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
     {
        "instType":"SWAP",
        "instId":"LTC-USD-SWAP",
        "last":"9999.99",
        "lastSz":"1",
        "askPx":"9999.99",
        "askSz":"11",
        "bidPx":"8888.88",
        "bidSz":"5",
        "open24h":"9000",
        "high24h":"10000",
        "low24h":"8888.88",
        "volCcy24h":"2222",
        "vol24h":"2222",
        "sodUtc0":"0.1",
        "sodUtc8":"0.1",
        "ts":"1597026383085"
     },
     {
        "instType":"SWAP",
        "instId":"BTC-USD-SWAP",
        "last":"9999.99",
        "lastSz":"1",
        "askPx":"9999.99",
        "askSz":"11",
        "bidPx":"8888.88",
        "bidSz":"5",
        "open24h":"9000",
        "high24h":"10000",
        "low24h":"8888.88",
        "volCcy24h":"2222",
        "vol24h":"2222",
        "sodUtc0":"0.1",
        "sodUtc8":"0.1",
        "ts":"1597026383085"
    }
  ]
}

返回参数

参数名	类型	描述
instType	String	产品类型
instId	String	产品ID
last	String	最新成交价
lastSz	String	最新成交的数量，0 代表没有成交量
askPx	String	卖一价
askSz	String	卖一价的挂单数数量
bidPx	String	买一价
bidSz	String	买一价的挂单数量
open24h	String	24小时开盘价
high24h	String	24小时最高价
low24h	String	24小时最低价
volCcy24h	String	24小时成交量，以`币`为单位如果是`衍生品`合约，数值为交易货币的数量。如果是`币币/币币杠杆`，数值为计价货币的数量。
vol24h	String	24小时成交量，以`张`为单位如果是`衍生品`合约，数值为合约的张数。如果是`币币/币币杠杆`，数值为交易货币的数量。
sodUtc0	String	UTC 0 时开盘价
sodUtc8	String	UTC+8 时开盘价
ts	String	ticker数据产生时间，Unix时间戳的毫秒数格式，如 `1597026383085`

GET / 获取单个产品行情信息

获取产品行情信息

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/ticker

请求示例

GET /api/v5/market/ticker?instId=BTC-USD-SWAP

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取单个产品行情信息
result = marketDataAPI.get_ticker(
    instId="BTC-USD-SWAP"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 `BTC-USD-SWAP`

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "instType": "SWAP",
            "instId": "BTC-USD-SWAP",
            "last": "56956.1",
            "lastSz": "3",
            "askPx": "56959.1",
            "askSz": "10582",
            "bidPx": "56959",
            "bidSz": "4552",
            "open24h": "55926",
            "high24h": "57641.1",
            "low24h": "54570.1",
            "volCcy24h": "81137.755",
            "vol24h": "46258703",
            "ts": "1620289117764",
            "sodUtc0": "55926",
            "sodUtc8": "55926"
        }
    ]
}

返回参数

参数名	类型	描述
instType	String	产品类型
instId	String	产品ID
last	String	最新成交价
lastSz	String	最新成交的数量，0 代表没有成交量
askPx	String	卖一价
askSz	String	卖一价对应的数量
bidPx	String	买一价
bidSz	String	买一价对应的数量
open24h	String	24小时开盘价
high24h	String	24小时最高价
low24h	String	24小时最低价
volCcy24h	String	24小时成交量，以`币`为单位如果是`衍生品`合约，数值为交易货币的数量。如果是`币币/币币杠杆`，数值为计价货币的数量。
vol24h	String	24小时成交量，以`张`为单位如果是`衍生品`合约，数值为合约的张数。如果是`币币/币币杠杆`，数值为交易货币的数量。
sodUtc0	String	UTC+0 时开盘价
sodUtc8	String	UTC+8 时开盘价
ts	String	ticker数据产生时间，Unix时间戳的毫秒数格式，如 `1597026383085`

GET / 获取产品深度

获取产品深度列表

限速：40次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/books

请求示例

GET /api/v5/market/books?instId=BTC-USDT

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取产品深度
result = marketDataAPI.get_orderbook(
    instId="BTC-USDT"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 `BTC-USDT`
sz	String	否	深度档位数量，最大值可传400，即买卖深度共800条不填写此参数，默认返回`1`档深度数据

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "asks": [
                [
                    "41006.8",
                    "0.60038921",
                    "0",
                    "1"
                ]
            ],
            "bids": [
                [
                    "41006.3",
                    "0.30178218",
                    "0",
                    "2"
                ]
            ],
            "ts": "1629966436396"
        }
    ]
}

返回参数

参数名	类型	描述
asks	Array	卖方深度
bids	Array	买方深度
ts	String	深度产生的时间

GET / 获取产品完整深度

获取产品深度列表。数据每秒更新一次。

限速：10次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/books-full

请求示例

GET /api/v5/market/books-full?instId=BTC-USDT&sz=20

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 `BTC-USDT`
sz	String	否	深度档位数量，最大值可传5000，即买卖深度共10000条不填写此参数，默认返回`1`档深度数据

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "asks": [
                [
                    "41006.8",
                    "0.60038921",
                    "1"
                ]
            ],
            "bids": [
                [
                    "41006.3",
                    "0.30178218",
                    "2"
                ]
            ],
            "ts": "1629966436396"
        }
    ]
}

返回参数

参数名	类型	描述
asks	Array	卖方深度
bids	Array	买方深度
ts	String	深度产生的时间

GET / 获取交易产品K线数据

获取K线数据。K线数据按请求的粒度分组返回，K线数据每个粒度最多可获取最近1,440条。

限速：40次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/candles

请求示例

GET /api/v5/market/candles?instId=BTC-USDT

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取交易产品K线数据
result = marketDataAPI.get_candlesticks(
    instId="BTC-USDT"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 `BTC-USDT`
bar	String	否	时间粒度，默认值`1m` 如 [1m/3m/5m/15m/30m/1H/2H/4H] 香港时间开盘价k线：[6H/12H/1D/2D/3D/1W/1M/3M] UTC时间开盘价k线：[/6Hutc/12Hutc/1Dutc/2Dutc/3Dutc/1Wutc/1Mutc/3Mutc]
after	String	否	请求此时间戳之前（更旧的数据）的分页内容，传的值为对应接口的`ts`
before	String	否	请求此时间戳之后（更新的数据）的分页内容，传的值为对应接口的`ts`, 单独使用时，会返回最新的数据。
limit	String	否	分页返回的结果集数量，最大为300，不填默认返回100条

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
     [
        "1597026383085",
        "3.721",
        "3.743",
        "3.677",
        "3.708",
        "8422410",
        "22698348.04828491",
        "12698348.04828491",
        "0"
    ],
    [
        "1597026383085",
        "3.731",
        "3.799",
        "3.494",
        "3.72",
        "24912403",
        "67632347.24399722",
        "37632347.24399722",
        "1"
    ]
    ]
}

返回参数

参数名	类型	描述
ts	String	开始时间，Unix时间戳的毫秒数格式，如 `1597026383085`
o	String	开盘价格
h	String	最高价格
l	String	最低价格
c	String	收盘价格
vol	String	交易量，以`张`为单位如果是`衍生品`合约，数值为合约的张数。如果是`币币/币币杠杆`，数值为交易货币的数量。
volCcy	String	交易量，以`币`为单位如果是`衍生品`合约，数值为交易货币的数量。如果是`币币/币币杠杆`，数值为计价货币的数量。
volCcyQuote	String	交易量，以计价货币为单位如 `BTC-USDT`和`BTC-USDT-SWAP`，单位均是`USDT`。 `BTC-USD-SWAP`单位是`USD`。
confirm	String	K线状态 `0`：K线未完结 `1`：K线已完结

GET / 获取交易产品历史K线数据

获取最近几年的历史k线数据(1s k线支持查询最近3个月的数据)

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/history-candles

请求示例

GET /api/v5/market/history-candles?instId=BTC-USDT

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取交易产品历史K线数据
result = marketDataAPI.get_history_candlesticks(
    instId="BTC-USDT"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 `BTC-USDT`
after	String	否	请求此时间戳之前（更旧的数据）的分页内容，传的值为对应接口的`ts`
before	String	否	请求此时间戳之后（更新的数据）的分页内容，传的值为对应接口的`ts`, 单独使用时，会返回最新的数据。
bar	String	否	时间粒度，默认值`1m` 如 [1s/1m/3m/5m/15m/30m/1H/2H/4H] 香港时间开盘价k线：[6H/12H/1D/2D/3D/1W/1M/3M] UTC时间开盘价k线：[6Hutc/12Hutc/1Dutc/2Dutc/3Dutc/1Wutc/1Mutc/3Mutc]
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
     [
        "1597026383085",
        "3.721",
        "3.743",
        "3.677",
        "3.708",
        "8422410",
        "22698348.04828491",
        "12698348.04828491",
        "1"
    ],
    [
        "1597026383085",
        "3.731",
        "3.799",
        "3.494",
        "3.72",
        "24912403",
        "67632347.24399722",
        "37632347.24399722",
        "1"
    ]
    ]
}

返回参数

参数名	类型	描述
ts	String	开始时间，Unix时间戳的毫秒数格式，如 `1597026383085`
o	String	开盘价格
h	String	最高价格
l	String	最低价格
c	String	收盘价格
vol	String	交易量，以`张`为单位如果是`衍生品`合约，数值为合约的张数。如果是`币币/币币杠杆`，数值为交易货币的数量。
volCcy	String	交易量，以`币`为单位如果是`衍生品`合约，数值为交易货币的数量。如果是`币币/币币杠杆`，数值为计价货币的数量。
volCcyQuote	String	交易量，以计价货币为单位如 `BTC-USDT`和`BTC-USDT-SWAP`，单位均是`USDT` `BTC-USD-SWAP`单位是`USD`
confirm	String	K线状态 `0`：K线未完结 `1`：K线已完结

GET / 获取交易产品公共成交数据

查询市场上的成交信息数据

限速：100次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/trades

请求示例

GET /api/v5/market/trades?instId=BTC-USDT

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取交易产品公共成交数据
result = marketDataAPI.get_trades(
    instId="BTC-USDT"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 `BTC-USDT`
limit	String	否	分页返回的结果集数量，最大为500，不填默认返回100条

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "instId": "BTC-USDT",
            "side": "sell",
            "sz": "0.00001",
            "px": "29963.2",
            "tradeId": "242720720",
            "ts": "1654161646974"
        },
        {
            "instId": "BTC-USDT",
            "side": "sell",
            "sz": "0.00001",
            "px": "29964.1",
            "tradeId": "242720719",
            "ts": "1654161641568"
        }
    ]
}

返回参数

参数名	类型	描述
instId	String	产品ID
tradeId	String	成交ID
px	String	成交价格
sz	String	成交数量对于币币交易，成交数量的单位为交易货币
side	String	成交方向 `buy`：买 `sell`：卖
ts	String	成交时间，Unix时间戳的毫秒数格式，如`1597026383085`

GET / 获取交易产品公共历史成交数据

查询市场上的成交信息数据，可以分页获取最近3个月的数据。

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/history-trades

请求示例

GET /api/v5/market/history-trades?instId=BTC-USDT

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取交易产品公共历史成交数据
result = marketDataAPI.get_history_trades(
    instId="BTC-USDT"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 `BTC-USDT`
type	String	否	分页类型 `1`：tradeId 分页 `2`：时间戳分页默认为`1`：tradeId 分页
after	String	否	请求此 ID 或 ts 之前的分页内容，传的值为对应接口的 tradeId 或 ts
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的 tradeId。不支持时间戳分页。单独使用时，会返回最新的数据。
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "instId": "BTC-USDT",
            "side": "sell",
            "sz": "0.00001",
            "px": "29963.2",
            "tradeId": "242720720",
            "ts": "1654161646974"
        },
        {
            "instId": "BTC-USDT",
            "side": "sell",
            "sz": "0.00001",
            "px": "29964.1",
            "tradeId": "242720719",
            "ts": "1654161641568"
        }
    ]
}

返回参数

参数名	类型	描述
instId	String	产品ID
tradeId	String	成交ID
px	String	成交价格
sz	String	成交数量
side	String	成交方向 `buy`：买 `sell`：卖
ts	String	成交时间，Unix时间戳的毫秒数格式，如`1597026383085`

GET / 获取期权品种公共成交数据

查询期权同一个交易品种下的成交信息数据，最多返回100条。

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/option/instrument-family-trades

请求示例

GET /api/v5/market/option/instrument-family-trades?instFamily=BTC-USD

请求参数

参数名	类型	是否必须	描述
instFamily	String	是	交易品种，如 BTC-USD，适用于期权

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "vol24h": "103381",
            "tradeInfo": [
                {
                    "instId": "BTC-USD-221111-17750-C",
                    "side": "sell",
                    "sz": "1",
                    "px": "0.0075",
                    "tradeId": "20",
                    "ts": "1668090715058"
                },
                {
                    "instId": "BTC-USD-221111-17750-C",
                    "side": "sell",
                    "sz": "91",
                    "px": "0.01",
                    "tradeId": "19",
                    "ts": "1668090421062"
                }
            ],
            "optType": "C"
        },
        {
            "vol24h": "144499",
            "tradeInfo": [
                {
                    "instId": "BTC-USD-230127-10000-P",
                    "side": "sell",
                    "sz": "82",
                    "px": "0.019",
                    "tradeId": "23",
                    "ts": "1668090967057"
                },
                {
                    "instId": "BTC-USD-221111-16250-P",
                    "side": "sell",
                    "sz": "102",
                    "px": "0.0045",
                    "tradeId": "24",
                    "ts": "1668090885050"
                }
            ],
            "optType": "P"
        }
    ]
}

返回参数

参数名	类型	描述
vol24h	String	24小时成交量，以张为单位
optType	String	期权类型，`C`：看涨期权 `P`：看跌期权
tradeInfo	Array	成交数据列表
> instId	String	产品ID
> tradeId	String	成交ID
> px	String	成交价格
> sz	String	成交数量
> side	String	成交方向 `buy`：买 `sell`：卖
> ts	String	成交时间，Unix时间戳的毫秒数格式，如1597026383085

GET / 获取期权公共成交数据

最多返回最近的100条成交数据

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/public/option-trades

请求示例

GET /api/v5/public/option-trades?instFamily=BTC-USD

请求参数

参数名	类型	是否必须	描述
instId	String	可选	产品ID，如 BTC-USD-221230-4000-C，`instId` 和 `instFamily` 必须传一个，若传两个，以 `instId` 为主
instFamily	String	可选	交易品种，如 BTC-USD
optType	String	否	期权类型，`C`：看涨期权 `P`：看跌期权

返回结果

{
    "code": "0",
    "data": [
        {
            "fillVol": "0.24415013671875",
            "fwdPx": "16676.907614127158",
            "idxPx": "16667",
            "instFamily": "BTC-USD",
            "instId": "BTC-USD-221230-16600-P",
            "markPx": "0.006308943261227884",
            "optType": "P",
            "px": "0.005",
            "side": "sell",
            "sz": "30",
            "tradeId": "65",
            "ts": "1672225112048"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品ID
instFamily	String	交易品种
tradeId	String	成交ID
px	String	成交价格
sz	String	成交数量
side	String	成交方向 `buy`：买 `sell`：卖
optType	String	期权类型，C：看涨期权 P：看跌期权，仅适用于期权
fillVol	String	成交时的隐含波动率（对应成交价格）
fwdPx	String	成交时的远期价格
idxPx	String	成交时的指数价格
markPx	String	成交时的标记价格
ts	String	成交时间，Unix时间戳的毫秒数格式，如`1597026383085`

GET / 获取平台24小时总成交量

24小时成交量滚动计算

限速：2次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/platform-24-volume

请求示例

GET /api/v5/market/platform-24-volume

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取平台24小时总成交量
result = marketDataAPI.get_volume()
print(result)

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
     {
         "volCny": "230900886396766",
         "volUsd": "34462818865189",
         "ts": "1657856040389"
     }
  ]
}

返回参数

参数名	类型	描述
volUsd	String	订单簿交易近24小时总成交量，以美元为单位
volCny	String	订单簿交易近24小时总成交量，以人民币为单位
ts	String	接口返回数据时间

GET / 集合竞价信息

获取集合竞价相关信息

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/call-auction-details

请求示例

GET /api/v5/market/call-auction-details?instId=ONDO-USDC

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 BTC-USDT

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "instId": "ONDO-USDC",
            "unmatchedSz": "9988764",
            "eqPx": "0.6",
            "matchedSz": "44978",
            "state": "continuous_trading",
            "auctionEndTime": "1726542000000",
            "ts": "1726542000007"
        }
    ]
}

返回参数

参数名	类型	描述
instId	String	产品ID
eqPx	String	均衡价格
matchedSz	String	买卖双边的匹配数量，单位为交易货币
unmatchedSz	String	未匹配数量
auctionEndTime	String	集合竞价结束时间，Unix时间戳的毫秒数格式，如 `1597026383085`
state	String	交易状态 `call_auction`：集合竞价 `continuous_trading`：连续交易
ts	String	数据产生时间，Unix时间戳的毫秒数格式，如 `1597026383085`

WS / 行情频道

获取产品的最新成交价、买一价、卖一价和24小时交易量等信息。
最快100ms推送一次，没有触发事件时不推送，触发推送的事件有：成交、买一卖一发生变动。

URL Path

/ws/v5/public

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "tickers",
        "instId": "BTC-USDT"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `tickers`
> instId	String	是	产品ID

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "tickers",
        "instId": "BTC-USDT"
    },
    "connId": "a4d3ae55"
}

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"tickers\", \"instId\" : \"LTC-USD-200327\"}]}",
    "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
    "arg": {
        "channel": "tickers",
        "instId": "BTC-USDT"
    },
    "data": [{
        "instType": "SPOT",
        "instId": "BTC-USDT",
        "last": "9999.99",
        "lastSz": "0.1",
        "askPx": "9999.99",
        "askSz": "11",
        "bidPx": "8888.88",
        "bidSz": "5",
        "open24h": "9000",
        "high24h": "10000",
        "low24h": "8888.88",
        "volCcy24h": "2222",
        "vol24h": "2222",
        "sodUtc0": "2222",
        "sodUtc8": "2222",
        "ts": "1597026383085"
    }]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
data	Array	订阅的数据
> instType	String	产品类型
> instId	String	产品ID
> last	String	最新成交价
> lastSz	String	最新成交的数量，0 代表没有成交量
> askPx	String	卖一价
> askSz	String	卖一价对应的量
> bidPx	String	买一价
> bidSz	String	买一价对应的数量
> open24h	String	24小时开盘价
> high24h	String	24小时最高价
> low24h	String	24小时最低价
> volCcy24h	String	24小时成交量，以`币`为单位如果是`衍生品`合约，数值为交易货币的数量。如果是`币币/币币杠杆`，数值为计价货币的数量。
> vol24h	String	24小时成交量，以`张`为单位如果是`衍生品`合约，数值为合约的张数。如果是`币币/币币杠杆`，数值为交易货币的数量。
> sodUtc0	String	UTC+0 时开盘价
> sodUtc8	String	UTC+8 时开盘价
> ts	String	数据产生时间，Unix时间戳的毫秒数格式，如 `1597026383085`

WS / K线频道

获取K线数据，推送频率最快是间隔1秒推送一次数据。

URL Path

/ws/v5/business

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "candle1D",
        "instId": "BTC-USDT"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `candle3M` `candle1M` `candle1W` `candle1D` `candle2D` `candle3D` `candle5D` `candle12H` `candle6H` `candle4H` `candle2H` `candle1H` `candle30m` `candle15m` `candle5m` `candle3m` `candle1m` `candle1s` `candle3Mutc` `candle1Mutc` `candle1Wutc` `candle1Dutc` `candle2Dutc` `candle3Dutc` `candle5Dutc` `candle12Hutc` `candle6Hutc`
> instId	String	是	产品ID

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "candle1D",
        "instId": "BTC-USDT"
    },
  "connId": "a4d3ae55"
}

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"candle1D\", \"instId\" : \"BTC-USD-191227\"}]}",
  "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
  "arg": {
    "channel": "candle1D",
    "instId": "BTC-USDT"
  },
  "data": [
    [
      "1629993600000",
      "42500",
      "48199.9",
      "41006.1",
      "41006.1",
      "3587.41204591",
      "166741046.22583129",
      "166741046.22583129",
      "0"
    ]
  ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
data	Array	订阅的数据
> ts	String	开始时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> o	String	开盘价格
> h	String	最高价格
> l	String	最低价格
> c	String	收盘价格
> vol	String	交易量，以`张`为单位如果是`衍生品`合约，数值为合约的张数。如果是`币币/币币杠杆`，数值为交易货币的数量。
> volCcy	String	交易量，以`币`为单位如果是`衍生品`合约，数值为交易货币的数量。如果是`币币/币币杠杆`，数值为计价货币的数量。
> volCcyQuote	String	交易量，以计价货币为单位如 `BTC-USDT`和`BTC-USDT-SWAP`单位均是`USDT`。 `BTC-USD-SWAP`单位是`USD`。
> confirm	String	K线状态 `0`：K线未完结 `1`：K线已完结

WS / 交易频道

获取最近的成交数据，有成交数据就推送，每次推送可能聚合多条成交数据。
根据每个taker订单的不同成交价格推送消息，并使用count字段表示聚合的订单匹配数量。

URL Path

/ws/v5/public

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "trades",
        "instId": "BTC-USDT"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `trades`
> instId	String	是	产品ID

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "trades",
        "instId": "BTC-USDT"
    },
  "connId": "a4d3ae55"
}

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"trades\", \"instId\" : \"BTC-USD-191227\"}]}",
  "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
  "arg": {
    "channel": "trades",
    "instId": "BTC-USDT"
  },
  "data": [
    {
      "instId": "BTC-USDT",
      "tradeId": "130639474",
      "px": "42219.9",
      "sz": "0.12060306",
      "side": "buy",
      "ts": "1630048897897",
      "count": "3"
    }
  ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
data	Array	订阅的数据
> instId	String	产品ID，如 `BTC-USDT`
> tradeId	String	聚合的多笔交易中最新一笔交易的成交ID
> px	String	成交价格
> sz	String	成交数量
> side	String	成交方向 `buy` `sell`
> ts	String	成交时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> count	String	聚合的订单匹配数量

WS / 全部交易频道

获取最近的成交数据，有成交数据就推送，每次推送仅包含一条成交数据。

URL Path

/ws/v5/business

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "trades-all",
        "instId": "BTC-USDT"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `trades-all`
> instId	String	是	产品ID

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "trades-all",
        "instId": "BTC-USDT"
    },
  "connId": "a4d3ae55"
}

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"trades-all\", \"instId\" : \"BTC-USD-191227\"}]}",
  "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
  "arg": {
    "channel": "trades-all",
    "instId": "BTC-USDT"
  },
  "data": [
    {
      "instId": "BTC-USDT",
      "tradeId": "130639474",
      "px": "42219.9",
      "sz": "0.12060306",
      "side": "buy",
      "ts": "1630048897897"
    }
  ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
data	Array	订阅的数据
> instId	String	产品ID，如 `BTC-USDT`
> tradeId	String	成交ID
> px	String	成交价格
> sz	String	成交数量
> side	String	成交方向 `buy` `sell`
> ts	String	成交时间，Unix时间戳的毫秒数格式，如 `1597026383085`

WS / 深度频道

获取深度数据，books是400档频道，books5是5档频道， bbo-tbt是先1档后实时推送的频道，books-l2-tbt是先400档后实时推送的频道，books50-l2-tbt是先50档后实时推的频道；

books 首次推400档快照数据，以后增量推送，每100毫秒推送一次变化的数据
books5 首次推5档快照数据，以后定量推送，每100毫秒当5档快照数据有变化推送一次5档数据
bbo-tbt 首次推1档快照数据，以后定量推送，每10毫秒当1档快照数据有变化推送一次1档数据
books-l2-tbt 首次推400档快照数据，以后增量推送，每10毫秒推送一次变化的数据
books50-l2-tbt 首次推50档快照数据，以后增量推送，每10毫秒推送一次变化的数据
单个连接、交易产品维度，深度频道的推送顺序固定为：bbo-tbt -> books-l2-tbt -> books50-l2-tbt -> books -> books5。
在相同连接下，用户将无法为相同交易产品同时订阅 books-l2-tbt 以及 books50-l2-tbt/books频道
- 更多细节，请参阅更新日志 2024-07-17

身份认证参考登录功能

服务地址

/ws/v5/public

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "books",
        "instId": "BTC-USDT"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `books` `books5` `bbo-tbt` `books-l2-tbt` `books50-l2-tbt`
> instId	String	是	产品ID

返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "books",
        "instId": "BTC-USDT"
    },
    "connId": "a4d3ae55"
}

失败示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"books\", \"instId\" : \"BTC-USD-191227\"}]}",
    "connId": "a4d3ae55"
}

返回参数

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

推送示例：全量

{
    "arg": {
        "channel": "books",
        "instId": "BTC-USDT"
    },
    "action": "snapshot",
    "data": [{
        "asks": [
            ["8476.98", "415", "0", "13"],
            ["8477", "7", "0", "2"],
            ["8477.34", "85", "0", "1"],
            ["8477.56", "1", "0", "1"],
            ["8505.84", "8", "0", "1"],
            ["8506.37", "85", "0", "1"],
            ["8506.49", "2", "0", "1"],
            ["8506.96", "100", "0", "2"]
        ],
        "bids": [
            ["8476.97", "256", "0", "12"],
            ["8475.55", "101", "0", "1"],
            ["8475.54", "100", "0", "1"],
            ["8475.3", "1", "0", "1"],
            ["8447.32", "6", "0", "1"],
            ["8447.02", "246", "0", "1"],
            ["8446.83", "24", "0", "1"],
            ["8446", "95", "0", "3"]
        ],
        "ts": "1597026383085",
        "checksum": -855196043,
        "prevSeqId": -1,
        "seqId": 123456
    }]
}

推送示例：增量

{
    "arg": {
        "channel": "books",
        "instId": "BTC-USDT"
    },
    "action": "update",
    "data": [{
        "asks": [
            ["8476.98", "415", "0", "13"],
            ["8477", "7", "0", "2"],
            ["8477.34", "85", "0", "1"],
            ["8477.56", "1", "0", "1"],
            ["8505.84", "8", "0", "1"],
            ["8506.37", "85", "0", "1"],
            ["8506.49", "2", "0", "1"],
            ["8506.96", "100", "0", "2"]
        ],
        "bids": [
            ["8476.97", "256", "0", "12"],
            ["8475.55", "101", "0", "1"],
            ["8475.54", "100", "0", "1"],
            ["8475.3", "1", "0", "1"],
            ["8447.32", "6", "0", "1"],
            ["8447.02", "246", "0", "1"],
            ["8446.83", "24", "0", "1"],
            ["8446", "95", "0", "3"]
        ],
        "ts": "1597026383085",
        "checksum": -855196043,
        "prevSeqId": 123456,
        "seqId": 123457
    }]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
action	String	推送数据动作，增量推送数据还是全量推送数据 `snapshot`：全量 `update`：增量
data	Array	订阅的数据
> asks	Array	卖方深度
> bids	Array	买方深度
> ts	String	数据更新时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
> checksum	Integer	检验和（下方注解）
> prevSeqId	Integer	上一个推送的序列号。仅适用 `books`，`books-l2-tbt`，`books50-l2-tbt`
> seqId	Integer	推送的序列号（下方注解）

序列号

seqId是交易所行情的一个序号。如果用户通过多个websocket连接同一频道，收到的序列号会是相同的。每个instId对应一套。用户可以使用在增量推送频道的prevSeqId和seqId来构建消息序列。这将允许用户检测数据包丢失和消息的排序。正常场景下seqId的值大于prevSeqId。新消息中的prevSeqId与上一条消息的seqId匹配。最小序列号值为0，除了快照消息的prevSeqId为-1。

异常情况：
1. 如果一段时间内没有深度更新，OKX将发一条消息'asks': [], 'bids': []以通知用户连接是正常的。推送的seqId跟上一条信息的一样，prevSeqId等于seqId。 2. 序列号可能由于维护而重置，在这种情况下，用户将收到一条seqId小于prevSeqId的增量消息。随后的消息将遵循常规的排序规则。

示例

快照推送：prevSeqId = -1，seqId = 10
增量推送1（正常更新）：prevSeqId = 10，seqId = 15
增量推送2（无更新）：prevSeqId = 15，seqId = 15
增量推送3（序列重置）：prevSeqId = 15，seqId = 3
增量推送4（正常更新）：prevSeqId = 3，seqId = 5

Checksum机制

此机制可以帮助用户校验深度数据的准确性。

深度合并

用户订阅增量推送（如：books400档）深度频道成功后，首先获取初始全量深度数据，当获取到增量推送数据后，更新本地全量深度数据。

如果有相同价格，则比较数量；数量为0删除此深度，数量有变化则替换此数据。
如果没有相同价格，则按照价格优劣排序（bid为价格降序，ask为价格升序），将深度信息插入到全量数据中

计算校验和

先用深度合并后前25档bids和asks组成一个字符串（其中ask和bid中的价格和数量以冒号连接），再计算其crc32值（32位有符号整型）。

计算校验和

1.bid和ask超过25档
合并后全量深度数据（在此仅展示2档数据，实际应截取25档数据）：

{
    "bids": [
        ["3366.1", "7", "0", "3"],
        ["3366", "6", "3", "4"]
    ],
    "asks": [
        ["3366.8", "9", "10", "3"],
        ["3368", "8", "3", "4"]
    ]
}

校验字符串：
"3366.1:7:3366.8:9:3366:6:3368:8"

2.bid或ask不足25档  
合并后全量深度数据：

{
    "bids": [
        ["3366.1", "7", "0", "3"]
    ],
    "asks": [
        ["3366.8", "9", "10", "3"],
        ["3368", "8", "3", "4"],
        ["3372", "8", "3", "4"]
    ]
}

校验字符串：
"3366.1:7:3366.8:9:3368:8:3372:8"

当bid和ask深度数据超过25档时，截取各自25档数据，要校验的字符串按照bid、ask深度数据交替方式连接。
如：bid[价格:数量]:ask[价格:数量]:bid[价格:数量]:ask[价格:数量]...
bid或ask深度数据不足25档时，直接忽略缺失的深度。
如：bid[价格:数量]:ask[价格:数量]:asks[价格:数量]:asks[价格:数量]...

bbo-tbt 频道推送示例

{
  "arg": {
    "channel": "bbo-tbt",
    "instId": "BCH-USDT-SWAP"
  },
  "data": [
    {
      "asks": [
        [
          "111.06","55154","0","2"
        ]
      ],
      "bids": [
        [
          "111.05","57745","0","2"
        ]
      ],
      "ts": "1670324386802",
      "seqId": 363996337
    }
  ]
}

books5 频道推送示例

{
  "arg": {
    "channel": "books5",
    "instId": "BCH-USDT-SWAP"
  },
  "data": [
    {
      "asks": [
        ["111.06","55154","0","2"],
        ["111.07","53276","0","2"],
        ["111.08","72435","0","2"],
        ["111.09","70312","0","2"],
        ["111.1","67272","0","2"]],
      "bids": [
        ["111.05","57745","0","2"],
        ["111.04","57109","0","2"],
        ["111.03","69563","0","2"],
        ["111.02","71248","0","2"],
        ["111.01","65090","0","2"]],
      "instId": "BCH-USDT-SWAP",
      "ts": "1670324386802",
      "seqId": 363996337
    }
  ]
}

WS / 期权公共成交频道

获取最近的期权成交数据，有成交数据就推送，每次推送仅包含一条成交数据。

URL Path

/ws/v5/public

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "option-trades",
        "instType": "OPTION",
        "instFamily": "BTC-USD"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `option-trades`
> instType	String	是	产品类型，`OPTION`：期权
> instId	String	可选	产品ID，如 BTC-USD-221230-4000-C，`instId` 和 `instFamily` 必须传一个，若传两个，以 `instId` 为主
> instFamily	String	可选	交易品种，如 BTC-USD

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "option-trades",
        "instType": "OPTION",
        "instFamily": "BTC-USD"
    },
    "connId": "a4d3ae55"
}

失败返回示例

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

返回参数

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

推送示例

{
    "arg": {
        "channel": "option-trades",
        "instType": "OPTION",
        "instFamily": "BTC-USD"
    },
    "data": [
        {
            "fillVol": "0.5066007836914062",
            "fwdPx": "16469.69928595038",
            "idxPx": "16537.2",
            "instFamily": "BTC-USD",
            "instId": "BTC-USD-230224-18000-C",
            "markPx": "0.04690107010619562",
            "optType": "C",
            "px": "0.045",
            "side": "sell",
            "sz": "2",
            "tradeId": "38",
            "ts": "1672286551080"
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
data	Array	订阅的数据
> instId	String	产品ID
> instFamily	String	交易品种
> tradeId	String	成交ID
> px	String	成交价格
> sz	String	成交数量
> side	String	成交方向 `buy`：买 `sell`：卖
> optType	String	期权类型，C：看涨期权 P：看跌期权，仅适用于期权
> fillVol	String	成交时的隐含波动率（对应成交价格）
> fwdPx	String	成交时的远期价格
> idxPx	String	成交时的指数价格
> markPx	String	成交时的标记价格
> ts	String	成交时间，Unix时间戳的毫秒数格式，如`1597026383085`

WS / 集合竞价信息频道

获取集合竞价相关信息

URL Path

/ws/v5/public

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "call-auction-details",
        "instId": "ONDO-USDC"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，`subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `call-auction-details`
> instId	String	是	产品ID

成功返回示例

{
  "event": "subscribe",
  "arg": {
      "channel": "call-auction-details",
      "instId": "ONDO-USDC"
    },
  "connId": "a4d3ae55"
}

失败返回示例

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"call-auction-details\", \"instId\" : \"BTC-USD-191227\"}]}",
  "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
  "arg": {
    "channel": "call-auction-details",
    "instId": "ONDO-USDC"
  },
  "data": [
        {
            "instId": "ONDO-USDC",
            "unmatchedSz": "9988764",
            "eqPx": "0.6",
            "matchedSz": "44978",
            "state": "continuous_trading",
            "auctionEndTime": "1726542000000",
            "ts": "1726542000007"
        }
  ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
data	Array	订阅的数据
> instId	String	产品ID
> eqPx	String	均衡价格
> matchedSz	String	买卖双边的匹配数量，单位为交易货币
> unmatchedSz	String	未匹配数量
> auctionEndTime	String	集合竞价结束时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> state	String	交易状态 `call_auction`：集合竞价 `continuous_trading`：连续交易
> ts	String	数据产生时间，Unix时间戳的毫秒数格式，如 `1597026383085`

大宗交易

大宗交易工作流程

大宗交易时指在非公开市场进行的、私下议定的、满足规定最小交易手数的期货、期权、交割、永续或混合产品的大单交易。交易细节一经确认，此笔交易会被提交到OKX以进行保证金计算，清算和执行。

基本概念

询价单（RFQs） - 询价单，由询价方发给报价方. 询价单包括询价方希望交易的一种或多种产品及其数量。
报价单 - 报价单，由报价方发给询价方对询价单的报价。
交易 - 当询价方接受并执行报价方的报价单，一笔交易就由此产生。

基本工作流程

要以询价方或报价方身份进行交易，用户需要在交易账户中存入至少100,000美元。此外，要成为报价方请填写表格以访问大宗交易.

询价方创建一个询价单（RFQ），并选择希望收到此询价单的报价方。
不同报价方发送报价单回应此询价单。
询价方选择执行最好的报价单产生交易。OKX收到此笔交易并做结算。
询价方和报价方收到交易执行的确认。
交易详情发布在公共市场数据频道上（不包含交易方信息）。

询价方角度

询价方使用POST /api/v5/rfq/create-rfq创建询价单。询价方可通过GET /api/v5/public/instruments查询可询价产品信息，并通过GET /api/v5/rfq/counterparties查询可选择报价方信息。
询价方可以在询价单有效的任何时候通过POST /api/v5/rfq/cancel-rfq取消询价单。
报价方，如果是询价方选择的报价方之一，会在rfqs推送频道收到询价单信息，并可作出相应报价。
询价方，在quotes推送频道收到报价信息后，可以选择最优报价并通过POST /api/v5/rfq/execute-quote执行。
询价方会在struc-block-trades和rfqs推送频道收到交易成功执行确认。
询价方也会在public-struc-block-trades推送频道收到此笔交易以及其他OKX大宗交易的确认信息。

报价方角度

当有一个新的询价单发出，并且报价方是被选择的报价方之一时，报价方会在rfqs推送频道接收到此询价单信息。
报价方创建一个单向或者双向的报价单并通过POST /api/v5/rfq/create-quote发出。
报价方可以通过POST /api/v5/rfq/cancel-quote任意取消一个有效的报价单。
询价方选择执行最优报价单。
报价方通过quotes推送频道接收他们报价单的状态更新。
报价方会在struc-block-trades和quotes推送频道收到他们报价单的交易成功执行确认。
报价方也会在public-struc-block-trades推送频道收到此笔交易以及其他OKX大宗交易的确认信息。

REST API

获取报价方信息

查询可以参与交易的报价方信息。

限速: 5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/rfq/counterparties

请求示例

GET /api/v5/rfq/counterparties

import okx.BlockTrading as BlockTrading

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

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

blockTradingAPI = BlockTrading.BlockTradingAPI(apikey, secretkey, passphrase, False, flag)

# 获取报价方信息
result = blockTradingAPI.counterparties()
print(result)

请求参数

无

响应示例

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "traderName" : "Satoshi Nakamoto",
            "traderCode" : "SATOSHI",
            "type" : "" 
        }
    ]
}

响应参数

参数名	类型	描述
traderName	String	报价方名称
traderCode	String	报价方唯一标识代码，公开可见；报价和询价的相关接口都使用该代码代表报价方。
type	String	报价方类型。`LP`指通过API连接的自动做市商。

询价

创建一个询价单。

了解更多，请访问帮助中心 > 常见问题 > 交易 > 流动性市场 > 模拟交易

限速: 5次/2s；150次/12h

限速规则：UserID

权限：交易

HTTP Requests

POST /api/v5/rfq/create-rfq

请求示例

POST /api/v5/rfq/create-rfq

{
    "anonymous": true,
    "counterparties":[
        "Trader1",
        "Trader2"
    ],
    "allowPartialExecution":false,
    "clRfqId":"rfq01",
    "tag":"123456",
    "legs":[
        {
            "sz":"25",
            "side":"buy",
            "posSide": "long",
            "tdMode":"cross",
            "ccy":"USDT",
            "instId":"BTC-USD-221208-100000-C"
        },
        {
            "sz":"150",
            "side":"buy",
            "posSide": "long",
            "tdMode":"cross",
            "ccy":"USDT",
            "instId":"ETH-USDT",
            "tgtCcy":"base_ccy"
        }
    ]
}

import okx.BlockTrading as BlockTrading

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

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

blockTradingAPI = BlockTrading.BlockTradingAPI(apikey, secretkey, passphrase, False, flag)

# 询价
result = blockTradingAPI.create_rfq(
    anonymous=True,
    counterparties=[
        "Trader1",
        "Trader2"
    ],
    clRfqId= "rfq01",
    legs=[
        {
            "sz":"25",
            "side":"buy",
            "posSide": "long",
            "tdMode":"cross",
            "ccy":"USDT",
            "instId":"BTC-USD-221208-100000-C"
        },
        {
            "sz":"150",
            "side":"buy",
            "posSide": "long",
            "tdMode":"cross",
            "ccy":"USDT",
            "instId":"ETH-USDT",
            "tgtCcy":"base_ccy"
        }
    ]
)
print(result)

请求参数

参数名	类型	是否必须	描述
counterparties	Array of strings	是	希望收到询价的报价方列表，可通过`/api/v5/rfq/counterparties/`获取。
anonymous	Boolean	否	是否匿名询价，`true`表示匿名询价，`false`表示公开询价，默认值为 `false`，为`true`时，即使在交易执行之后，身份也不会透露给报价方。
clRfqId	String	否	询价单自定义ID，字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
tag	String	否	询价单标签，与此询价单关联的大宗交易将有相同的标签。字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。
allowPartialExecution	Boolean	否	RFQ是否可以被部分执行，如果腿的比例和原RFQ一致。有效值为`true`或`false`。默认为`false`。
legs	Array of objects	是	组合交易，每次最多可以提交15组交易信息
> instId	String	是	产品ID
> tdMode	String	否	交易模式保证金模式：`cross`全仓 `isolated`逐仓非保证金模式：`cash`非保证金. 如未提供，tdMode 将继承系统设置的默认值：现货和合约模式 & 现货: `cash` 现货和合约模式和跨币种保证金模式下买入期权： `isolated` 其他情况: `cross`
> ccy	String	否	保证金币种，仅适用于`现货和合约模式`下的`全仓杠杆`订单在其他情况下该参数将被忽略。
> sz	String	是	委托数量
> lmtPx	String	否	询价方期望的报价价格若提供了该字段，在报价价格优于或等于所指定价格，询价将自动被执行，直到该询价单被取消或过期为止。该字段必须提供所有组合交易的价格，以便自动执行询价；或者对所有组合交易留空，否则请求将被拒绝。自动执行的方向取决于询价单的腿方向。对于`币币/币币杠杆/交割/永续`，lmtPx将以计价货币单位计算。对于`期权`，lmtPx将以结算货币单位计算。该字段不会被披露给交易对手方。
> side	String	是	询价单方向
> posSide	String	否	持仓方向买卖模式下默认为`net`。在开平仓模式下仅可选择`long`或`short`。如未指定，则处于开平仓模式下的用户始终会开新仓位。仅适用交割、永续。
> tgtCcy	String	否	委托数量的类型定义`sz`属性的单位。仅适用于 instType=`SPOT`。有效值为`base_ccy`和`quote_ccy`。未指定时，默认为`base_ccy`。

返回示例

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "cTime":"1611033737572",
            "uTime":"1611033737572",
            "traderCode":"SATOSHI",
            "tag":"123456",
            "rfqId":"22534",
            "clRfqId":"rfq01",
            "allowPartialExecution":false,
            "state":"active",
            "validUntil":"1611033857557",
            "counterparties":[
                "Trader1",
                "Trader2"
            ],
            "legs":[
                {
                    "instId":"BTC-USD-221208-100000-C",
                    "sz":"25",
                    "side":"buy",
                    "posSide": "long",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "tgtCcy":""
                },
                {
                    "instId":"ETH-USDT",
                    "sz":"150",
                    "side":"buy",
                    "posSide": "long",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "tgtCcy":"base_ccy"     
                }
            ]
        }
    ]
}

返回参数

参数名	类型	描述
code	String	结果代码，0 表示成功。
msg	String	错误信息，如果代码不为 0，则不为空。
data	Array of objects	询价单结果
> cTime	String	询价单创建时间，Unix时间戳的毫秒数格式。
> uTime	String	询价单状态更新时间，Unix时间戳的毫秒数格式。
> state	String	询价单的状态有效值为 `active` `canceled` `pending_fill` `filled` `expired` `traded_away` `failed` `traded_away` 仅适用于报价方
> counterparties	Array of strings	报价方列表
> validUntil	String	询价单的过期时间，Unix时间戳的毫秒数格式。若所有腿都为期权，则询价单将在10分钟后过期；其他情况，询价单将在2分钟后过期。
> clRfqId	String	询价单自定义ID，为客户端敏感信息，不会公开，对报价方返回""。
> tag	String	RFQ标签，与此RFQ关联的大宗交易将有相同的标签。
> allowPartialExecution	Boolean	RFQ是否可以被部分执行，如果腿的比例和原RFQ一致。有效值为`true`或`false`。未指定时，默认为`false`。
> traderCode	String	询价方唯一标识代码。
> rfqId	String	询价单ID
> legs	Array of objects	组合交易，每个请求最多可放置15条腿
>> instId	String	产品ID，如 "BTC-USDT-SWAP"
>> tdMode	String	交易模式保证金模式：`cross`全仓 `isolated`逐仓非保证金模式：`cash`非保证金. 如未提供，tdMode 将继承系统设置的默认值：现货和合约模式 & 现货: `cash` 现货和合约模式和跨币种保证金模式下买入期权： `isolated` 其他情况: `cross`
>> ccy	String	保证金币种，仅适用于`现货和合约模式`下的`全仓杠杆`订单在其他情况下该参数将被忽略。
>> sz	String	委托数量
>> side	String	询价单方向有效值为`buy`和`sell`。
>> posSide	String	持仓方向买卖模式下默认为`net`。如未指定，则返回""，相当于`net`。在开平仓模式下仅可选择`long`或`short`。如未指定，则返回""，对应于为交易开新仓位的方向（买入=>`long`，卖出=>`short`）。仅适用交割、永续。
>> tgtCcy	String	委托数量的类型定义`sz`属性的单位。仅适用于 instType=`SPOT`。有效值为`base_ccy`和`quote_ccy`。未指定时，默认为`base_ccy`。

取消询价单

取消一个询价单。

限速: 5次/2s

限速规则：UserID

权限：交易

HTTP Requests

POST /api/v5/rfq/cancel-rfq

请求示例

POST /api/v5/rfq/cancel-rfq
{
    "rfqId":"22535",
    "clRfqId":"rfq001"
}

import okx.BlockTrading as BlockTrading

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

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

blockTradingAPI = BlockTrading.BlockTradingAPI(apikey, secretkey, passphrase, False, flag)

# 取消询价单
result = blockTradingAPI.cancel_rfq(
    rfqId="22535",
    clRfqId="rfq001"
)
print(result)

请求参数

参数名	类型	是否必须	描述
rfqId	String	可选	询价单ID
clRfqId	String	可选	询价单自定义ID，字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。当 clRfqId 和 rfqId 都传时，以 rfqId 为准。

返回示例

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "rfqId":"22535",
            "clRfqId":"rfq001",
            "sCode":"0",
            "sMsg":""
        }
    ]
}

返回参数

参数名	类型	描述
code	String	结果代码，0 表示成功。
msg	String	错误信息，如果代码不为 0，则不为空。
data	Array of objects	包含结果的对象数组
> rfqId	String	RFQ ID
> clRfqId	String	由用户设置的 RFQ ID
> sCode	String	事件执行结果的code，0代表成功
> sMsg	String	事件执行失败时的msg

批量取消询价单

取消一个或多个询价单，每次最多可以撤销100个询价单。

限速: 2次/2s

限速规则：UserID

权限：交易

HTTP Requests

POST /api/v5/rfq/cancel-batch-rfqs

请求示例

POST /api/v5/rfq/cancel-batch-rfqs
{
    "rfqIds":[
        "2201",
        "2202",
        "2203"
    ],
    "clRfqIds":[
        "r1",
        "r2",
        "r3"
    ]
}

import okx.BlockTrading as BlockTrading

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

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

blockTradingAPI = BlockTrading.BlockTradingAPI(apikey, secretkey, passphrase, False, flag)

# 批量取消询价单
result = blockTradingAPI.cancel_batch_rfqs(
    rfqIds=[
        "2201",
        "2202",
        "2203"
    ],
    clRfqIds=[
        "r1",
        "r2",
        "r3"
    ],
)
print(result)

请求参数

参数名	类型	是否必须	描述
rfqIds	Array of strings	可选	询价单IDs
clRfqIds	Array of strings	可选	询价单自定义ID，当 clRfqIds 和 rfqIds 都传时，以 rfqIds 为准。

全部成功示例

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "rfqId":"2201",
            "clRfqId":"r1",
            "sCode":"0",
            "sMsg":""
        },
        {
            "rfqId":"2202",
            "clRfqId":"r2",
            "sCode":"0",
            "sMsg":""
        },
        {
            "rfqId":"2203",
            "clRfqId":"r3",
            "sCode":"0",
            "sMsg":""
        }
    ]
}

部分成功示例

{
    "code":"2",
    "msg":"Bulk operation partially ",
    "data":[
        {
            "rfqId":"2201",
            "clRfqId":"r1",
            "sCode":"70000",
            "sMsg":"RFQ does not exist."
        },
        {
            "rfqId":"2202",
            "clRfqId":"r2",
            "sCode":"0",
            "sMsg":""
        },
        {
            "rfqId":"2203",
            "clRfqId":"r3",
            "sCode":"0",
            "sMsg":""
        }
    ]
}

失败示例

{
    "code":"1",
    "msg":"Operation failed.",
    "data":[
        {
            "rfqId":"2201",
            "clRfqId":"r1",
            "sCode":"70000",
            "sMsg":"RFQ does not exist."
        },
        {
            "rfqId":"2202",
            "clRfqId":"r2",
            "sCode":"70000",
            "sMsg":"RFQ does not exist."
        },
        {
            "rfqId":"2203",
            "clRfqId":"r3",
            "sCode":"70000",
            "sMsg":"RFQ does not exist."
        }
    ]
}

返回参数

参数名	类型	描述
code	String	结果代码，0 表示成功。
msg	String	错误信息，如果代码不为 0，则不为空。
data	Array of objects	包含结果的对象数组
> rfqId	String	询价单ID
> clRfqId	String	询价单自定义ID.
> sCode	String	事件执行结果的code，0代表成功
> sMsg	String	事件执行失败时的msg

取消所有询价单

限速: 2次/2s

限速规则：UserID

权限：交易

HTTP Requests

POST /api/v5/rfq/cancel-all-rfqs

请求示例

POST /api/v5/rfq/cancel-all-rfqs

import okx.BlockTrading as BlockTrading

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

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

blockTradingAPI = BlockTrading.BlockTradingAPI(apikey, secretkey, passphrase, False, flag)

# 取消所有询价单
result = blockTradingAPI.cancel_all_rfqs()
print(result)

请求参数

无

返回示例

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

返回参数

参数名	类型	描述
code	String	结果代码，0 表示成功。
msg	String	错误信息，如果代码不为 0，则不为空。
data	Array of objects	包含结果的对象数组
> ts	String	成功取消时间，Unix时间戳的毫秒数格式，例如 1597026383085。

执行报价

执行报价，仅限询价的创建者使用

限速: 2次/3s

限速规则：UserID

权限：交易

HTTP Requests

POST /api/v5/rfq/execute-quote

请求示例

POST /api/v5/rfq/execute-quote
{
    "rfqId":"22540",
    "quoteId":"84073",
    "legs":[
    {
        "sz":"25",
        "instId":"BTC-USD-20220114-13250-C"
    },
    {
        "sz":"25",
        "instId":"BTC-USDT"
    }
     ]
}

import okx.BlockTrading as BlockTrading

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

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

blockTradingAPI = BlockTrading.BlockTradingAPI(apikey, secretkey, passphrase, False, flag)

# 执行报价
result = blockTradingAPI.execute_quote(
    rfqId="22540",
    quoteId="84073"
)
print(result)

请求参数

参数名	类型	是否必须	描述
rfqId	String	是	询价单ID
quoteId	String	是	报价单ID
legs	Array of objects	否	用于部分执行的腿的数量。腿的数量比例必须与原RFQ相同。注意：每条腿的`tgtCcy`和`side`和原RFQ一致，`px`和对应Quote一致。
> instId	String	是	产品ID, 如 "BTC-USDT-SWAP".
> sz	String	是	该条腿的部分执行数量

响应示例

{  
   "code":"0",
   "msg":"",
   "data":[
       {
            "blockTdId":"180184",
            "rfqId":"1419",
            "clRfqId":"r0001",
            "quoteId":"1046",
            "clQuoteId":"q0001",
            "tag":"123456",
            "tTraderCode":"Trader1",
            "mTraderCode":"Trader2",
            "cTime":"1649670009",
            "legs":[
                {
                    "px":"43000",
                    "sz":"25",
                    "instId":"BTC-USD-20220114-13250-C",
                    "side":"sell",
                    "fee":"-1.001",
                    "feeCcy":"BTC",
                    "tradeId":"10211"
                },
                {
                    "px":"42800",
                    "sz":"25",
                    "instId":"BTC-USDT",
                    "side":"buy",
                    "fee":"-1.001",
                    "feeCcy":"BTC",
                    "tradeId":"10212"
                }
            ]
        }
   ]
}

响应参数

参数名	类型	描述
code	String	结果代码，0 表示成功。
msg	String	错误信息，如果代码不为 0，则不为空。
data	Array of objects	包含结果的对象数组
> cTime	String	交易执行的时间，Unix时间戳的毫秒数格式。
> rfqId	String	询价单ID
> clRfqId	String	询价单自定义ID，为客户敏感信息，不会公开，对报价方返回""。
> quoteId	String	报价单ID
> clQuoteId	String	报价单自定义ID，为客户敏感信息，不会公开，对询价方返回""。
> blockTdId	String	大宗交易ID
> tag	String	询价单标签
> tTraderCode	String	询价价方唯一标识代码。询价时 anonymous 设置为 `true` 时不可见。
> mTraderCode	String	报价方唯一标识代码。报价时 anonymous 设置为 `true` 时不可见。
> legs	Array of objects	组合交易
>> instId	String	产品ID
>> px	String	成交价格
>> sz	String	成交数量
>> side	String	询价单方向，`buy` 或者 `sell`。
>> fee	String	手续费，正数代表平台返佣，负数代表平台扣除
>> feeCcy	String	手续费币种
>> tradeId	String	最新的成交Id.

获取可报价产品

用于maker查询特定的接受询价和报价的产品, 以及数量和价格范围。

限速: 5次/2s

限速规则：UserID

权限：读取

HTTP Requests

GET /api/v5/rfq/maker-instrument-settings

请求示例

GET /api/v5/rfq/maker-instrument-settings

请求参数

无

返回示例

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "instType": "OPTION",
            "includeALL": true,
            "data": [
                {
                    "uly": "BTC-USD",
                    "maxBlockSz": "10000",
                    "makerPxBand": "5"
                },
                {
                    "uly": "SOL-USD",
                    "maxBlockSz": "100000",
                    "makerPxBand": "15"
                }
            ]
        },
        {
            "instType": "FUTURES",
            "includeALL": false,
            "data": [
                {
                    "uly": "BTC-USD",
                    "maxBlockSz": "10000",
                    "makerPxBand": "5"
                },
                {
                    "uly": "ETH-USDT",
                    "maxBlockSz": "100000",
                    "makerPxBand": "15"
                }
            ]
        },
        {
            "instType:": "SWAP",
            "includeALL": false,
            "data": [
                {
                    "uly": "BTC-USD",
                    "maxBlockSz": "10000",
                    "makerPxBand": "5"
                },
                {
                    "uly": "ETH-USDT"
                }
            ]
        },
        {
            "instType:": "SPOT",
            "includeALL": false,
            "data": [
                {
                    "instId": "BTC-USDT"
                },
                {
                    "instId": "TRX-USDT"
                }
            ]
        }
    ]
}

返回参数

参数名	类型	描述
code	String	结果代码，`0` 表示成功
msg	String	错误信息，如果代码不为`0`，则不为空
data	Array of objects	请求返回值，包含请求结果
> instType	String	产品类别，枚举值包括`FUTURES`,`OPTION`,`SWAP`和`SPOT`
> includeAll	Boolean	是否接收该instType下所有产品。有效值为`true`或`false`。默认`false`。
> data	Array of objects	instType的元素
>> instFamily	String	交易品种 `交割/永续/期权`情况下必填
>> instId	String	产品ID，如 `BTC-USDT`。对`SPOT`产品类别有效且必须。
>> maxBlockSz	String	该种产品最大可交易数量。FUTURES, OPTION and SWAP 的单位是合约数量。SPOT的单位是交易货币。
>> makerPxBand	String	价格限制以价格精度tick为单位，以标记价格为基准。设置makerPxBand为1个tick代表: 如果买一价 > 标记价格 + 1 tick, 操作将被拦截如果买一价 < 标记价格 - 1 tick, 操作将被拦截

设置可报价产品

用于maker设置特定的接受询价和报价的产品, 以及数量和价格范围。

限速: 5次/2s

限速规则：UserID

权限：交易

HTTP Requests

POST /api/v5/rfq/maker-instrument-settings

请求示例

POST /api/v5/rfq/maker-instrument-settings
[
    {
     "instType": "OPTION",
     "data":
        [{
            "instFamily": "BTC-USD",
            "maxBlockSz": "10000",
            "makerPxBand": "5"
        },
        {
            "instFamily": "SOL-USD",
            "maxBlockSz": "100000",
            "makerPxBand": "15"
        }]
    },
    {
     "instType": "FUTURES",
     "data":
        [{
            "instFamily": "BTC-USD",
            "maxBlockSz": "10000",
            "makerPxBand": "5"
        },
        {
            "instFamily": "ETH-USDT",
            "maxBlockSz": "100000",
            "makerPxBand": "15"
        }]
    },
    {
     "instType": "SWAP",
     "data":
        [{
            "instFamily": "BTC-USD",
            "maxBlockSz": "10000",
            "makerPxBand": "5"
         },
        {
            "instFamily": "ETH-USDT"
        }]
    },
    {
    "instType": "SPOT",
     "data":
        [{
            "instId": "BTC-USDT"
         },
        {
            "instId": "TRX-USDT"
        }]
    }
]

import okx.BlockTrading as BlockTrading

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

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

blockTradingAPI = BlockTrading.BlockTradingAPI(apikey, secretkey, passphrase, False, flag)

# 设置可报价产品
data =[{
    "instType": "OPTION",
    "data": [{
            "uly": "BTC-USD",
            "maxBlockSz": "10000",
            "makerPxBand": "5"
        },
        {
            "uly": "SOL-USD",
            "maxBlockSz": "100000",
            "makerPxBand": "15"
        }
    ]
}]

result = blockTradingAPI.set_marker_instrument(
    data
)
print(result)

请求参数

参数名	类型	是否必须	描述
instType	String	是	产品类别，枚举值包括`FUTURES`,`OPTION`,`SWAP`和`SPOT`
includeAll	Boolean	否	是否接收该instType下所有产品。有效值为`true`或`false`。默认`false`。
data	Array of objects	是	instType的元素
> instFamily	String	可选	交易品种 `交割/永续/期权`情况下必填
> instId	String	可选	产品ID，如 `BTC-USDT`。对`SPOT`产品类别有效且必须。
> maxBlockSz	String	否	该种产品最大可交易数量。FUTURES, OPTION and SWAP 的单位是合约数量。SPOT的单位是交易货币。
> makerPxBand	String	否	价格限制以价格精度tick为单位，以标记价格为基准。以设置makerPxBand为1个tick为例: 如果买价 > 标记价格 + 1 tick, 操作将被拦截如果卖价 < 标记价格 - 1 tick, 操作将被拦截

返回示例

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

返回参数

参数名	类型	描述
code	String	结果代码，`0` 表示成功
msg	String	错误信息，如果代码不为`0`，则不为空
data	Array of objects	请求返回值，包含请求结果
> result	Boolean	请求结果，枚举值为`true`,`false`

重设MMP状态

重设MMP状态为无效。

限速: 5次/2s

限速规则：UserID

权限：交易

HTTP Requests

POST /api/v5/rfq/mmp-reset

请求示例

POST /api/v5/rfq/mmp-reset

import okx.BlockTrading as BlockTrading

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

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

blockTradingAPI = BlockTrading.BlockTradingAPI(apikey, secretkey, passphrase, False, flag)

# 重设MMP状态
result = blockTradingAPI.reset_mmp()
print(result)

请求参数

None

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

返回参数

参数名	类型	描述
code	String	结果代码，`0` 表示成功
msg	String	错误信息，如果代码不为`0`，则不为空
data	Array of objects	请求返回值，包含请求结果
ts	String	重设时间. Unix 时间戳的毫秒数格式，如 `1597026383085`.

设置 MMP

该接口用于设置 MMP 的配置，仅适用于大宗交易中的maker。

限速：1次/10s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/rfq/mmp-config

请求示例

POST /api/v5/rfq/mmp-config
body
{
    "timeInterval":"5000",
    "frozenInterval":"2000",
    "countLimit": "100"
}

请求参数

参数名	类型	是否必须	描述
timeInterval	String	是	时间窗口 (毫秒)。 "0" 代表不使用 MMP。最大为 600,000。
frozenInterval	String	是	冻结时间长度 (毫秒)。 "0" 代表一直冻结，直到调用 "重置 MMP 状态" 接口解冻
countLimit	String	是	尝试执行次数限制

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "frozenInterval": "2000",
            "countLimit": "100",
            "timeInterval": "5000"
        }
    ]
}

返回参数

参数名	类型	描述
timeInterval	String	时间窗口 (毫秒)
frozenInterval	String	冻结时间长度 (毫秒)
countLimit	String	尝试执行次数限制

查看 MMP 配置

该接口用于获取 MMP 的配置信息，仅适用于大宗交易中的maker。

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/rfq/mmp-config

请求示例

GET /api/v5/rfq/mmp-config

请求参数

none

返回结果

{
  "code": "0",
  "data": [
    {
      "frozenInterval": "2000",
      "mmpFrozen": true,
      "mmpFrozenUntil": "1000",
      "countLimit": "10",
      "timeInterval": "5000"
    }
  ],
  "msg": ""
}

返回参数

参数名	类型	描述
timeInterval	String	时间窗口 (毫秒)。 "0" 代表不使用 MMP。
frozenInterval	String	冻结时间长度 (毫秒)。如果为"0"，代表一直冻结，直到调用 "重置 MMP 状态" 接口解冻，且`mmpFrozenUntil`为 ""。
countLimit	String	尝试执行次数限制
mmpFrozen	Boolean	MMP 是否被触发。 `true` 或者 `false`
mmpFrozenUntil	String	如果配置了 frozenInterval 且 mmpFrozen = `true`，则为不再触发MMP时的时间窗口（单位为ms），否则为""。

报价

允许询价单指定的报价方进行报价，需要对整个询价单报价，不允许部分报价。

限速: 50次/2s

限速规则：UserID

权限：交易

HTTP Requests

POST /api/v5/rfq/create-quote

请求示例

POST /api/v5/rfq/create-quote
{
    "rfqId":"22539",
    "clQuoteId":"q001",
    "tag":"123456",
    "quoteSide":"buy",
    "anonymous": true,
    "expiresIn":"30",
    "legs":[
        {
            "px":"39450.0",
            "sz":"200000",
            "instId":"BTC-USDT-SWAP",
            "tdMode":"cross",
            "ccy":"USDT",
            "side":"buy",
            "posSide": "long"
        },
        {
            "px":"39450.0",
            "sz":"200000",
            "instId":"BTC-USDT-SWAP",
            "tdMode":"cross",
            "ccy":"USDT",
            "side":"buy",
            "posSide": "long"
        }
    ]
}

import okx.BlockTrading as BlockTrading

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

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

blockTradingAPI = BlockTrading.BlockTradingAPI(apikey, secretkey, passphrase, False, flag)

# 报价
result = blockTradingAPI.create_quote(
    rfqId="22539",
    clQuoteId="q001",
    anonymous=True,
    quoteSide="buy",
    expiresIn="30",
    legs=[
        {
            "px": "39450.0",
            "sz": "200000",
            "instId": "BTC-USDT-SWAP",
            "side": "buy"
        }
    ]
)
print(result)

请求参数

参数名	类型	是否必须	描述
rfqId	String	是	询价单ID
clQuoteId	String	否	报价单自定义ID
tag	String	否	报价单标签，与此报价单关联的大宗交易将有相同的标签。字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。
anonymous	Boolean	否	是否匿名报价，`true`表示匿名报价，`false`表示公开报价，默认值为`false`，为`true`时，即使在交易执行之后，身份也不会透露给询价方。
quoteSide	String	是	报价单方向，`buy`或者`sell`。当报价单方向为`buy`，对maker来说，执行方向与legs里的方向相同，对taker来说相反。反之同理
expiresIn	String	否	报价单的有效时长（以秒为单位）。 10到120之间的任何整数。默认值为60
legs	Array of objects	是	组合交易
> instId	String	是	产品ID
> tdMode	String	否	交易模式保证金模式：`cross`全仓 `isolated`逐仓非保证金模式：`cash`非保证金. 如未提供，tdMode 将继承系统设置的默认值：现货和合约模式 & 现货: `cash` 现货和合约模式和跨币种保证金模式下买入期权： `isolated` 其他情况: `cross`
> ccy	String	否	保证金币种，仅适用于`现货和合约模式`下的`全仓杠杆`订单在其他情况下该参数将被忽略。
> sz	String	是	委托数量
> px	String	是	委托价格
> side	String	是	报价单方向
> posSide	String	否	持仓方向买卖模式下默认为`net`。在开平仓模式下仅可选择`long`或`short`。如未指定，则处于开平仓模式下的用户始终会开新仓位。仅适用交割、永续。
> tgtCcy	String	否	委托数量的类型定义`sz`属性的单位。仅适用于 instType=`SPOT`。有效值为`base_ccy`和`quote_ccy`。未指定时，默认为`base_ccy`。

返回示例

{
    "code": "",
    "msg": "",
    "data": [
        {
            "validUntil": "1608997227834",
            "uTime": "1608267227834",
            "cTime": "1608267227834",
            "legs": [
                {
                    "px": "46000",
                    "sz": "25",
                    "instId": "BTC-USD-220114-25000-C",
                    "tdMode": "cross",
                    "ccy": "USDT",
                    "side": "sell",
                    "posSide": "long",
                    "tgtCcy": ""
                },
                {
                    "px": "4000",
                    "sz": "25",
                    "instId": "ETH-USD-220114-25000-C",
                    "tdMode": "cross",
                    "ccy": "USDT",
                    "side": "buy",
                    "posSide": "long",
                    "tgtCcy": ""
                }
            ],
            "quoteId": "25092",
            "rfqId": "18753",
            "tag": "123456",
            "quoteSide": "sell",
            "state": "active",
            "reason": "mmp_canceled",
            "clQuoteId": "",
            "clRfqId": "",
            "traderCode": "Aksha"
        }
    ]
}

返回参数

参数名	类型	描述
code	String	结果代码，0表示成功。
msg	String	错误信息，如果代码不为0，则不为空。
data	Array of objects	包含结果的对象数组
> cTime	String	报价单创建时间，Unix时间戳的毫秒数格式。
> uTime	String	报价单状态更新时间，Unix时间戳的毫秒数格式。
> state	String	报价单的状态有效值为 `active` `canceled` `pending_fill` `filled` `expired` `failed`
> reason	String	状态原因. 有效值包括 `mmp_canceled`.
> validUntil	String	报价单的过期时间，Unix时间戳的毫秒数格式。
> rfqId	String	询价单ID
> clRfqId	String	询价单自定义ID，为客户敏感信息，不会公开，对报价方返回""。
> quoteId	String	报价单ID
> clQuoteId	String	报价单自定义ID，为客户敏感信息，不会公开，对询价方返回""。
> tag	String	报价单标签，与此报价单关联的大宗交易将有相同的标签。
> traderCode	String	报价方唯一标识代码。
> quoteSide	String	报价单方向，有效值为`buy`或者`sell`。当报价单方向为`buy`，对maker来说，执行方向与legs里的方向相同，对taker来说相反。反之同理。
> legs	Array of objects	组合交易
>> instId	String	产品ID
>> tdMode	String	交易模式保证金模式：`cross`全仓 `isolated`逐仓非保证金模式：`cash`非保证金. 如未提供，tdMode 将继承系统设置的默认值：现货和合约模式 & 现货: `cash` 现货和合约模式和跨币种保证金模式下买入期权： `isolated` 其他情况: `cross`
>> ccy	String	保证金币种，仅适用于`现货和合约模式`下的`全仓杠杆`订单在其他情况下该参数将被忽略。
>> sz	String	委托数量
>> px	String	委托价格
>> side	String	腿的方向，有效值为`buy`或者`sell`。
>> posSide	String	持仓方向买卖模式下默认为`net`。如未指定，则返回""，相当于`net`。在开平仓模式下仅可选择`long`或`short`。如未指定，则返回""，对应于为交易开新仓位的方向（买入=>`long`，卖出=>`short`）。仅适用交割、永续。
>> tgtCcy	String	委托数量的类型定义`sz`属性的单位。仅适用于 instType=`SPOT`。有效值为`base_ccy`和`quote_ccy`。未指定时，默认为`base_ccy`。

取消报价单

取消一个报价单。

限速: 50次/2s

限速规则：UserID

权限：交易

HTTP Requests

POST /api/v5/rfq/cancel-quote

请求示例

POST /api/v5/rfq/cancel-quote
{
    "quoteId": "007",
    "clQuoteId":"Bond007"
}

import okx.BlockTrading as BlockTrading

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

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

blockTradingAPI = BlockTrading.BlockTradingAPI(apikey, secretkey, passphrase, False, flag)

# 取消报价单
result = blockTradingAPI.cancel_quote(
    quoteId="007",
    clQuoteId="Bond007"
)
print(result)

请求参数

参数名	类型	是否必须	描述
quoteId	String	可选	报价单ID
clQuoteId	String	可选	报价单自定义ID，字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间，当 clRfqId 和 rfqId 都传时，以 rfqId 为准。
rfqId	String	否	询价单ID

返回示例

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "quoteId":"007",
            "clQuoteId":"Bond007",
            "sCode":"0",
            "sMsg":""
        }
    ]
}

返回参数

参数名	类型	描述
code	String	结果代码，0 表示成功。
msg	String	错误信息，如果代码不为 0，则不为空。
data	Array of objects	包含结果的对象数组
> quoteId	String	报价单ID
> clQuoteId	String	询价单自定义ID
> sCode	String	事件执行结果的code，0代表成功
> sMsg	String	事件执行失败时的msg

批量取消报价单

取消一个或多个报价单，每次最多可以撤销100个订单。

限速: 2次/2s

限速规则：UserID

权限：交易

HTTP Requests

POST /api/v5/rfq/cancel-batch-quotes

请求示例

POST /api/v5/rfq/cancel-batch-quotes
{
    "quoteIds": ["1150","1151","1152"],
    "clQuoteIds": ["q1","q2","q3"]
}

import okx.BlockTrading as BlockTrading

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

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

blockTradingAPI = BlockTrading.BlockTradingAPI(apikey, secretkey, passphrase, False, flag)

# 批量取消报价单
result = blockTradingAPI.cancel_batch_quotes(
    quoteIds=["1150","1151","1152"],
    clQuoteIds=["q1","q2","q3"]
)
print(result)

请求参数

参数名	类型	是否必须	描述
quoteIds	Array of strings	可选	报价单ID
clQuoteIds	Array of strings	可选	报价单自定义ID，当 clQuoteIds 和 quoteIds 都传时，以 quoteIds 为准。

全部成功的示例

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "quoteId":"1150",
            "clQuoteId":"q1",
            "sCode":"0",
            "sMsg":""
        },
        {
            "quoteId":"1151",
            "clQuoteId":"q2",
            "sCode":"0",
            "sMsg":""
        },
        {
            "quoteId":"1152",
            "clQuoteId":"q3",
            "sCode":"0",
            "sMsg":""
        }
    ]
}

部分成功的示例

{
    "code":"2",
    "msg":"Bulk operation partially succeeded.",
    "data":[
        {
            "quoteId":"1150",
            "clQuoteId":"q1",
            "sCode":"0",
            "sMsg":""
        },
        {
            "quoteId":"1151",
            "clQuoteId":"q2",
            "sCode":"70001",
            "sMsg":"Quote does not exist."
        },
        {
            "quoteId":"1152",
            "clQuoteId":"q3",
            "sCode":"70001",
            "sMsg":"Quote does not exist."
        }
    ]
}

失败示例

{
    "code":"1",
    "msg":"Operation failed.",
    "data":[
        {
            "quoteId":"1150",
            "clQuoteId":"q1",
            "sCode":"70001",
            "sMsg":"Quote does not exist."
        },
        {
            "quoteId":"1151",
            "clQuoteId":"q2",
            "sCode":"70001",
            "sMsg":"Quote does not exist."
        },
        {
            "quoteId":"1151",
            "clQuoteId":"q3",
            "sCode":"70001",
            "sMsg":"Quote does not exist."
        }
    ]
}

返回参数

参数名	类型	描述
code	String	结果代码，0 表示成功。
msg	String	错误信息，如果代码不为 0，则不为空。
data	Array of objects	包含结果的对象数组
> quoteId	String	报价单ID
> clQuoteId	String	报价单自定义ID
> sCode	String	事件执行结果的code，0代表成功
> sMsg	String	事件执行失败时的msg

取消所有报价单

限速: 2次/2s

限速规则：UserID

权限：交易

HTTP Requests

POST /api/v5/rfq/cancel-all-quotes

请求示例

POST /api/v5/rfq/cancel-all-quotes

import okx.BlockTrading as BlockTrading

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

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

blockTradingAPI = BlockTrading.BlockTradingAPI(apikey, secretkey, passphrase, False, flag)

# 取消所有报价单
result = blockTradingAPI.cancel_all_quotes()
print(result)

请求参数

无

响应示例

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

响应参数

参数名	类型	描述
code	String	结果代码，0 表示成功。
msg	String	错误信息，如果代码不为 0，则不为空。
data	Array of objects	包含结果的对象数组
> ts	String	成功取消时间，Unix时间戳的毫秒数格式，例如 1597026383085。

倒计时全部撤单

在倒计时结束后，取消所有报价单。

限速：1次/s

限速规则：UserID

权限：交易

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

获取询价单信息

获取用户发出的或收到的询价单信息

限速: 2次/2s

限速规则：UserID

权限：读取

HTTP Requests

GET /api/v5/rfq/rfqs

请求示例

GET /api/v5/rfq/rfqs

import okx.BlockTrading as BlockTrading

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

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

blockTradingAPI = BlockTrading.BlockTradingAPI(apikey, secretkey, passphrase, False, flag)

# 获取询价单信息
result = blockTradingAPI.get_rfqs()
print(result)

请求参数

参数名	类型	是否必须	描述
rfqId	String	否	询价单ID .
clRfqId	String	否	客户询价单自定义ID，当 clRfqId 和 rfqId 都传时，以 rfqId 为准
state	String	否	询价单的状态 `active` `canceled` `pending_fill` `filled` `expired` `failed` `traded_away` `traded_away` 仅适用于报价方
beginId	String	否	请求的起始询价单ID，请求此ID之后（更新的数据）的分页内容，不包括 beginId
endId	String	否	请求的结束询价单ID，请求此ID之前（更旧的数据）的分页内容，不包括 endId
limit	String	否	返回结果的数量，最大为100，默认100条

返回示例

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "rfqId": "123456",
            "clRfqId": "",
            "tag": "123456",
            "traderCode": "VITALIK",
            "validUntil": "1650969031817",
            "allowPartialExecution": false,
            "state": "filled",
            "flowType": "",
            "counterparties": [
                "SATOSHI"
            ],
            "legs": [
                {
                    "instId": "BTC-USDT",
                    "tdMode": "cross",
                    "ccy": "USDT",
                    "side": "buy",
                    "posSide": "long",
                    "sz": "25",
                    "tgtCcy": "base_ccy"
                }
            ],
            "cTime": "1650968131817",
            "uTime": "1650968164944"
        },
        {
            "rfqId": "1234567",
            "clRfqId": "",
            "tag": "1234567",
            "traderCode": "VITALIK",
            "validUntil": "1650967623729",
            "state": "filled",
            "flowType": "",
            "counterparties": [
                "SATOSHI"
            ],
            "legs": [
                {
                    "instId": "BTC-USDT",
                    "tdMode": "cross",
                    "ccy": "USDT",
                    "side": "buy",
                    "posSide": "long",
                    "sz": "1500000",
                    "tgtCcy": "quote_ccy"
                }
            ],
            "cTime": "1650966723729",
            "uTime": "1650966816577"
        }
    ]
}

返回参数

参数名	类型	描述
code	String	结果代码，0 表示成功。
msg	String	错误信息，如果代码不为 0，则不为空。
data	Array of objects	包含结果的对象数组
> cTime	String	询价单创建时间，Unix时间戳的毫秒数格式。
> uTime	String	询价单状态更新时间，Unix时间戳的毫秒数格式。
> state	String	询价单的状态 `active` `canceled` `pending_fill` `filled` `expired` `failed` `traded_away` `traded_away` 仅适用于报价方
> counterparties	Array of srings	报价方列表
> validUntil	String	询价单的过期时间，Unix时间戳的毫秒数格式。
> clRfqId	String	询价单自定义ID，为客户敏感信息，不会公开，对报价方返回""。
> tag	String	询价单标签，与此询价单关联的大宗交易将有相同的标签。
> flowType	String	识别询价单的类型。仅适用于报价方，返回""给询价方。
> traderCode	String	询价方唯一标识代码，询价时 anonymous 设置为 `true` 时不可见
> rfqId	String	询价单ID
> allowPartialExecution	Boolean	RFQ是否可以被部分执行，如果腿的比例和原RFQ一致。有效值为`true`或`false`。未指定时，默认为`false`。
> legs	Array of objects	组合交易，每个请求最多可放置15条腿
>> instId	String	产品ID，如 "BTC-USDT-SWAP"
>> tdMode	String	交易模式保证金模式：`cross`全仓 `isolated`逐仓非保证金模式：`cash`非保证金. 如未提供，tdMode 将继承系统设置的默认值：现货和合约模式 & 现货: `cash` 现货和合约模式和跨币种保证金模式下买入期权： `isolated` 其他情况: `cross`
>> ccy	String	保证金币种，仅适用于`现货和合约模式`下的`全仓杠杆`订单在其他情况下该参数将被忽略。
>> sz	String	委托数量
>> side	String	询价单方向有效值为`buy`和`sell`。
>> posSide	String	持仓方向买卖模式下默认为`net`。如未指定，则返回""，相当于`net`。在开平仓模式下仅可选择`long`或`short`。如未指定，则返回""，对应于为交易开新仓位的方向（买入=>`long`，卖出=>`short`）。仅适用交割、永续。
>> tgtCcy	String	委托数量的类型定义`sz`属性的单位。仅适用于 instType=`SPOT`。有效值为`base_ccy`和`quote_ccy`。未指定时，默认为`base_ccy`。

获取报价单信息

获取用户发出的或收到的报价单信息

限速: 2次/2s

限速规则：UserID

权限：读取

HTTP Requests

GET /api/v5/rfq/quotes

请求示例

GET /api/v5/rfq/quotes

import okx.BlockTrading as BlockTrading

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

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

blockTradingAPI = BlockTrading.BlockTradingAPI(apikey, secretkey, passphrase, False, flag)

# 获取报价单信息
result = blockTradingAPI.get_quotes()
print(result)

请求参数

参数名	类型	是否必须	描述
rfqId	String	否	询价单ID
clRfqId	String	否	询价单自定义ID，当 clRfqId 和 rfqId 都传时，以 rfqId 为准。
quoteId	String	否	报价单ID
clQuoteId	String	否	报价单自定义ID，当 clRfqId 和 rfqId 都传时，以 rfqId 为准。
state	String	否	报价单的状态有效值为 `active` `canceled` `pending_fill` `filled` `expired` `failed`
beginId	String	否	请求的起始报价单ID，请求此ID之后（更新的数据）的分页内容，不包括 beginId
endId	String	否	请求的结束报价单ID，请求此ID之前（更旧的数据）的分页内容，不包括 endId
limit	String	否	返回结果的数量，最大为100，默认100条

返回示例

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "validUntil":"1608997227834",
            "uTime":"1608267227834",
            "cTime":"1608267227834",
            "legs":[
                {
                    "px":"46000",
                    "sz":"25",
                    "instId":"BTC-USD-220114-25000-C",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "side":"sell",
                    "posSide": "long",
                    "tgtCcy":""
                },
                {
                    "px":"45000",
                    "sz":"25",
                    "instId":"BTC-USDT",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "side":"buy",
                    "posSide": "long",
                    "tgtCcy":"base_ccy"
                }
            ],
            "quoteId":"25092",
            "rfqId":"18753",
            "quoteSide":"sell",
            "state":"canceled",
            "reason":"mmp_canceled",
            "clQuoteId":"cq001",
            "clRfqId":"cr001",
            "tag":"123456",
            "traderCode":"Trader1"
        }
    ]
}

返回参数

参数名	类型	描述
code	String	结果代码，0 表示成功。
msg	String	错误信息，如果代码不为 0，则不为空。
data	Array of objects	包含结果的数组
> cTime	String	报价单创建时间，Unix时间戳的毫秒数格式
> uTime	String	报价单状态更新时间，Unix时间戳的毫秒数格式。
> state	String	报价单的状态 `active` `canceled` `pending_fill` `filled` `expired` `failed`
> reason	String	状态原因. 有效值包括 `mmp_canceled`.
> validUntil	String	报价单的过期时间，Unix时间戳的毫秒数格式。
> rfqId	String	询价单ID
> clRfqId	String	询价单自定义ID，为客户敏感信息，不会公开，对报价方返回""。
> quoteId	String	报价单ID
> clQuoteId	String	报价单自定义ID，为客户敏感信息，不会公开，对询价方返回""。
> tag	String	报价单标签，与此报价单关联的大宗交易将有相同的标签。
> traderCode	String	报价方唯一标识代码，报价时 Anonymous 设置为 `True` 时不可见。
> quoteSide	String	报价单方向，`buy`或者`sell`。当报价单方向为`buy`，对maker来说，执行方向与legs里的方向相同，对taker来说相反。反之同理
> legs	Array of objects	组合交易
>> instId	String	产品ID
>> tdMode	String	交易模式保证金模式：`cross`全仓 `isolated`逐仓非保证金模式：`cash`非保证金. 如未提供，tdMode 将继承系统设置的默认值：现货和合约模式 & 现货: `cash` 现货和合约模式和跨币种保证金模式下买入期权： `isolated` 其他情况: `cross`
>> ccy	String	保证金币种，仅适用于`现货和合约模式`下的`全仓杠杆`订单在其他情况下该参数将被忽略。
>> sz	String	委托数量
>> px	String	委托价格.
>> side	String	报价单方向
>> posSide	String	持仓方向买卖模式下默认为`net`。如未指定，则返回""，相当于`net`。在开平仓模式下仅可选择`long`或`short`。如未指定，则返回""，对应于为交易开新仓位的方向（买入=>`long`，卖出=>`short`）。仅适用交割、永续。
>> tgtCcy	String	委托数量的类型定义`sz`属性的单位。仅适用于 instType=`SPOT`。有效值为`base_ccy`和`quote_ccy`。未指定时，默认为`base_ccy`。

获取大宗交易信息

获取该用户大宗交易成交信息

限速: 5次/2s

限速规则：UserID

权限：读取

HTTP Requests

GET /api/v5/rfq/trades

请求示例

GET /api/v5/rfq/trades

import okx.BlockTrading as BlockTrading

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

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

blockTradingAPI = BlockTrading.BlockTradingAPI(apikey, secretkey, passphrase, False, flag)

# 获取大宗交易信息
result = blockTradingAPI.get_trades()
print(result)

请求参数

参数名	类型	是否必须	描述
rfqId	String	否	询价单ID
clRfqId	String	否	由用户设置的询价单ID. 如果 `clRfqId` 和 `rfqId` 都通过了，rfqId 将被视为主要
quoteId	String	否	报价单ID
blockTdId	String	否	大宗交易ID
clQuoteId	String	否	由用户设置的报价单ID。如果同时传递了 `clQuoteId` 和 `quoteId`，则 quoteId 将被视为主要标识符
beginId	String	否	请求的起始大宗交易ID，请求此ID之后（更新的数据）的分页内容，不包括 beginId
endId	String	否	请求的结束大宗交易ID，请求此ID之前（更旧的数据）的分页内容，不包括 endId
beginTs	String	否	用开始时间戳筛选交易执行时间（UTC时区）。Unix时间戳的毫秒数格式，例如 1597026383085。
endTs	String	否	用结束时间戳筛选交易执行时间（UTC时区）。Unix时间戳的毫秒数格式，例如 1597026383085。
limit	String	否	返回结果的数量，最大为100，默认100条。如果请求范围内的交易数量大于100，则返回该范围内最近的100笔交易。
isSuccessful	Boolean	否	交易是否成功。 `true`: 成功，默认值。 `false`: 未成功。

返回示例

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "rfqId": "123456",
            "clRfqId": "",
            "quoteId": "0T5342O",
            "clQuoteId": "",
            "blockTdId": "439127542058958848",
            "tag": "123456",
            "isSuccessful": true,
            "errorCode": "",
            "legs": [
                {
                    "instId": "BTC-USDT",
                    "side": "sell",
                    "sz": "0.666",
                    "px": "100",
                    "tradeId": "439127542058958850",
                    "fee": "-0.0333",
                    "feeCcy": "USDT"
                }
            ],
            "cTime": "1650968164900",
            "tTraderCode": "SATS",
            "mTraderCode": "MIKE"
        },
        {
            "rfqId": "1234567",
            "clRfqId": "",
            "quoteId": "0T533T0",
            "clQuoteId": "",
            "blockTdId": "439121886014849024",
            "tag": "123456",
            "isSuccessful": true,
            "errorCode": "",
            "legs": [
                {
                    "instId": "BTC-USDT",
                    "side": "sell",
                    "sz": "0.532",
                    "px": "100",
                    "tradeId": "439121886014849026",
                    "fee": "-0.0266",
                    "feeCcy": "USDT"
                }
            ],
            "cTime": "1650966816550",
            "tTraderCode": "SATS",
            "mTraderCode": "MIKE"
        }
    ]
}

返回参数

参数名	类型	描述
code	String	结果代码，0 表示成功。
msg	String	错误信息，如果代码不为 0，则不为空。
data	Array of objects	包含结果的对象数组
> cTime	String	执行创建的时间，Unix时间戳的毫秒数格式。
> rfqId	String	询价单ID
> clRfqId	String	询价单自定义ID，为客户敏感信息，不会公开，对报价方返回""。
> quoteId	String	报价单ID
> clQuoteId	String	报价单自定义ID，为客户敏感信息，不会公开，对询价方返回""。
> blockTdId	String	大宗交易ID
> tag	String	交易标签，大宗交易将有与其对应的询价单或报价单相同的标签。
> tTraderCode	String	询价方唯一标识代码，询价时 anonymous 设置为 `true` 时不可见
> mTraderCode	String	报价方唯一标识代码。报价时 anonymous 设置为 `true` 时不可见
> isSuccessful	Boolean	交易是否成功
> errorCode	String	未成功交易的错误码。对于成功交易为 ""。
> legs	Array of objects	组合交易
>> instId	String	产品ID
>> px	String	成交价格
>> sz	String	成交数量
>> side	String	询价单方向，buy 或者 sell。
>> fee	String	手续费，正数代表平台返佣，负数代表平台扣除
>> feeCcy	String	手续费币种
>> tradeId	String	最新的成交Id

获取大宗交易所有产品行情信息

获取最近24小时大宗交易量

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/block-tickers

请求示例

GET /api/v5/market/block-tickers?instType=SWAP

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取大宗交易所有产品行情信息
result = marketDataAPI.get_block_tickers(
    instType="SPOT"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instType	String	是	产品类型 `SPOT`：币币 `SWAP`：永续合约 `FUTURES`：交割合约 `OPTION`：期权
uly	String	否	标的指数适用于`交割/永续/期权`，如 `BTC-USD`
instFamily	String	否	交易品种适用于`交割/永续/期权`，如 `BTC-USD`

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
     {
        "instType":"SWAP",
        "instId":"LTC-USD-SWAP",
        "volCcy24h":"2222",
        "vol24h":"2222",
        "ts":"1597026383085"
     },
     {
        "instType":"SWAP",
        "instId":"BTC-USD-SWAP",
        "volCcy24h":"2222",
        "vol24h":"2222",
        "ts":"1597026383085"
    }
  ]
}

返回参数

参数名	类型	描述
instId	String	产品ID
instType	String	产品类型
volCcy24h	String	24小时成交量，以`币`为单位如果是`衍生品`合约，数值为交易货币的数量。如果是`币币/币币杠杆`，数值为计价货币的数量。
vol24h	String	24小时成交量，以`张`为单位如果是`衍生品`合约，数值为合约的张数。如果是`币币/币币杠杆`，数值为交易货币的数量。
ts	String	数据产生时间，Unix时间戳的毫秒数格式，如 `1597026383085`

获取大宗交易单个产品行情信息

获取最近24小时大宗交易量

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/block-ticker

请求示例

GET /api/v5/market/block-ticker?instId=BTC-USD-SWAP

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取大宗交易单个产品行情信息
result = marketDataAPI.get_block_ticker(
    instId="BTC-USDT"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 `BTC-USD-SWAP`

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
     {
        "instType":"SWAP",
        "instId":"LTC-USD-SWAP",
        "volCcy24h":"2222",
        "vol24h":"2222",
        "ts":"1597026383085"
     }
  ]
}

返回参数

参数名	类型	描述
instId	String	产品ID
instType	String	产品类型
volCcy24h	String	24小时成交量，以`币`为单位如果是`衍生品`合约，数值为交易货币的数量。如果是`币币/币币杠杆`，数值为计价货币的数量。
vol24h	String	24小时成交量，以`张`为单位如果是`衍生品`合约，数值为合约的张数。如果是`币币/币币杠杆`，数值为交易货币的数量。
ts	String	数据产生时间，Unix时间戳的毫秒数格式，如 `1597026383085`

获取大宗交易公共多腿成交数据

获取已经执行的大宗交易。数据将在大宗交易执行15分钟后更新。

限速: 5次/2s

限速规则：IP

权限：读取

HTTP Requests

GET /api/v5/rfq/public-trades

请求示例

GET /api/v5/rfq/public-trades

import okx.BlockTrading as BlockTrading

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

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

blockTradingAPI = BlockTrading.BlockTradingAPI(apikey, secretkey, passphrase, False, flag)

# 获取大宗交易公共成交数据
result = blockTradingAPI.get_public_trades()
print(result)

请求参数

参数名	类型	是否必须	描述
beginId	String	否	请求的起始大宗交易ID，请求此ID之后（更新的数据）的分页内容，不包括 beginId
endId	String	否	请求的结束大宗交易ID，请求此ID之前（更旧的数据）的分页内容，不包括 endId
limit	String	否	返回结果的数量，最大为100，默认100条

返回示例

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "blockTdId": "439161457415012352",
            "legs": [
                {
                    "instId": "BTC-USD-210826",
                    "side": "sell",
                    "sz": "100",
                    "px": "11000",
                    "tradeId": "439161457415012354"
                },
                {
                    "instId": "BTC-USD-SWAP",
                    "side": "sell",
                    "sz": "100",
                    "px": "50",
                    "tradeId": "439161457415012355"
                },
                {
                    "instId": "BTC-USDT",
                    "side": "buy",
                    "sz": "0.1", //for public feed, spot "sz" is in baseccy
                    "px": "10.1",
                    "tradeId": "439161457415012356"
                },
                {
                    "instId": "BTC-USD-210326-60000-C",
                    "side": "buy",
                    "sz": "200",
                    "px": "0.008",
                    "tradeId": "439161457415012357"
                },
                {
                    "instId": "BTC-USD-220930-5000-P",
                    "side": "sell",
                    "sz": "200",
                    "px": "0.008",
                    "tradeId": "439161457415012360"
                },
                {
                    "instId": "BTC-USD-220930-10000-C",
                    "side": "sell",
                    "sz": "200",
                    "px": "0.008",
                    "tradeId": "439161457415012361"
                },
                {
                    "instId": "BTC-USD-220930-10000-P",
                    "side": "sell",
                    "sz": "200",
                    "px": "0.008",
                    "tradeId": "439161457415012362"
                },
                {
                    "instId": "ETH-USD-220624-100100-C",
                    "side": "sell",
                    "sz": "100",
                    "px": "0.008",
                    "tradeId": "439161457415012363"
                }
            ],
            "strategy":"CALL_CALENDAR_SPREAD",
            "cTime": "1650976251241"
        }
    ]
}

返回参数

参数名	类型	描述
code	String	结果代码，0 表示成功。
msg	String	错误信息，如果代码不为 0，则不为空。
data	Array of objects	包含结果的对象数组.
> strategy	String	期权策略, 如 `CALL_CALENDAR_SPREAD`
> cTime	String	执行创建的时间，Unix时间戳的毫秒数格式。
> blockTdId	String	大宗交易ID
> legs	Array of objects	组合交易
>> instId	String	产品ID
>> px	String	成交价格
>> sz	String	成交数量
>> side	String	询价单方向，从 Taker的视角看
>> tradeId	String	最新成交ID

获取大宗交易公共单腿成交数据

查询市场上交易产品维度的大宗交易公共成交数据，根据 tradeId 倒序排序。数据将在大宗交易执行15分钟后更新。

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/public/block-trades

请求示例

GET /api/v5/public/block-trades?instId=BTC-USDT

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 `BTC-USDT`

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "fillVol": "5",
            "fwdPx": "26857.86591585",
            "idxPx": "26889.7",
            "instId": "BTC-USD-231013-22000-P",
            "markPx": "0.0000000000000001",
            "px": "0.0026",
            "side": "buy",
            "sz": "1",
            "tradeId": "632960608383700997",
            "ts": "1697181568974"
        }
    ]
}

返回参数

参数名	类型	描述
instId	String	产品ID
tradeId	String	成交ID
px	String	成交价格
sz	String	成交数量
side	String	成交方向 `buy`：买 `sell`：卖
fillVol	String	成交时的隐含波动率仅适用于 `期权`
fwdPx	String	成交时的远期价格仅适用于 `期权`
idxPx	String	成交时的指数价格适用于 `交割`, `永续`, `期权`
markPx	String	成交时的标记价格适用于 `交割`, `永续`, `期权`
ts	String	成交时间，Unix时间戳的毫秒数格式，如`1597026383085`

WebSocket 私有频道

询价频道

获取用户自身发送或接收的询价信息。每当用户自身发送或接收询价时，数据都将被推送。

服务地址

/ws/v5/business (需要登录)

请求示例

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

请求参数

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

成功返回示例

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

失败返回示例

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

返回参数

参数名	类型	是否必填	描述
event	String	是	操作 `subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名 `rfqs`
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket连接ID

推送示例

{
    "arg":{
        "channel":"rfqs",
        "uid": "77982378738415879"
    },
    "data":[
        {
            "cTime":"1611033737572",
            "uTime":"1611033737572",
            "traderCode":"DSK2",
            "rfqId":"22534",
            "clRfqId":"",
            "tag":"123456",
            "state":"active",
            "flowType": "",
            "validUntil":"1611033857557",
            "allowPartialExecution": false,
            "counterparties":[
                "DSK4",
                "DSK5"
            ],
            "legs":[
                {
                    "instId":"BTCUSD-211208-36000-C",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "sz":"25.0",
                    "side":"buy",
                    "posSide": "long",
                    "tgtCcy":""
                },
                {
                    "instId":"ETHUSD-211208-45000-C",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "sz":"25.0",
                    "side":"sell",
                    "posSide": "long",
                    "tgtCcy":""
                }
            ]
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> uid	String	用户标识
data	Array	订阅的数据
> cTime	String	询价单创建时间，Unix时间戳的毫秒数格式。
> uTime	String	询价单状态更新时间，Unix时间戳的毫秒数格式。
> state	String	询价单的状态有效值有 `active` `canceled` `filled` `expired` `traded_away` `failed` `traded_away` 仅适用于报价方。
> counterparties	Array of Strings	报价方列表
> validUntil	String	询价单的过期时间，Unix时间戳的毫秒数格式。
> clRfqId	String	询价单自定义ID，为客户敏感信息，不会公开，对报价方返回""。
> tag	String	询价单标签，与此询价单关联的大宗交易将有相同的标签。
> flowType	String	识别询价单的类型。仅适用于报价方，返回""给询价方。
> traderCode	String	询价方唯一标识代码，询价时 Anonymous 设置为 `True` 时不可见
> rfqId	String	询价单ID
> allowPartialExecution	Boolean	RFQ是否可以被部分执行，如果腿的比例和原RFQ一致。>有效值为`true`或`false`。
> legs	Array of objects	组合交易
>> instId	String	产品ID
>> tdMode	String	交易模式保证金模式：`cross`全仓 `isolated`逐仓非保证金模式：`cash`非保证金. 如未提供，tdMode 将继承系统设置的默认值：现货和合约模式 & 现货: `cash` 现货和合约模式和跨币种保证金模式下买入期权： `isolated` 其他情况: `cross`
>> ccy	String	保证金币种，仅适用于`现货和合约模式`下的`全仓杠杆`订单在其他情况下该参数将被忽略。
>> sz	String	委托数量
>> side	String	询价单方向
>> posSide	String	持仓方向买卖模式下默认为`net`。如未指定，则返回""，相当于`net`。在开平仓模式下仅可选择`long`或`short`。如未指定，则返回""，对应于为交易开新仓位的方向（买入=>`long`，卖出=>`short`）。仅适用交割、永续。
>> tgtCcy	String	委托数量的类型定义`sz`属性的单位。仅适用于 instType=`SPOT`。有效值为`base_ccy`和`quote_ccy`。未指定时，默认为`base_ccy`。

报价频道

获取用户自身发送或接收的报价信息。每当用户自身发送或接收报价时，数据都将被推送。

服务地址

/ws/v5/business (需要登录)

请求示例

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

请求参数

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

成功返回示例

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

失败返回示例

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

返回参数

参数名	类型	是否必填	描述
event	String	是	操作 `subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名 `quotes`
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket连接ID

推送示例

{
    "arg":{
        "channel":"quotes",
        "uid": "77982378738415879"
    },
    "data":[
        {
            "validUntil":"1608997227854",
            "uTime":"1608267227834",
            "cTime":"1608267227834",
            "legs":[
                {
                    "px":"0.0023",
                    "sz":"25.0",
                    "instId":"BTC-USD-220114-25000-C",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "side":"sell",
                    "posSide": "long",
                    "tgtCcy":""

                },
                {
                    "px":"0.0045",
                    "sz":"25",
                    "instId":"BTC-USD-220114-35000-C",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "side":"buy",
                    "posSide": "long",
                    "tgtCcy":""

                }
            ],
            "quoteId":"25092",
            "rfqId":"18753",
            "tag":"123456",
            "traderCode":"SATS",
            "quoteSide":"sell",
            "state":"canceled",
            "reason":"mmp_canceled",
            "clQuoteId":""
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> uid	String	账户ID，账户uid和app上的一致
data	Array	订阅的数据
> cTime	String	报价单创建时间，Unix时间戳的毫秒数格式。
> uTime	String	报价单状态更新时间，Unix时间戳的毫秒数格式。
> state	String	报价单的状态有效值为 `active` `canceled` `filled` `expired` `failed`
> reason	String	状态原因,有效值包括`mmp_canceled`
> validUntil	String	报价单的过期时间，Unix时间戳的毫秒数格式。
> rfqId	String	询价单ID
> clRfqId	String	询价单自定义ID，为客户敏感信息，不会公开，对报价方返回""。
> quoteId	String	报价单ID
> clQuoteId	String	报价单自定义ID，为客户敏感信息，不会公开，对询价方返回""。
> tag	String	报价单标签，与此报价单关联的大宗交易将有相同的标签。
> traderCode	String	报价方唯一标识代码，报价时 Anonymous 设置为 `True` 时不可见。
> quoteSide	String	报价单方向，`buy`或者`sell`。当报价单方向为`buy`，对maker来说，执行方向与legs里的方向相同，对taker来说相反。反之同理。
> legs	Array of objects	组合交易
>> instId	String	产品ID
>> tdMode	String	交易模式保证金模式：`cross`全仓 `isolated`逐仓非保证金模式：`cash`非保证金. 如未提供，tdMode 将继承系统设置的默认值：现货和合约模式 & 现货: `cash` 现货和合约模式和跨币种保证金模式下买入期权： `isolated` 其他情况: `cross`
>> ccy	String	保证金币种，仅适用于`现货和合约模式`下的`全仓杠杆`订单在其他情况下该参数将被忽略。
>> sz	String	委托数量
>> px	String	委托价格
>> side	String	报价单方向
>> posSide	String	持仓方向买卖模式下默认为`net`。如未指定，则返回""，相当于`net`。在开平仓模式下仅可选择`long`或`short`。如未指定，则返回""，对应于为交易开新仓位的方向（买入=>`long`，卖出=>`short`）。仅适用交割、永续。
>> tgtCcy	String	委托数量的类型定义`sz`属性的单位。仅适用于 instType=`SPOT`。有效值为`base_ccy`和`quote_ccy`。未指定时，默认为`base_ccy`。

大宗交易频道

获取用户自身的大宗交易信息。同一大宗交易中的所有腿都包含在同一更新中。只要用户自身作为交易对手进行大宗交易，数据都将被推送。

服务地址

/ws/v5/business (需要登录)

请求示例

{
  "op": "subscribe",
  "args": [
    {
      "channel": "struc-block-trades"
    }
  ]
}

请求参数

参数名	类型	是否必填	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `struc-block-trades`

成功返回示例

{
  "event": "subscribe",
  "arg": {
    "channel": "struc-block-trades"
  },
  "connId": "a4d3ae55"
}

失败返回示例

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

返回参数

参数名	类型	是否必填	描述
event	String	是	操作 `subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名 `struc-block-trades`
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket连接ID

推送示例

{
    "arg":{
        "channel":"struc-block-trades",
        "uid": "77982378738415879"
    },
    "data":[
        {
            "cTime":"1608267227834",
            "rfqId":"18753",
            "clRfqId":"",
            "quoteId":"25092",
            "clQuoteId":"",
            "blockTdId":"180184",
            "tag":"123456",
            "tTraderCode":"ANAND",
            "mTraderCode":"WAGMI",
            "isSuccessful": true,
            "errorCode": "",
            "legs":[
                {
                    "px":"0.0023",
                    "sz":"25.0",
                    "instId":"BTC-USD-20220630-60000-C",
                    "side":"sell",
                    "fee":"0.1001",
                    "feeCcy":"BTC",
                    "tradeId":"10211",
                    "tgtCcy":""

                },
                {
                    "px":"0.0033",
                    "sz":"25",
                    "instId":"BTC-USD-20220630-50000-C",
                    "side":"buy",
                    "fee":"0.1001",
                    "feeCcy":"BTC",
                    "tradeId":"10212",
                    "tgtCcy":""

                }
            ]
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> uid	String	用户标识
data	Array	订阅的数据
> cTime	String	执行创建的时间戳，Unix 时间戳格式，以毫秒为单位。
> rfqId	String	RFQ ID.
> clRfqId	String	由用户设置的 RFQ ID。此属性被视为客户端敏感信息。不会暴露给 Maker，只返回空字符串“”给 Maker。
> quoteId	String	Quote ID.
> clQuoteId	String	由用户设置的 Quote ID。此属性被视为客户端敏感信息。不会暴露给 Taker，只为 Taker 返回空字符串“”。
> blockTdId	String	大宗交易ID
> tag	String	交易标签，大宗交易将有与其对应的询价单或报价单相同的标签。
> tTraderCode	String	报价方唯一标识代码。询价时 Anonymous 设置为 `True` 时不可见。
> mTraderCode	String	询价方唯一标识代码。报价时 Anonymous 设置为 `True` 时不可见。
> isSuccessful	Boolean	交易是否成功
> errorCode	String	未成功交易的错误码。对于成功交易为 ""。
> legs	Array of objects	组合交易
>> instId	String	产品ID
>> px	String	成交价格
>> sz	String	成交数量
>> side	String	询价单方向
>> tgtCcy	String	委托数量的类型定义`sz`属性的单位。仅适用于 instType=`SPOT`。有效值为`base_ccy`和`quote_ccy`。未指定时，默认为`base_ccy`。
>> fee	String	手续费，正数代表平台返佣，负数代表平台扣除。
>> feeCcy	String	手续费币种
>> tradeId	String	最新成交Id

WebSocket 公共频道

公共大宗交易频道

获取欧易的最新大宗交易信息。同一大宗交易中的所有腿都包含在同一更新中。数据将在大宗交易执行15分钟后被推送。

URL Path

/ws/v5/business

请求示例

{
  "op": "subscribe",
  "args": [
    {
      "channel": "public-struc-block-trades"
    }
  ]
}

请求参数

参数名	类型	是否必填	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `public-struc-block-trades`

成功返回示例

{
  "event": "subscribe",
  "arg": {
    "channel": "public-struc-block-trades"
  },
  "connId": "a4d3ae55"
}

失败返回示例

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"public-struc-block-trades\""}]}",
  "connId": "a4d3ae55"
}

返回参数

参数名	类型	是否必填	描述
event	String	是	操作 `subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名 `public-struc-block-trades`
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket连接ID

推送示例

{
    "arg":{
        "channel":"public-struc-block-trades"
    },
    "data":[
        {

            "cTime":"1608267227834",
            "blockTdId":"1802896",
            "legs":[
                {
                    "px":"0.323",
                    "sz":"25.0",
                    "instId":"BTC-USD-20220114-13250-C",
                    "side":"sell",
                    "tradeId":"15102"
                },
                {
                    "px":"0.666",
                    "sz":"25",
                    "instId":"BTC-USD-20220114-21125-C",
                    "side":"buy",
                    "tradeId":"15103"
                }
            ]
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
data	Array	订阅的数据
> cTime	String	执行创建的时间戳，Unix 时间戳格式，以毫秒为单位。
> blockTdId	String	大宗交易ID
> legs	Array of objects	组合交易
>> instId	String	产品名Id
>> px	String	成交价格
>> sz	String	成交数量
>> side	String	询价单方向，从 Taker的视角看
>> tradeId	String	最新成交Id

公共大宗交易单腿交易频道

获取欧易的最新大宗交易单腿交易信息。大宗交易中的每条腿都在单独的更新中推送。数据将在大宗交易执行15分钟后被推送。

URL Path

/ws/v5/business

请求示例

{
  "op": "subscribe",
  "args": [
    {
      "channel": "public-block-trades",
      "instId": "BTC-USDT-SWAP"
    }
  ]
}

请求参数

参数名	类型	是否必填	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `public-block-trades`
> instId	String	是	产品 ID, 如 `BTC-USDT-SWAP`

成功返回示例

{
  "event": "subscribe",
  "arg": {
    "channel": "public-block-trades",
    "instId": "BTC-USDT-SWAP"
  },
  "connId": "a4d3ae55"
}

失败返回示例

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"args\":[{ \"channel\" : \"public-block-trades\""}]}",
  "connId": "a4d3ae55"
}

返回参数

参数名	类型	是否必需	描述
event	String	是	操作 `subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名 `public-block-trades`
> instId	String	是	产品 ID, 如 `BTC-USDT-SWAP`
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket连接ID

推送示例

{
   "arg":{
      "channel":"public-block-trades",
      "instId":"BTC-USD-231020-5000-P"
   },
   "data":[
      {
         "fillVol":"5",
         "fwdPx":"26808.16",
         "idxPx":"27222.5",
         "instId":"BTC-USD-231020-5000-P",
         "markPx":"0.0022406326071111",
         "px":"0.0048",
         "side":"buy",
         "sz":"1",
         "tradeId":"633971452580106242",
         "ts":"1697422572972"
      }
   ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品 ID, 如 `BTC-USDT-SWAP`
data	Array	公共大宗交易单腿交易信息
> instId	String	产品 ID, 如 `BTC-USDT-SWAP`
> tradeId	String	交易 ID, 由柜台提供.
> px	String	该单腿交易价格.
> sz	String	交易数量.
> side	String	交易方向, buy, sell, 从taker角度看.
> fillVol	String	成交时的隐含波动率仅适用于 `期权`
> fwdPx	String	成交时的远期价格仅适用于 `期权`
> idxPx	String	成交时的指数价格适用于 `交割`, `永续`, `期权`
> markPx	String	成交时的标记价格适用于 `交割`, `永续`, `期权`
> ts	String	成交时间, 时间戳格式，以毫秒为单位. 如 1597026383085.

大宗交易行情频道

获取最近24小时大宗交易量

当发生成交事件时触发推送，此外，也会根据订阅维度每隔5分钟推送一次

服务地址

/ws/v5/business

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "block-tickers",
        "instId": "BTC-USDT"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `block-tickers`
> instId	String	是	产品ID

成功返回示例

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

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"block-tickers\", \"instId\" : \"LTC-USD-200327\"}]}",
    "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
    "arg": {
        "channel": "block-tickers"
    },
    "data": [
        {
            "instType": "SWAP",
            "instId": "LTC-USD-SWAP",
            "volCcy24h": "0",
            "vol24h": "0",
            "ts": "1597026383085"
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
data	Array	订阅的数据
> instId	String	产品ID
> instType	String	产品类型
> volCcy24h	String	24小时成交量，以`币`为单位如果是`衍生品`合约，数值为交易货币的数量。如果是`币币/币币杠杆`，数值为计价货币的数量。
> vol24h	String	24小时成交量，以`张`为单位如果是`衍生品`合约，数值为合约的张数。如果是`币币/币币杠杆`，数值为交易货币的数量。
> ts	String	数据产生时间，Unix时间戳的毫秒数格式，如 `1597026383085`

价差交易

介绍

基本概念

价差（Spread） - 做多一种产品并同时做空数量等价的另一种相关产品，形成具有两条风险互相抵消的腿的交易
订单簿（Order-book） - 一种或一组交易产品的报价集合。每个报价都包含一个或一组定义的产品、相关数量以及Maker(报价者)愿意交易的价格。然后，Taker(接受者)可以立即消耗这些报价，直至订单簿上列出的全部数量。价差交易挂单限额为所有价差挂单合计不超过500个。

基本工作流程

Nitro Spreads 以熟悉的中央限价订单簿 (CLOB) 概念为中心：

Spreads里包含的产品来自OKX交易所，交易之后也在OKX交易所进行清算和结算。
任何人都可以充当“Taker”，消耗现有的剩余订单，或“Maker”，其订单被消耗。
交易在订单被匹配时发生，之后它们被发送到 OKX 进行清算和结算。

简单来说，Nitro Spreads 工作流程是

Maker 在 Spread 的订单簿上设置限价订单。
Taker通过限价单消耗一个resting Order。
被匹配的订单被发送去清算和结算。
Taker和Maker收到交易成功或拒绝的确认
所有用户都会收到成功结算和清算交易的通知，除去涉及的交易双方以交易方向 (买入或卖出) 等信息。

Nitro Spreads 的主要方面：

所有价差都有可公开访问的中央限价订单簿 (CLOB)。
Spreads的可用性由OKX决定。通常，这些Spreads包括同一标的下（例如“BTC/USDT”或“ETH/USDC”）中 delta one 衍生品（交割和永续）和现货的所有可能组合。
部分成交和多个订单可以作为单笔交易的一部分。
交易对手方不是任由用户选择的。任何人都可以参与所有Spread的订单簿，有效地与更广泛的市场进行交易。
整个过程保持匿名，所有订单和交易均在匿名的基础上进行。
用户可以灵活地在订单簿的买卖双方下多个订单，从而实现阶梯式配置。

全面的 API 工作流程

当用户的订单被另一个订单执行时，用户将承担Maker的角色。当用户提交的订单与订单簿中的现有订单相匹配时，他们就会成为 Taker

获取可用Spreads

要检索在 OKX 上交易的所有可用Spreads，您应该向 GET /api/v5/sprd/spreads 发出请求

检索您的订单

要在 OKX 上检索您的订单，您应该向 GET /api/v5/sprd/order 发出请求。

检索您的交易

要检索您在 OKX 上的交易，您应该向 GET /api/v5/sprd/trades 发出请求。

提交订单

要向某个Spread 的订单簿提交订单，您应该请求 POST /api/v5/sprd/order 。

Spread状态

Spread 的生命周期中存在三种不同的状态：live，suspend，和 expired:

live: 在 Nitro Spread 上活跃交易的Spreads
suspend：其中至少一条腿被暂停，另一条在 OKX 订单簿交易所处于活跃或暂停状态的价差；或标的工具仍在 OKX 订单簿交易所中存在但已从 Nitro Spread 中移除的Spread
expired：至少一条腿在 OKX 订单簿交易所到期的Spread

给定每条腿的状态以及 Nitro Spreads 上的Spread状态（除了在 Nitro Spread上退市的情况），所有可能Spread状态的情况请参考下表：

交易产品A	交易产品B	Spread状态
Live	Live	Live
Suspend	Live	Suspend
Live	Suspend	Suspend
Suspend	Suspend	Suspend
Expired	Live	Expired
Live	Expired	Expired
Suspend	Expired	Expired
Expired	Suspend	Expired
Expired	Expired	Expired

交易生命周期

为了进行交易，需要在价差撮合交易中匹配两个订单。通过订阅 sprd-ordersWebSocket 通道，您可以获得有关订单状态的信息并确定它是否已达到最终状态。通道中的state值表示订单的当前状态。

如果状态为live 或 partially_filled，则意味着订单仍有未达最终状态（filled或canceled）数量，创建者或其他用户仍可能可以对其执行操作。
另一方面，如果状态为canceled或filled，创建者或任何其他用户将无法对此订单执行任何操作。

请密切跟踪以下属性：sz（数量）、pendingFillSz（待完成数量）、canceledSz（被取消数量）和 accFillSz（累积完成数量）。这些属性提供了有关订单状态和进展的重要信息。

用户的订单状态

通过订阅 sprd-ordersWebSocket 频道，用户可以跟踪他们的订单状态。

提交订单后，无论是 Maker 还是 Taker，用户都会通过订单 WebSocket 频道道收到订单更新消息。该消息将指示订单的state == live。
订单成交和结算是异步的。当订单已成交但还没结算，用户将收到pendingSettleSz>0，fillSz == ""的订单更新消息
如果订单已部分成交且仍有待处理数量，用户将收到state == partially_filled 的订单更新消息
如果订单完全成交，用户将收到state == filled的订单更新消息
如果订单未完全消耗，但已达到最终状态，用户将收到state == canceled的订单更新消息。
如果订单的某个部分被拒绝，用户会收到更新的订单更新，其中包含更新的 canceledSz 和 pendingFillSz，以及与错误对应的code和msg。

用户的交易状态

通过订阅 sprd-tradesWebSocket 频道，用户可以跟踪他们的交易状态。 1. 一笔已执行的交易在OKX上进行清算结算后，即为最终交易。 2. 对于成功清算的交易，用户会收到一条 WebSocket 消息，其中的state表示filled。 3. 在交易清算不成功的情况下，用户会收到一条交易更新消息，state反映为rejected。 4. 如果交易state为rejected，交易更新消息还将包含错误代码code和解释拒绝原因的相应错误消息 msg。

所有交易

所有用户都能够接收通过 OKX Nitro Spread 产品发生的所有交易的更新。请务必注意，OKX Nitro Spreads 不会披露有关交易双方及交易方向（买入或卖出）的信息。

用户可以订阅sprd-public-trades频道来获取所有已成功结算的交易。

REST API

下单

限速:：20次/ 2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/sprd/order

请求示例

# 下价差订单
POST /api/v5/sprd/order
body
{
  "sprdId":"BTC-USDT_BTC-USDT-SWAP",
  "clOrdId":"b15",
  "side":"buy",
  "ordType":"limit",
  "px":"2.15",
  "sz":"2"
}

import okx.SpreadTrading as SpreadTrading

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

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

spreadAPI = SpreadTrading.SpreadTradingAPI(apikey, secretkey, passphrase, False, flag)

# 下单
result = spreadAPI.place_order(sprdId='BTC-USDT_BTC-USDT-SWAP',
                               clOrdId='b16',side='buy',ordType='limit',
                               px='2',sz='2')
print(result)

请求参数

参数名	类型	是否必须	描述
sprdId	String	是	spread ID，如 BTC-USDT_BTC-USDT-SWAP
clOrdId	String	否	客户自定义订单ID字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
tag	String	否	订单标签字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。
side	String	是	订单方向 `buy`：买，`sell`：卖
ordType	String	是	订单类型 `market`：市价单 `limit`：限价单 `post_only`：只做maker单 `ioc`：立即成交并取消剩余
sz	String	是	委托数量。反向价差的数量单位为USD，正向及混合价差为其对应`baseCcy`
px	String	是	委托价格，仅适用于`limit`, `post_only`, `ioc`类型的订单

返回示例

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "clOrdId": "b15",
      "ordId": "312269865356374016",
      "tag": "",
      "sCode": "0",
      "sMsg": ""
    }
  ]
}

返回参数

参数名	类型	描述
ordId	String	订单ID
clOrdId	String	客户自定义订单ID
tag	String	订单标签
sCode	String	事件执行结果的code，0代表成功
sMsg	String	事件执行失败或成功时的msg

撤单

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

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/sprd/cancel-order

请求示例

POST /api/v5/sprd/cancel-order
body
{
    "ordId":"2510789768709120"
}

import okx.SpreadTrading as SpreadTrading

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

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

spreadAPI = SpreadTrading.SpreadTradingAPI(apikey, secretkey, passphrase, False, flag)

# 撤单
result = spreadAPI.cancel_order(ordId='1905309079888199680')
print(result)

请求参数

参数名	类型	是否必须	描述
ordId	String	可选	订单ID， `ordId`和`clOrdId`必须传一个，若传两个，以`ordId`为主
clOrdId	String	可选	用户自定义ID

返回示例

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

返回参数

参数名	类型	描述
ordId	String	订单ID
clOrdId	String	客户自定义订单ID
sCode	String	事件执行结果的code，0代表成功
sMsg	String	事件执行失败时的msg

全部撤单

撤销所有挂单

限速：10次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/sprd/mass-cancel

请求示例

POST /api/v5/sprd/mass-cancel
 body
 {
    "sprdId": "BTC-USDT_BTC-USDT-SWAP"
}

import okx.SpreadTrading as SpreadTrading

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

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

spreadAPI = SpreadTrading.SpreadTradingAPI(apikey, secretkey, passphrase, False, flag)

# 全部撤单
result = spreadAPI.cancel_all_orders(sprdId="BTC-USDT_BTC-USDT-SWAP")
print(result)

请求参数

参数名	类型	是否必须	描述
sprdId	String	否	spread ID

返回参数

参数名	类型	描述
result	Boolean	请求结果`true`, `false`

返回示例

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

修改订单

修改当前未成交的挂单

限速：20次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/sprd/amend-order

请求示例

POST /api/v5/sprd/amend-order
body
{
    "ordId":"2510789768709120",
    "newSz":"2"
}

请求参数

参数名	类型	是否必须	描述
ordId	String	可选	订单ID， `ordId`和`clOrdId`必须传一个，若传两个，以`ordId`为主
clOrdId	String	可选	用户自定义order ID
reqId	String	否	用户自定义修改事件ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
newSz	String	可选	修改的新数量，对于部分成交订单，该数量应包含已成交数量。 `newSz` 和 `newPx`不可同时为空。
newPx	String	可选	修改后的新价格。 `newSz` 和 `newPx`不可同时为空。

返回结果

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

返回参数

参数名	类型	描述
ordId	String	订单ID
clOrdId	String	用户自定义order ID
reqId	String	用户自定义修改事件ID
sCode	String	事件执行结果的code，0代表成功
sMsg	String	事件执行失败或成功时的msg

获取订单信息

查订单信息

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/sprd/order

请求示例

GET /api/v5/sprd/order?ordId=2510789768709120

import okx.SpreadTrading as SpreadTrading

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

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

spreadAPI = SpreadTrading.SpreadTradingAPI(apikey, secretkey, passphrase, False, flag)

# 获取订单详情
result = spreadAPI.get_order_details(ordId='1905309079888199680')
print(result)

请求参数

参数名	类型	是否必须	描述
ordId	String	可选	订单ID，`ordId`和`clOrdId`必须传一个，若传两个，以`ordId`为主
clOrdId	String	可选	用户自定义ID，如果`clOrdId`关联了多个订单，只会返回最近的那笔订单

返回示例

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "sprdId": "BTC-USD-SWAP_BTC-USD-200329",
      "ordId": "312269865356374016",
      "clOrdId": "b1",
      "tag": "",
      "px": "999",
      "sz": "3",
      "ordType": "limit",
      "side": "buy",
      "fillSz": "0",
      "fillPx": "",
      "tradeId": "",
      "accFillSz": "0",
      "pendingFillSz": "2",
      "pendingSettleSz": "1",
      "canceledSz": "1",
      "state": "live",
      "avgPx": "0",
      "cancelSource": "",
      "uTime": "1597026383085",
      "cTime": "1597026383085"
    }
  ]
}

返回参数

参数名	类型	描述
sprdId	String	Spread ID
ordId	String	订单ID
clOrdId	String	客户自定义订单ID
tag	String	订单标签
px	String	委托价格
sz	String	委托数量
ordType	String	订单类型 `market`：市价单 `limit`：限价单 `post_only`：只做maker单 `ioc`：立即成交并取消剩余
side	String	订单方向
fillSz	String	最新成交数量
fillPx	String	最新成交价格
tradeId	String	最近成交ID
accFillSz	String	累计成交数量
pendingFillSz	String	待成交数量（包括待结算数量）
pendingSettleSz	String	待结算数量
canceledSz	String	被取消数量
avgPx	String	成交均价，如果成交数量为0，该字段为"0"
state	String	订单状态 `canceled`：撤单成功 `live`：等待成交 `partially_filled`：部分成交 `filled`：完全成交
cancelSource	String	撤单原因 `0`: 系统撤单 `1`: 用户撤单 `14`: 已撤单：IOC 委托订单未完全成交，仅部分成交，导致部分挂单被撤回 `15`: 已撤单：该订单委托价不在限价范围内 `20`: 系统倒计时撤单 `31`: 当前只挂单订单 (Post only) 将会吃掉挂单深度 `32`: 自成交保护 `34`: 订单结算失败因为保证金不足 `35`: 撤单因为其他订单保证金不足
uTime	String	订单状态更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`

获取未成交订单列表

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

限速：10次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/sprd/orders-pending

请求示例

GET /api/v5/sprd/orders-pending

import okx.SpreadTrading as SpreadTrading

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

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

spreadAPI = SpreadTrading.SpreadTradingAPI(apikey, secretkey, passphrase, False, flag)

# 获取未完成订单
result = spreadAPI.get_active_orders()
print(result)

请求参数

参数名	类型	是否必须	描述
sprdId	String	否	spread ID，如BTC-USDT_BTC-USDT-SWAP
ordType	String	否	订单类型 `market`：市价单 `limit`：限价单 `post_only`：只做maker单 `ioc`：立即成交并取消剩余
state	String	否	订单状态 `live`：等待成交 `partially_filled`：部分成交
beginId	String	否	请求的起始订单ID，请求此ID之后（更新的数据）的分页内容，不包括 beginId
endId	String	否	请求的结束订单ID，请求此ID之前（更旧的数据）的分页内容，不包括 endId
limit	String	否	返回结果的数量，最大为100，默认100条

返回示例

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "sprdId": "BTC-USDT_BTC-UST-SWAP",
      "ordId": "312269865356374016",
      "clOrdId": "b1",
      "tag": "",
      "px": "999",
      "sz": "3",
      "ordType": "limit",
      "side": "buy",
      "fillSz": "0",
      "fillPx": "",
      "tradeId": "",
      "accFillSz": "0",
      "pendingFillSz": "2",
      "pendingSettleSz": "1",
      "canceledSz": "1",
      "state": "live",
      "avgPx": "0",
      "cancelSource": "",
      "uTime": "1597026383085",
      "cTime": "1597026383085"
    }
  ]
}

返回参数

参数名	类型	描述
sprdId	String	spread ID，如BTC-USDT_BTC-USDT-SWAP
ordId	String	订单ID
clOrdId	String	客户自定义订单ID
tag	String	订单标签
px	String	委托价格
sz	String	委托数量
ordType	String	订单类型 `market`：市价单 `limit`：限价单 `post_only`：只做maker单 `ioc`：立即成交并取消剩余
side	String	订单方向
fillSz	String	最新成交数量
fillPx	String	最新成交价格
tradeId	String	最近成交ID
accFillSz	String	累计成交数量
pendingFillSz	String	待成交数量（包括待结算数量）
pendingSettleSz	String	待结算数量
canceledSz	String	被取消数量
avgPx	String	成交均价，如果成交数量为0，该字段为"0"
state	String	订单状态 `live`：等待成交 `partially_filled`：部分成交
cancelSource	String	撤单原因 `0`: 系统撤单 `1`: 用户撤单 `14`: 已撤单：IOC 委托订单未完全成交，仅部分成交，导致部分挂单被撤回 `15`: 已撤单：该订单委托价不在限价范围内 `20`: 系统倒计时撤单 `31`: 当前只挂单订单 (Post only) 将会吃掉挂单深度 `32`: 自成交保护 `34`: 订单结算失败因为保证金不足 `35`: 撤单因为其他订单保证金不足
uTime	String	订单状态更新时间，Unix时间戳的毫秒数格式，如：`1597026383085`
cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如：`1597026383085`

获取历史订单记录（近21天)

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

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

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/sprd/orders-history

请求示例

GET /api/v5/sprd/orders-history

import okx.SpreadTrading as SpreadTrading

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

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

spreadAPI = SpreadTrading.SpreadTradingAPI(apikey, secretkey, passphrase, False, flag)

# 获取历史订单
result = spreadAPI.get_orders()
print(result)

请求参数

参数名	类型	是否必须	描述
sprdId	String	否	spread ID，如BTC-USDT_BTC-USDT-SWAP
ordType	String	否	订单类型 `market`：市价单 `limit`：限价单 `post_only`：只做maker单 `ioc`：立即成交并取消剩余
state	String	否	订单状态 `canceled`：撤单成功 `filled`：完全成交
beginId	String	否	请求的起始订单ID，请求此ID之后（更新的数据）的分页内容，不包括 beginId
endId	String	否	请求的结束订单ID，请求此ID之前（更旧的数据）的分页内容，不包括 endId
begin	String	否	筛选的开始时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
end	String	否	筛选的结束时间戳，Unix 时间戳为毫秒数格式，如 `1597027383085`
limit	String	否	返回结果的数量，最大为100，默认100条

返回示例

{
  "code": "0",
  "msg": "",
  "data": [
     {
      "sprdId": "BTC-USDT_BTC-UST-SWAP",
      "ordId": "312269865356374016",
      "clOrdId": "b1",
      "tag": "",
      "px": "999",
      "sz": "3",
      "ordType": "limit",
      "side": "buy",
      "fillSz": "0",
      "fillPx": "",
      "tradeId": "",
      "accFillSz": "0",
      "pendingFillSz": "2",
      "canceledSz": "1",
      "state": "live",
      "avgPx": "0",
      "cancelSource": "",
      "uTime": "1597026383085",
      "cTime": "1597026383085"
    }
  ]
}

返回参数

参数名	类型	描述
sprdId	String	spread ID，如BTC-USDT_BTC-USDT-SWAP
ordId	String	订单ID
clOrdId	String	客户自定义订单ID
tag	String	订单标签
px	String	委托价格
sz	String	委托数量
ordType	String	订单类型 `market`：市价单 `limit`：限价单 `post_only`：只做maker单 `ioc`：立即成交并取消剩余
side	String	订单方向
fillSz	String	最新成交数量
fillPx	String	最新成交价格
tradeId	String	最近成交ID
accFillSz	String	累计成交数量
pendingFillSz	String	待成交数量（包括待结算数量）
pendingSettleSz	String	待结算数量
canceledSz	String	被取消数量
avgPx	String	成交均价，如果成交数量为0，该字段为"0"
state	String	订单状态 `canceled`：撤单成功 `filled`：完全成交
cancelSource	String	撤单原因 `0`: 系统撤单 `1`: 用户撤单 `14`: 已撤单：IOC 委托订单未完全成交，仅部分成交，导致部分挂单被撤回 `15`: 已撤单：该订单委托价不在限价范围内 `20`: 系统倒计时撤单 `31`: 当前只挂单订单 (Post only) 将会吃掉挂单深度 `32`: 自成交保护 `34`: 订单结算失败因为保证金不足 `35`: 撤单因为其他订单保证金不足
uTime	String	订单状态更新时间，Unix时间戳的毫秒数格式，如：`1597026383085`
cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如： `1597026383085`

获取历史订单记录（近三月)

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

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

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

请求示例

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

请求参数

参数名	类型	是否必须	描述
sprdId	String	否	spread ID，如BTC-USDT_BTC-USDT-SWAP
ordType	String	否	订单类型 `market`：市价单 `limit`：限价单 `post_only`：只做maker单 `ioc`：立即成交并取消剩余
state	String	否	订单状态 `canceled`：撤单成功 `filled`：完全成交
instType	String	否	产品类型 `SPOT`：币币 `FUTURES`:交割合约 `SWAP`：永续合约订单任意一条腿的spread包含相应产品类型，则返回
instFamily	String	否	交易品种，例如 BTC-USDT 订单任意一条腿的spread包含相应交易品种，则返回
beginId	String	否	请求的起始订单ID，请求此ID之后（更新的数据）的分页内容，不包括 beginId
endId	String	否	请求的结束订单ID，请求此ID之前（更旧的数据）的分页内容，不包括 endId
begin	String	否	筛选的开始时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
end	String	否	筛选的结束时间戳，Unix 时间戳为毫秒数格式，如 `1597027383085`
limit	String	否	返回结果的数量，最大为100，默认100条

返回示例

{
  "code": "0",
  "msg": "",
  "data": [
     {
      "sprdId": "BTC-USDT_BTC-UST-SWAP",
      "ordId": "312269865356374016",
      "clOrdId": "b1",
      "tag": "",
      "px": "999",
      "sz": "3",
      "ordType": "limit",
      "side": "buy",
      "fillSz": "0",
      "fillPx": "",
      "tradeId": "",
      "accFillSz": "0",
      "pendingFillSz": "2",
      "pendingSettleSz": "1",
      "canceledSz": "1",
      "state": "cancelled",
      "avgPx": "0",
      "cancelSource": "",
      "uTime": "1597026383085",
      "cTime": "1597026383085"
    }
  ]
}

返回参数

参数名	类型	描述
sprdId	String	spread ID，如BTC-USDT_BTC-USDT-SWAP
ordId	String	订单ID
clOrdId	String	客户自定义订单ID
tag	String	订单标签
px	String	委托价格
sz	String	委托数量
ordType	String	订单类型 `market`：市价单 `limit`：限价单 `post_only`：只做maker单 `ioc`：立即成交并取消剩余
side	String	订单方向
fillSz	String	最新成交数量
fillPx	String	最新成交价格
tradeId	String	最近成交ID
accFillSz	String	累计成交数量
pendingFillSz	String	待成交数量（包括待结算数量）
pendingSettleSz	String	待结算数量
canceledSz	String	被取消数量
avgPx	String	成交均价，如果成交数量为0，该字段为"0"
state	String	订单状态 `canceled`：撤单成功 `filled`：完全成交
cancelSource	String	撤单原因 `0`: 系统撤单 `1`: 用户撤单 `14`: 已撤单：IOC 委托订单未完全成交，仅部分成交，导致部分挂单被撤回 `15`: 已撤单：该订单委托价不在限价范围内 `20`: 系统倒计时撤单 `31`: 当前只挂单订单 (Post only) 将会吃掉挂单深度 `32`: 自成交保护 `34`: 订单结算失败因为保证金不足 `35`: 撤单因为其他订单保证金不足
uTime	String	订单状态更新时间，Unix时间戳的毫秒数格式，如：`1597026383085`
cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如： `1597026383085`

获取历史成交数据（近七天）

获取近7天的订单成交明细信息. 结果按时间倒序返回。

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/sprd/trades

请求示例

GET /api/v5/sprd/trades

import okx.SpreadTrading as SpreadTrading

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

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

spreadAPI = SpreadTrading.SpreadTradingAPI(apikey, secretkey, passphrase, False, flag)

# 获取私有交易
result = spreadAPI.get_trades()
print(result)

请求参数

参数名	类型	是否必须	描述
sprdId	String	否	spread ID，如BTC-USDT_BTC-USDT-SWAP
tradeId	String	否	交易 ID
ordId	String	否	订单 ID
beginId	String	否	请求的起始交易ID，请求此ID之后（更新的数据）的分页内容，不包括 beginId
endId	String	否	请求的结束交易ID，请求此ID之前（更旧的数据）的分页内容，不包括 endId
begin	String	否	筛选的开始时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
end	String	否	筛选的结束时间戳，Unix 时间戳为毫秒数格式，如 `1597027383085`
limit	String	否	返回结果的数量，最大为100，默认100条

返回示例

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "sprdId": "BTC-USDT-SWAP_BTC-USDT-200329",
            "tradeId": "123",
            "ordId": "123445",
            "clOrdId": "b16",
            "tag": "",
            "fillPx": "999",
            "fillSz": "3",
            "state": "filled",
            "side": "buy",
            "execType": "M",
            "ts": "1597026383085",
            "legs": [
                {
                    "instId": "BTC-USDT-SWAP",
                    "px": "20000",
                    "sz": "3",
                    "szCont": "0.03",
                    "side": "buy",
                    "fillPnl": "",
                    "fee": "",
                    "feeCcy": "",
                    "tradeId": "1232342342"
                },
                {
                    "instId": "BTC-USDT-200329",
                    "px": "21000",
                    "sz": "3",
                    "szCont": "0.03",
                    "side": "sell",
                    "fillpnl": "",
                    "fee": "",
                    "feeCcy": "",
                    "tradeId": "5345646634"
                }
            ],
            "code": "",
            "msg": ""
        }
    ]
}

返回参数

参数名	类型	描述
sprdId	String	spread ID，如BTC-USDT_BTC-USDT-SWAP
tradeId	String	交易ID
ordId	String	订单ID
clOrdId	String	客户自定义订单ID
tag	String	订单标签
fillPx	String	成交价格
fillSz	String	成交数量
side	String	交易方向 `buy`：买 `sell`：卖
state	String	交易状态 `filled`：已成交 `rejected`：被拒绝
execType	String	流动性方向 `T`：taker `M`：maker
ts	String	成交明细产生时间，Unix时间戳的毫秒数格式，如 `1597026383085`
legs	Array of objects	交易的腿
> instId	String	产品 ID
> px	String	价格
> sz	String	数量
> szCont	String	成交合约数量仅适用于合约，现货将返回""
> side	String	交易方向 `buy`：买 `sell`：卖
> fillPnl	String	最新成交收益，适用于有成交的平仓订单。其他情况均为0。
> fee	String	手续费金额或者返佣金额，手续费扣除为‘负数’，如-0.01；手续费返佣为‘正数’，如 0.01
> feeCcy	String	交易手续费币种或者返佣金币种
> tradeId	String	交易ID
code	String	错误码，默认0
msg	String	错误提示，默认 ""

获取Spreads（公共）

获取可交易的Spreads。

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/sprd/spreads

请求示例

GET /api/v5/sprd/spreads?instId=BTC-USDT

import okx.SpreadTrading as SpreadTrading

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

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

spreadAPI = SpreadTrading.SpreadTradingAPI(apikey, secretkey, passphrase, False, flag)

# 获取价差产品
result = spreadAPI.get_spreads()
print(result)

请求参数

参数名	类型	是否必须	描述
baseCcy	string	否	Spread币种。例如BTC, ETH
instId	String	否	Spread里包含的产品ID。
sprdId	String	否	Spread ID
state	string	否	Spread状态 `live`：交易中 `suspend`：暂停中 `expired`：订单过期

返回示例

{
    "code": "0",
    "msg": "",
    "data": [{
            "sprdId": "ETH-USD-SWAP_ETH-USD-231229",
            "sprdType": "inverse",
            "state": "live",
            "baseCcy": "ETH",
            "szCcy": "USD",
            "quoteCcy": "USD",
            "tickSz": "0.01",
            "minSz": "10",
            "lotSz": "10",
            "listTime": "1686903000159",
            "legs": [{
                    "instId": "ETH-USD-SWAP",
                    "side": "sell"
                },
                {
                    "instId": "ETH-USD-231229",
                    "side": "buy"
                }
            ],
            "expTime": "1703836800000",
            "uTime": "1691376905595"
        },
        {
            "sprdId": "BTC-USDT_BTC-USDT-SWAP",
            "sprdType": "linear",
            "state": "live",
            "baseCcy": "BTC",
            "szCcy": "BTC",
            "quoteCcy": "USDT",
            "tickSz": "0.0001",
            "minSz": "0.001",
            "lotSz": "1",
            "listTime": "1597026383085",
            "expTime": "1597029999085",
            "uTime": "1597028888085",
            "legs": [{
                    "instId": "BTC-USDT",
                    "side": "sell"
                },
                {
                    "instId": "BTC-USDT-SWAP",
                    "side": "buy"
                }
            ]
        },
        {
            "sprdId": "BTC-USDT_BTC-USDT-230317",
            "sprdType": "linear",
            "state": "live",
            "baseCcy": "BTC",
            "szCcy": "BTC",
            "quoteCcy": "USDT",
            "tickSz": "0.0001",
            "minSz": "0.001",
            "lotSz": "1",
            "listTime": "1597026383085",
            "expTime": "1597029999085",
            "uTime": "1597028888085",
            "legs": [{
                    "instId": "BTC-USDT",
                    "side": "sell"
                },
                {
                    "instId": "BTC-USDT-230317",
                    "side": "buy"
                }
            ]
        }
    ]
}

返回参数

参数名	类型	描述
sprdId	String	spread ID
sprdType	String	Spread类型，有效值为`linear`, `inverse`, `hybrid`
state	String	Spread状态 `live`：交易中 `suspend`：暂停中 `expired`：已过期
baseCcy	String	Spread币种。例如BTC, ETH。
szCcy	String	Spread数量单位。例如USD, BTC, ETH, USD。
quoteCcy	String	Spread计价单位。例如USDT，USD。
tickSz	String	下单价格精度，如 0.0001。单位为Spread计价单位quoteCcy。
minSz	String	最小下单数量。单位为Spread数量单位szCcy。
lotSz	String	下单数量精度。单位为Spread数量单位szCcy。
listTime	String	上线日期。Unix时间戳的毫秒数格式，如 `1597026383085`
expTime	String	失效日期。Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	上次更新时间。Unix时间戳的毫秒数格式，如 `1597026383085`
legs	array of objects	腿
> instId	String	产品ID
> side	String	产品方向。`buy`：买入 `sell`：卖出

获取Spread产品深度（公共）

获取Spread产品深度列表

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/sprd/books

请求示例

GET /api/v5/sprd/books?sprdId=BTC-USDT_BTC-USDT-SWAP

import okx.SpreadTrading as SpreadTrading

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

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

spreadAPI = SpreadTrading.SpreadTradingAPI(apikey, secretkey, passphrase, False, flag)

# 获取深度
result = spreadAPI.get_order_book(sprdId="BTC-USDT_BTC-USDT-SWAP", sz=20)
print(result)

请求参数

参数名	类型	是否必须	描述
sprdId	String	是	spread ID，如BTC-USDT_BTC-USDT-SWAP
sz	String	否	深度档位数量。最大值为400。默认值为5。

返回示例

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "asks": [
                [
                    "41006.8", // 价格
                    "0.60038921", // 数量
                    "1" // 此价格上订单数量
                ]
            ],
            "bids": [
                [
                    "41006.3",
                    "0.30178218",
                    "2"
                ]
            ],
            "ts": "1629966436396"
        }
    ]
}

返回参数

参数名	类型	描述
asks	Array	卖方深度
bids	Array	买方深度
ts	String	深度产生的时间

获取单个Spread产品行情信息（公共）

获取单个Spread产品行情信息，包括最新成交价，买一卖一价及数量。

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/sprd-ticker

请求示例

GET /api/v5/market/sprd-ticker?sprdId=BTC-USDT_BTC-USDT-SWAP

请求参数

参数名	类型	是否必须	描述
sprdId	String	是	spread ID, 如 BTC-USDT_BTC-USDT-SWAP

返回示例

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "sprdId": "BTC-USDT_BTC-USDT-SWAP",
            "last": "14.5",
            "lastSz": "0.5",
            "askPx": "8.5",
            "askSz": "12.0",
            "bidPx": "0.5",
            "bidSz": "12.0",
            "open24h": "4",
            "high24h": "14.5",
            "low24h": "-2.2",
            "vol24h": "6.67",
            "ts": "1715331406485"
        }
    ]
}

返回参数

参数名	类型	描述
sprdId	String	spread ID
last	String	最新成交价
lastSz	String	最新成交的数量
askPx	String	卖一价
askSz	String	卖一价对应的数量
bidPx	String	买一价
bidSz	String	买一价对应的数量
open24h	String	24小时开盘价
high24h	String	24小时最高价
low24h	String	24小时最低价
vol24h	String	24小时交易量正向及混合价差，单位为交易货币；反向价差，单位为美元
ts	String	数据产生时间，Unix时间戳的毫秒数格式，如 1597026383085

获取公共成交数据（公共）

查询市场上的Spread成交信息数据，每次请求最多返回500条结果。结果按时间倒序返回。

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/sprd/public-trades

请求示例

GET /api/v5/sprd/public-trades?sprdId=BTC-USDT_BTC-USDT-SWAP

import okx.SpreadTrading as SpreadTrading

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

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

spreadAPI = SpreadTrading.SpreadTradingAPI(apikey, secretkey, passphrase, False, flag)

# 获取公共交易信息
result = spreadAPI.get_public_trades(sprdId='ETH-USDT-SWAP_ETH-USDT-230929')
print(result)

请求参数

参数名	类型	是否必须	描述
sprdId	String	否	Spread ID，例如BTC-USDT_BTC-USDT-SWAP

返回示例

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "sprdId": "BTC-USDT_BTC-USDC-SWAP",
            "side": "sell",
            "sz": "0.1",
            "px": "964.1",
            "tradeId": "242720719",
            "ts": "1654161641568"
        }
    ]
}

返回参数

参数名	类型	描述
sprdId	String	spread ID
tradeId	String	交易ID
px	String	成交价格
sz	String	成交数量
side	String	Taker的交易方向 `buy`：买 `sell`：卖
ts	String	交易时间，Unix时间戳的毫秒数格式，如： `1597026383085`

获取价差交易产品K线数据

获取K线数据。K线数据按请求的粒度分组返回，K线数据每个粒度最多可获取最近1,440条。

限速: 40次/2s

限速规则： IP

权限：读取

HTTP请求

GET /api/v5/market/sprd-candles

请求示例

GET /api/v5/market/sprd-candles?sprdId=BTC-USDT_BTC-USDT-SWAP

请求参数

参数名	类型	是否必须	描述
sprdId	String	是	Spread ID
bar	String	否	时间粒度，默认值1m，如 [1m/3m/5m/15m/30m/1H/2H/4H] 香港时间开盘价k线：[6H/12H/1D/2D/3D/1W/1M/3M] UTC时间开盘价k线：[/6Hutc/12Hutc/1Dutc/2Dutc/3Dutc/1Wutc/1Mutc/3Mutc]
after	String	否	请求此时间戳之前（更旧的数据）的分页内容，传的值为对应接口的ts
before	String	否	请求此时间戳之后（更新的数据）的分页内容，传的值为对应接口的ts, 单独使用时，会返回最新的数据。
limit	String	否	分页返回的结果集数量，最大为300，不填默认返回100条

返回示例

{
    "code":"0",
    "msg":"",
    "data":[
     [
        "1597026383085",
        "3.721",
        "3.743",
        "3.677",
        "3.708",
        "8422410",
        "0"
    ],
    [
        "1597026383085",
        "3.731",
        "3.799",
        "3.494",
        "3.72",
        "24912403",
        "1"
    ]
    ]
}

返回参数

参数名	类型	描述
ts	String	开始时间，Unix时间戳的毫秒数格式，如 1597026383085
o	String	开盘价格
h	String	最高价格
l	String	最低价格
c	String	收盘价格
vol	String	交易量
confirm	String	K线状态 `0`：K线未完结 `1`：K线已完结

获取价差交易产品历史K线数据

获取最近几年的历史k线数据

限速: 20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/sprd-history-candles

请求示例

GET /api/v5/market/sprd-history-candles?sprdId=BTC-USDT_BTC-USDT-SWAP

请求参数

参数名	类型	是否必须	描述
sprdId	String	是	Spread ID
after	String	否	请求此时间戳之前（更旧的数据）的分页内容，传的值为对应接口的ts
before	String	否	请求此时间戳之后（更新的数据）的分页内容，传的值为对应接口的ts, 单独使用时，会返回最新的数据。
bar	String	否	时间粒度，默认值1m，如 [1m/3m/5m/15m/30m/1H/2H/4H] 香港时间开盘价k线：[6H/12H/1D/2D/3D/1W/1M/3M] UTC时间开盘价k线：[6Hutc/12Hutc/1Dutc/2Dutc/3Dutc/1Wutc/1Mutc/3Mutc]
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回示例

{
    "code":"0",
    "msg":"",
    "data":[
     [
        "1597026383085",
        "3.721",
        "3.743",
        "3.677",
        "3.708",
        "8422410",
        "1"
    ],
    [
        "1597026383085",
        "3.731",
        "3.799",
        "3.494",
        "3.72",
        "24912403",
        "1"
    ]
    ]
}

返回参数

参数名	类型	描述
ts	String	开始时间，Unix时间戳的毫秒数格式，如 1597026383085
o	String	开盘价格
h	String	最高价格
l	String	最低价格
c	String	收盘价格
vol	String	交易量
confirm	String	K线状态 `0`：K线未完结 `1`：K线已完结

倒计时全部撤单

在倒计时结束后，取消所有挂单。仅适用于价差交易。

限速：1次/s

限速规则：UserID

权限：交易

HTTP请求

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

请求示例

POST /api/v5/sprd/cancel-all-after
{
   "timeOut":"30"
}

请求参数

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

返回结果

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

返回参数

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

Websocket交易API

WS / 下单

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

服务地址

/ws/v5/business (需要登录)

限速：20次/2s

限速规则：UserID

请求示例

{
  "id": "1512",
  "op": "sprd-order",
  "args": [
    {
       "sprdId":"BTC-USDT_BTC-USDT-SWAP",
       "clOrdId":"b15",
       "side":"buy",
       "ordType":"limit",
       "px":"2.15",
       "sz":"2"
    }
  ]
}

请求参数

参数名	类型	是否必须	描述
id	String	是	消息的唯一标识用户提供，返回参数中会返回以便于找到相应的请求。字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	支持的业务操作，`sprd-order`
args	Array	是	请求参数
> sprdId	String	是	产品ID，如 `BTC-USDT_BTC-USDT-SWAP`
> clOrdId	String	否	由用户设置的订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
> tag	String	否	订单标签字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-16位之间。
> side	String	是	订单方向，`buy` `sell`
> ordType	String	是	订单类型 `market`：市价单 `limit`：限价单 `post_only`：只做maker单 `ioc`：立即成交并取消剩余
> sz	String	是	委托数量
> px	String	是	委托价，仅适用于`limit`、`post_only`、`ioc`类型的订单

成功返回示例

{
    "id": "1512",
    "op": "sprd-order",
    "data": [{
        "clOrdId": "",
        "ordId": "12345689",
        "tag": "",
        "sCode": "0",
        "sMsg": ""
    }],
    "code": "0",
    "msg": ""
}

失败返回示例

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

格式错误返回示例

{
    "id": "1512",
    "op": "sprd-order",
    "data": [],
    "code": "60013",
    "msg": "Invalid args"
}

返回参数

参数名	类型	描述
id	String	消息的唯一标识
op	String	业务操作
code	String	代码
msg	String	消息
data	Array	请求成功后返回的数据
> ordId	String	订单ID
> clOrdId	String	由用户设置的订单ID
> tag	String	订单标签
> sCode	String	订单状态码，0 代表成功
> sMsg	String	订单状态消息

WS / 改单

修改当前未成交的订单

服务地址

/ws/v5/business (需要登录)

限速：20次/2s

限速规则：UserID

请求示例

{
   "id":"1512",
   "op":"sprd-amend-order",
   "args":[
      {
         "ordId":"2510789768709120",
         "newSz":"2"
      }
   ]
}

请求参数

Parameter	Type	Required	Description
id	String	是	消息的唯一标识用户提供，返回参数中会返回以便于找到相应的请求。字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	支持的业务操作，`sprd-amend-order`
args	Array	是	请求参数
> ordId	String	可选	订单ID ordId 和 clOrdId必须传一个，若传两个，以 ordId 为主
> clOrdId	String	可选	由用户设置的订单ID
> reqId	String	否	用户自定义修改事件ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
> newSz	String	可选	修改的新数量，对于部分成交订单，该数量应包含已成交数量。 `newSz` 或 `newPx`至少传一个。
> newPx	String	可选	修改后的新价格

成功返回示例

{
  "id": "1512",
  "op": "sprd-amend-order",
  "data": [
    {
      "clOrdId": "",
      "ordId": "2510789768709120",
      "reqId": "b12344",
      "sCode": "0",
      "sMsg": ""
    }
  ],
  "code": "0",
  "msg": ""
}

失败返回示例

{
  "id": "1512",
  "op": "sprd-amend-order",
  "data": [
    {
      "clOrdId": "",
      "ordId": "2510789768709120",
      "reqId": "b12344",
      "sCode": "5XXXX",
      "sMsg": "order not exist"
    }
  ],
  "code": "1",
  "msg": ""
}

格式错误返回示例

{
  "id": "1512",
  "op": "sprd-amend-order",
  "data": [],
  "code": "60013",
  "msg": "Invalid args"
}

返回参数

参数	类型	描述
id	String	消息的唯一标识
op	String	操作
code	String	代码
msg	String	消息
data	Array	请求成功后返回的数据
> ordId	String	订单ID
> clOrdId	String	由用户设置的订单ID
> reqId	String	用户自定义修改事件ID
> sCode	String	订单状态码，0 代表成功
> sMsg	String	订单状态消息

WS / 撤单

撤销当前未完成订单

服务地址

/ws/v5/business (需要登录)

限速：20次/2s

限速规则：UserID

请求示例

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

请求参数

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

成功返回示例

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

失败返回示例

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

格式错误返回示例

{
    "id": "1514",
    "op": "sprd-cancel-order",
    "data": [],
    "code": "60013",
    "msg": "Invalid args"
}

返回参数

参数	类型	描述
id	String	消息的唯一标识
op	String	业务操作
code	String	代码
msg	String	消息
data	Array	请求成功后返回的数据
> ordId	String	订单ID
> clOrdId	String	由用户设置的订单ID
> sCode	String	订单状态码，0 代表成功
> sMsg	String	订单状态消息

WS / 全部撤单

服务地址

/ws/v5/business (需要登录)

限速：5次/2s

限速规则：UserID

请求示例

{
    "id": "1512",
    "op": "sprd-mass-cancel",
    "args": [{
        "sprdId":"BTC-USDT_BTC-USDT-SWAP"
    }]
}

请求参数

参数名	类型	是否必须	描述
id	String	是	消息的唯一标识用户提供，返回参数中会返回以便于找到相应的请求。字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	支持的业务操作，`sprd-mass-cancel`
args	Array	是	请求参数
> sprdId	String	否	价差ID

成功返回示例

{
    "id": "1512",
    "op": "sprd-mass-cancel",
    "data": [
        {
            "result": true
        }
    ],
    "code": "0",
    "msg": ""
}

格式错误返回示例

{
    "id": "1512",
    "op": "sprd-mass-cancel",
    "data": [],
    "code": "60013",
    "msg": "Invalid args"
}

返回参数

参数名	类型	描述
id	String	消息的唯一标识
op	String	业务操作
code	String	代码
msg	String	消息
data	Array	请求成功后返回的数据
> result	Boolean	撤单结果 `true`：全部撤单成功 `false`：全部撤单失败

WebSocket私有频道

实盘地址: wss://ws.okx.com:8443/ws/v5/business
AWS实盘地址: wss://wsaws.okx.com:8443/ws/v5/business
模拟盘地址: wss://wspap.okx.com:8443/ws/v5/business

订单频道

通过订阅sprd-orders频道获取Spread订单信息，首次订阅不推送，只有当下单、撤单等事件触发时，推送数据。

服务地址

/ws/v5/business (需要登录)

请求示例：单个

{
  "op": "subscribe",
  "args": [
    {
      "channel": "sprd-orders",
      "sprdId": "BTC-USDT_BTC-USDT-SWAP"
    }
  ]
}

请求示例：

{
  "op": "subscribe",
  "args": [
    {
      "channel": "sprd-orders",
    }
  ]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，`subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `sprd-orders`
> sprdId	String	是	Spread ID

成功返回示例：单个

{
  "event": "subscribe",
  "arg": {
    "channel": "sprd-orders",
    "sprdId": "BTC-USDT_BTC-UST-SWAP"
  },
  "connId": "a4d3ae55"
}

成功返回示例

{
  "event": "subscribe",
  "arg": {
    "channel": "sprd-orders"
  },
  "connId": "a4d3ae55"
}

失败返回示例

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

返回参数

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

推送示例：单个

{
  "arg": {
        "channel": "sprd-orders",
        "sprdId": "BTC-USDT_BTC-USDT-SWAP",
        "uid": "614488474791936"
    },
  "data": [
     {
      "sprdId": "BTC-USDT_BTC-UST-SWAP",
      "ordId": "312269865356374016",
      "clOrdId": "b1",
      "tag": "",
      "px": "999",
      "sz": "3",
      "ordType": "limit",
      "side": "buy",
      "fillSz": "0",
      "fillPx": "",
      "tradeId": "",
      "accFillSz": "0",
      "pendingFillSz": "2",
      "pendingSettleSz": "1",
      "canceledSz": "1",
      "state": "live",
      "avgPx": "0",
      "cancelSource": "",
      "uTime": "1597026383085",
      "cTime": "1597026383085",
      "code": "0",
      "msg": "",
      "reqId": "",
      "amendResult": ""
    }
  ]

}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> uid	String	用户标识
> sprdId	String	spread ID
data	Array	订阅的数据
> sprdId	String	spread ID
> ordId	String	订单ID
> clOrdId	String	由用户设置的订单ID来识别您的订单
> tag	String	订单标签
> px	String	委托价格
> sz	String	原始委托数量，单位szCcy
> ordType	String	订单类型 `market`：市价单 `limit`：限价单 `post_only`：只做maker单 `ioc`：立即成交并取消剩余
> side	String	订单方向 `buy` `sell`
> fillSz	String	最新成交数量，适用于结算成功的订单更新
> fillPx	String	最新成交价格，适用于结算成功的订单更新
> tradeId	String	最近成交ID
> accFillSz	String	累计成交数量
> pendingFillSz	String	待成交数量，包括待结算数量
> pendingSettleSz	String	待结算数量
> canceledSz	String	撤单数量
> avgPx	String	成交均价，如果成交数量为0，该字段为"0"
> state	String	订单状态 `canceled`：撤单成功 `live`：等待成交 `partially_filled`：部分成交 `filled`：完全成交
> cancelSource	String	撤单原因 `0`: 系统撤单 `1`: 用户撤单 `14`: 已撤单：IOC 委托订单未完全成交，仅部分成交，导致部分挂单被撤回 `15`: 已撤单：该订单委托价不在限价范围内 `20`: 系统倒计时撤单 `31`: 当前只挂单订单 (Post only) 将会吃掉挂单深度 `32`: 自成交保护 `34`: 订单结算失败因为保证金不足 `35`: 撤单因为其他订单保证金不足
> uTime	String	订单更新时间，Unix时间戳的毫秒数格式，如 1597026383085
> cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085
> code	String	错误码，默认为0
> msg	String	错误消息，默认为""
> reqId	String	修改订单时使用的request ID，如果没有修改，该字段为""
> amendResult	String	修改订单的结果 `-1`：失败 `0`：成功如果没有修改，该字段为""

成交数据频道

通过订阅 sprd-trades 频道接收与用户成交信息相关的更新。

已成交（filled）和被拒绝（rejected）的交易都会通过此频道推送更新。

如果你的订单与多个订单相匹配，你有可能会收到多条更新推送。

服务地址

/ws/v5/business (需要登录)

请求示例：单个

{
  "op": "subscribe",
  "args": [
    {
      "channel": "sprd-trades",
      "sprdId": "BTC-USDT_BTC-USDT-SWAP"
    }
  ]
}

请求示例：

{
  "op": "subscribe",
  "args": [
    {
      "channel": "sprd-trades",
    }
  ]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，`subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `sprd-trades`
> sprdId	String	否	Spread ID

返回参数

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

推送示例

{
    "arg": {
        "channel": "sprd-trades",
        "sprdId": "BTC-USDT_BTC-USDT-SWAP",
        "uid": "614488474791936"
    },
    "data":[
         {
            "sprdId":"BTC-USDT-SWAP_BTC-USDT-200329",
            "tradeId":"123",
            "ordId":"123445",
            "clOrdId": "b16",
            "tag":"",
            "fillPx":"999",
            "fillSz":"3",
            "state": "filled",
            "side":"buy",
            "execType":"M",
            "ts":"1597026383085",
            "legs": [
                {
                    "instId": "BTC-USDT-SWAP",
                    "px": "20000",
                    "sz": "3",
                    "szCont": "0.03",
                    "side": "buy",
                    "fillPnl": "",
                    "fee": "",
                    "feeCcy": "",
                    "tradeId": "1232342342"
                },
                {
                    "instId": "BTC-USDT-200329",
                    "px": "21000",
                    "sz": "3",
                    "szCont": "0.03",
                    "side": "sell",
                    "fillPnl": "",
                    "fee": "",
                    "feeCcy": "",
                    "tradeId": "5345646634"
                },
            ]
            "code": "",
            "msg": ""
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> uid	String	用户标识
> sprdId	String	spread ID
data	Array	Subscribed data
> sprdId	String	spread ID
> tradeId	String	交易ID
> ordId	String	订单ID
> clOrdId	String	由用户设置的订单ID
> tag	String	订单标签
> fillPx	String	最新成交价
> fillSz	String	最新成交数量
> side	String	交易方向 `buy` `sell`
> state	String	交易状态。 `filled`: 已成交 `rejected`: 被拒绝
> execType	String	流动性方向 `T`：taker `M`：maker
>ts	String	成交明细产生时间，Unix时间戳的毫秒数格式，如1597026383085
> legs	Array of objects	交易的腿
>> instId	String	产品 ID
>> px	String	价格
>> sz	String	数量
>> szCont	String	成交合约数量仅适用于合约，现货将返回""
>> side	String	交易方向 `buy`：买 `sell`：卖
>> fillPnl	String	最新成交收益，适用于有成交的平仓订单。其他情况均为0。
>> fee	String	手续费金额或者返佣金额，手续费扣除为‘负数’，如-0.01；手续费返佣为‘正数’，如 0.01
>> feeCcy	String	交易手续费币种或者返佣金币种
>> tradeId	String	交易ID
> code	String	错误码，默认0
> msg	String	错误提示，默认 ""

WebSocket公共频道

实盘地址: wss://ws.okx.com:8443/ws/v5/business
AWS实盘地址: wss://wsaws.okx.com:8443/ws/v5/business
模拟盘地址: wss://wspap.okx.com:8443/ws/v5/business

深度频道

获取Spread深度数据。可用频道有：

sprd-bbo-tbt: 首次推1档快照数据，以后定量推送，每10毫秒当1档快照数据有变化推送一次1档数据
sprd-books5: 首次推5档快照数据，以后定量推送，每100毫秒当5档快照数据有变化推送一次5档数据
sprd-books-l2-tbt: 首次推400档快照数据，以后增量推送，每10毫秒推送一次变化的数据
单个连接、交易产品维度，深度频道的推送顺序固定为：sprd-bbo-tbt -> sprd-books-l2-tbt -> sprd-books5

URL Path

/ws/v5/business

请求示例：sprd-books5

{
  "op": "subscribe",
  "args": [
    {
      "channel": "sprd-books5",
      "sprdId": "BTC-USDT_BTC-USDT-SWAP"
    }
  ]
}

请求示例：sprd-books-l2-tbt

{
  "op": "subscribe",
  "args": [
    {
      "channel": "sprd-books-l2-tbt",
      "sprdId": "BTC-USDT_BTC-USDT-SWAP"
    }
  ]
}

请求参数

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

返回示例：sprd-books5

{
  "event": "subscribe",
  "arg": {
    "channel": "sprd-books5",
    "sprdId": "BTC-USDT_BTC-USDT-SWAP"
  },
  "connId": "a4d3ae55"
}

返回示例：sprd-books-l2-tbt

{
   "event":"subscribe",
   "arg":{
      "channel":"sprd-books-l2-tbt",
      "sprdId":"BTC-USDT_BTC-USDT-SWAP"
   },
   "connId":"214fdd24"
}

失败示例

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"args\":[{ \"channel\" : \"sprd-books5\", \"sprdId\" : \"BTC-USD_BTC-USD-191227\"}]}",
  "connId": "a4d3ae55"
}

返回参数

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

推送示例：sprd-books5

{
  "arg": {
    "channel": "sprd-books5",
    "sprdId": "BTC-USDT_BTC-USDT-SWAP"
  },
  "data": [
    {
      "asks": [
        ["111.06","55154","2"],
        ["111.07","53276","2"],
        ["111.08","72435","2"],
        ["111.09","70312","2"],
        ["111.1","67272","2"]],
      "bids": [
        ["111.05","57745","2"],
        ["111.04","57109","2"],
        ["111.03","69563","2"],
        ["111.02","71248","2"],
        ["111.01","65090","2"]],
      "ts": "1670324386802",
      "seqId":1724294007352168320
    }
  ]
}

推送示例：sprd-books-l2-tbt

{
   "arg":{
      "channel":"sprd-books-l2-tbt",
      "sprdId":"BTC-USDT_BTC-USDT-SWAP"
   },
   "action":"snapshot",
   "data":[
      {
         "asks":[
            ["1.9","1.1","3"],
            ["2.5","0.9","1"],
            ["3.2","4.921","1"],
            ["4.8","0.165","1"],
            ["5.2","4.921","1"]
          ......
         ],
         "bids":[
            ["1.8","0.165","1"],
            ["0.6","0.2","2"],
            ["0","23.49","1"],
            ["-0.1","1","1"],
            ["-0.6","1","1"],
            ["-3.9","4.921","1"]
            ......
         ],
         "ts":"1724391380926",
         "checksum":-1285595583,
         "prevSeqId":-1,
         "seqId":1724294007352168320
      }
   ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> sprdId	String	Spread ID
action	String	推送数据动作，增量推送数据还是全量推送数据 `snapshot`：全量 `update`：增量
data	Array	订阅的数据
> asks	Array	卖方深度
> bids	Array	买方深度
> ts	String	数据更新时间戳，Unix时间戳的毫秒数格式，如 1597026383085
> checksum	Integer	检验和（下方注解）。仅适用 `sprd-books-l2-tbt`
> prevSeqId	Integer	上一个推送的序列号。仅适用 `sprd-books-l2-tbt`
> seqId	Integer	推送的序列号（下方注解）

序列号

seqId是交易所行情的一个序号。如果用户通过多个websocket连接同一频道，收到的序列号会是相同的。每个sprdId对应一套。用户可以使用在增量推送频道的prevSeqId和seqId来构建消息序列。这将允许用户检测数据包丢失和消息的排序。正常场景下seqId的值大于prevSeqId。新消息中的prevSeqId与上一条消息的seqId匹配。最小序列号值为0，除了快照消息的prevSeqId为-1。

示例

快照推送：prevSeqId = -1，seqId = 10
增量推送1（正常更新）：prevSeqId = 10，seqId = 15
增量推送2（无更新）：prevSeqId = 15，seqId = 15
增量推送3（序列重置）：prevSeqId = 15，seqId = 3
增量推送4（正常更新）：prevSeqId = 3，seqId = 5

Checksum机制

此机制可以帮助用户校验深度数据的准确性。

深度合并

用户订阅增量推送深度频道成功后，首先获取初始全量深度数据，当获取到增量推送数据后，更新本地全量深度数据。

如果有相同价格，则比较数量；数量为0删除此深度，数量有变化则替换此数据。
如果没有相同价格，则按照价格优劣排序（bid为价格降序，ask为价格升序），将深度信息插入到全量数据中

计算校验和

先用深度合并后前25档bids和asks组成一个字符串（其中ask和bid中的价格和数量以冒号连接），再计算其crc32值（32位有符号整型）。

公共成交数据频道

订阅sprd-public-trades获取最近的成交数据，有成交数据就推送，每次推送仅包含一条成交数据。

URL Path

/ws/v5/business

请求示例

{
  "op": "subscribe",
  "args": [
    {
      "channel": "sprd-public-trades",
      "sprdId": "BTC-USDT_BTC-USDT-SWAP"
    }
  ]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，`subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `sprd-public-trades`
> sprdId	String	是	Spread ID

成功返回示例

{
  "event": "subscribe",
  "arg": {
      "channel": "sprd-public-trades",
      "sprdId": "BTC-USDT_BTC-USDT-SWAP"
  },
  "connId": "a4d3ae55"
}

失败返回示例

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"sprd-public-trades\", \"instId\" : \"BTC-USD-191227\"}]}",
  "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
    "arg": {
        "channel": "sprd-public-trades",
        "sprdId": "BTC-USDT_BTC-USDT-SWAP"
    },
    "data": [
        {
            "sprdId": "BTC-USDT_BTC-USDT-SWAP",
            "tradeId": "2499206329160695808",
            "px": "-10",
            "sz": "0.001",
            "side": "sell",
            "ts": "1726801105519"
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> sprdId	String	spread ID
data	Array	订阅的数据
> sprdId	String	spread ID
> tradeId	String	交易 ID
> px	String	成交价格
> sz	String	成交数量
> side	String	成交方向 `buy` `sell`
> ts	String	成交时间，Unix时间戳的毫秒数格式，如 1597026383085

行情频道

订阅sprd-tickers获取产品的最新成交价、买一价、卖一价及数量等信息。最快100ms推送一次，没有触发事件时最慢1s推送一次，触发推送的事件有：成交、买一卖一发生变动。

URL Path

/ws/v5/business

请求示例

{
  "op": "subscribe",
  "args": [
    {
      "channel": "sprd-tickers",
      "sprdId": "BTC-USDT_BTC-USDT-SWAP"
    }
  ]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，`subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `sprd-tickers`
> sprdId	String	是	spread ID

成功返回示例

{
  "event": "subscribe",
  "arg": {
    "channel": "sprd-tickers",
    "sprdId": "BTC-USDT_BTC-USDT-SWAP"
  }
}

失败返回示例

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"sprd-tickers\", \"instId\" : \"LTC-USD-200327\"}]}"
}

返回参数

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

推送示例

{
    "arg": {
        "channel": "sprd-tickers",
        "sprdId": "BTC-USDT_BTC-USDT-SWAP"
    },
    "data": [
        {
            "sprdId": "BTC-USDT_BTC-USDT-SWAP",
            "last": "4",
            "lastSz": "0.01",
            "askPx": "19.7",
            "askSz": "5.79",
            "bidPx": "5.9",
            "bidSz": "5.79",
            "open24h": "-7",
            "high24h": "19.6",
            "low24h": "-7",
            "vol24h": "9.87",
            "ts": "1715247061026"
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> sprdId	String	spread ID
data	Array	订阅的数据
> sprdId	String	spread ID
> last	String	最新成交价
> lastSz	String	最新成交的数量
> askPx	String	卖一价
> askSz	String	卖一价对应的量
> bidPx	String	买一价
> bidSz	String	买一价对应的数量
> open24h	String	24小时开盘价
> high24h	String	24小时最高价
> low24h	String	24小时最低价
> vol24h	String	24小时交易量，单元为交易货币或美元
> ts	String	数据产生时间，Unix时间戳的毫秒数格式，如 1597026383085

K线频道

该频道使用业务WebSocket，不需鉴权。

获取K线数据，推送频率最快是间隔1秒推送一次数据。

URL Path

/ws/v5/business

请求示例

{
   "op":"subscribe",
   "args":[
      {
         "channel":"sprd-candle1D",
         "sprdId":"BTC-USDT_BTC-USDT-SWAP"
      }
   ]
}

请求参数

参数名	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
channel	String	是	频道名 `sprd-candle3M` `sprd-candle1M` `sprd-candle1W` `sprd-candle1D` `sprd-candle2D` `sprd-candle3D` `sprd-candle5D` `sprd-candle12H` `sprd-candle6H` `sprd-candle4H` `sprd-candle2H` `sprd-candle1H` `sprd-candle30m` `sprd-candle15m` `sprd-candle5m` `sprd-candle3m` `sprd-candle1m` `sprd-candle3Mutc` `sprd-candle1Mutc` `sprd-candle1Wutc` `sprd-candle1Dutc` `sprd-candle2Dutc` `sprd-candle3Dutc` `sprd-candle5Dutc` `sprd-candle12Hutc` `sprd-candle6Hutc`
sprdId	String	是	Spread ID

成功返回示例

{
  "event": "subscribe",
  "arg": {
    "channel": "sprd-candle1D",
    "sprdId": "BTC-USDT_BTC-USDT-SWAP"
  }
}

失败返回示例

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"sprd-candle1D\", \"instId\" : \"BTC-USD-191227\"}]}"
}

返回参数

参数名	类型	是否必须	描述
event	String	是	事件 `subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
channel	String	是	频道名
sprdId	String	是	Spread ID
code	String	否	错误码
msg	String	否	错误消息

推送示例

{
  "arg": {
    "channel": "sprd-candle1D",
    "sprdId": "BTC-USDT_BTC-USD-SWAP"
  },
  "data": [
    [
      "1597026383085",
      "8533.02",
      "8553.74",
      "8527.17",
      "8548.26",
      "45247",
      "0"
    ]
  ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> sprdId	String	Spread ID
data	Array	订阅的数据
> ts	String	开始时间，Unix时间戳的毫秒数格式，如 1597026383085
> o	String	开盘价格
> h	String	最高价格
> l	String	最低价格
> c	String	收盘价格
> vol	String	交易量
> confirm	String	K线状态 `0`：K线未完结 `1`：K线已完结

公共数据

公共数据功能模块下的API接口不需要身份验证。

REST API

获取交易产品基础信息

获取所有可交易产品的信息列表。

限速：20次/2s

限速规则：IP +instType

权限：读取

HTTP请求

GET /api/v5/public/instruments

请求示例

GET /api/v5/public/instruments?instType=SPOT

import okx.PublicData as PublicData

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

publicDataAPI = PublicData.PublicAPI(flag=flag)

# 获取交易产品基础信息
result = publicDataAPI.get_instruments(
    instType="SPOT"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instType	String	是	产品类型 `SPOT`：币币 `MARGIN`：币币杠杆 `SWAP`：永续合约 `FUTURES`：交割合约 `OPTION`：期权
uly	String	可选	标的指数，仅适用于`交割/永续/期权`，期权必填
instFamily	String	否	交易品种，仅适用于`交割/永续/期权`
instId	String	否	产品ID

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
      {
            "alias": "",
            "auctionEndTime": "",
            "baseCcy": "BTC",
            "category": "1",
            "ctMult": "",
            "ctType": "",
            "ctVal": "",
            "ctValCcy": "",
            "expTime": "",
            "instFamily": "",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "lever": "10",
            "listTime": "1606468572000",
            "lotSz": "0.00000001",
            "maxIcebergSz": "9999999999.0000000000000000",
            "maxLmtAmt": "1000000",
            "maxLmtSz": "9999999999",
            "maxMktAmt": "1000000",
            "maxMktSz": "",
            "maxStopSz": "",
            "maxTriggerSz": "9999999999.0000000000000000",
            "maxTwapSz": "9999999999.0000000000000000",
            "minSz": "0.00001",
            "optType": "",
            "quoteCcy": "USDT",
            "settleCcy": "",
            "state": "live",
            "ruleType": "normal",
            "stk": "",
            "tickSz": "0.1",
            "uly": ""
        }
    ]
}

返回参数

参数名	类型	描述
instType	String	产品类型
instId	String	产品id，如 `BTC-USDT`
uly	String	标的指数，如 `BTC-USD`，仅适用于`杠杆/交割/永续/期权`
instFamily	String	交易品种，如 `BTC-USD`，仅适用于`杠杆/交割/永续/期权`
category	String	~~币种类别~~（已废弃）
baseCcy	String	交易货币币种，如 `BTC-USDT` 中的 `BTC` ，仅适用于`币币/币币杠杆`
quoteCcy	String	计价货币币种，如 `BTC-USDT` 中的`USDT` ，仅适用于`币币/币币杠杆`
settleCcy	String	盈亏结算和保证金币种，如 `BTC` 仅适用于`交割/永续/期权`
ctVal	String	合约面值，仅适用于`交割/永续/期权`
ctMult	String	合约乘数，仅适用于`交割/永续/期权`
ctValCcy	String	合约面值计价币种，仅适用于`交割/永续/期权`
optType	String	期权类型，`C`或`P` 仅适用于`期权`
stk	String	行权价格，仅适用于`期权`
listTime	String	上线时间 Unix时间戳的毫秒数格式，如 `1597026383085`
auctionEndTime	String	集合竞价结束时间，Unix时间戳的毫秒数格式，如 `1597026383085` 仅适用于通过集合竞价方式上线的`币币`，其余情况返回""
expTime	String	产品下线时间适用于`币币/杠杆/交割/永续/期权`，对于 `交割/期权`，为交割/行权日期；亦可以为产品下线时间，有变动就会推送。
lever	String	该`instId`支持的最大杠杆倍数，不适用于`币币`、`期权`
tickSz	String	下单价格精度，如 `0.0001` 对于期权来说，是梯度中的最小下单价格精度，如果想要获取期权价格梯度，请使用"获取期权价格梯度"接口
lotSz	String	下单数量精度合约的数量单位是`张`，现货的数量单位是`交易货币`
minSz	String	最小下单数量合约的数量单位是`张`，现货的数量单位是`交易货币`
ctType	String	合约类型 `linear`：正向合约 `inverse`：反向合约仅适用于`交割/永续`
alias	String	合约日期别名 `this_week`：本周 `next_week`：次周 `this_month`：本月 `next_month`：次月 `quarter`：季度 `next_quarter`：次季度仅适用于`交割` 不建议使用，用户应通过 expTime 字段获取合约的交割日期
state	String	产品状态 `live`：交易中 `suspend`：暂停中 `preopen`：预上线，交割和期权合约轮转生成到开始交易；部分交易产品上线前 `test`：测试中（测试产品，不可交易）
ruleType	String	交易规则类型 `normal`：普通交易 `pre_market`：盘前交易
maxLmtSz	String	限价单的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`交易货币`
maxMktSz	String	市价单的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`USDT`
maxLmtAmt	String	限价单的单笔最大美元价值
maxMktAmt	String	市价单的单笔最大美元价值仅适用于`币币/币币杠杆`
maxTwapSz	String	时间加权单的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`交易货币`。单笔最小委托数量为 minSz*2
maxIcebergSz	String	冰山委托的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`交易货币`
maxTriggerSz	String	计划委托委托的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`交易货币`
maxStopSz	String	止盈止损市价委托的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`USDT`

获取交割和行权记录

获取3个月内的交割合约的交割记录和期权的行权记录

限速：40次/2s

限速规则：IP + (instrumentType + uly)

权限：读取

HTTP请求

GET /api/v5/public/delivery-exercise-history

请求示例

GET /api/v5/public/delivery-exercise-history?instType=OPTION&uly=BTC-USD

import okx.PublicData as PublicData

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

publicDataAPI = PublicData.PublicAPI(flag=flag)

# 获取交割和行权记录
result = publicDataAPI.get_delivery_exercise_history(
    instType="FUTURES",
    uly="BTC-USD"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instType	String	是	产品类型 `FUTURES`：交割合约 `OPTION`：期权
uly	String	可选	标的指数 `uly`与`instFamily`必须传一个,若传两个，以`instFamily`为主
instFamily	String	可选	交易品种 `uly`与`instFamily`必须传一个,若传两个，以`instFamily`为主
after	String	否	请求此时间戳之前（更旧的数据）的分页内容，传的值为对应接口的`ts`
before	String	否	请求此时间戳之后（更新的数据）的分页内容，传的值为对应接口的`ts`
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "ts":"1597026383085",
            "details":[
                {
                    "type":"delivery",
                    "insId":"BTC-USD-190927",
                    "px":"0.016"
                }
            ]
        },
        {
            "ts":"1597026383085",
            "details":[
                {
                    "insId":"BTC-USD-200529-6000-C",
                    "type":"exercised",
                    "px":"0.016"
                },
                {
                    "insId":"BTC-USD-200529-8000-C",
                    "type":"exercised",
                    "px":"0.016"
                }
            ]
        }
    ]
}

返回参数

参数名	类型	描述
ts	String	交割/行权日期，Unix时间戳的毫秒数格式，如 `1597026383085`
details	String	详细数据
> insId	String	交割/行权的合约ID
> px	String	交割/行权的价格
> type	String	类型 `delivery`：交割 `exercised`：实值已行权 `expired_otm`：虚值已过期

获取持仓总量

查询单个交易产品的市场的持仓总量

限速：20次/2s

限速规则：IP + instrumentID

权限：读取

HTTP请求

GET /api/v5/public/open-interest

请求示例

GET /api/v5/public/open-interest?instType=SWAP

import okx.PublicData as PublicData

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

publicDataAPI = PublicData.PublicAPI(flag=flag)

# 获取持仓总量
result = publicDataAPI.get_open_interest(
    instType="FUTURES",
)
print(result)

请求参数

参数名	类型	是否必须	描述
instType	String	是	产品类型 `SWAP`：永续合约 `FUTURES`：交割合约 `OPTION`：期权
uly	String	可选	标的指数适用于`交割/永续/期权` `期权`情况下，`uly`和`instFamily`必须传一个
instFamily	String	可选	交易品种适用于`交割/永续/期权` `期权`情况下，`uly`和`instFamily`必须传一个
instId	String	否	产品ID，如 `BTC-USDT-SWAP` 仅适用于`交割`/`永续`/`期权`

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
    {
        "instType":"SWAP",
        "instId":"BTC-USDT-SWAP",
        "oi":"5000",
        "oiCcy":"555.55",
        "oiUsd": "50000",
        "ts":"1597026383085"
    }
  ]
}

返回参数

参数名	类型	描述
instType	String	产品类型
instId	String	产品ID
oi	String	持仓量（按`张`折算）
oiCcy	String	持仓量（按`币`折算）
oiUsd	String	持仓量（按`USD`折算）
ts	String	数据返回时间，Unix时间戳的毫秒数格式，如 `1597026383085`

获取永续合约当前资金费率

获取当前资金费率

限速：20次/2s

限速规则：IP +instrumentID

权限：读取

HTTP请求

GET /api/v5/public/funding-rate

请求示例

GET /api/v5/public/funding-rate?instId=BTC-USD-SWAP

import okx.PublicData as PublicData

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

publicDataAPI = PublicData.PublicAPI(flag=flag)

# 获取永续合约当前资金费率
result = publicDataAPI.get_funding_rate(
    instId="BTC-USD-SWAP",
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID ，如 `BTC-USD-SWAP` 仅适用于`永续`

返回结果

{
    "code": "0",
    "data": [
        {
            "fundingRate": "0.0000792386885340",
            "fundingTime": "1703088000000",
            "instId": "BTC-USDT-SWAP",
            "instType": "SWAP",
            "method": "next_period",
            "maxFundingRate": "0.00375",
            "minFundingRate": "-0.00375",
            "nextFundingRate": "0.0002061194322149",
            "nextFundingTime": "1703116800000",
            "premium": "0.0001233824646391",
            "settFundingRate": "0.0001418433662153",
            "settState": "settled",
            "ts": "1703070685309"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instType	String	产品类型 `SWAP`：永续合约
instId	String	产品ID，如`BTC-USD-SWAP`
method	String	资金费收取逻辑 `current_period`：当期收 `next_period`：跨期收
fundingRate	String	资金费率
nextFundingRate	String	下一期预测资金费率当收取逻辑为`current_period`时，nextFundingRate字段将返回""
fundingTime	String	资金费时间，Unix时间戳的毫秒数格式，如 `1597026383085`
nextFundingTime	String	下一期资金费时间，Unix时间戳的毫秒数格式，如 `1622851200000`
minFundingRate	String	下一期的预测资金费率下限
maxFundingRate	String	下一期的预测资金费率上限
settState	String	资金费率结算状态 `processing`：结算中 `settled`：已结算
settFundingRate	String	若 settState = `processing`，该字段代表用于本轮结算的资金费率；若 settState = `settled`，该字段代表用于上轮结算的资金费率
premium	String	溢价，为合约的中间价和指数价格的差异
ts	String	数据更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`

获取永续合约历史资金费率

获取最近3个月的历史资金费率

限速：10次/2s

限速规则：IP +instrumentID

权限：读取

HTTP请求

GET /api/v5/public/funding-rate-history

请求示例

GET /api/v5/public/funding-rate-history?instId=BTC-USD-SWAP

import okx.PublicData as PublicData

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

publicDataAPI = PublicData.PublicAPI(flag=flag)

# 获取永续合约历史资金费率
result = publicDataAPI.funding_rate_history(
    instId="BTC-USD-SWAP",
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID ，如 `BTC-USD-SWAP` 仅适用于`永续`
before	String	否	请求此时间戳之后（更新的数据）的分页内容，传的值为对应接口的`fundingTime`
after	String	否	请求此时间戳之前（更旧的数据）的分页内容，传的值为对应接口的`fundingTime`
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "fundingRate": "0.0000746604960499",
            "fundingTime": "1703059200000",
            "instId": "BTC-USD-SWAP",
            "instType": "SWAP",
            "method": "next_period",
            "realizedRate": "0.0000746572360545"
        },
        {
            "fundingRate": "0.000227985782722",
            "fundingTime": "1703030400000",
            "instId": "BTC-USD-SWAP",
            "instType": "SWAP",
            "method": "next_period",
            "realizedRate": "0.0002279755647389"
        }
  ]
}

返回参数

参数名	类型	描述
instType	String	产品类型 `SWAP`：永续合约
instId	String	产品ID，如 `BTC-USD-SWAP`
fundingRate	String	预计资金费率
realizedRate	String	实际资金费率
fundingTime	String	资金费时间，Unix时间戳的毫秒数格式，如 `1597026383085`
method	String	资金费收取逻辑 `current_period`：当期收 `next_period`：跨期收

获取限价

查询单个交易产品的最高买价和最低卖价

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/public/price-limit

请求示例

GET /api/v5/public/price-limit?instId=BTC-USDT-SWAP

import okx.PublicData as PublicData

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

publicDataAPI = PublicData.PublicAPI(flag=flag)

# 获取限价
result = publicDataAPI.get_price_limit(
    instId="BTC-USD-SWAP",
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 `BTC-USDT-SWAP`

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
    {
        "instType":"SWAP",
        "instId":"BTC-USDT-SWAP",
        "buyLmt":"17057.9",
        "sellLmt":"16388.9",
        "ts":"1597026383085",
        "enabled": true
    }
  ]
}

返回参数

参数名	类型	描述
instType	String	产品类型 `SPOT`：币币 `MARGIN`：杠杆 `SWAP`：永续合约 `FUTURES`：交割合约 `OPTION`：期权若产品ID支持杠杆交易，则返回`MARGIN`；否则，返回`SPOT`。
instId	String	产品ID ，如 `BTC-USDT-SWAP`
buyLmt	String	最高买价当enabled为false时，返回""
sellLmt	String	最低卖价当enabled为false时，返回""
ts	String	限价数据更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
enabled	Boolean	限价是否生效 `true`：限价生效 `false`：限价不生效

获取期权定价

查询期权详细信息

限速：20次/2s

限速规则：IP +uly

权限：读取

HTTP请求

GET /api/v5/public/opt-summary

请求示例

GET /api/v5/public/opt-summary?uly=BTC-USD

import okx.PublicData as PublicData

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

publicDataAPI = PublicData.PublicAPI(flag=flag)

# 获取期权定价
result = publicDataAPI.get_opt_summary(
    uly="BTC-USD",
)
print(result)

请求参数

参数名	类型	是否必须	描述
uly	String	可选	标的指数，仅适用于期权 `uly`与`instFamily`必须传一个,若传两个，以`instFamily`为主
instFamily	String	可选	交易品种，仅适用于期权 `uly`与`instFamily`必须传一个,若传两个，以`instFamily`为主
expTime	String	否	合约到期日，格式为"YYMMDD"，如 "200527"

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
      {
            "askVol": "3.7207056835937498",
            "bidVol": "0",
            "delta": "0.8310206676289528",
            "deltaBS": "0.9857332101544538",
            "fwdPx": "39016.8143629068452065",
            "gamma": "-1.1965483553276135",
            "gammaBS": "0.000011933182397798109",
            "instId": "BTC-USD-220309-33000-C",
            "instType": "OPTION",
            "lever": "0",
            "markVol": "1.5551965233045728",
            "realVol": "0",
            "volLv": "0",
            "theta": "-0.0014131955002093717",
            "thetaBS": "-66.03526900575946",
            "ts": "1646733631242",
            "uly": "BTC-USD",
            "vega": "0.000018173851073258973",
            "vegaBS": "0.7089307622132419"
        },
        {
            "askVol": "1.7968814062499998",
            "bidVol": "0",
            "delta": "-0.014668822072611904",
            "deltaBS": "-0.01426678984554619",
            "fwdPx": "39016.8143629068452065",
            "gamma": "0.49483062407551576",
            "gammaBS": "0.000011933182397798109",
            "instId": "BTC-USD-220309-33000-P",
            "instType": "OPTION",
            "lever": "0",
            "markVol": "1.5551965233045728",
            "realVol": "0",
            "volLv": "0",
            "theta": "-0.0014131955002093717",
            "thetaBS": "-54.93377294845015",
            "ts": "1646733631242",
            "uly": "BTC-USD",
            "vega": "0.000018173851073258973",
            "vegaBS": "0.7089307622132419"
        }
  ]
}

返回参数

参数名	类型	描述
instType	String	产品类型 `OPTION`：期权
instId	String	产品ID，如 `BTC-USD-200103-5500-C`
uly	String	标的指数
delta	String	期权价格对`uly`价格的敏感度
gamma	String	delta对`uly`价格的敏感度
vega	String	期权价格对隐含波动率的敏感度
theta	String	期权价格对剩余期限的敏感度
deltaBS	String	BS模式下期权价格对`uly`价格的敏感度
gammaBS	String	BS模式下delta对`uly`价格的敏感度
vegaBS	String	BS模式下期权价格对隐含波动率的敏感度
thetaBS	String	BS模式下期权价格对剩余期限的敏感度
lever	String	杠杆倍数
markVol	String	标记波动率
bidVol	String	bid波动率
askVol	String	ask波动率
realVol	String	已实现波动率（目前该字段暂未启用）
volLv	String	价平期权的隐含波动率
fwdPx	String	远期价格
ts	String	数据更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`

获取预估交割/行权价格

获取交割合约和期权预估交割/行权价。交割/行权预估价只有交割/行权前一小时才有返回值

限速：10次/2s

限速规则：IP +instrumentID

权限：读取

HTTP请求

GET /api/v5/public/estimated-price

请求示例

GET /api/v5/public/estimated-price?instId=BTC-USDT-191227

import okx.PublicData as PublicData

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

publicDataAPI = PublicData.PublicAPI(flag=flag)

# 获取预估交割/行权价格
result = publicDataAPI.get_estimated_price(
    instId="BTC-USDT-220916",
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 `BTC-USD-200214` 仅适用于`交割/期权`

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
    {
        "instType":"FUTURES",
        "instId":"BTC-USDT-201227",
        "settlePx":"200",
        "ts":"1597026383085"
    }
  ]
}

返回参数

参数名	类型	描述
instType	String	产品类型 `FUTURES`：交割合约 `OPTION`：期权
instId	String	产品ID，如 `BTC-USDT-SWAP`
settlePx	String	预估交割、行权价格
ts	String	数据返回时间，Unix时间戳的毫秒数格式，如 `1597026383085`

获取免息额度和币种折算率等级

限速：2 次/2s

限速规则：IP

权限：读取

HTTP 请求

GET /api/v5/public/discount-rate-interest-free-quota

请求示例

GET /api/v5/public/discount-rate-interest-free-quota?ccy=BTC

import okx.PublicData as PublicData

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

publicDataAPI = PublicData.PublicAPI(flag=flag)

# 获取免息额度和币种折算率等级
result = publicDataAPI.discount_interest_free_quota()
print(result)

请求参数

参数名	类型	是否必须	描述
ccy	String	否	币种
discountLv	String	否	~~折算率等级（已废弃）~~

返回结果

{
    "code": "0",
    "data": [
        {
            "amt": "0",
            "ccy": "BTC",
            "details": [
                {
                    "discountRate": "0.98",
                    "liqPenaltyRate": "0.02",
                    "maxAmt": "20",
                    "minAmt": "0",
                    "tier": "1",
                    "disCcyEq": "1000"
                },
                {
                    "discountRate": "0.9775",
                    "liqPenaltyRate": "0.0225",
                    "maxAmt": "25",
                    "minAmt": "20",
                    "tier": "2",
                    "disCcyEq": "2000"
                }
            ],
            "discountLv": "1",
            "minDiscountRate": "0"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	币种
amt	String	免息金额
discountLv	String	~~折算率等级~~（已废弃）~~~~
minDiscountRate	String	最小折算率，针对数量超过最后一档的最大值时
details	Array	新的币种折算率详情
> discountRate	String	折算率
> maxAmt	String	梯度区间上限，单位为币种，如 BTC，"" 表示正无穷
> minAmt	String	梯度区间下限，单位为币种，如 BTC，最小值是0
> tier	String	档位
> liqPenaltyRate	String	强平罚金费率
> disCcyEq	String	折扣后的币种权益（取当前梯度区间上限），便于快速计算

获取系统时间

限速：10次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/public/time

请求示例

GET /api/v5/public/time

import okx.PublicData as PublicData

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

publicDataAPI = PublicData.PublicAPI(flag=flag)

# 获取系统时间
result = publicDataAPI.get_system_time()
print(result)

返回结果

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

返回参数

参数名	类型	描述
ts	String	系统时间，Unix时间戳的毫秒数格式，如 `1597026383085`

获取标记价格

为了防止个别用户恶意操控市场导致合约价格波动剧烈，我们根据现货指数和合理基差设定标记价格。

限速：10次/2s

限速规则：IP +instrumentID

权限：读取

HTTP请求

GET /api/v5/public/mark-price

请求示例

GET /api/v5/public/mark-price?instType=SWAP

import okx.PublicData as PublicData

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

publicDataAPI = PublicData.PublicAPI(flag=flag)

# 获取标记价格
result = publicDataAPI.get_mark_price(
    instType="SWAP",
)
print(result)

请求参数

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

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
    {
        "instType":"SWAP",
        "instId":"BTC-USDT-SWAP",
        "markPx":"200",
        "ts":"1597026383085"
    }
  ]
}

返回参数

参数名	类型	描述
instType	String	产品类型 `MARGIN`：币币杠杆 `SWAP`：永续合约 `FUTURES`：交割合约 `OPTION`：期权
instId	String	产品ID，如 `BTC-USD-200214`
markPx	String	标记价格
ts	String	接口数据返回时间，Unix时间戳的毫秒数格式，如`1597026383085`

获取衍生品仓位档位

全部仓位档位对应信息，当前最高可开杠杆倍数由您的借币持仓和保证金率决定。

限速：10次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/public/position-tiers

请求示例

GET /api/v5/public/position-tiers?tdMode=cross&instType=SWAP&instFamily=BTC-USDT

import okx.PublicData as PublicData

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

publicDataAPI = PublicData.PublicAPI(flag=flag)

# 获取衍生品仓位档位
result = publicDataAPI.get_position_tiers(
    instType="SWAP",
    tdMode="cross",
    uly="BTC-USD"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instType	String	是	产品类型 `MARGIN`：币币杠杆 `SWAP`：永续合约 `FUTURES`：交割合约 `OPTION`：期权
tdMode	String	是	保证金模式 `isolated`：逐仓；`cross`：全仓
uly	String	可选	标的指数，支持多uly，半角逗号分隔，最大不超过3个当产品类型是`永续`、`交割`、`期权` 之一时，`uly`与`instFamily`必须传一个，若传两个，以`instFamily`为主当产品类型是 `MARGIN` 时忽略
instFamily	String	可选	交易品种，支持多instFamily，半角逗号分隔，最大不超过5个当产品类型是`永续`、`交割`、`期权` 之一时，`uly`与`instFamily`必须传一个，若传两个，以`instFamily`为主
instId	String	可选	产品ID，支持多instId，半角逗号分隔，最大不超过5个仅适用`币币杠杆`，`instId`和`ccy`必须传一个，若传两个，以`instId`为主
ccy	String	可选	保证金币种仅适用杠杆全仓，该值生效时，返回的是`跨币种保证金模式`和`组合保证金模式`下的借币量
tier	String	否	查指定档位

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
    {
            "baseMaxLoan": "50",
            "imr": "0.1",
            "instId": "BTC-USDT",
            "instFamily": "",
            "maxLever": "10",
            "maxSz": "50",
            "minSz": "0",
            "mmr": "0.03",
            "optMgnFactor": "0",
            "quoteMaxLoan": "500000",
            "tier": "1",
            "uly": ""
        }
  ]
}

返回参数

参数名	类型	描述
uly	String	标的指数适用于`交割/永续/期权`
instFamily	String	交易品种适用于`交割/永续/期权`
instId	String	币对
tier	String	仓位档位
minSz	String	该档位最少借币量或者持仓数量杠杆/期权/永续/交割最小持仓量默认0 当 `ccy` 参数生效时，返回 `ccy` 的最小借币量
maxSz	String	该档位最多借币量或者持仓数量杠杆/期权/永续/交割当 `ccy` 参数生效时，返回 `ccy` 的最大借币量
mmr	String	维持保证金率
imr	String	最低初始保证金率
maxLever	String	最高可用杠杆倍数
optMgnFactor	String	期权保证金系数（仅适用于期权）
quoteMaxLoan	String	计价货币最大借币量（仅适用于杠杆，且`instId`参数生效时），例如 BTC-USDT 里的 USDT最大借币量
baseMaxLoan	String	交易货币最大借币量（仅适用于杠杆，且`instId`参数生效时），例如 BTC-USDT 里的 BTC最大借币量

获取市场借币杠杆利率和借币限额

限速：2次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/public/interest-rate-loan-quota

请求示例

GET /api/v5/public/interest-rate-loan-quota

import okx.PublicData as PublicData

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

publicDataAPI = PublicData.PublicAPI(flag=flag)

# 获取市场借币杠杆利率和借币限额
result = publicDataAPI.get_interest_rate_loan_quota()
print(result)

返回结果

{
    "code": "0",
    "data": [
        {
            "basic": [
                {
                    "ccy": "USDT",
                    "quota": "500000",
                    "rate": "0.00043728"
                },
                {
                    "ccy": "BTC",
                    "quota": "10",
                    "rate": "0.00019992"
                }
            ],
            "vip": [
                {
                    "irDiscount": "",
                    "loanQuotaCoef": "6",
                    "level": "VIP1"
                },
                {
                    "irDiscount": "",
                    "loanQuotaCoef": "7",
                    "level": "VIP2"
                }
            ],
            "regular": [
                {
                    "irDiscount": "",
                    "loanQuotaCoef": "1",
                    "level": "Lv1"
                },
                {
                    "irDiscount": "",
                    "loanQuotaCoef": "2",
                    "level": "Lv2"
                }
            ]
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
basic	Array	基础利率和借币限额
> ccy	String	币种
> rate	String	基础杠杆日利率
> quota	String	基础借币限额
vip	Array	专业用户
> level	String	账户交易手续费等级，如 `VIP1`
> loanQuotaCoef	String	借币限额系数，借币限额 = 基础借币限额 * 该系数
> irDiscount	String	~~利率的折扣率~~(已废弃)
regular	Array	普通用户
> level	String	账户交易手续费等级，如 `Lv1`
> loanQuotaCoef	String	借币限额系数，借币限额 = 基础借币限额 * 该系数
> irDiscount	String	~~利率的折扣率~~(已废弃)

获取衍生品标的指数

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/public/underlying

请求示例

GET /api/v5/public/underlying?instType=FUTURES

import okx.PublicData as PublicData

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

publicDataAPI = PublicData.PublicAPI(flag=flag)

# 获取衍生品标的指数
result = publicDataAPI.get_underlying(
    instType="FUTURES"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instType	String	是	产品类型 `SWAP`：永续合约 `FUTURES`：交割合约 `OPTION`：期权

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        [
            "LTC-USDT",
            "BTC-USDT",
            "ETC-USDT"
        ]
    ]
}

返回参数

参数名	类型	描述
uly	Array	标的指数如：BTC-USDT

获取风险准备金余额

通过该接口获取系统风险准备金余额信息

限速：10次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/public/insurance-fund

请求示例

GET /api/v5/public/insurance-fund?instType=SWAP&uly=BTC-USD

import okx.PublicData as PublicData

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

publicDataAPI = PublicData.PublicAPI(flag=flag)


# 获取风险准备金余额
result = publicDataAPI.get_insurance_fund(
    instType="SWAP",
    uly="BTC-USD"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instType	String	是	产品类型 `MARGIN`：币币杠杆 `SWAP`：永续合约 `FUTURES`：交割合约 `OPTION`：期权
type	String	否	风险准备金类型 `regular_update`：定期更新 `liquidation_balance_deposit`：强平注入 `bankruptcy_loss`：穿仓亏损 `platform_revenue`：平台收入注入 `adl`：自动减仓历史数据默认返回全部类型
uly	String	可选	标的指数 `交割/永续/期权`情况下，`uly`与`instFamily`必须传一个，若传两个，以`instFamily`为主
instFamily	String	可选	交易品种 `交割/永续/期权`情况下，`uly`与`instFamily`必须传一个，若传两个，以`instFamily`为主
ccy	String	可选	币种，仅适用`币币杠杆`，且必填写
before	String	否	请求此时间戳之后（更新的数据）的分页内容，传的值为对应接口的`ts`
after	String	否	请求此时间戳之前（更旧的数据）的分页内容，传的值为对应接口的`ts`
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code": "0",
    "data": [
        {
            "details": [
                {
                    "adlType": "",
                    "amt": "",
                    "balance": "1343.1308",
                    "ccy": "ETH",
                    "decRate": "",
                    "maxBal": "",
                    "maxBalTs": "",
                    "ts": "1704883083000",
                    "type": "regular_update"
                }
            ],
            "instFamily": "ETH-USD",
            "instType": "OPTION",
            "total": "1369179138.7489"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
total	String	平台风险准备金总计，单位为USD
instFamily	String	交易品种适用于`交割/永续/期权`
instType	String	产品类型
details	Array of objects	风险准备金详情
> balance	String	风险准备金总量
> amt	String	风险准备金更新数量在type为`liquidation_balance_deposit`，`bankruptcy_loss`，`platform_revenue`时适用
> ccy	String	风险准备金总量对应的币种
> type	String	风险准备金类型
> maxBal	String	过去八小时内的风险准备金余额最大值仅在type为`adl`时适用
> maxBalTs	String	过去八小时内风险准备金余额最大值对应的时间戳，Unix时间戳的毫秒数格式，如 `1597026383085` 仅在type为`adl`时适用
> decRate	String	风险准备金实时下降率（balance与maxBal相比较）仅在type为`adl`时适用
> adlType	String	关于自动减仓的事件 `rate_adl_start`：由于风险准备金下降率过高造成的自动减仓开始 `bal_adl_start`：由于风险准备金余额下降过高造成的自动减仓开始 `pos_adl_start`：由于强平单的规模积累到一定程度的自动减仓开始（仅适用于盘前交易市场） `adl_end`：自动减仓结束仅在type为`adl`时适用
> ts	String	风险准备金更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`

张币转换

由币转换为张，或者张转换为币。

限速：10次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/public/convert-contract-coin

请求示例

GET /api/v5/public/convert-contract-coin?instId=BTC-USD-SWAP&px=35000&sz=0.888

import okx.PublicData as PublicData

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

publicDataAPI = PublicData.PublicAPI(flag=flag)


# 张币转换
result = publicDataAPI.get_convert_contract_coin(
    instId="BTC-USD-SWAP",
    px="35000",
    sz="0.888"
)
print(result)

请求参数

参数名	类型	是否必须	描述
type	String	否	转换类型 `1`：币转张 `2`：张转币默认为`1`
instId	String	是	产品ID，仅适用于`交割/永续/期权`
sz	String	是	数量，币转张时，为币的数量，张转币时，为张的数量。
px	String	可选	委托价格币本位合约的张币转换时必填 U本位合约，usdt 与张的转换时，必填；coin 与张的转换时，可不填期权的张币转换时，可不填。
unit	String	否	币的单位 `coin`：币 `usds`：usdt/usdc 仅适用于`交割`/`永续`的U本位合约
opType	String	否	将要下单的类型 `open`：开仓时将sz舍位 `close`：平仓时将sz四舍五入默认值为`close` 适用于`交割`/`永续`

返回结果

{
    "code": "0",
    "data": [
        {
            "instId": "BTC-USD-SWAP",
            "px": "35000",
            "sz": "311",
            "type": "1",
            "unit": "coin"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
type	String	转换类型 `1`：币转张 `2`：张转币
instId	String	产品ID
px	String	委托价格
sz	String	数量张转币时，为币的数量；币转张时，为张的数量。
unit	String	币的单位 `coin`：币 `usds`：usdt/usdc

获取期权价格梯度

获取期权价格梯度信息

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/public/instrument-tick-bands

请求示例

GET /api/v5/public/instrument-tick-bands?instType=OPTION

请求参数

参数名	类型	是否必须	描述
instType	String	是	产品类型 `OPTION`：期权
instFamily	String	否	交易品种，仅适用于期权

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "instType": "OPTION",
            "instFamily": "BTC-USD",
            "tickBand": [
                {
                    "minPx": "0",
                    "maxPx": "100",
                    "tickSz": "0.1"
                },
                {
                    "minPx": "100",
                    "maxPx": "10000",
                    "tickSz": "1"
                }
            ]
        },
        {
            "instType": "OPTION",
            "instFamily": "ETH-USD",
            "tickBand": [
                {
                    "minPx": "0",
                    "maxPx": "100",
                    "tickSz": "0.1"
                },
                {
                    "minPx": "100",
                    "maxPx": "10000",
                    "tickSz": "1"
                }
            ]
        }
    ]
}

返回参数

参数名	类型	描述
instType	String	产品类型
instFamily	String	交易品种
tickBand	String	下单价格精度梯度
> minPx	String	最低下单价格
> maxPx	String	最高下单价格
> tickSz	String	下单价格精度，如 0.0001

获取溢价历史数据

获取最近6个月的溢价历史数据

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/public/premium-history

请求示例

GET /api/v5/public/premium-history?instId=BTC-USDT-SWAP

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 `BTC-USDT-SWAP` 适用于`永续`
after	String	否	请求此时间戳（不包含）之前的分页内容，传的值为对应接口的`ts`
before	String	否	请求此时间戳（不包含）之后的分页内容，传的值为对应接口的`ts`
limit	String	否	分页返回的结果集数量，最大为`100`。默认返回`100`条。

返回结果

{
    "code": "0",
    "data": [
        {
            "instId": "BTC-USDT-SWAP",
            "premium": "0.0000578896878167",
            "ts": "1713925924000"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品ID ，如 `BTC-USDT-SWAP`
premium	String	溢价，为合约的中间价和指数价格的差异
ts	String	数据产生的时间，Unix时间戳的毫秒数格式，如 `1597026383085`

获取指数行情

获取指数行情数据

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/index-tickers

请求示例

GET /api/v5/market/index-tickers?instId=BTC-USDT

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取指数行情
result = marketDataAPI.get_index_tickers(
    instId="BTC-USD"
)
print(result)

请求参数

参数名	类型	是否必须	描述
quoteCcy	String	可选	指数计价单位，目前只有 `USD/USDT/BTC/USDC`为计价单位的指数，`quoteCcy`和`instId`必须填写一个
instId	String	可选	指数，如 `BTC-USD`

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "instId": "BTC-USDT",
            "idxPx": "43350",
            "high24h": "43649.7",
            "sodUtc0": "43444.1",
            "open24h": "43640.8",
            "low24h": "43261.9",
            "sodUtc8": "43328.7",
            "ts": "1649419644492"
        }
    ]
}

返回参数

参数名	类型	描述
instId	String	指数
idxPx	String	最新指数价格
high24h	String	24小时指数最高价格
low24h	String	24小时指数最低价格
open24h	String	24小时指数开盘价格
sodUtc0	String	UTC 0 时开盘价
sodUtc8	String	UTC+8 时开盘价
ts	String	指数价格更新时间，Unix时间戳的毫秒数格式，如`1597026383085`

获取指数K线数据

指数K线数据每个粒度最多可获取最近1,440条。

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/index-candles

请求示例

GET /api/v5/market/index-candles?instId=BTC-USD

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取指数K线数据
result = marketDataAPI.get_index_candlesticks(
    instId="BTC-USD"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	现货指数，如 `BTC-USD`
after	String	否	请求此时间戳之前（更旧的数据）的分页内容，传的值为对应接口的`ts`
before	String	否	请求此时间戳之后（更新的数据）的分页内容，传的值为对应接口的`ts`, 单独使用时，会返回最新的数据。
bar	String	否	时间粒度，默认值`1m` 如 [`1m`/`3m`/`5m`/`15m`/`30m`/`1H`/`2H`/`4H`] 香港时间开盘价k线：[`6H`/`12H`/`1D`/`1W`/`1M`/`3M`] UTC时间开盘价k线：[`6Hutc`/`12Hutc`/`1Dutc`/`1Wutc`/`1Mutc`/`3Mutc`]
limit	String	否	分页返回的结果集数量，最大为`100`，不填默认返回`100`条

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
     [
        "1597026383085",
        "3.721",
        "3.743",
        "3.677",
        "3.708",
        "0"
    ],
    [
        "1597026383085",
        "3.731",
        "3.799",
        "3.494",
        "3.72",
        "1"
    ]
    ]
}

返回参数

参数名	类型	描述
ts	String	开始时间，Unix时间戳的毫秒数格式，如 `1597026383085`
o	String	开盘价格
h	String	最高价格
l	String	最低价格
c	String	收盘价格
confirm	String	K线状态 `0` 代表 K 线未完结，`1` 代表 K 线已完结。

获取指数历史K线数据

获取最近几年的指数K线数据

限速：10次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/history-index-candles

请求示例

GET /api/v5/market/history-index-candles?instId=BTC-USD

请求参数

参数名	类型	是否必须	描述
instId	String	是	现货指数，如`BTC-USD`
after	String	否	请求此时间戳之前（更旧的数据）的分页内容，传的值为对应接口的`ts`
before	String	否	请求此时间戳之后（更新的数据）的分页内容，传的值为对应接口的`ts`, 单独使用时，会返回最新的数据。
bar	String	否	时间粒度，默认值`1m` 如 [1m/3m/5m/15m/30m/1H/2H/4H] 香港时间开盘价k线：[6H/12H/1D/1W/1M] UTC时间开盘价k线：[/6Hutc/12Hutc/1Dutc/1Wutc/1Mutc]
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
     [
        "1597026383085",
        "3.721",
        "3.743",
        "3.677",
        "3.708",
        "1"
    ],
    [
        "1597026383085",
        "3.731",
        "3.799",
        "3.494",
        "3.72",
        "1"
    ]
    ]
}

返回参数

参数名	类型	描述
ts	String	开始时间，Unix时间戳的毫秒数格式，如 `1597026383085`
o	String	开盘价格
h	String	最高价格
l	String	最低价格
c	String	收盘价格
confirm	String	K线状态 `0` 代表 K 线未完结，`1` 代表 K 线已完结。

获取标记价格K线数据

标记价格K线数据每个粒度最多可获取最近1,440条。

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/mark-price-candles

请求示例

GET /api/v5/market/mark-price-candles?instId=BTC-USD-SWAP

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取标记价格K线数据
result = marketDataAPI.get_mark_price_candlesticks(
    instId="BTC-USD-SWAP"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如`BTC-USD-SWAP`
after	String	否	请求此时间戳之前（更旧的数据）的分页内容，传的值为对应接口的`ts`
before	String	否	请求此时间戳之后（更新的数据）的分页内容，传的值为对应接口的`ts`, 单独使用时，会返回最新的数据。
bar	String	否	时间粒度，默认值`1m` 如 [1m/3m/5m/15m/30m/1H/2H/4H] 香港时间开盘价k线：[6H/12H/1D/1W/1M/3M] UTC时间开盘价k线：[6Hutc/12Hutc/1Dutc/1Wutc/1Mutc/3Mutc]
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
     [
        "1597026383085",
        "3.721",
        "3.743",
        "3.677",
        "3.708",
        "0"
    ],
    [
        "1597026383085",
        "3.731",
        "3.799",
        "3.494",
        "3.72",
        "1"
    ]
    ]
}

返回参数

参数名	类型	描述
ts	String	开始时间，Unix时间戳的毫秒数格式，如 `1597026383085`
o	String	开盘价格
h	String	最高价格
l	String	最低价格
c	String	收盘价格
confirm	String	K线状态 `0` 代表 K 线未完结，`1` 代表 K 线已完结。

获取标记价格历史K线数据

获取最近几年的标记价格K线数据

限速：10次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/history-mark-price-candles

请求示例

GET /api/v5/market/history-mark-price-candles?instId=BTC-USD-SWAP

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如`BTC-USD-SWAP`
after	String	否	请求此时间戳之前（更旧的数据）的分页内容，传的值为对应接口的`ts`
before	String	否	请求此时间戳之后（更新的数据）的分页内容，传的值为对应接口的`ts`, 单独使用时，会返回最新的数据。
bar	String	否	时间粒度，默认值`1m` 如 [1m/3m/5m/15m/30m/1H/2H/4H] 香港时间开盘价k线：[6H/12H/1D/1W/1M] UTC时间开盘价k线：[6Hutc/12Hutc/1Dutc/1Wutc/1Mutc]
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
     [
        "1597026383085",
        "3.721",
        "3.743",
        "3.677",
        "3.708",
        "1"
    ],
    [
        "1597026383085",
        "3.731",
        "3.799",
        "3.494",
        "3.72",
        "1"
    ]
    ]
}

返回参数

参数名	类型	描述
ts	String	开始时间，Unix时间戳的毫秒数格式，如 `1597026383085`
o	String	开盘价格
h	String	最高价格
l	String	最低价格
c	String	收盘价格
confirm	String	K线状态 `0` 代表 K 线未完结，`1` 代表 K 线已完结。

Oracle 上链交易数据

获取使用 Open Oracle 智能合约签名后加密资产价格。

限速：1次/5s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/open-oracle

请求示例

GET /api/v5/market/open-oracle

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# Oracle 上链交易数据
result = marketDataAPI.get_oracle(
)
print(result)

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "messages":[
                "0x000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000616d3b1400000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000e70528b800000000000000000000000000000000000000000000000000000000000000006707269636573000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000034254430000000000000000000000000000000000000000000000000000000000"
            ],
            "prices":{
                "BTC":"62014"
            },
            "signatures":[
                "0xf18330e59eaf42373c2c40f1f9e24113ba21d4ed734dd3ed3bc1d12290fa74ba5623fca1113c5d245a1202dc065e333615b90f810f12132ce4a1ecacb8c6b24a000000000000000000000000000000000000000000000000000000000000001b"
            ],
            "timestamp":"1634548500"
        }
    ]
}

返回参数

参数名	类型	描述
messages	String	数组包含对[ kind，timestamp，key，value]进行ABI编码的值，其中kind恒等于`prices`，timestamp是获取价格的时间戳，key是加密资产（例如，`ETH`），value是资产价格
prices	String	价格
signatures	String	每个消息的以太坊兼容ECDSA签名的数组
timestamp	String	获取最新数据点的时间，Unix时间戳,如 `1597026387`

获取法币汇率

该接口提供的是2周的平均汇率数据

限速：1次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/exchange-rate

请求示例

GET /api/v5/market/exchange-rate

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取法币汇率
result = marketDataAPI.get_exchange_rate(
)
print(result)

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "usdCny": "7.162"
        }
    ]
}

返回参数

参数名	类型	描述
usdCny	String	人民币兑美元汇率

获取指数成分数据

查询市场上的指数成分信息数据

限速：20次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/market/index-components

请求示例

GET /api/v5/market/index-components?index=BTC-USD

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取指数成分数据
result = marketDataAPI.get_index_components(
    index="BTC-USD"
)
print(result)

请求参数

参数名	类型	是否必须	描述
index	String	是	指数，如 `BTC-USDT`

返回结果

{
    "code": "0",
    "msg": "",
    "data": {
        "components": [
            {
                "symbol": "BTC/USDT",
                "symPx": "52733.2",
                "wgt": "0.25",
                "cnvPx": "52733.2",
                "exch": "OKEx"
            },
            {
                "symbol": "BTC/USDT",
                "symPx": "52739.87000000",
                "wgt": "0.25",
                "cnvPx": "52739.87000000",
                "exch": "Binance"
            },
            {
                "symbol": "BTC/USDT",
                "symPx": "52729.1",
                "wgt": "0.25",
                "cnvPx": "52729.1",
                "exch": "Huobi"
            },
            {
                "symbol": "BTC/USDT",
                "symPx": "52739.47929397",
                "wgt": "0.25",
                "cnvPx": "52739.47929397",
                "exch": "Poloniex"
            }
        ],
        "last": "52735.4123234925",
        "index": "BTC-USDT",
        "ts": "1630985335599"
    }
}

返回参数

参数名	类型	描述
index	String	指数名称
last	String	最新指数价格
ts	String	数据产生时间，Unix时间戳的毫秒数格式，如`1597026383085`
components	String	成分
> exch	String	交易所名称
> symbol	String	采集的币对名称
> symPx	String	采集的币对价格
> wgt	String	权重
> cnvPx	String	换算成指数后的价格

获取经济日历数据

获取过去三个月的宏观经济日历数据。三个月前的历史数据仅开放给交易费等级VIP1及以上的用户。

限速：1次/5s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/public/economic-calendar

请求示例

GET /api/v5/public/economic-calendar

请求参数

参数名	类型	是否必须	描述
region	string	否	国家，地区或实体 `afghanistan`, `albania`, `algeria`, `andorra`, `angola`, `antigua_and_barbuda`, `argentina`, `armenia`, `aruba`, `australia`, `austria`, `azerbaijan`, `bahamas`, `bahrain`, `bangladesh`, `barbados`, `belarus`, `belgium`, `belize`, `benin`, `bermuda`, `bhutan`, `bolivia`, `bosnia_and_herzegovina`, `botswana`, `brazil`, `brunei`, `bulgaria`, `burkina_faso`, `burundi`, `cambodia`, `cameroon`, `canada`, `cape_verde`, `cayman_islands`, `central_african_republic`, `chad`, `chile`, `china`, `colombia`, `comoros`, `congo`, `costa_rica`, `croatia`, `cuba`, `cyprus`, `czech_republic`, `denmark`, `djibouti`, `dominica`, `dominican_republic`, `east_timor`, `ecuador`, `egypt`, `el_salvador`, `equatorial_guinea`, `eritrea`, `estonia`, `ethiopia`, `euro_area`, `european_union`, `faroe_islands`, `fiji`, `finland`, `france`, `g20`, `g7`, `gabon`, `gambia`, `georgia`, `germany`, `ghana`, `greece`, `greenland`, `grenada`, `guatemala`, `guinea`, `guinea_bissau`, `guyana`, `hungary`, `haiti`, `honduras`, `hong_kong`, `hungary`, `imf`, `indonesia`, `iceland`, `india`, `indonesia`, `iran`, `iraq`, `ireland`, `isle_of_man`, `israel`, `italy`, `ivory_coast`, `jamaica`, `japan`, `jordan`, `kazakhstan`, `kenya`, `kiribati`, `kosovo`, `kuwait`, `kyrgyzstan`, `laos`, `latvia`, `lebanon`, `lesotho`, `liberia`, `libya`, `liechtenstein`, `lithuania`, `luxembourg`, `macau`, `macedonia`, `madagascar`, `malawi`, `malaysia`, `maldives`, `mali`, `malta`, `mauritania`, `mauritius`, `mexico`, `micronesia`, `moldova`, `monaco`, `mongolia`, `montenegro`, `morocco`, `mozambique`, `myanmar`, `namibia`, `nepal`, `netherlands`, `new_caledonia`, `new_zealand`, `nicaragua`, `niger`, `nigeria`, `north_korea`, `northern_mariana_islands`, `norway`, `opec`, `oman`, `pakistan`, `palau`, `palestine`, `panama`, `papua_new_guinea`, `paraguay`, `peru`, `philippines`, `poland`, `portugal`, `puerto_rico`, `qatar`, `russia`, `republic_of_the_congo`, `romania`, `russia`, `rwanda`, `slovakia`, `samoa`, `san_marino`, `sao_tome_and_principe`, `saudi_arabia`, `senegal`, `serbia`, `seychelles`, `sierra_leone`, `singapore`, `slovakia`, `slovenia`, `solomon_islands`, `somalia`, `south_africa`, `south_korea`, `south_sudan`, `spain`, `sri_lanka`, `st_kitts_and_nevis`, `st_lucia`, `sudan`, `suriname`, `swaziland`, `sweden`, `switzerland`, `syria`, `taiwan`, `tajikistan`, `tanzania`, `thailand`, `togo`, `tonga`, `trinidad_and_tobago`, `tunisia`, `turkey`, `turkmenistan`, `uganda`, `ukraine`, `united_arab_emirates`, `united_kingdom`, `united_states`, `uruguay`, `uzbekistan`, `vanuatu`, `venezuela`, `vietnam`, `world`, `yemen`, `zambia`, `zimbabwe`
importance	string	否	重要性 `1`: 低 `2`: 中等 `3`: 高
before	String	否	查询发布日期(date)之后的内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
after	String	否	查询发布日期(date)之前的内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085` 默认值为请求时刻的时间戳
limit	String	否	分页返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "actual": "7.8%",
            "calendarId": "330631",
            "category": "Harmonised Inflation Rate YoY",
            "ccy": "",
            "date": "1700121600000",
            "dateSpan": "0",
            "event": "Harmonised Inflation Rate YoY",
            "forecast": "7.8%",
            "importance": "1",
            "prevInitial": "",
            "previous": "9%",
            "refDate": "1698710400000",
            "region": "Slovakia",
            "uTime": "1700121605007",
            "unit": "%"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
calendarId	string	经济日历ID
date	string	actual字段值的预期发布时间，Unix时间戳的毫秒数格式，如 `1597026383085`
region	string	国家，地区或实体
category	string	类别名
event	string	事件名
refDate	string	当前事件指向的日期
actual	string	事件实际值
previous	string	当前事件上个周期的最新实际值。若发生数据修正，该字段存储上个周期修正后的实际值。
forecast	string	由权威经济学家共同得出的预测值
dateSpan	string	`0`：事件的具体发生时间已知 `1`：事件的具体发生日期已知，但时间未知
importance	string	重要性 `1`: 低 `2`: 中等 `3`: 高
uTime	string	当前事件的最新更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
prevInitial	string	该事件上一周期的初始值仅在修正发生时有值
ccy	string	事件实际值对应的货币
unit	string	事件实际值对应的单位

WebSocket

产品频道

当有产品状态变化时（如期货交割、期权行权、新合约/币对上线、人工暂停/恢复交易等），推送产品的增量数据。
(2022年12月28日起不再推送全量数据，点此查看详情)；

URL Path

/ws/v5/public

请求示例

{ 
  "op": "subscribe",  
  "args":   [    
    {     
      "channel": "instruments",
      "instType": "SPOT"
    }
  ] 
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `instruments`
> instType	String	是	产品类型 `SPOT`：币币 `MARGIN`：币币杠杆 `SWAP`：永续合约 `FUTURES`：交割合约 `OPTION`：期权

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "instruments",
        "instType": "SPOT"
    },
    "connId": "a4d3ae55"
}

失败返回示例

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

返回参数

参数	类型	是否必须	描述
event	String	是	事件 `subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名
> instType	String	是	产品类型 `SPOT`：币币 `MARGIN`：币币杠杆 `SWAP`：永续合约 `FUTURES`：交割合约 `OPTION`：期权
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket连接ID

推送示例

{
  "arg": {
    "channel": "instruments",
    "instType": "SPOT"
  },
  "data": [
    {
        "alias": "",
        "auctionEndTime": "",
        "baseCcy": "BTC",
        "category": "1",
        "ctMult": "",
        "ctType": "",
        "ctVal": "",
        "ctValCcy": "",
        "expTime": "",
        "instFamily": "",
        "instId": "BTC-USDT",
        "instType": "SPOT",
        "lever": "10",
        "listTime": "1606468572000",
        "lotSz": "0.00000001",
        "maxIcebergSz": "9999999999.0000000000000000",
        "maxLmtAmt": "1000000",
        "maxLmtSz": "9999999999",
        "maxMktAmt": "1000000",
        "maxMktSz": "",
        "maxStopSz": "",
        "maxTriggerSz": "9999999999.0000000000000000",
        "maxTwapSz": "9999999999.0000000000000000",
        "minSz": "0.00001",
        "optType": "",
        "quoteCcy": "USDT",
        "settleCcy": "",
        "state": "live",
        "ruleType": "normal",
        "stk": "",
        "tickSz": "0.1",
        "uly": ""
    }
  ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅的频道
> channel	String	频道名
> instType	String	产品类型
data	Array	订阅的数据
> instType	String	产品类型
> instId	String	产品ID，如 `BTC-USDT`
> category	String	~~币种类别~~（已废弃）
> uly	String	标的指数，如 `BTC-USD`，仅适用于`交割/永续/期权`
> instFamily	String	交易品种，如 `BTC-USD`，仅适用于`交割/永续/期权`
> baseCcy	String	交易货币币种，如 `BTC-USDT`中`BTC`，仅适用于`币币/币币杠杆`
> quoteCcy	String	计价货币币种，如 `BTC-USDT`中`USDT`，仅适用于`币币/币币杠杆`
> settleCcy	String	盈亏结算和保证金币种，如 `BTC`，仅适用于 `交割/永续/期权`
> ctVal	String	合约面值
> ctMult	String	合约乘数
> ctValCcy	String	合约面值计价币种
> optType	String	期权类型 `C`：看涨期权 `P`：看跌期权仅适用于`期权`
> stk	String	行权价格，仅适用于 `期权`
> listTime	String	上线时间
> auctionEndTime	String	集合竞价结束时间，Unix时间戳的毫秒数格式，如 `1597026383085` 仅适用于通过集合竞价方式上线的`币币`，其余情况返回""
> expTime	String	产品下线时间适用于`币币/杠杆/交割/永续/期权`，对于 `交割/期权`，为自然的交割/行权时间；如果`币币/杠杆/交割/永续`产品人工下线，为产品下线时间，有变动就会推送。
> lever	String	该产品支持的最大杠杆倍数不适用于`币币`/`期权`。可用来区分`币币杠杆`和`币币`
> tickSz	String	下单价格精度，如 `0.0001` 对于期权来说，是梯度中的最小下单价格精度。
> lotSz	String	下单数量精度合约的数量单位是`张`，现货的数量单位是`交易货币`
> minSz	String	最小下单数合约的数量单位是`张`，现货的数量单位是`交易货币`
> ctType	String	合约类型 `linear`：正向合约 `inverse`：反向合约仅适用于`交割/永续`
> alias	String	合约日期别名 `this_week`：本周 `next_week`：次周 `this_month`：本月 `next_month`：次月 `quarter`：季度 `next_quarter`：次季度仅适用于`交割` 不建议使用，用户应通过 expTime 字段获取合约的交割日期
> state	String	产品状态 `live`：交易中 `suspend`：暂停中 `expired`：已过期 `preopen`：预上线，交割和期权合约轮转生成到开始交易；部分交易产品上线前 `test`：测试中（测试产品，不可交易）
> ruleType	String	交易规则类型 `normal`：普通交易 `pre_market`：盘前交易
> maxLmtSz	String	限价单的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`交易货币`
> maxMktSz	String	市价单的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`USDT`
> maxTwapSz	String	时间加权单的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`交易货币`
> maxIcebergSz	String	冰山委托的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`交易货币`
> maxTriggerSz	String	计划委托委托的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`交易货币`
> maxStopSz	String	止盈止损市价委托的单笔最大委托数量合约的数量单位是`张`，现货的数量单位是`USDT`

持仓总量频道

获取持仓总量，每3s有数据更新推送一次数据

URL Path

/ws/v5/public

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "open-interest",
        "instId": "LTC-USD-SWAP"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `open-interest`
> instId	String	是	产品ID

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "open-interest",
        "instId": "LTC-USD-SWAP"
    },
    "connId": "a4d3ae55"
}

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"open-interest\", \"instId\" : \"LTC-USD-SWAP\"}]}",
    "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
    "arg": {
        "channel": "open-interest",
        "instId": "LTC-USD-SWAP"
    },
    "data": [{
        "instType": "SWAP",
        "instId": "LTC-USD-SWAP",
        "oi": "5000",
        "oiCcy": "555.55",
        "ts": "1597026383085"
    }]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
data	Array	订阅的数据
> instType	String	产品类型
> instId	String	产品ID，如 `LTC-USD-SWAP`
> oi	String	持仓量，按张为单位，open interest
> oiCcy	String	持仓量，按币为单位
> ts	String	数据更新的时间，Unix时间戳的毫秒数格式，如 `1597026383085`

资金费率频道

获取永续合约资金费率，30秒到90秒内推送一次数据

URL Path

/ws/v5/public

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "funding-rate",
        "instId": "BTC-USD-SWAP"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `funding-rate`
> instId	String	是	产品ID

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "funding-rate",
        "instId": "BTC-USD-SWAP"
    },
    "connId": "a4d3ae55"
}

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"funding-rate\", \"instId\" : \"BTC-USD-SWAP\"}]}",
    "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
   "arg":{
      "channel":"funding-rate",
      "instId":"BTC-USD-SWAP"
   },
   "data":[
      {
         "fundingRate":"0.0001875391284828",
         "fundingTime":"1700726400000",
         "instId":"BTC-USD-SWAP",
         "instType":"SWAP",
         "method": "next_period",
         "maxFundingRate":"0.00375",
         "minFundingRate":"-0.00375",
         "nextFundingRate":"0.0002608059239328",
         "nextFundingTime":"1700755200000",
         "premium": "0.0001233824646391",
         "settFundingRate":"0.0001699799259033",
         "settState":"settled",
         "ts":"1700724675402"
      }
   ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
data	Array	订阅的数据
> instType	String	产品类型，`SWAP`
> instId	String	产品ID，如 `BTC-USD-SWAP`
> method	String	资金费收取逻辑 `current_period`：当期收 `next_period`：跨期收
> fundingRate	String	资金费率
> fundingTime	String	最新的到期结算的资金费时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> nextFundingRate	String	下一期预测资金费率
> nextFundingTime	String	下一期资金费时间，Unix时间戳的毫秒数格式，如 `1622851200000`
> minFundingRate	String	下一期的预测资金费率下限
> maxFundingRate	String	下一期的预测资金费率上限
> settState	String	资金费率结算状态 `processing`：结算中 `settled`：已结算
> settFundingRate	String	若 settState = `processing`，该字段代表用于本轮结算的资金费率；若 settState = `settled`，该字段代表用于上轮结算的资金费率
> premium	String	溢价，为合约的中间价和指数价格的差异
> ts	String	数据更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`

限价频道

获取交易产品的最高买价和最低卖价。限价有变化时，每秒推送一次数据，限价没变化时，不推送数据

URL Path

/ws/v5/public

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "price-limit",
        "instId": "LTC-USD-190628"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `price-limit`
> instId	String	是	产品ID

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "price-limit",
        "instId": "LTC-USD-190628"
    },
    "connId": "a4d3ae55"
}

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"price-limit\", \"instId\" : \"LTC-USD-190628\"}]}",
    "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
    "arg": {
        "channel": "price-limit",
        "instId": "LTC-USD-190628"
    },
    "data": [{
        "instId": "LTC-USD-190628",
        "buyLmt": "200",
        "sellLmt": "300",
        "ts": "1597026383085",
        "enabled": true
    }]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
data	Array	订阅的数据
> instType	String	产品类型
> instId	String	产品ID，如 `BTC-USD-SWAP`
> buyLmt	String	最高买价当enabled为false时，返回""
> sellLmt	String	最低卖价当enabled为false时，返回""
> ts	String	限价数据更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> enabled	Boolean	限价是否生效 `true`：限价生效 `false`：限价不生效

期权定价频道

获取所有期权合约详细定价信息，一次性推送所有

URL Path

/ws/v5/public

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "opt-summary",
        "instFamily": "BTC-USD"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `opt-summary`
> instFamily	String	是	交易品种

返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "opt-summary",
        "instFamily": "BTC-USD"
    },
    "connId": "a4d3ae55"
}

失败示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"opt-summary\", \"instFamily\" : \"BTC-USD\"}]}",
    "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
    "arg": {
        "channel": "opt-summary",
        "instFamily": "BTC-USD"
    },
    "data": [
        {
            "instType": "OPTION",
            "instId": "BTC-USD-241013-70000-P",
            "uly": "BTC-USD",
            "delta": "-1.1180902625",
            "gamma": "2.2361957091",
            "vega": "0.0000000001",
            "theta": "0.0000032334",
            "lever": "8.465747567",
            "markVol": "0.3675503331",
            "bidVol": "0",
            "askVol": "1.1669998535",
            "realVol": "",
            "deltaBS": "-0.9999672034",
            "gammaBS": "0.0000000002",
            "thetaBS": "28.2649858387",
            "vegaBS": "0.0000114332",
            "ts": "1728703155650",
            "fwdPx": "62604.6993093463",
            "volLv": "0.2044711229"
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instFamily	String	交易品种
data	Array	订阅的数据
> instType	String	产品类型， `OPTION`
> instId	String	产品ID
> uly	String	标的指数
> delta	String	期权价格对`uly`价格的敏感度
> gamma	String	delta对`uly`价格的敏感度
> vega	String	期权价格对隐含波动率的敏感度
> theta	String	期权价格对剩余期限的敏感度
> deltaBS	String	BS模式下期权价格对`uly`价格的敏感度
> gammaBS	String	BS模式下delta对`uly`价格的敏感度
> vegaBS	String	BS模式下期权价格对隐含波动率的敏感度
> thetaBS	String	BS模式下期权价格对剩余期限的敏感度
> lever	String	杠杆倍数
> markVol	String	标记波动率
> bidVol	String	bid波动率
> askVol	String	ask波动率
> realVol	String	已实现波动率，目前该字段暂未启用
> volLv	String	价平期权的隐含波动率
> fwdPx	String	远期价格
> ts	String	数据更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`

预估交割/行权价格频道

获取永续合约，交割合约和期权预估交割/行权价。交割/行权预估价只有交割/行权前一小时开始推送预估交割/行权价，有价格变化就推送

URL Path

/ws/v5/public

请求示例

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

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `estimated-price`
> instType	String	是	产品类型 `FUTURES`：交割合约 `SWAP`：永续合约 `OPTION`：期权
> instFamily	String	可选	交易品种 `instFamily`和`instId`必须指定一个
> instId	String	可选	产品ID `instFamily`和`instId`必须指定一个

成功返回示例

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

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"estimated-price\", \"instId\" : \"FUTURES\",\"instFamily\" :\"BTC-USD\"}]}",
    "connId": "a4d3ae55"
}

返回参数

参数	类型	是否必须	描述
event	String	是	事件 `subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名
> instType	String	是	产品类型 `FUTURES`：交割合约 `SWAP`：永续合约 `OPTION`：期权
> instFamily	String	否	交易品种
> instId	String	否	产品ID
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket连接ID

推送示例

{
    "arg": {
        "channel": "estimated-price",
        "instType": "FUTURES",
        "instFamily": "BTC-USD"
    },
    "data": [{
        "instType": "FUTURES",
        "instId": "BTC-USD-170310",
        "settlePx": "200",
        "ts": "1597026383085"
    }]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instType	String	产品类型 `FUTURES`：交割合约 `SWAP`：永续合约 `OPTION`：期权
> instFamily	String	交易品种
> instId	String	产品ID
data	Array	订阅的数据
> instType	String	产品类型
> instId	String	产品ID，如 `BTC-USD-170310`
> settlePx	String	预估交割/行权价
> ts	String	数据更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`

标记价格频道

获取标记价格，标记价格有变化时，每200ms推送一次数据，标记价格没变化时，每10s推送一次数据

URL Path

/ws/v5/public

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "mark-price",
        "instId": "BTC-USDT"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `mark-price`
> instId	String	是	产品ID

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "mark-price",
        "instId": "BTC-USDT"
    },
    "connId": "a4d3ae55"
}

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"mark-price\", \"instId\" : \"LTC-USD-190628\"}]}",
    "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
  "arg": {
    "channel": "mark-price",
    "instId": "BTC-USDT"
  },
  "data": [
    {
      "instType": "MARGIN",
      "instId": "BTC-USDT",
      "markPx": "42310.6",
      "ts": "1630049139746"
    }
  ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
data	Array	订阅的数据
> instType	String	交易品种
> instId	String	产品ID
> markPx	String	标记价格
> ts	String	标记价格数据更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`

指数行情频道

获取指数的行情数据。每100ms有变化就推送一次数据，否则一分钟推一次。

URL Path

/ws/v5/public

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "index-tickers",
        "instId": "BTC-USDT"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	`subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `index-tickers`
> instId	String	是	指数，以USD、USDT、BTC、USDC 为计价货币的指数，如 `BTC-USDT`

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "index-tickers",
        "instId": "BTC-USDT"
    },
    "connId": "a4d3ae55"
}

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"index-tickers\", \"instId\" : \"BTC-USDT\"}]}",
    "connId": "a4d3ae55"
}

返回参数

参数	类型	是否必须	描述
event	String	是	`subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名 `index-tickers`
> instId	String	是	指数，以USD、USDT、BTC、USDC 为计价货币的指数，如 `BTC-USDT`
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket连接ID

推送示例

{
    "arg": {
        "channel": "index-tickers",
        "instId": "BTC-USDT"
    },
    "data": [{
        "instId": "BTC-USDT",
        "idxPx": "0.1",
        "high24h": "0.5",
        "low24h": "0.1",
        "open24h": "0.1",
        "sodUtc0": "0.1",
        "sodUtc8": "0.1",
        "ts": "1597026383085"
    }]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	指数
data	Array	订阅的数据
> instId	String	指数，以USD、USDT、BTC 为计价货币的指数，如 `BTC-USDT`
> idxPx	String	最新指数价格
> open24h	String	24小时开盘价
> high24h	String	24小时指数最高价格
> low24h	String	24小时指数最低价格
> sodUtc0	String	UTC 0 时开盘价
> sodUtc8	String	UTC+8 时开盘价
> ts	String	指数价格更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`

标记价格K线频道

获取标记价格的K线数据，推送频率最快是间隔1秒推送一次数据。

URL Path

/ws/v5/business

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "mark-price-candle1D",
        "instId": "BTC-USD-190628"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `mark-price-candle3M` `mark-price-candle1M` `mark-price-candle1W` `mark-price-candle1D` `mark-price-candle2D` `mark-price-candle3D` `mark-price-candle5D` `mark-price-candle12H` `mark-price-candle6H` `mark-price-candle4H` `mark-price-candle2H` `mark-price-candle1H` `mark-price-candle30m` `mark-price-candle15m` `mark-price-candle5m` `mark-price-candle3m` `mark-price-candle1m` `mark-price-candle3Mutc` `mark-price-candle1Mutc` `mark-price-candle1Wutc` `mark-price-candle1Dutc` `mark-price-candle2Dutc` `mark-price-candle3Dutc` `mark-price-candle5Dutc` `mark-price-candle12Hutc` `mark-price-candle6Hutc`
> instId	String	是	产品ID

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "mark-price-candle1D",
        "instId": "BTC-USD-190628"
    },
    "connId": "a4d3ae55"
}

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"mark-price-candle1D\", \"instId\" : \"BTC-USD-190628\"}]}",
    "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
    "arg": {
        "channel": "mark-price-candle1D",
        "instId": "BTC-USD-190628"
    },
    "data": [
        ["1597026383085", "3.721", "3.743", "3.677", "3.708", "0"],
        ["1597026383085", "3.731", "3.799", "3.494", "3.72", "1"]
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
data	Array	订阅的数据
> ts	String	开始时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> o	String	开盘价格
> h	String	最高价格
> l	String	最低价格
> c	String	收盘价格
> confirm	String	K线状态 `0` 代表 K 线未完结，`1` 代表 K 线已完结。

指数K线频道

获取指数的K线数据，推送频率最快是间隔1秒推送一次数据。

URL Path

/ws/v5/business

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "index-candle30m",
        "instId": "BTC-USD"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `index-candle3M` `index-candle1M` `index-candle1W` `index-candle1D` `index-candle2D` `index-candle3D` `index-candle5D` `index-candle12H` `index-candle6H` `index-candle4H` `index -candle2H` `index-candle1H` `index-candle30m` `index-candle15m` `index-candle5m` `index-candle3m` `index-candle1m` `index-candle3Mutc` `index-candle1Mutc` `index-candle1Wutc` `index-candle1Dutc` `index-candle2Dutc` `index-candle3Dutc` `index-candle5Dutc` `index-candle12Hutc` `index-candle6Hutc`
> instId	String	是	现货指数，如 `BTC-USD`

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "index-candle30m",
        "instId": "BTC-USD"
    },
    "connId": "a4d3ae55"
}

失败返回示例

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"index-candle30m\", \"instId\" : \"BTC-USD\"}]}",
    "connId": "a4d3ae55"
}

返回参数

参数	类型	是否必须	描述
event	String	是	`subscribe` `unsubscribe`
arg	Object	否	订阅的频道
> channel	String	是	频道名
> instId	String	否	现货指数
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket连接ID

推送示例

{
    "arg": {
        "channel": "index-candle30m",
        "instId": "BTC-USD"
    },
    "data": [
        ["1597026383085", "3811.31", "3811.31", "3811.31", "3811.31","0"]
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	现货指数
data	Array	订阅的数据
> ts	String	开始时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> o	String	开盘价格
> h	String	最高价格
> l	String	最低价格
> c	String	收盘价格
> confirm	String	K线状态 `0` 代表 K 线未完结，`1` 代表 K 线已完结。

平台公共爆仓单频道

获取爆仓单信息。对于交割和永续合约，强平数据代表每个交易对在任何一秒内的最多一个强平订单。因此，显示的强平数据并不准确代表欧易的总强平量，亦不应被当做总强平量使用。

URL Path

/ws/v5/public

请求示例

{
  "op": "subscribe",
  "args": [
    {
      "channel": "liquidation-orders",
      "instType": "SWAP"
    }
  ]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，`subscribe` `unsubscribe`
args	Array	是	请求订阅的频道
> channel	String	是	频道名 `liquidation-orders`
> instType	String	是	产品类型 `MARGIN`：币币杠杆 `SWAP`：永续合约 `FUTURES`：交割合约 `OPTION`：期权

返回结果

{
    "arg": {
        "channel": "liquidation-orders",
        "instType": "SWAP"
    },
    "data": [
        {
            "details": [
                {
                    "bkLoss": "0",
                    "bkPx": "0.007831",
                    "ccy": "",
                    "posSide": "short",
                    "side": "buy",
                    "sz": "13",
                    "ts": "1692266434010"
                }
            ],
            "instFamily": "IOST-USDT",
            "instId": "IOST-USDT-SWAP",
            "instType": "SWAP",
            "uly": "IOST-USDT"
        }
    ]
}

返回参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instType	String	产品类型
data	Array	订阅的数据
> instType	String	产品类型
> instId	String	产品ID，如 `BTC-USD-SWAP`
> uly	String	标的指数，仅适用于`交割/永续/期权`
> details	Array	详细内容
>> side	String	订单方向 `buy`：买 `sell`：卖，仅适用于`交割/永续`
>> posSide	String	持仓方向 `long`：多 `short`：空 `side`和`posSide`组合方式，sell/long：强平多 ; buy/short:强平空，仅适用于`交割/永续`
>> bkPx	String	破产价格，与系统爆仓账号委托成交的价格，仅适用于`交割/永续`
>> sz	String	强平数量，仅适用于`杠杆/交割/永续`
>> bkLoss	String	穿仓亏损数量
>> ccy	String	强平币种，仅适用于`币币杠杆`
>> ts	String	强平发生的时间，Unix时间戳的毫秒数格式，如 `1597026383085` /

自动减仓预警频道

自动减仓预警。

普通状态（normal）下，每分钟推送一次，展示风险准备金的余额等信息。

预警状态下或有自动减仓风险（warning/adl）时，每1秒推送一次数据，展示风险准备金的实时下降率等信息。

更多自动减仓细节，请见自动减仓机制介绍

服务地址

/ws/v5/public

请求示例

{
    "op": "subscribe",
    "args": [{
        "channel": "adl-warning",
        "instType": "FUTURES",
        "instFamily": "BTC-USDT"
    }]
}

请求参数

参数	类型	是否必须	描述
op	String	是	操作，`subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `adl-warning`
> instType	String	是	产品类型 `FUTURES`：交割合约 `SWAP`：永续合约 `OPTION`：期权
> instFamily	String	否	交易品种

成功返回示例

{
   "event":"subscribe",
   "arg":{
      "channel":"adl-warning",
      "instType":"FUTURES",
      "instFamily":"BTC-USDT"
   },
   "connId":"48d8960a"
}

失败返回示例

{
   "event":"error",
   "msg":"Illegal request: { \"event\": \"subscribe\", \"arg\": { \"channel\": \"adl-warning\", \"instType\": \"FUTURES\", \"instFamily\": \"BTC-USDT\" } }",
   "code":"60012",
   "connId":"48d8960a"
}

返回参数

参数	类型	是否必须	描述
event	String	是	事件，`subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名 `adl-warning`
> instType	String	是	产品类型
> instFamily	String	否	交易品种
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket连接ID

推送示例

{
   "arg":{
      "channel":"adl-warning",
      "instType":"FUTURES",
      "instFamily":"BTC-USDT"
   },
   "data":[
      {
         "decRate":"",
         "maxBal":"",
         "adlRecRate":"0.25",
         "adlRecBal":"8000.0",
         "bal":"280784384.9564228289548144",
         "instType":"FUTURES",
         "adlRate":"0.5",
         "ccy": "USDT",
         "instFamily":"BTC-USDT",
         "maxBalTs":"",
         "adlType":"",
         "state":"normal",
         "adlBal":"0",
         "ts":"1700210763001"
      }
   ]
}

推送数据参数

参数名	类型	描述
arg	Object	请求订阅的频道
> channel	String	频道名 `adl-warning`
> instType	String	是
> instFamily	String	可选
data	Array	订阅的数据
> instType	String	是
> instFamily	String	交易品种
> state	String	状态 `normal`：普通状态 `warning`：预警状态 `adl`：已开启自动减仓
> bal	String	实时风险准备金余额
> ccy	String	风险准备金余额对应币种
> maxBal	String	过去八小时内的风险准备金余额最大值仅在状态为`warning`及`adl`时推送，状态为`normal`时推送空字符串""
> maxBalTs	String	过去八小时内风险准备金余额最大值对应的时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
> decRate	String	风险准备金实时下降率（bal与maxBal相比较）仅在状态为`warning`及`adl`时推送，状态为`normal`时推送空字符串""
> adlType	String	关于自动减仓的事件 `rate_adl_start`：由于风险准备金下降率过高造成的自动减仓开始 `bal_adl_start`：由于风险准备金余额下降过高造成的自动减仓开始 `pos_adl_start`：由于强平单的规模积累到一定程度的自动减仓开始（仅适用于盘前交易市场） `adl_end`：自动减仓结束
> adlBal	String	触发自动减仓的风险准备金余额
> adlRate	String	触发自动减仓的风险准备金下降率
> adlRecBal	String	自动减仓结束的风险准备金余额
> adlRecRate	String	自动减仓结束的风险准备金下降率
> ts	String	数据更新时间，Unix时间戳的毫秒数格式，如 1597026383085

经济日历频道

获取最新经济日历数据。该频道仅开放给交易费等级VIP1及以上的用户。

服务地址

/ws/v5/business (需要登录)

请求示例

{
    "op": "subscribe",
    "args": [
      {
          "channel": "economic-calendar"
      }
    ]
}

请求参数

参数名	类型	是否必填	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `economic-calendar`

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "economic-calendar"
    }
}

失败返回示例

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"economic-calendar\", \"instId\" : \"LTC-USD-190628\"}]}"
}

返回参数

参数名	类型	是否必填	描述
event	String	是	操作 `subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名 `economic-calendar`
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket连接ID

推送示例

{
    "arg": {
        "channel": "economic-calendar"
    },
    "data": [
        {
            "calendarId": "319275",
            "date": "1597026383085",
            "region": "United States",
            "category": "Manufacturing PMI",
            "event": "S&P Global Manufacturing PMI Final",
            "refDate": "1597026383085",
            "actual": "49.2",
            "previous": "47.3",
            "forecast": "49.3",
            "importance": "2",
            "prevInitial": "",
            "ccy": "",
            "unit": "",
            "ts": "1698648096590"
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
data	Array	订阅的数据
> event	string	事件名
> region	string	国家，地区或实体
> category	string	类别名
> actual	string	事件实际值
> previous	string	当前事件上个周期的最新实际值若发生数据修正，该字段存储上个周期修正后的实际值
> forecast	string	由权威经济学家共同得出的预测值
> prevInitial	string	该事件上一周期的初始值仅在修正发生时有值
> date	string	actual字段值的预期发布时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> refDate	string	当前事件指向的日期
> calendarId	string	经济日历ID
> unit	string	事件实际值对应的单位
> ccy	string	事件实际值对应的货币
> importance	string	重要性 `1`: 低 `2`: 中等 `3`: 高
> ts	string	推送时间

交易大数据

REST API

获取交易大数据支持币种

获取支持交易大数据的币种

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/rubik/stat/trading-data/support-coin

请求示例

GET /api/v5/rubik/stat/trading-data/support-coin

import okx.TradingData as TradingData_api

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

tradingDataAPI = TradingData_api.TradingDataAPI(flag=flag)

# 获取交易大数据支持币种
result = tradingDataAPI.get_support_coin()
print(result)

返回结果

{
    "code": "0",
    "data": {
        "contract": [
            "ADA",
            "BTC",
        ],
        "option": [
            "BTC"
        ],
        "spot": [
            "ADA",
            "BTC",
        ]
    },
    "msg": ""
}

返回参数

参数名	类型	描述
contract	Array of strings	合约交易大数据接口功能支持的币种
option	Array of strings	期权交易大数据接口功能支持的币种
spot	Array of strings	现货交易大数据接口功能支持的币种

获取合约持仓量历史

获取交割及永续合约的历史持仓量数据。每个粒度最多可获取最近1,440条数据。

对于时间粒度period=1D，数据时间范围最早至2024年1月1日；对于其他时间粒度period，最早至2024年2月初。

限速：10次/2s

限速规则：IP + instrumentID

权限：读取

HTTP请求

GET /api/v5/rubik/stat/contracts/open-interest-history

请求示例

GET /api/v5/rubik/stat/contracts/open-interest-history?instId=BTC-USDT-SWAP

import okx.TradingData as TradingData_api

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

tradingDataAPI = TradingData_api.TradingDataAPI(flag=flag)

# 获取持仓量历史
result = tradingDataAPI.get_open_interest_history(
    instId="BTC-USDT-SWAP"
)

print(result)

请求参数

参数名	类型	是否必须	描述
instId	string	是	产品ID，如 BTC-USDT-SWAP 仅适用于`交割`，`永续`
period	string	否	时间粒度，默认值`5m`, 如 [`5m/15m/30m/1H/2H/4H`] 香港时间开盘价k线：[`6H/12H/1D/2D/3D/5D/1W/1M/3M`] UTC时间开盘价k线： [`6Hutc/12Hutc/1Dutc/2Dutc/3Dutc/5Dutc/1Wutc/1Mutc/3Mutc`]
end	string	否	筛选的结束时间戳 ts，Unix 时间戳为毫秒数格式，如 `1597027383085`
begin	string	否	筛选的开始时间戳 ts，Unix 时间戳为毫秒数格式，如 `1597026383085`
limit	string	否	分页返回的结果集数量，最大为`100`，不填默认返回`100`条

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        [
            "1701417600000",    // timestamp
            "731377.57500501",   // open interest (oi, contracts)
            "111",              // open interest (oiCcy, coin)
            "8888888"         // open interest (oiUsd, USD)
        ],
        [
            "1701417500000",    // timestamp
            "731377.57500501",   // open interest (oi, contracts)
            "111",              // open interest (oiCcy, coin)
            "8888888"         // open interest (oiUsd, USD)
        ]
    ]
}

返回参数

参数名	类型	描述
ts	String	时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
oi	String	合约单位的持仓量
oiCcy	String	币种单位的持仓量
oiUsd	String	USD单位的持仓量

返回值数组顺序分别为是：[ts, oi, oiCcy, oiUsd]

获取主动买入/卖出情况

获取taker主动买入和卖出的交易量

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/rubik/stat/taker-volume

请求示例

GET /api/v5/rubik/stat/taker-volume?ccy=BTC&instType=SPOT

import okx.TradingData as TradingData_api

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

tradingDataAPI = TradingData_api.TradingDataAPI(flag=flag)

# 获取主动买入/卖出情况
result = tradingDataAPI.get_taker_volume(
    ccy="BTC",
    instType="SPOT"
)
print(result)

请求参数

参数名	类型	是否必须	描述
ccy	String	是	币种
instType	String	是	产品类型 `SPOT`：币币 `CONTRACTS`：衍生品
begin	String	否	开始时间，Unix时间戳的毫秒数格式，如 `1597026383085`
end	String	否	结束时间，Unix时间戳的毫秒数格式，如 `1597026383011`
period	String	否	时间粒度，默认值`5m`。支持[`5m`/`1H`/`1D`] `5m`粒度最多只能查询两天之内的数据 `1H`粒度最多只能查询30天之内的数据 `1D`粒度最多只能查询180天之内的数据

返回结果

{
    "code": "0",
    "data": [
        [
            "1630425600000",
            "7596.2651",
            "7149.4855"
        ],
        [
            "1630339200000",
            "5312.7876",
            "7002.7541"
        ]
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ts	String	数据产生时间
sellVol	String	卖出量
buyVol	String	买入量

获取合约主动买入/卖出情况

获取合约维度taker主动买入和卖出的交易量。每个粒度最多可获取最近1,440条数据。

对于时间粒度period=1D，数据时间范围最早至2024年1月1日；对于其他时间粒度period，最早至2024年2月初。

限速： 5次/2s

限速规则： IP + instrumentID

权限：读取

HTTP请求

GET /api/v5/rubik/stat/taker-volume-contract

请求示例

GET /api/v5/rubik/stat/taker-volume-contract?instId=BTC-USDT-SWAP

import okx.TradingData as TradingData_api

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

tradingDataAPI = TradingData_api.TradingDataAPI(flag=flag)

# 获取合约taker主动买入和卖出的交易量
result = tradingDataAPI.get_contract_taker_volume(
    instId="BTC-USDT-SWAP"
)

print(result)

请求参数

参数名	类型	是否必须	描述
instId	string	是	产品ID，如 BTC-USDT 仅适用于`交割`，`永续`
period	string	否	时间粒度，默认值`5m`, 如 [`5m/15m/30m/1H/2H/4H`] 香港时间开盘价k线：[`6H/12H/1D/2D/3D/5D/1W/1M/3M`] UTC时间开盘价k线： [`6Hutc/12Hutc/1Dutc/2Dutc/3Dutc/5Dutc/1Wutc/1Mutc/3Mutc`]
unit	string	否	买入、卖出的单位，默认值是`1` `0`: 币 `1`: 合约 `2`: U
end	string	否	筛选的结束时间戳 ts，Unix 时间戳为毫秒数格式，如 `1597027383085`
begin	string	否	筛选的开始时间戳 ts，Unix 时间戳为毫秒数格式，如 `1597026383085`
limit	string	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        [
            "1701417600000",    // timestamp
            "200",              // taker sell volume
            "380"               // taker buy volume
        ],
        [
            "1701417600000",    // timestamp
            "100",              // taker sell volume
            "300"               // taker buy volume
        ]
    ]
}

返回参数

参数名	类型	描述
ts	String	时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
sellVol	String	卖出量
buyVol	String	买入量

返回值数组顺序分别为是：[ts, sellVol, buyVol]

获取杠杆多空比

获取借入计价货币与借入交易货币的累计数额比值。

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/rubik/stat/margin/loan-ratio

请求示例

GET /api/v5/rubik/stat/margin/loan-ratio?ccy=BTC

import okx.TradingData as TradingData_api

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

tradingDataAPI = TradingData_api.TradingDataAPI(flag=flag)

# 获取杠杆多空比
result = tradingDataAPI.get_margin_lending_ratio(
    ccy="BTC",
)
print(result)

请求参数

参数名	类型	是否必须	描述
ccy	String	是	币种
begin	String	否	开始时间，如 `1597026383085`
end	String	否	结束时间，如 `1597026383011`
period	String	否	时间粒度 `m`：分钟，`H`：小时，`D`：天默认值`5m`，支持[`5m`/`1H`/`1D`] `5m`粒度最多只能查询两天之内的数据 `1H`粒度最多只能查询30天之内的数据 `1D`粒度最多只能查询180天之内的数据

返回结果

{
    "code": "0",
    "data": [
        [
            "1630492800000",
            "0.4614"
        ],
        [
            "1630492500000",
            "0.5767"
        ]
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ts	String	数据产生时间
ratio	String	多空比值

获取精英交易员合约多空持仓人数比

获取精英交易员交割永续净开多持仓用户数与净开空持仓用户数的比值。精英交易员指持仓价值前5%的用户。每个粒度最多可获取最近1,440条数据。数据时间范围最早至2024年3月22日。

限速： 5次/2s

限速规则： IP + instrumentID

权限：读取

HTTP请求

GET /api/v5/rubik/stat/contracts/long-short-account-ratio-contract-top-trader

请求示例

GET /api/v5/rubik/stat/contracts/long-short-account-ratio-contract-top-trader?instId=BTC-USDT-SWAP

import okx.TradingData as TradingData_api

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

tradingDataAPI = TradingData_api.TradingDataAPI(flag=flag)

# 获取精英交易员合约多空持仓人数比
result = tradingDataAPI.get_top_trader_long_short_account_ratio(
    instId="BTC-USDT-SWAP"
)

print(result)

请求参数

参数名	类型	是否必须	描述
instId	string	是	产品ID，如 BTC-USDT-SWAP 仅适用于`交割`，`永续`
period	string	否	时间粒度，默认值`5m`, 如 [`5m/15m/30m/1H/2H/4H`] 香港时间开盘价k线：[`6H/12H/1D/2D/3D/5D/1W/1M/3M`] UTC时间开盘价k线： [`6Hutc/12Hutc/1Dutc/2Dutc/3Dutc/5Dutc/1Wutc/1Mutc/3Mutc`]
end	string	否	筛选的结束时间戳 ts，Unix 时间戳为毫秒数格式，如 `1597027383085`
begin	string	否	筛选的开始时间戳 ts，Unix 时间戳为毫秒数格式，如 `1597026383085`
limit	string	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        [
            "1701417600000",    // timestamp
            "1.1739"            // long/short account num ratio of top traders
        ],
        [
            "1701417600000",    // timestamp
            "0.1236"            // long/short account num ratio of top traders
        ],
    ]
}

返回参数

参数名	类型	描述
ts	String	时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
longShortAcctRatio	String	多空人数比

返回值数组顺序分别为是：[ts, longShortAcctRatio]

获取精英交易员合约多空持仓仓位比

获取交割永续开多、开空仓位占总持仓的比值。精英交易员指持仓价值前5%的用户。每个粒度最多可获取最近1,440条数据。数据时间范围最早至2024年3月22日。

限速： 5次/2s

限速规则： IP + instrumentID

权限：读取

HTTP请求

GET /api/v5/rubik/stat/contracts/long-short-position-ratio-contract-top-trader

请求示例

GET /api/v5/rubik/stat/contracts/long-short-position-ratio-contract-top-trader?instId=BTC-USDT-SWAP

import okx.TradingData as TradingData_api

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

tradingDataAPI = TradingData_api.TradingDataAPI(flag=flag)

# 获取精英交易员合约多空持仓仓位比
result = tradingDataAPI.get_top_trader_long_short_position_ratio(
    instId="BTC-USDT-SWAP"
)

print(result)

请求参数

参数名	类型	是否必须	描述
instId	string	是	产品ID，如 `BTC-USDT-SWAP` 仅适用于`交割`/`永续`
period	string	否	时间粒度，默认值`5m`, 如 [`5m/15m/30m/1H/2H/4H`] 香港时间开盘价k线：[`6H/12H/1D/2D/3D/5D/1W/1M/3M`] UTC时间开盘价k线： [`6Hutc/12Hutc/1Dutc/2Dutc/3Dutc/5Dutc/1Wutc/1Mutc/3Mutc`]
end	string	否	筛选的结束时间戳 ts，Unix 时间戳为毫秒数格式，如 `1597027383085`
begin	string	否	筛选的开始时间戳 ts，Unix 时间戳为毫秒数格式，如 `1597026383085`
limit	string	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        [
            "1701417600000",    // timestamp
            "1.1739"            // long/short position num ratio of top traders
        ],
        [
            "1701417600000",    // timestamp
            "0.1236"            // long/short position num ratio of top traders
        ],
    ]
}

返回参数

参数名	类型	描述
ts	String	时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
longShortPosRatio	String	多空仓位占总持仓比值

返回值数组顺序分别为是：[ts, longShortPosRatio]

获取合约多空持仓人数比

获取交割永续净开多持仓用户数与净开空持仓用户数的比值。每个粒度最多可获取最近1,440条数据。

对于时间粒度period=1D，数据时间范围最早至2024年1月1日；对于其他时间粒度period，最早至2024年2月初。

限速： 5次/2s

限速规则： IP + instrumentID

权限：读取

HTTP请求

GET /api/v5/rubik/stat/contracts/long-short-account-ratio-contract

请求示例

GET /api/v5/rubik/stat/contracts/long-short-account-ratio-contract?instId=BTC-USDT-SWAP

import okx.TradingData as TradingData_api

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

tradingDataAPI = TradingData_api.TradingDataAPI(flag=flag)

# 获取合约净开多持仓用户数与净开空持仓用户数的比值
result = tradingDataAPI.get_contract_long_short_ratio(
    instId="BTC-USDT-SWAP"
)

print(result)

请求参数

参数名	类型	是否必须	描述
instId	string	是	产品ID，如 BTC-USDT 仅适用于`交割`，`永续`
period	string	否	时间粒度，默认值`5m`, 如 [`5m/15m/30m/1H/2H/4H`] 香港时间开盘价k线：[`6H/12H/1D/2D/3D/5D/1W/1M/3M`] UTC时间开盘价k线： [`6Hutc/12Hutc/1Dutc/2Dutc/3Dutc/5Dutc/1Wutc/1Mutc/3Mutc`]
end	string	否	筛选的结束时间戳 ts，Unix 时间戳为毫秒数格式，如 `1597027383085`
begin	string	否	筛选的开始时间戳 ts，Unix 时间戳为毫秒数格式，如 `1597026383085`
limit	string	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        [
            "1701417600000",    // timestamp
            "1.1739"            // long/short account num ratio of traders
        ],
        [
            "1701417600000",    // timestamp
            "0.1236"            // long/short account num ratio of traders
        ],
    ]
}

返回参数

参数名	类型	描述
ts	String	时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
longShortAcctRatio	String	多空人数比

返回值数组顺序分别为是：[ts, longAcctPosRatio]

获取多空持仓人数比

获取交割永续净开多持仓用户数与净开空持仓用户数的比值。

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/rubik/stat/contracts/long-short-account-ratio

请求示例

GET /api/v5/rubik/stat/contracts/long-short-account-ratio?ccy=BTC

import okx.TradingData as TradingData_api

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

tradingDataAPI = TradingData_api.TradingDataAPI(flag=flag)

# 获取合约多空持仓人数比
result = tradingDataAPI.get_long_short_ratio(
    ccy="BTC",
)
print(result)

请求参数

参数名	类型	是否必须	描述
ccy	String	是	币种
begin	String	否	开始时间，如 `1597026383085`
end	String	否	结束时间，如 `1597026383011`
period	String	否	时间粒度，默认值`5m`。支持[5m/1H/1D] `5m`粒度最多只能查询两天之内的数据 `1H`粒度最多只能查询30天之内的数据 `1D`粒度最多只能查询180天之内的数据

返回结果

{
    "code": "0",
    "data": [
        [
            "1630502100000",
            "1.25"
        ]
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ts	String	数据产生时间
ratio	String	多空人数比

获取合约持仓量及交易量

获取交割永续的持仓量和交易量。

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/rubik/stat/contracts/open-interest-volume

请求示例

GET /api/v5/rubik/stat/contracts/open-interest-volume?ccy=BTC

import okx.TradingData as TradingData_api

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

tradingDataAPI = TradingData_api.TradingDataAPI(flag=flag)

# 获取合约持仓量及交易量
result = tradingDataAPI.get_contracts_interest_volume(
    ccy="BTC",
)
print(result)

请求参数

参数名	类型	是否必须	描述
ccy	String	是	币种
begin	String	否	开始时间，如 `1597026383085`
end	String	否	结束时间，如 `1597026383011`
period	String	否	时间粒度，默认值`5m`。支持[5m/1H/1D] `5m`粒度最多只能查询两天之内的数据 `1H`粒度最多只能查询30天之内的数据 `1D`粒度最多只能查询180天之内的数据

返回结果

{
    "code": "0",
    "data": [
        [
            "1630502400000",
            "1713028741.6898",
            "39800873.554"
        ]
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ts	String	数据产生时间
oi	String	持仓总量（USD）
vol	String	交易总量（USD）

获取期权持仓量及交易量

获取期权的持仓量和交易量。

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/rubik/stat/option/open-interest-volume

请求示例

GET /api/v5/rubik/stat/option/open-interest-volume?ccy=BTC

import okx.TradingData as TradingData_api

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

tradingDataAPI = TradingData_api.TradingDataAPI(flag=flag)

# 获取期权持仓量及交易量
result = tradingDataAPI.get_options_interest_volume(
    ccy="BTC",
)
print(result)

请求参数

参数名	类型	是否必须	描述
ccy	String	是	币种
period	String	否	时间粒度，默认值`8H`。支持[`8H/1D`] 每个粒度最多只能查询72条数据

返回结果

{
    "code": "0",
    "data": [
        [
            "1630368000000",
            "3458.1000",
            "78.8000"
        ]
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ts	String	数据产生时间
oi	String	持仓总量，单位为请求参数的`ccy`
vol	String	交易总量，单位为请求参数的`ccy`

看涨/看跌期权合约持仓总量比/交易总量比

获取看涨期权和看跌期权的持仓量比值，以及交易量比值。

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/rubik/stat/option/open-interest-volume-ratio

请求示例

GET /api/v5/rubik/stat/option/open-interest-volume-ratio?ccy=BTC

import okx.TradingData as TradingData_api

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

tradingDataAPI = TradingData_api.TradingDataAPI(flag=flag)

# 看涨/看跌期权合约 持仓总量比/交易总量比
result = tradingDataAPI.get_put_call_ratio(
    ccy="BTC",
)
print(result)

请求参数

参数名	类型	是否必须	描述
ccy	String	是	币种
period	String	否	时间粒度，默认值`8H`。支持[`8H/1D`] 每个粒度最多只能查询72条数据

返回结果

{
    "code": "0",
    "data": [
        [
            "1630512000000",
            "2.7261",
            "2.3447"
        ],
        [
            "1630425600000",
            "2.8101",
            "2.3438"
        ]
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ts	String	数据产生时间
oiRatio	String	看涨/看跌持仓总量比
volRatio	String	看涨/看跌交易总量比

看涨看跌持仓总量及交易总量（按到期日分）

获取每个到期日上看涨期权和看跌期权的持仓量和交易量。

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/rubik/stat/option/open-interest-volume-expiry

请求示例

GET /api/v5/rubik/stat/option/open-interest-volume-expiry?ccy=BTC

import okx.TradingData as TradingData_api

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

tradingDataAPI = TradingData_api.TradingDataAPI(flag=flag)

# 看涨看跌持仓总量及交易总量（按到期日分）
result = tradingDataAPI.get_interest_volume_expiry(
    ccy="BTC"
)
print(result)

请求参数

参数名	类型	是否必须	描述
ccy	String	是	币种
period	String	否	时间粒度，默认值`8H`。支持[`8H/1D`] 每个粒度仅展示最新的一份数据

返回结果

{
    "code": "0",
    "data": [
        [
            "1630540800000",
            "20210902",
            "6.4",
            "18.4",
            "0.7",
            "0.4"
        ],
        [
            "1630540800000",
            "20210903",
            "47",
            "36.6",
            "1",
            "10.7"
        ]
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ts	String	数据产生时间
expTime	String	到期日（格式: YYYYMMDD，如 "20210623"）
callOI	String	看涨持仓总量（以`币`为单位）
putOI	String	看跌持仓总量（以`币`为单位）
callVol	String	看涨交易总量（以`币`为单位）
putVol	String	看跌交易总量（以`币`为单位）

看涨看跌持仓总量及交易总量（按执行价格分）

获取看涨期权和看跌期权的taker主动买入和卖出的交易量。

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/rubik/stat/option/open-interest-volume-strike

请求示例

GET /api/v5/rubik/stat/option/open-interest-volume-strike?ccy=BTC&expTime=20210901

import okx.TradingData as TradingData_api

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

tradingDataAPI = TradingData_api.TradingDataAPI(flag=flag)

# 看涨看跌持仓总量及交易总量（按执行价格分）
result = tradingDataAPI.get_interest_volume_strike(
    ccy="BTC",
    expTime="20210623"
)
print(result)

请求参数

参数名	类型	是否必须	描述
ccy	String	是	币种
expTime	String	是	到期日（格式: `YYYYMMdd`，如 "20210623"）
period	String	否	时间粒度，默认值`8H`。支持[`8H/1D`] 每个粒度仅展示最新的一份数据

返回结果

{
    "code": "0",
    "data": [
        [
            "1630540800000",
            "10000",
            "0",
            "0.5",
            "0",
            "0"
        ],
        [
            "1630540800000",
            "14000",
            "0",
            "5.2",
            "0",
            "0"
        ]
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ts	String	数据产生时间
strike	String	执行价格
callOI	String	看涨持仓总量（以`币`为单位）
putOI	String	看跌持仓总量（以`币`为单位）
callVol	String	看涨交易总量（以`币`为单位）
putVol	String	看跌交易总量（以`币`为单位）

看跌/看涨期权合约主动买入/卖出量

该指标展示某一时刻，单位时间内看跌/看涨期权的主动（taker）买入/卖出交易量

限速：5次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/rubik/stat/option/taker-block-volume

请求示例

GET /api/v5/rubik/stat/option/taker-block-volume?ccy=BTC

import okx.TradingData as TradingData_api

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

tradingDataAPI = TradingData_api.TradingDataAPI(flag=flag)

# 看跌/看涨期权合约 主动买入/卖出量
result = tradingDataAPI.get_taker_block_volume(
    ccy="BTC",
)
print(result)

请求参数

参数名	类型	是否必须	描述
ccy	String	是	币种
period	String	否	时间粒度，默认值`8H`。支持[`8H/1D`] 每个粒度仅展示最新的一份数据

返回结果

{
    "code": "0",
    "data": [
        "1630512000000",
        "8.55",
        "67.3",
        "16.05",
        "16.3",
        "126.4",
        "40.7"
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ts	String	数据产生时间
callBuyVol	String	看涨买入量以结算货币为单位
callSellVol	String	看涨卖出量以结算货币为单位
putBuyVol	String	看跌买入量以结算货币为单位
putSellVol	String	看跌卖出量以结算货币为单位
callBlockVol	String	看涨大单
putBlockVol	String	看跌大单

资金账户

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

REST API

获取币种列表

获取当前用户KYC实体支持的币种列表。

限速：6 次/s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/asset/currencies

请求示例

GET /api/v5/asset/currencies

import okx.Funding as Funding

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

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

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# 获取币种列表
result = fundingAPI.get_currencies()
print(result)

请求参数

参数	类型	是否必须	描述
ccy	String	否	币种，如 `BTC` 支持多币种查询，币种之间半角逗号分隔

返回结果

{
  "code": "0",
  "msg": "",
  "data": [
    {
        "burningFeeRate": "",
        "canDep": true,
        "canInternal": true,
        "canWd": true,
        "ccy": "BTC",
        "chain": "BTC-Bitcoin",
        "ctAddr": "",
        "depEstOpenTime": "",
        "depQuotaFixed": "",
        "depQuoteDailyLayer2": "",
        "fee": "0.00005",
        "logoLink": "https://static.coinall.ltd/cdn/oksupport/asset/currency/icon/btc20230419112752.png",
        "mainNet": true,
        "maxFee": "0.00005",
        "maxFeeForCtAddr": "",
        "maxWd": "500",
        "minDep": "0.0005",
        "minDepArrivalConfirm": "1",
        "minFee": "0.00005",
        "minFeeForCtAddr": "",
        "minInternal": "0.0001",
        "minWd": "0.0005",
        "minWdUnlockConfirm": "2",
        "name": "Bitcoin",
        "needTag": false,
        "usedDepQuotaFixed": "",
        "usedWdQuota": "0",
        "wdEstOpenTime": "",
        "wdQuota": "10000000",
        "wdTickSz": "8"
    }
  ]
}

返回参数

参数名	类型	描述
ccy	String	币种名称，如 `BTC`
name	String	币种名称，不显示则无对应名称
logoLink	String	币种Logo链接
chain	String	币种链信息有的币种下有多个链，必须要做区分，如`USDT`下有`USDT-ERC20`，`USDT-TRC20`多个链
ctAddr	String	合约地址
canDep	Boolean	当前是否可充值 `false`：不可链上充值 `true`：可以链上充值
canWd	Boolean	当前是否可提币 `false`：不可链上提币 `true`：可以链上提币
canInternal	Boolean	当前是否可内部转账 `false`：不可内部转账 `true`：可以内部转账
depEstOpenTime	String	充值预期开放时间，Unix时间戳的毫秒数格式，如 `1597026383085`
wdEstOpenTime	String	提币预期开放时间，Unix时间戳的毫秒数格式，如 `1597026383085`
minDep	String	币种单笔最小充值量
minWd	String	币种单笔最小`链上提币`量
minInternal	String	币种单笔最小`内部转账`量无单笔最大`内部转账`量限制，受24小时内提币额度(`wdQuota`)限制
maxWd	String	币种单笔最大`链上提币`量
wdTickSz	String	提币精度,表示小数点后的位数。提币手续费精度与提币精度保持一致。内部转账提币精度为小数点后8位。
wdQuota	String	过去24小时内提币额度（包含`链上提币`和`内部转账`），单位为`USD`
usedWdQuota	String	过去24小时内已用提币额度，单位为`USD`
fee	String	固定的提币手续费数量适用于`链上提币`
minFee	String	普通地址最小提币手续费数量适用于`链上提币` 该字段已废弃
maxFee	String	普通地址最大提币手续费数量适用于`链上提币` 该字段已废弃
minFeeForCtAddr	String	合约地址最小提币手续费数量适用于`链上提币` 该字段已废弃
maxFeeForCtAddr	String	合约地址最大提币手续费数量适用于`链上提币` 该字段已废弃
burningFeeRate	String	燃烧费率，如 `0.05` 代表 `5%`。部分币种会收取燃烧费用。燃烧费用按照提币数量（不含gas fee）乘以燃烧费率，在提币数量基础上扣除。适用于`链上提币`
mainNet	Boolean	当前链是否为主链
needTag	Boolean	当前链提币是否需要标签（tag/memo）信息，如 `EOS`该字段为`true`
minDepArrivalConfirm	String	充值到账最小网络确认数。币已到账但不可提。
minWdUnlockConfirm	String	提现解锁最小网络确认数
depQuotaFixed	String	充币固定限额，单位为`USD` 没有充币限制则返回""
usedDepQuotaFixed	String	已用充币固定额度，单位为`USD` 没有充币限制则返回""
depQuoteDailyLayer2	String	Layer2网络每日充值上限

获取资金账户余额

获取资金账户所有资产列表，查询各币种的余额、冻结和可用等信息。

限速：6次/s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/asset/balances

请求示例

GET /api/v5/asset/balances

import okx.Funding as Funding

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

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

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# 获取资金账户余额
result = fundingAPI.get_balances()
print(result)

请求参数

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

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
            "availBal": "37.11827078",
            "bal": "37.11827078",
            "ccy": "ETH",
            "frozenBal": "0"
        }
    ]
}

返回参数

参数名	类型	描述
ccy	String	币种，如 `BTC`
bal	String	余额
frozenBal	String	冻结余额
availBal	String	可用余额

获取不可交易资产

限速：6 次/s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/asset/non-tradable-assets

请求示例

GET /api/v5/asset/non-tradable-assets

import okx.Funding as Funding

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

result = fundingAPI.get_non_tradable_assets()
print(result)

请求参数

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

返回结果

{
    "code": "0",
    "data": [
        {
            "bal": "989.84719571",
            "burningFeeRate": "",
            "canWd": true,
            "ccy": "CELT",
            "chain": "CELT-OKTC",
            "ctAddr": "f403fb",
            "fee": "2",
            "feeCcy": "USDT",
            "logoLink": "https://static.coinall.ltd/cdn/assets/imgs/221/460DA8A592400393.png",
            "minWd": "0.1",
            "name": "",
            "needTag": false,
            "wdAll": false,
            "wdTickSz": "8"
        },
        {
            "bal": "0.001",
            "burningFeeRate": "",
            "canWd": true,
            "ccy": "MEME",
            "chain": "MEME-ERC20",
            "ctAddr": "09b760",
            "fee": "5",
            "feeCcy": "USDT",
            "logoLink": "https://static.coinall.ltd/cdn/assets/imgs/207/2E664E470103C613.png",
            "minWd": "0.001",
            "name": "MEME Inu",
            "needTag": false,
            "wdAll": false,
            "wdTickSz": "8"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	币种名称，如 `CELT`
name	String	币种中文名称，不显示则无对应名称
logoLink	String	币种Logo链接
bal	String	可提余额
canWd	Boolean	是否可提 `false`: 不可提 `true`: 可提
chain	String	支持提币的链
minWd	String	币种单笔最小提币量
wdAll	Boolean	该币种资产是否必须一次性全部提取
fee	String	提币固定手续费。提币手续费精度为小数点后8位。
feeCcy	String	提币固定手续费单位
burningFeeRate	String	燃烧费率，如 `0.05` 代表 `5%`。部分币种会收取燃烧费用。燃烧费用按照提币数量（不含gas fee）乘以燃烧费率，在提币数量基础上扣除。
ctAddr	String	合约地址后6位
wdTickSz	String	提币精度,表示小数点后的位数
needTag	Boolean	提币的链是否需要标签（tag/memo）信息

获取账户资产估值

查看账户资产估值

限速：1次/s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/asset/asset-valuation

请求示例

GET /api/v5/asset/asset-valuation

import okx.Funding as Funding

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

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

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# 获取账户资产估值
result = fundingAPI.get_asset_valuation()
print(result)

请求参数

参数	类型	是否必须	描述
ccy	String	否	资产估值对应的单位 BTC 、USDT USD 、CNY 、JPY、KRW、RUB、EUR VND 、IDR 、INR、PHP、THB、TRY AUD 、SGD 、ARS、SAR、AED、IQD 默认为`BTC`为单位的估值

返回结果

{
    "code": "0",
    "data": [
        {
            "details": {
                "classic": "124.6",
                "earn": "1122.73",
                "funding": "0.09",
                "trading": "2544.28"
            },
            "totalBal": "3790.09",
            "ts": "1637566660769"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
totalBal	String	账户总资产估值
ts	String	数据更新时间，Unix时间戳的毫秒数格式，如 1597026383085
details	Object	各个账户的资产估值
> funding	String	资金账户
> trading	String	交易账户
> classic	String	经典账户 (已废弃)
> earn	String	金融账户

资金划转

调用时，API Key 需要有交易权限。

支持母账户的资金账户划转到交易账户，母账户到子账户的资金账户和交易账户划转。

子账户默认可转出至母账户，划转到同一母账户下的其他子账户，需要先调用设置子账户主动转出权限接口进行授权。

限速：2 次/s

限速规则：UserID + Currency

权限：交易

HTTP 请求

POST /api/v5/asset/transfer

请求示例

# 母账户USDT从资金账户划转1.5USDT到交易账户
POST /api/v5/asset/transfer
body 
{
    "ccy":"USDT",
    "amt":"1.5",
    "from":"6",
    "to":"18"
}

# 母账户从资金账户划转1.5USDT到子账户的资金账户
POST /api/v5/asset/transfer
body 
{
    "ccy":"USDT",
    "type":"1",
    "amt":"1.5",
    "from":"6",
    "to":"6",
    "subAcct":"mini"
}

# 子账户从资金账户划转1.5USDT到另一子账户的资金账户
POST /api/v5/asset/transfer
body 
{
    "ccy":"USDT",
    "type":"4",
    "amt":"1.5",
    "from":"6",
    "to":"6",
    "subAcct":"mini"
}

import okx.Funding as Funding

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

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

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# 资金划转
result = fundingAPI.funds_transfer(
    ccy="USDT",
    amt="1.5",
    from_="6",
    to="18"
)
print(result)

请求参数

参数名	类型	是否必须	描述
type	String	否	划转类型 `0`：账户内划转 `1`：母账户转子账户(仅适用于母账户APIKey) `2`：子账户转母账户(仅适用于母账户APIKey) `3`：子账户转母账户(仅适用于子账户APIKey) `4`：子账户转子账户(仅适用于子账户APIKey，且目标账户需要是同一母账户下的其他子账户。子账户主动转出权限默认是关闭的，权限调整参考设置子账户主动转出权限。) 默认是`0` 如果您希望通过母账户API Key控制子账户之间的划转，参考接口子账户间资金划转
ccy	String	是	划转币种，如 `USDT`
amt	String	是	划转数量
from	String	是	转出账户 `6`：资金账户 `18`：交易账户
to	String	是	转入账户 `6`：资金账户 `18`：交易账户
subAcct	String	可选	子账户名称当`type`为`1`/`2`/`4`时，该字段必填
loanTrans	Boolean	否	是否支持`现货模式`/`跨币种保证金模式`/`组合保证金模式`下的借币转出 `true`：支持借币转出 `false`：不支持借币转出默认为`false`
omitPosRisk	String	否	是否忽略仓位风险默认为`false` 仅适用于`组合保证金模式`
clientId	String	否	客户自定义ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。

返回结果

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "transId": "754147",
      "ccy": "USDT",
      "clientId": "",
      "from": "6",
      "amt": "0.1",
      "to": "18"
    }
  ]
}

返回参数

参数名	类型	描述
transId	String	划转 ID
ccy	String	划转币种
from	String	转出账户
amt	String	划转量
to	String	转入账户
clientId	String	客户自定义ID

获取资金划转状态

获取最近2个星期内的资金划转状态数据

限速：10 次/s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/asset/transfer-state

请求示例

GET /api/v5/asset/transfer-state?transId=1&type=1

import okx.Funding as Funding

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

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

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# 获取资金划转状态
result = fundingAPI.transfer_state(
    transId="248424899",
    type="0"
)
print(result)

请求参数

参数名	类型	是否必须	描述
transId	String	可选	划转ID transId和clientId必须传一个，若传两个，以transId为主
clientId	String	可选	客户自定义ID
type	String	否	划转类型 `0`：账户内划转 `1`：母账户转子账户(仅适用于母账户APIKey) `2`：子账户转母账户(仅适用于母账户APIKey) `3`：子账户转母账户(仅适用于子账户APIKey) `4`：子账户转子账户(仅适用于子账户APIKey，且目标账户需要是同一母账户下的其他子账户) 默认是`0` 对于Custody账户该参数可以不传或者传0。

返回结果

{
    "code": "0",
    "data": [
        {
            "amt": "1.5",
            "ccy": "USDT",
            "clientId": "",
            "from": "18",
            "instId": "", //已废弃
            "state": "success",
            "subAcct": "test",
            "to": "6",
            "toInstId": "", //已废弃
            "transId": "1",
            "type": "1"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
transId	String	划转 ID
clientId	String	客户自定义 ID
ccy	String	划转币种
amt	String	划转量
type	String	划转类型 `0`：账户内划转 `1`：母账户转子账户(仅适用于母账户APIKey) `2`：子账户转母账户(仅适用于母账户APIKey) `3`：子账户转母账户(仅适用于子账户APIKey) `4`：子账户转子账户(仅适用于子账户APIKey，且目标账户需要是同一母账户下的其他子账户)
from	String	转出账户 `6`：资金账户 `18`：交易账户
to	String	转入账户 `6`：资金账户 `18`：交易账户
subAcct	String	子账户名称
instId	String	已废弃
toInstId	String	已废弃
state	String	转账状态 `success`：成功 `pending`：处理中 `failed`：失败

获取资金流水

查询最近一个月内资金账户账单流水

限速：6 次/s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/asset/bills

请求示例

GET /api/v5/asset/bills

GET /api/v5/asset/bills?type=1

import okx.Funding as Funding

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

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

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# 获取资金流水
result = fundingAPI.get_bills()
print(result)

请求参数

参数名	类型	是否必须	描述
ccy	String	否	币种
type	String	否	账单类型 `1`：充值 `2`：提现 `13`：撤销提现 `20`：转出至子账户（主体是母账户） `21`：从子账户转入（主体是母账户） `22`：转出到母账户（主体是子账户） `23`：母账户转入（主体是子账户） `28`：领取 `47`：系统冲正 `48`：活动得到 `49`：活动送出 `68`：手续费返佣(通过返佣卡) `72`：收币 `73`：送币 `74`：送币退还 `75`：申购余币宝 `76`：赎回余币宝 `77`：Jumpstart派发 `78`：Jumpstart锁定 `80`：DEFI/锁仓挖矿产品申购 `82`：DEFI/锁仓挖矿产品赎回 `83`：锁仓挖矿收益 `84`：违约金 `116`：法币创建订单 `117`：法币完成订单 `118`：法币取消订单 `124`：Jumpstart 解锁 `130`：从交易账户转入 `131`：转出至交易账户 `132`：[P2P] 客服冻结 `133`：[P2P] 客服解冻 `134`：[P2P] 客服转交 `135`：跨链兑换 `137`：[ETH质押] 申购 `138`：[ETH质押] 兑换 `139`：[ETH质押] 收益 `146`：客户回馈 `150`：节点返佣 `151`：邀请奖励 `152`：经纪商返佣 `160`：双币赢申购 `161`：双币赢回款 `162`：双币赢收益 `163`：双币赢退款 `172`：[节点计划] 助力人返佣 `173`：[节点计划] 手续费返现 `174`：Jumpstart支付 `175`：锁定质押物 `176`：借款转入 `177`：添加质押物 `178`：减少质押物 `179`：还款 `180`：释放质押物 `181`：偿还空投糖果 `185`：[经纪商] 闪兑返佣 `187`：[经纪商] 闪兑划转 `189`：盲盒奖励 `195`：不可交易资产提币 `196`：不可交易资产提币撤销 `197`：不可交易资产充值 `198`：不可交易资产减少 `199`：不可交易资产增加 `200`：买入 `202`：价格锁定申购 `203`：价格锁定回款 `204`：价格锁定收益 `205`：价格锁定退款 `207`：双币赢精简版申购 `208`：双币赢精简版回款 `209`：双币赢精简版收益 `210`：双币赢精简版退款 `212`：[活期借币] 多币种借贷锁定质押物 `215`：[活期借币] 多币种借贷释放质押物 `217`：[活期借币] 多币种借贷借款转入 `218`：[活期借币] 多币种借贷还款 `232`：[活期借币] 利息补贴转出 `220`：已下架数字货币 `221`：提币手续费支出 `222`：提币手续费退款 `223`：合约带单分润 `225`：鲨鱼鳍申购 `226`：鲨鱼鳍回款 `227`：鲨鱼鳍收益 `228`：鲨鱼鳍退款 `229`：空投发放 `232`：利息补贴入账 `233`：经纪商佣金补偿 `240`：雪球申購 `241`：雪球回款 `242`：雪球收益 `243`：雪球交易失败 `249`：海鸥申购 `250`：海鸥回款 `251`：海鸥收益 `252`：海鸥退款 `263`：策略分润 `265`：信号收入 `266`：现货带单分润 `270`：DCD经纪商划转 `271`：DCD经纪商返佣 `272`：[闪兑] 买入数字货币/法币 `273`：[闪兑] 卖出数字货币/法币 `284`：[Custody] 转出交易子账户 `285`：[Custody] 转入交易子账户 `286`：[Custody] 转出托管资金账户 `287`：[Custody] 转入托管资金账户 `288`：[Custody] 托管资金入金 `289`：[Custody] 托管资金出金 `299`：推荐节点返佣 `300`：手续费折扣返现 `303`：雪球做市商转账 `304`：[定期简单赚币] 订单提交 `305`：[定期简单赚币] 订单赎回 `306`：[定期简单赚币] 本金发放 `307`：[定期简单赚币] 收益发放 (提前终止订单补偿) `308`：[定期简单赚币] 收益发放 `309`：[定期简单赚币] 补偿收益发放 (订单延期补偿) `311`：系统转入小额资产 `328`：[SOL质押] 流动性质押收益 `329`：[SOL质押] 流动性质押申购 `330`：[SOL质押] 流动性质押铸币 `331`：[SOL质押] 流动性质押赎回 `332`：[SOL质押] 流动性质押结算 `333`：体验金收益
clientId	String	否	转账或提币的客户自定义ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
after	String	否	查询在此之前的内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
before	String	否	查询在此之后的内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
limit	String	否	分页返回的结果集数量，最大为 100，不填默认返回 100 条

返回结果

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "billId": "12344",
      "ccy": "BTC",
      "clientId": "",
      "balChg": "2",
      "bal": "12",
      "type": "1",
      "ts": "1597026383085"
    }
  ]
}

返回参数

参数名	类型	描述
billId	String	账单 ID
ccy	String	账户余额币种
clientId	String	转账或提币的客户自定义ID
balChg	String	账户层面的余额变动数量
bal	String	账户层面的余额数量
type	String	账单类型
ts	String	账单创建时间，Unix 时间戳的毫秒数格式，如 `1597026383085`

获取充值地址信息

获取各个币种的充值地址，包括曾使用过的老地址。

限速：6次/s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/asset/deposit-address

请求示例

GET /api/v5/asset/deposit-address?ccy=BTC

import okx.Funding as Funding

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

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

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# 获取充值地址信息
result = fundingAPI.get_deposit_address(
    ccy="USDT"
)
print(result)

请求参数

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

返回结果

{
    "code": "0",
    "data": [
        {
            "chain": "BTC-Bitcoin",
            "ctAddr": "",
            "ccy": "BTC",
            "to": "6",
            "addr": "39XNxK1Ryqgg3Bsyn6HzoqV4Xji25pNkv6",
            "verifiedName":"John Corner",
            "selected": true
        },
        {
            "chain": "BTC-OKC",
            "ctAddr": "",
            "ccy": "BTC",
            "to": "6",
            "addr": "0x66d0edc2e63b6b992381ee668fbcb01f20ae0428",
            "verifiedName":"John Corner",
            "selected": true
        },
        {
            "chain": "BTC-ERC20",
            "ctAddr": "5807cf",
            "ccy": "BTC",
            "to": "6",
            "addr": "0x66d0edc2e63b6b992381ee668fbcb01f20ae0428",
            "verifiedName":"John Corner",
            "selected": true
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
addr	String	充值地址
tag	String	部分币种充值需要标签，若不需要则不返回此字段
memo	String	部分币种充值需要 memo，若不需要则不返回此字段
pmtId	String	部分币种充值需要此字段（payment_id），若不需要则不返回此字段
addrEx	Object	充值地址备注，部分币种充值需要，若不需要则不返回此字段如币种`TONCOIN`的充值地址备注标签名为`comment`,则该字段返回：{'comment':'123456'}
ccy	String	币种，如`BTC`
chain	String	币种链信息有的币种下有多个链，必须要做区分，如`USDT`下有`USDT-ERC20`，`USDT-TRC20`多个链
to	String	转入账户 `6`：资金账户 `18`：交易账户某些主体用户(如巴西)只支持充值到交易账户
verifiedName	String	(接受方)已验证姓名
selected	Boolean	该地址是否为页面选中的地址
ctAddr	String	合约地址后6位

获取充值记录

根据币种，充值状态，时间范围获取充值记录，按照时间倒序排列，默认返回 100 条数据。
支持Websocket订阅，参考充值信息频道。

限速：6次/s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/asset/deposit-history

请求示例

# 查询最近的充值记录
GET /api/v5/asset/deposit-history

# 查询从2022年06月01日到2022年07月01日之间的BTC的充值记录
GET /api/v5/asset/deposit-history?ccy=BTC&after=1654041600000&before=1656633600000

import okx.Funding as Funding

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

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

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# 获取充值记录
result = fundingAPI.get_deposit_history()
print(result)

请求参数

参数名	类型	是否必须	描述
ccy	String	否	币种名称，如 `BTC`
depId	String	否	充值记录 ID
fromWdId	String	否	内部转账发起者提币申请 ID 如果该笔充值来自于内部转账，则该字段展示内部转账发起者的提币申请 ID
txId	String	否	区块转账哈希记录
type	String	否	充值方式 `3`：内部转账 `4`：链上充值
state	String	否	充值状态 `0`：等待确认 `1`：确认到账 `2`：充值成功 `8`：因该币种暂停充值而未到账，恢复充值后自动到账 `11`：命中地址黑名单 `12`：账户或充值被冻结 `13`：子账户充值拦截 `14`：KYC限额
after	String	否	查询在此之前的内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1654041600000`
before	String	否	查询在此之后的内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1656633600000`
limit	string	否	返回的结果集数量，默认为100，最大为100，不填默认返回100条

返回结果

{
  "code": "0",
  "msg": "",
  "data": [
    {
        "actualDepBlkConfirm": "2",
        "amt": "1",
        "areaCodeFrom": "",
        "ccy": "USDT",
        "chain": "USDT-TRC20",
        "depId": "88****33",
        "from": "",
        "fromWdId": "",
        "state": "2",
        "to": "TN4hGjVXMzy*********9b4N1aGizqs",
        "ts": "1674038705000",
        "txId": "fee235b3e812********857d36bb0426917f0df1802"
    }
  ]
}

返回参数

参数名	类型	描述
ccy	String	币种名称，如 `BTC`
chain	String	币种链信息有的币种下有多个链，必须要做区分，如`USDT`下有`USDT-ERC20`，`USDT-TRC20`多个链
amt	String	充值数量
from	String	充值账户如果该笔充值来自于内部转账，则该字段展示内部转账发起者的账户信息，可以是手机号、邮箱、账户名称，其他情况返回""
areaCodeFrom	String	如果`from`为手机号，该字段为该手机号的区号
to	String	到账地址如果该笔充值来自于链上充值，则该字段展示链上地址，其他情况返回""
txId	String	区块转账哈希记录
ts	String	充值记录创建时间，Unix 时间戳的毫秒数格式，如 `1655251200000`
state	String	充值状态 `0`：等待确认 `1`：确认到账 `2`：充值成功 `8`：因该币种暂停充值而未到账，恢复充值后自动到账 `11`：命中地址黑名单 `12`：账户或充值被冻结 `13`：子账户充值拦截 `14`：KYC限额
depId	String	充值记录 ID
fromWdId	String	内部转账发起者提币申请 ID 如果该笔充值来自于内部转账，则该字段展示内部转账发起者的提币申请 ID，其他情况返回""
actualDepBlkConfirm	String	最新的充币网络确认数

提币

支持资金账户资产提币。普通子账户不支持提币。

限速：6次/s

限速规则：UserID

权限：提币

HTTP请求

POST /api/v5/asset/withdrawal

请求示例

# 链上提币
POST /api/v5/asset/withdrawal
body
{
    "amt":"1",
    "dest":"4",
    "ccy":"BTC",
    "chain":"BTC-Bitcoin",
    "toAddr":"17DKe3kkkkiiiiTvAKKi2vMPbm1Bz3CMKw"
}

# 内部转账
POST /api/v5/asset/withdrawal
body
{
    "amt":"10",
    "dest":"3",
    "ccy":"USDT",
    "areaCode":"86",
    "toAddr":"15651000000"
}

# 特定主体用户需要提供接收方信息
POST /api/v5/asset/withdrawal
body
{
    "amt":"1",
    "dest":"4",
    "ccy":"BTC",
    "chain":"BTC-Bitcoin",
    "toAddr":"17DKe3kkkkiiiiTvAKKi2vMPbm1Bz3CMKw",
    "rcvrInfo":{
        "walletType":"exchange",
        "exchId":"did:ethr:0xfeb4f99829a9acdf52979abee87e83addf22a7e1",
        "rcvrFirstName":"Bruce",
        "rcvrLastName":"Wayne"
    }
}

import okx.Funding as Funding

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

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

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# 提币
result = fundingAPI.withdrawal(
    ccy="USDT",
    toAddr="TXtvfb7cdrn6VX9H49mgio8bUxZ3DGfvYF",
    amt="100",
    dest="4",
    chain="USDT-TRC20"
)
print(result)

请求参数

参数名	类型	是否必须	描述
ccy	String	是	币种，如 `USDT`
amt	String	是	提币数量该数量不包含手续费。提币时需预留足够的手续费。链上提币所需网络手续费可以通过接口获取币种列表获取内部转账无需手续费
dest	String	是	提币方式 `3`：内部转账 `4`：链上提币
toAddr	String	是	`toAddr`必须是认证过的地址/账户。如果选择链上提币，某些数字货币地址格式为`地址:标签`，如 `ARDOR-7JF3-8F2E-QUWZ-CAN7F:123456` 如果选择内部转账，`toAddr`必须是接收方地址，可以是邮箱、手机或者账户名（只有子账户才有账户名）。
chain	String	可选	币种链信息如`USDT`下有`USDT-ERC20`，`USDT-TRC20`多个链如果不填此参数，则默认为主链对于无效资产提币，不填此参数，则默认为唯一的提币链适用于`链上提币`，链信息可以通过接口获取币种列表获取
areaCode	String	可选	手机区号，如 `86` 当`toAddr`为手机号时，该参数必填适用于`内部转账`
rcvrInfo	Object	可选	接收方信息特定主体用户做`链上提币`/`闪电网络提币` 需要提供此信息
> walletType	String	是	钱包类型 `exchange`：提币到交易所钱包 `private`：提币到私人钱包如果提币到交易所钱包，必须提供接收方相关信息。对于交易所钱包接收方为公司的，`rcvrFirstName`可以填公司名称，`rcvrLastName`可以填"N/A"，地址信息可以填写公司注册地址。提币到私人钱包，则不需要提供接收方信息。
> exchId	String	可选	交易所 ID 可以通过获取交易所列表（公共）接口查询支持的交易所如果交易所不在支持的交易所列表中，该字段填`0` 适用于walletType=`exchange`
> rcvrFirstName	String	可选	接收方名字，如 `Bruce` 适用于walletType=`exchange`
> rcvrLastName	String	可选	接收方姓氏，如 `Wayne` 适用于walletType=`exchange`
> rcvrCountry	String	可选	接收方所在国家，如 `United States` 必须输入英文国家名称，或者两字母国家代码(ISO 3166-1)。输入内容参考下方国家信息表中`国家名称(英)`，`国家代码` 适用于walletType=`exchange`
> rcvrCountrySubDivision	String	可选	接收方所在州/省，如 `California` 适用于walletType=`exchange`
> rcvrTownName	String	可选	接收方所在城镇，如 `San Jose` 适用于walletType=`exchange`
> rcvrStreetName	String	可选	接收方所在街道地址，如 `Clementi Avenue 1` 适用于walletType=`exchange`
clientId	String	否	客户自定义ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "amt": "0.1",
        "wdId": "67485",
        "ccy": "BTC",
        "clientId": "",
        "chain": "BTC-Bitcoin"
    }]
}

返回参数

参数名	类型	描述
ccy	String	提币币种
chain	String	币种链信息有的币种下有多个链，必须要做区分，如`USDT`下有`USDT-ERC20`，`USDT-TRC20`多个链
amt	String	提币数量
wdId	String	提币申请ID
clientId	String	客户自定义ID

国家信息表

国家名称(英)	国家名称(中)	国家代码
Afghanistan	阿富汗	AF
Albania	阿尔巴尼亚	AL
Algeria	阿尔及利亚	DZ
Andorra	安道尔	AD
Angola	安哥拉	AO
Anguilla	安圭拉	AI
Antigua and Barbuda	安提瓜和巴布达	AG
Argentina	阿根廷	AR
Armenia	亚美尼亚	AM
Australia	澳大利亚	AU
Austria	奥地利	AT
Azerbaijan	阿塞拜疆	AZ
Bahamas	巴哈马	BS
Bahrain	巴林	BH
Bangladesh	孟加拉国	BD
Barbados	巴巴多斯	BB
Belarus	白俄罗斯	BY
Belgium	比利时	BE
Belize	伯利兹	BZ
Benin	贝宁	BJ
Bermuda	百慕大	BM
Bhutan	不丹	BT
Bolivia	玻利维亚	BO
Bosnia and Herzegovina	波斯尼亚和黑塞哥维那 (波黑)	BA
Botswana	博茨瓦纳	BW
Brazil	巴西	BR
British Virgin Islands	英属维尔京群岛	VG
Brunei	文莱	BN
Bulgaria	保加利亚	BG
Burkina Faso	布基纳法索	BF
Burundi	布隆迪	BI
Cambodia	柬埔寨	KH
Cameroon	喀麦隆	CM
Canada	加拿大	CA
Cape Verde	佛得角	CV
Cayman Islands	开曼群岛	KY
Central African Republic	中非共和国	CF
Chad	乍得	TD
Chile	智利	CL
Colombia	哥伦比亚	CO
Comoros	科摩罗	KM
Congo (Republic)	刚果共和国	CG
Congo (Democratic Republic)	刚果民主共和国	CD
Costa Rica	哥斯达黎加	CR
Cote d´Ivoire (Ivory Coast)	象牙海岸	CI
Croatia	克罗地亚	HR
Cuba	古巴	CU
Cyprus	塞浦路斯	CY
Czech Republic	捷克共和国	CZ
Denmark	丹麦	DK
Djibouti	吉布提	DJ
Dominica	多米尼克	DM
Dominican Republic	多明尼加共和国	DO
Ecuador	厄瓜多尔	EC
Egypt	埃及	EG
El Salvador	萨尔瓦多	SV
Equatorial Guinea	赤道几内亚	GQ
Eritrea	厄立特里亚	ER
Estonia	爱沙尼亚	EE
Ethiopia	埃塞俄比亚	ET
Fiji	斐济	FJ
Finland	芬兰	FI
France	法国	FR
Gabon	加蓬	GA
Gambia	冈比亚	GM
Georgia	格鲁吉亚	GE
Germany	德国	DE
Ghana	加纳	GH
Greece	希腊	GR
Grenada	格林纳达	GD
Guatemala	危地马拉	GT
Guinea	几内亚	GN
Guinea-Bissau	几内亚比绍	GW
Guyana	圭亚那	GY
Haiti	海地	HT
Honduras	洪都拉斯	HN
Hong Kong	香港	HK
Hungary	匈牙利	HU
Iceland	冰岛	IS
India	印度	IN
Indonesia	印度尼西亚	ID
Iran	伊朗	IR
Iraq	伊拉克	IQ
Ireland	爱尔兰	IE
Israel	以色列	IL
Italy	意大利	IT
Jamaica	牙买加	JM
Japan	日本	JP
Jordan	约旦	JO
Kazakhstan	哈萨克斯坦	KZ
Kenya	肯尼亚	KE
Kiribati	基里巴斯	KI
North Korea	朝鲜	KP
South Korea	韩国	KR
Kuwait	科威特	KW
Kyrgyzstan	吉尔吉斯斯坦	KG
Laos	老挝	LA
Latvia	拉脱维亚	LV
Lebanon	黎巴嫩	LB
Lesotho	莱索托	LS
Liberia	利比里亚	LR
Libya	利比亚	LY
Liechtenstein	列支敦士登	LI
Lithuania	立陶宛	LT
Luxembourg	卢森堡	LU
Macau	澳门	MO
Macedonia	马其顿	MK
Madagascar	马达加斯加	MG
Malawi	马拉维	MW
Malaysia	马来西亚	MY
Maldives	马尔代夫	MV
Mali	马里	ML
Malta	马耳他	MT
Marshall Islands	马绍尔群岛	MH
Mauritania	毛里塔尼亚	MR
Mauritius	毛里求斯	MU
Mexico	墨西哥	MX
Micronesia	密克罗尼西亚	FM
Moldova	摩尔多瓦	MD
Monaco	摩纳哥	MC
Mongolia	蒙古	MN
Montenegro	黑山	ME
Morocco	摩洛哥	MA
Mozambique	莫桑比克	MZ
Myanmar (Burma)	缅甸	MM
Namibia	纳米比亚	NA
Nauru	瑙鲁	NR
Nepal	尼泊尔	NP
Netherlands	荷兰	NL
New Zealand	新西兰	NZ
Nicaragua	尼加拉瓜	NI
Niger	尼日尔	NE
Nigeria	尼日利亚	NG
Norway	挪威	NO
Oman	阿曼	OM
Pakistan	巴基斯坦	PK
Palau	帕劳	PW
Panama	巴拿马	PA
Papua New Guinea	巴布亚新几内亚	PG
Paraguay	巴拉圭	PY
Peru	秘鲁	PE
Philippines	菲律宾	PH
Poland	波兰	PL
Portugal	葡萄牙	PT
Qatar	卡塔尔	QA
Romania	罗马尼亚	RO
Russia	俄国	RU
Rwanda	卢旺达	RW
Saint Kitts and Nevis	圣基茨和尼维斯	KN
Saint Lucia	圣卢西亚	LC
Saint Vincent and the Grenadines	圣文森特和格林纳丁斯	VC
Samoa	萨摩亚	WS
San Marino	圣马力诺	SM
Sao Tome and Principe	圣多美和普林西比	ST
Saudi Arabia	沙特阿拉伯	SA
Senegal	塞内加尔	SN
Serbia	塞尔维亚	RS
Seychelles	塞舌尔	SC
Sierra Leone	塞拉利昂	SL
Singapore	新加坡	SG
Slovakia	斯洛伐克	SK
Slovenia	斯洛文尼亚	SI
Solomon Islands	所罗门群岛	SB
Somalia	索马里	SO
South Africa	南非	ZA
Spain	西班牙	ES
Sri Lanka	斯里兰卡	LK
Sudan	苏丹	SD
Suriname	苏里南	SR
Swaziland	斯威士兰	SZ
Sweden	瑞典	SE
Switzerland	瑞士	CH
Syria	叙利亚	SY
Taiwan	台湾	TW
Tajikistan	塔吉克斯坦	TJ
Tanzania	坦桑尼亚	TZ
Thailand	泰国	TH
Timor-Leste (East Timor)	东帝汶	TL
Togo	多哥	TG
Tonga	汤加	TO
Trinidad and Tobago	特里尼达和多巴哥	TT
Tunisia	突尼斯	TN
Turkey	土耳其	TR
Turkmenistan	土库曼斯坦	TM
Tuvalu	图瓦卢	TV
U.S. Virgin Islands	美属维尔京群岛	VI
Uganda	乌干达	UG
Ukraine	乌克兰	UA
United Arab Emirates	阿拉伯联合酋长国	AE
United Kingdom	英国	GB
United States	美国	US
Uruguay	乌拉圭	UY
Uzbekistan	乌兹别克斯坦	UZ
Vanuatu	瓦努阿图	VU
Vatican City	梵蒂冈城	VA
Venezuela	委内瑞拉	VE
Vietnam	越南	VN
Yemen	也门	YE
Zambia	赞比亚	ZM
Zimbabwe	津巴布韦	ZW
Kosovo	科索沃	XK
South Sudan	南苏丹	SS
China	中国	CN
Palestine	巴勒斯坦	PS
Curacao	库拉索	CW
Dominican Republic	多明尼加共和国	DO
Dominican Republic	多明尼加共和国	DO
Gibraltar	英属直布罗陀	GI
New Caledonia	新喀里多尼亚	NC
Cook Islands	库克群岛	CK
Reunion	留尼旺	RE
Guernsey	根西岛	GG
Guadeloupe	瓜德罗普	GP
Martinique	马提尼克	MQ
French Polynesia	法属波利尼西亚	PF
Faroe Islands	法罗群岛	FO
Greenland	格陵兰岛	GL
Jersey	泽西岛	JE
Aruba	阿鲁巴	AW
Puerto Rico	波多黎各	PR
Isle of Man	曼岛	IM
Guam	关岛	GU
Sint Maarten	荷属圣马丁	SX
Turks and Caicos	特克斯和凯科斯群岛	TC
Åland Islands	奥兰群岛	AX
Caribbean Netherlands	荷属加勒比	BQ
British Indian Ocean Territory	英属印度洋领地	IO
Christmas as Island	圣诞岛	CX
Cocos (Keeling) Islands	科科斯 (基林) 群岛	CC
Falkland Islands (Islas Malvinas)	福克兰群岛 (马尔维纳斯群岛)	FK
Mayotte	马约特	YT
Niue	纽埃	NU
Norfolk Island	诺福克岛	NF
Northern Mariana Islands	北马里亚纳群岛	MP
Pitcairn Islands	皮特凯恩群岛	PN
Saint Helena, Ascension and Tristan da Cunha	圣赫勒拿、阿森松岛和特里斯坦-达库尼亚	SH
Collectivity of Saint Martin	法属圣马丁	MF
Saint Pierre and Miquelon	圣皮埃尔和密克隆	PM
Tokelau	托克劳	TK
Wallis and Futuna	瓦利斯和富图纳	WF
American Samoa	美属萨摩亚	AS

撤销提币

可以撤销普通提币，但不支持撤销闪电网络上的提币。

限速：6次/s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/asset/cancel-withdrawal

请求示例

POST /api/v5/asset/cancel-withdrawal
body {
   "wdId":"1123456"
}

import okx.Funding as Funding

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

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

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# 撤销提币
result = fundingAPI.cancel_withdrawal(
    wdId="123456"
)
print(result)

请求参数

参数名	类型	是否必须	描述
wdId	String	是	提币申请ID

返回结果

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "wdId": "1123456"   
    }
  ]
}

返回参数

参数名	类型	描述
wdId	String	提币申请ID

获取提币记录

根据币种，提币状态，时间范围获取提币记录，按照时间倒序排列，默认返回100条数据。
支持Websocket订阅，参考提币信息频道。

限速：6 次/s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/asset/withdrawal-history

请求示例

# 查询最近的提币记录
GET /api/v5/asset/withdrawal-history

# 查询从2022年06月01日到2022年07月01日之间的BTC的提币记录
GET /api/v5/asset/withdrawal-history?ccy=BTC&after=1654041600000&before=1656633600000

请求参数

参数名	类型	是否必须	描述
ccy	String	否	币种名称，如 `BTC`
wdId	String	否	提币申请ID
clientId	String	否	客户自定义ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
txId	String	否	区块转账哈希记录
type	String	否	提币方式 `3`：内部转账 `4`：链上提币
state	String	否	提币状态阶段1：等待提币 `10`：等待划转 `0`：等待提币 `4`/`5`/`6`/`8`/`9`/`12`：等待客服审核 `7`：审核通过阶段2：提币处理中（适用于链上提币，内部转账无此阶段） `1`：正在将您的交易广播到链上 `15`：交易待确认 `16`：根据当地法律法规，您的提币最多可能需要 24 小时才能到账 `-3`：撤销中最终阶段 `-2`：已撤销 `-1`：失败 `2`：提币成功
after	String	否	查询在此之前的内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1654041600000`
before	String	否	查询在此之后的内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1656633600000`
limit	string	否	返回的结果集数量，默认为100，最大为100，不填默认返回100条

返回结果

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "chain": "ETH-Ethereum",
      "fee": "0.007",
      "feeCcy": "ETH",
      "ccy": "ETH",
      "clientId": "",
      "amt": "0.029809",
      "txId": "0x35c******b360a174d",
      "from": "156****359",
      "areaCodeFrom": "86",
      "to": "0xa30d1fab********7CF18C7B6C579",
      "areaCodeTo": "",
      "state": "2",
      "ts": "1655251200000",
      "nonTradableAsset": false,
      "wdId": "15447421"
    }
  ]
}

返回参数

参数名	类型	描述
ccy	String	币种
chain	String	币种链信息有的币种下有多个链，必须要做区分，如`USDT`下有`USDT-ERC20`，`USDT-TRC20`多个链
nonTradableAsset	Boolean	是否为不可交易资产 `true`：不可交易资产，`false`：可交易资产
amt	String	数量
ts	String	提币申请时间，Unix 时间戳的毫秒数格式，如 `1655251200000`
from	String	提币账户可以是`邮箱`/`手机号`/`子账户名`
areaCodeFrom	String	如果`from`为手机号，该字段为该手机号的区号
to	String	收币地址
areaCodeTo	String	如果`to`为手机号，该字段为该手机号的区号
tag	String	部分币种提币需要标签，若不需要则不返回此字段
pmtId	String	部分币种提币需要此字段（payment_id），若不需要则不返回此字段
memo	String	部分币种提币需要此字段，若不需要则不返回此字段
addrEx	Object	提币地址备注，部分币种提币需要，若不需要则不返回此字段。如币种TONCOIN的提币地址备注标签名为comment,则该字段返回：{'comment':'123456'}
txId	String	提币哈希记录内部转账该字段返回""
fee	String	提币手续费数量
feeCcy	String	提币手续费币种，如 `USDT`
state	String	提币状态
wdId	String	提币申请ID
clientId	String	客户自定义ID

获取充值/提现的详细状态

获取充值与提现的详细状态信息与预估完成时间。

限速：1次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/asset/deposit-withdraw-status

请求示例

# 查询充值
GET /api/v5/asset/deposit-withdraw-status?txId=xxxxxx&to=1672734730284&ccy=USDT&chain=USDT-ERC20

# 查询提现
GET /api/v5/asset/deposit-withdraw-status?wdId=200045249

请求参数

参数	类型	是否必须	描述
wdId	String	可选	提币申请ID，用于查询资金提现 `wdId`与`txId`必传其一也仅可传其一
txId	String	可选	区块转账哈希记录ID，用于查询资金充值 `wdId`与`txId`必传其一也仅可传其一
ccy	String	可选	币种，如`USDT` 查询充值时必填，需要与`txId`一并提供
to	String	可选	资金充值到账账户地址查询充值时必填，需要与`txId`一并提供
chain	String	可选	币种链信息，例如 USDT-ERC20 查询充值时必填，需要与`txId`一并提供

返回结果

{
    "code":"0",
    "data":[
        {
            "wdId": "200045249",
            "txId": "16f3638329xxxxxx42d988f97", 
            "state": "Pending withdrawal: Wallet is under maintenance, please wait.",
            "estCompleteTime": "01/09/2023, 8:10:48 PM"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
estCompleteTime	String	预估完成时间时区为 UTC+8；格式为 MM/dd/yyyy, h:mm:ss AM/PM estCompleteTime仅为预估完成时间，仅供参考
state	String	充值/提现的现处于的详细阶段提示冒号前面代表阶段，后面代表状态
txId	String	区块转账哈希记录提币如果`txId`已经生成，则返回，否则返回""
wdId	String	提币申请ID 如查询的是充值，该字段返回""

获取交易所列表（公共）

公共接口无须鉴权

限速：6次/s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/asset/exchange-list

请求示例

GET /api/v5/asset/exchange-list

请求参数

无

返回结果

{
  "code": "0",
  "msg": "",
  "data": [
    {
        "exchId": "did:ethr:0xfeb4f99829a9acdf52979abee87e83addf22a7e1",
        "exchName": "1xbet"
    }
  ]
}

返回参数

参数名	类型	描述
exchName	String	交易所名称，如 `1xbet`
exchId	String	交易所 ID，如 `did:ethr:0xfeb4f99829a9acdf52979abee87e83addf22a7e1`

申请月结单 (近一年)

申请最近一年的月结单。

限速：20 次/月

限速规则：UserID

权限：读取

HTTP Request

POST /api/v5/asset/monthly-statement

请求示例

POST /api/v5/asset/monthly-statement
body
{
    "month":"Jan"
}

请求参数

参数	类型	是否必须	描述
month	String	否	月份,默认上一个月。有效值是`Jan`, `Feb`, `Mar`, `Apr`,`May`, `Jun`, `Jul`,`Aug`, `Sep`,`Oct`,`Nov`,`Dec`

返回结果

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

返回参数

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

获取月结单 (近一年)

获取近一年的月结单

限速：10 次/2s

限速规则：UserID

权限：读取

HTTP Request

GET /api/v5/asset/monthly-statement

请求示例

GET /api/v5/asset/monthly-statement?month=Jan

请求参数

参数	类型	是否必须	描述
month	String	是	月份, 有效值是`Jan`, `Feb`, `Mar`, `Apr`,`May`, `Jun`, `Jul`,`Aug`, `Sep`,`Oct`,`Nov`,`Dec`

返回结果

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

返回参数

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

获取闪兑币种列表

限速：6次/s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/asset/convert/currencies

请求示例

GET /api/v5/asset/convert/currencies

请求参数

无

返回结果

{
    "code": "0",
    "data": [
        {
            "min": "",  // 已废弃
            "max": "",  // 已废弃
            "ccy": "BTC"
        },
        {
            "min": "",
            "max": "",
            "ccy": "ETH"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	币种名称，如 `BTC`
min	String	~~支持闪兑的最小值~~(已废弃)
max	String	~~支持闪兑的最大值~~(已废弃)

获取闪兑币对信息

限速：6次/s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/asset/convert/currency-pair

请求示例

GET /api/v5/asset/convert/currency-pair?fromCcy=USDT&toCcy=BTC

请求参数

参数	类型	是否必须	描述
fromCcy	String	是	消耗币种，如 `USDT`
toCcy	String	是	获取币种，如 `BTC`

返回结果

{
    "code": "0",
    "data": [
        {
            "baseCcy": "BTC",
            "baseCcyMax": "0.5",
            "baseCcyMin": "0.0001",
            "instId": "BTC-USDT",
            "quoteCcy": "USDT",
            "quoteCcyMax": "10000",
            "quoteCcyMin": "1"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	币对，如 `BTC-USDT`
baseCcy	String	交易货币币种，如 `BTC-USDT`中的`BTC`
baseCcyMax	String	交易货币支持闪兑的最大值
baseCcyMin	String	交易货币支持闪兑的最小值
quoteCcy	String	计价货币币种，如 `BTC-USDT`中的`USDT`
quoteCcyMax	String	计价货币支持闪兑的最大值
quoteCcyMin	String	计价货币支持闪兑的最小值

闪兑预估询价

限速：10次/s

限速规则：UserID

限速：1次/5s

限速规则：Instrument

权限：交易

权限：读取

HTTP请求

POST /api/v5/asset/convert/estimate-quote

请求示例

POST /api/v5/asset/convert/estimate-quote
body
{
    "baseCcy": "ETH",
    "quoteCcy": "USDT",
    "side": "buy",
    "rfqSz": "30",
    "rfqSzCcy": "USDT"
}

请求参数

参数名	类型	是否必须	描述
baseCcy	String	是	交易货币币种，如 `BTC-USDT`中的`BTC`
quoteCcy	String	是	计价货币币种，如 `BTC-USDT`中的`USDT`
side	String	是	交易方向买：`buy` 卖：`sell` 描述的是对于baseCcy的交易方向
rfqSz	String	是	询价数量
rfqSzCcy	String	是	询价币种
clQReqId	String	否	客户端自定义的订单标识字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
tag	String	否	订单标签适用于broker用户

返回结果

{
    "code": "0",
    "data": [
        {
            "baseCcy": "ETH",
            "baseSz": "0.01023052",
            "clQReqId": "",
            "cnvtPx": "2932.40104429",
            "origRfqSz": "30",
            "quoteCcy": "USDT",
            "quoteId": "quoterETH-USDT16461885104612381",
            "quoteSz": "30",
            "quoteTime": "1646188510461",
            "rfqSz": "30",
            "rfqSzCcy": "USDT",
            "side": "buy",
            "ttlMs": "10000"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
quoteTime	String	生成报价时间，Unix时间戳的毫秒数格式
ttlMs	String	报价有效期，单位为毫秒
clQReqId	String	客户端自定义的订单标识
quoteId	String	报价ID
baseCcy	String	交易货币币种，如 BTC-USDT 中BTC
quoteCcy	String	计价货币币种，如 BTC-USDT 中USDT
side	String	交易方向买：`buy` 卖：`sell`
origRfqSz	String	原始报价的数量
rfqSz	String	实际报价的数量
rfqSzCcy	String	报价的币种
cnvtPx	String	闪兑价格，单位为计价币
baseSz	String	闪兑交易币数量
quoteSz	String	闪兑计价币数量

闪兑交易

闪兑交易前需要先询价。

限速：10次/s

限速规则：UserID

权限：交易

同一方向(buy/sell) 1次/5s 交易限制

HTTP请求

POST /api/v5/asset/convert/trade

请求示例

POST /api/v5/asset/convert/trade
body
{
    "baseCcy": "ETH",
    "quoteCcy": "USDT",
    "side": "buy",
    "sz": "30",
    "szCcy": "USDT",
    "quoteId": "quoterETH-USDT16461885104612381"
}

请求参数

参数名	类型	是否必须	描述
quoteId	String	是	报价ID
baseCcy	String	是	交易货币币种，如 `BTC-USDT`中的`BTC`
quoteCcy	String	是	计价货币币种，如 `BTC-USDT`中的`USDT`
side	String	是	交易方向 `buy`：买 `sell`：卖描述的是对于`baseCcy`的交易方向
sz	String	是	用户报价数量报价数量应不大于预估询价中的询价数量
szCcy	String	是	用户报价币种
clTReqId	String	否	用户自定义的订单标识字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
tag	String	否	订单标签适用于broker用户

返回结果

{
    "code": "0",
    "data": [
        {
            "baseCcy": "ETH",
            "clTReqId": "",
            "fillBaseSz": "0.01023052",
            "fillPx": "2932.40104429",
            "fillQuoteSz": "30",
            "instId": "ETH-USDT",
            "quoteCcy": "USDT",
            "quoteId": "quoterETH-USDT16461885104612381",
            "side": "buy",
            "state": "fullyFilled",
            "tradeId": "trader16461885203381437",
            "ts": "1646188520338"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
tradeId	String	成交ID
quoteId	String	报价ID
clTReqId	String	用户自定义的订单标识
state	String	状态 `fullyFilled`：交易成功 `rejected`：交易失败
instId	String	币对，如 `BTC-USDT`
baseCcy	String	交易货币币种，如 `BTC-USDT`中`BTC`
quoteCcy	String	计价货币币种，如 `BTC-USDT`中`USDT`
side	String	交易方向买：`buy` 卖：`sell`
fillPx	String	成交价格，单位为计价币
fillBaseSz	String	成交的交易币数量
fillQuoteSz	String	成交的计价币数量
ts	String	闪兑交易时间，值为时间戳，Unix时间戳为毫秒数格式，如 `1597026383085`

获取闪兑交易历史

限速：6次/s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/asset/convert/history

请求示例

GET /api/v5/asset/convert/history

请求参数

参数	类型	是否必须	描述
clTReqId	String	否	用户自定义的订单标识字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
after	String	否	查询在此之前的内容，值为时间戳，Unix时间戳为毫秒数格式，如 `1597026383085`
before	String	否	查询在此之后的内容，值为时间戳，Unix时间戳为毫秒数格式，如 `1597026383085`
limit	String	否	返回的结果集数量，默认为100，最大为100
tag	String	否	订单标签适用于broker用户如果闪兑交易带上了`tag`,查询时必须也带上此参数

返回结果

{
    "code": "0",
    "data": [
        {
            "clTReqId": "",
            "instId": "ETH-USDT",
            "side": "buy",
            "fillPx": "2932.401044",
            "baseCcy": "ETH",
            "quoteCcy": "USDT",
            "fillBaseSz": "0.01023052",
            "state": "fullyFilled",
            "tradeId": "trader16461885203381437",
            "fillQuoteSz": "30",
            "ts": "1646188520000"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
tradeId	String	成交ID
clTReqId	String	用户自定义的订单标识
state	String	`fullyFilled`：交易成功 `rejected`：交易失败
instId	String	币对，如 `BTC-USDT`
baseCcy	String	交易货币币种，如 `BTC-USDT`中的`BTC`
quoteCcy	String	计价货币币种，如 `BTC-USDT`中的`USDT`
side	String	交易方向买：`buy` 卖：`sell`
fillPx	String	成交价格，单位为计价币
fillBaseSz	String	成交的交易币数量
fillQuoteSz	String	成交的计价币数量
ts	String	闪兑交易时间，值为时间戳，Unix时间戳为毫秒数格式，如 `1597026383085`

WebSocket

充值信息频道

当发起充值或者充值状态发生变化时会触发消息推送。
支持母账户或者子账户的订阅

如果是母账户订阅，可以同时接受母账户与子账户的充值信息的推送
如果是子账户订阅，则仅支持子账户充值信息的推送

服务地址

/ws/v5/business (需要登录)

请求示例

{
    "op": "subscribe",
    "args": [
        {
            "channel": "deposit-info"
        }
    ]
}

请求参数

参数名	类型	是否必填	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `deposit-info`
> ccy	String	否	币种名称，如 `BTC`

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "deposit-info"
    },
    "connId": "a4d3ae55"
}

失败返回示例

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

返回参数

参数名	类型	是否必填	描述
event	String	是	操作 `subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名 `deposit-info`
> ccy	String	否	币种名称，如 `BTC`
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket连接ID

推送示例

{
    "arg": {
        "channel": "deposit-info",
        "uid": "289320****60975104"
    },
    "data": [{
        "actualDepBlkConfirm": "0",
        "amt": "1",
        "areaCodeFrom": "",
        "ccy": "USDT",
        "chain": "USDT-TRC20",
        "depId": "88165462",
        "from": "",
        "fromWdId": "",
        "pTime": "1674103661147",
        "state": "0",
        "subAcct": "test",
        "to": "TEhFAqpuHa3LY*****8ByNoGnrmexeGMw",
        "ts": "1674103661123",
        "txId": "bc5376817*****************dbb0d729f6b",
        "uid": "289320****60975104"
    }]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> uid	String	用户标识
> ccy	String	币种名称，如 `BTC`
data	Array	订阅的数据
> uid	String	(产生数据者的）用户标识
> subAcct	String	子账户名称如果是母账户产生的数据，该字段返回""
> pTime	String	推送时间，Unix时间戳的毫秒数格式，如 1597026383085
> ccy	String	币种名称，如 `BTC`
> chain	String	币种链信息有的币种下有多个链，必须要做区分，如`USDT`下有`USDT-ERC20`，`USDT-TRC20`多个链
> amt	String	充值数量
> from	String	充值账户，只显示内部账户转账地址，不显示区块链充值地址
> areaCodeFrom	String	如果`from`为手机号，该字段为该手机号的区号
> to	String	到账地址
> txId	String	区块转账哈希记录
> ts	String	充值记录创建时间，Unix 时间戳的毫秒数格式，如 `1655251200000`
> state	String	充值状态 `0`：等待确认 `1`：确认到账 `2`：充值成功 `8`：因该币种暂停充值而未到账，恢复充值后自动到账 `11`：命中地址黑名单 `12`：账户或充值被冻结 `13`：子账户充值拦截 `14`：KYC限额
> depId	String	充值记录 ID
> fromWdId	String	内部转账发起者提币申请 ID 如果该笔充值来自于内部转账，则该字段展示内部转账发起者的提币申请 ID，其他情况返回""
> actualDepBlkConfirm	String	最新的充币网络确认数

提币信息频道

当发起提币或者提币状态发生变化时会触发消息推送。
支持母账户或者子账户的订阅

如果是母账户订阅，可以同时接受母账户与子账户的提币信息的推送
如果是子账户订阅，则仅支持子账户提币信息的推送

服务地址

/ws/v5/business (需要登录)

请求示例

{
    "op": "subscribe",
    "args": [
        {
            "channel": "withdrawal-info"
        }
    ]
}

请求参数

参数名	类型	是否必填	描述
op	String	是	操作 `subscribe` `unsubscribe`
args	Array	是	请求订阅的频道列表
> channel	String	是	频道名 `withdrawal-info`
> ccy	String	否	币种名称，如 `BTC`

成功返回示例

{
    "event": "subscribe",
    "arg": {
        "channel": "withdrawal-info"
    },
    "connId": "a4d3ae55"
}

失败返回示例

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

返回参数

参数名	类型	是否必填	描述
event	String	是	操作 `subscribe` `unsubscribe` `error`
arg	Object	否	订阅的频道
> channel	String	是	频道名 `withdrawal-info`
> ccy	String	否	币种名称，如 `BTC`
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket连接ID

推送示例

{
    "arg": {
        "channel": "withdrawal-info",
        "uid": "289320*****0975104"
    },
    "data": [{
        "addrEx": null,
        "amt": "2",
        "areaCodeFrom": "",
        "areaCodeTo": "",
        "ccy": "USDT",
        "chain": "USDT-TRC20",
        "clientId": "",
        "fee": "0.8",
        "feeCcy": "USDT",
        "from": "",
        "memo": "",
        "nonTradableAsset": false,
        "pTime": "1674103268578",
        "pmtId": "",
        "state": "0",
        "subAcct": "test",
        "tag": "",
        "to": "TN8CKTQMnpWfT******8KipbJ24ErguhF",
        "ts": "1674103268472",
        "txId": "",
        "uid": "289333*****1101696",
        "wdId": "63754560"
    }]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> uid	String	用户标识
> ccy	String	币种名称，如 `BTC`
data	Array	订阅的数据
> uid	String	(产生数据者的）用户标识
> subAcct	String	子账户名称如果是母账户产生的数据，该字段返回""
> pTime	String	推送时间，Unix时间戳的毫秒数格式，如 1597026383085
> ccy	String	币种
> chain	String	币种链信息有的币种下有多个链，必须要做区分，如`USDT`下有`USDT-ERC20`，`USDT-TRC20`多个链
> nonTradableAsset	String	是否为不可交易资产 `true`：不可交易资产，`false`：可交易资产
> amt	String	数量
> ts	String	提币申请时间，Unix 时间戳的毫秒数格式，如 `1655251200000`
> from	String	提币账户可以是`邮箱`/`手机号`/`子账户名`
> areaCodeFrom	String	如果`from`为手机号，该字段为该手机号的区号
> to	String	收币地址
> areaCodeTo	String	如果`to`为手机号，该字段为该手机号的区号
> tag	String	部分币种提币需要标签
> pmtId	String	部分币种提币需要此字段（payment_id）
> memo	String	部分币种提币需要此字段
> addrEx	Object	提币地址备注。如币种TONCOIN的提币地址备注标签名为comment,则该字段返回：{'comment':'123456'}
> txId	String	提币哈希记录内部转账该字段返回""
> fee	String	提币手续费数量
> feeCcy	String	提币手续费币种，如 `USDT`
> state	String	提币状态阶段1：等待提币 `10`：等待划转 `0`：等待提币 `4`/`5`/`6`/`8`/`9`/`12`：等待客服审核 `7`：审核通过阶段2：提币处理中（适用于链上提币，内部转账无此阶段） `1`：正在将您的交易广播到链上 `15`：交易待确认 `16`：根据当地法律法规，您的提币最多可能需要 24 小时才能到账 `-3`：撤销中最终阶段 `-2`：已撤销 `-1`：失败 `2`：提币成功
> wdId	String	提币申请ID
> clientId	String	客户自定义ID

子账户

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

REST API

查看子账户列表

仅适用于母账户

限速：2次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/users/subaccount/list

请求示例

GET /api/v5/users/subaccount/list

import okx.SubAccount as SubAccount

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

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

subAccountAPI = SubAccount.SubAccountAPI(apikey, secretkey, passphrase, False, flag)

# 查看子账户列表
result = subAccountAPI.get_subaccount_list()
print(result)

请求参数

参数名	类型	是否必须	描述
enable	String	否	子账户状态 `true`: 正常使用 `false`: 冻结
subAcct	String	否	子账户名称
after	String	否	查询在此之前的内容，值为子账户创建时间戳，Unix时间戳为毫秒数格式
before	String	否	查询在此之后的内容，值为子账户创建时间戳，Unix时间戳为毫秒数格式
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "canTransOut": false,
            "enable": true,
            "frozenFunc": [
            ],
            "gAuth": false,
            "label": "D456DDDLx",
            "mobile": "",
            "subAcct": "D456DDDL",
            "ts": "1659334756000",
            "type": "1",
            "uid": "3400***********7413"
        }
    ]
}

返回参数

参数名	类型	描述
type	String	子账户类型 `1`：普通子账户 `2`：资管子账户 `5`：托管交易子账户 - Copper `9`：资管交易子账户 - Copper `12`：托管交易子账户 - Komainu
enable	Boolean	子账户状态 `true`：正常使用 `false`：冻结（全局）
subAcct	String	子账户名称
uid	String	子账户UID
label	String	子账户备注
mobile	String	子账户绑定手机号
gAuth	Boolean	子账户是否开启的登录时的谷歌验证 `true`：已开启 `false`：未开启
frozenFunc	Array of string	被冻结的功能 `trading`：交易 `convert`：闪兑 `transfer`：母子账户间资金划转 `withdrawal`：提币 `deposit`：充值 `flexible_loan`：活期借币
canTransOut	Boolean	是否可以主动转出 `true`：可以转出 `false`：不可转出
ts	String	子账户创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`

重置子账户的APIKey

仅适用于母账户，且母账户APIKey必须绑定IP。仅适用于有交易权限的母账户 API key。

限速：1次/s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/users/subaccount/modify-apikey

请求示例

POST /api/v5/users/subaccount/modify-apikey
body
{
    "subAcct":"yongxu",
    "apiKey":"49e1b84b-6dee-4894-80ee-ce9eb7ad614f",
    "ip":"1.1.1.1"
}

import okx.SubAccount as SubAccount

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

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

subAccountAPI = SubAccount.SubAccountAPI(apikey, secretkey, passphrase, False, flag)

# 重置子账户的APIKey
result = subAccountAPI.reset_subaccount_apikey(
    subAcct="hahawang1",
    apiKey="",
    ip=""
)
print(result)

请求参数

参数名	类型	是否必须	描述
subAcct	String	是	子账户名称
apiKey	String	是	子账户API的公钥
label	String	否	子账户APIKey的备注，如果填写该字段，则该字段会被重置
perm	String	否	子账户APIKey权限 `read_only`：读取 `trade`：交易多个权限用半角逗号隔开。如果填写该字段，则该字段会被重置。
ip	String	否	子账户APIKey绑定ip地址，多个ip用半角逗号隔开，最多支持20个ip。如果填写该字段，那该字段会被重置。如果ip传""，则表示解除IP绑定。

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "subAcct": "yongxu",
        "label": "v5",
        "apiKey": "arg13sdfgs",
        "perm": "read,trade",
        "ip": "1.1.1.1",
        "ts": "1597026383085"
    }]
}

返回参数

参数名	类型	描述
subAcct	String	子账户名称
label	String	APIKey的备注
apiKey	String	API公钥
perm	String	APIKey权限
ip	String	APIKey绑定的ip地址
ts	String	创建时间

获取子账户交易账户余额

获取子账户交易账户余额（适用于母账户）

限速：6次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/account/subaccount/balances

请求示例

GET /api/v5/account/subaccount/balances?subAcct=test1

import okx.SubAccount as SubAccount

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

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

subAccountAPI = SubAccount.SubAccountAPI(apikey, secretkey, passphrase, False, flag)

# 获取子账户交易账户余额
result = subAccountAPI.get_account_balance(
    subAcct="hahawang1"
)
print(result)

请求参数

参数名	类型	是否必须	描述
subAcct	String	是	子账户名称

返回结果

{
    "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",
                    "smtSyncEq": "0",
                    "spotCopyTradingEq": "0",
                    "fixedBal": "0",
                    "frozenBal": "0",
                    "imr": "",
                    "interest": "0",
                    "isoEq": "0",
                    "isoLiab": "0",
                    "liab": "0",
                    "maxLoan": "10000",
                    "mgnRatio": "",
                    "mmr": "",
                    "notionalLever": "",
                    "ordFrozen": "0",
                    "twap": "0",
                    "uTime": "1620722938250",
                    "upl": "0",
                    "uplLiab": "0",
                    "borrowFroz": "",
                    "spotIsoBal": "0",
                    "spotBal": "",
                    "openAvgPx": "",
                    "accAvgPx": "",
                    "spotUpl": "",
                    "spotUplRatio": "",
                    "totalPnl": "",
                    "totalPnlRatio": ""
                },
                {
                    "availBal": "",
                    "availEq": "33.6799714158199414",
                    "cashBal": "33.2009985",
                    "ccy": "BTC",
                    "crossLiab": "0",
                    "disEq": "1239950.9687532129092577",
                    "eq": "33.771820625136023",
                    "eqUsd": "1239950.9687532129092577",
                    "smtSyncEq": "0",
                    "spotCopyTradingEq": "0",
                    "fixedBal": "0",
                    "frozenBal": "0.0918492093160816",
                    "imr": "",
                    "interest": "0",
                    "isoEq": "0",
                    "isoLiab": "0",
                    "liab": "0",
                    "maxLoan": "1453.92289531493594",
                    "mgnRatio": "",
                    "mmr": "",
                    "notionalLever": "",
                    "ordFrozen": "0",
                    "twap": "0",
                    "uTime": "1620722938250",
                    "upl": "0.570822125136023",
                    "uplLiab": "0",
                    "borrowFroz": "",
                    "spotIsoBal": "0",
                    "spotBal": "",
                    "openAvgPx": "",
                    "accAvgPx": "",
                    "spotUpl": "",
                    "spotUplRatio": "",
                    "totalPnl": "",
                    "totalPnlRatio": ""
                }
            ],
            "imr": "3372.2942371050594217",
            "isoEq": "0",
            "mgnRatio": "70375.35408747017",
            "mmr": "134.8917694842024",
            "notionalUsd": "33722.9423710505978888",
            "ordFroz": "0",
            "totalEq": "11172992.1657531589092577",
            "uTime": "1623392334718",
            "upl": "-7.571730042000012"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
uTime	String	获取账户信息的最新时间，Unix时间戳的毫秒数格式，如 `1597026383085`
totalEq	String	美金层面权益
isoEq	String	美金层面逐仓仓位权益适用于`现货和合约模式`/`跨币种保证金模式`/`组合保证金模式`
adjEq	String	美金层面有效保证金适用于`跨币种保证金模式`/`组合保证金模式`
ordFroz	String	美金层面全仓挂单占用保证金适用于`跨币种保证金模式`
imr	String	美金层面占用保证金适用于`跨币种保证金模式`/`组合保证金模式`
mmr	String	美金层面维持保证金适用于`跨币种保证金模式`/`组合保证金模式`
borrowFroz	String	账户美金层面潜在借币占用保证金仅适用于`跨币种保证金模式`/`组合保证金模式`。在其他账户模式下为""。
mgnRatio	String	美金层面保证金率适用于`跨币种保证金模式`/`组合保证金模式`
notionalUsd	String	以美金价值为单位的持仓数量，即仓位美金价值适用于`跨币种保证金模式`/`组合保证金模式`
upl	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	币种负债额适用于`跨币种保证金模式`/`组合保证金模式`
> upl	String	未实现盈亏适用于`现货和合约模式`/`跨币种保证金模式`/`组合保证金模式`
> uplLiab	String	由于仓位未实现亏损导致的负债适用于`跨币种保证金模式`/`组合保证金模式`
> crossLiab	String	币种全仓负债额适用于`跨币种保证金模式`/`组合保证金模式`
> isoLiab	String	币种逐仓负债额适用于`跨币种保证金模式`/`组合保证金模式`
> mgnRatio	String	币种全仓保证金率，衡量账户内某项资产风险的指标适用于`现货和合约模式`且有全仓仓位时
> imr	String	币种维度全仓占用保证金适用于`现货和合约模式`且有全仓仓位时
> mmr	String	币种维度全仓维持保证金适用于`现货和合约模式`且有全仓仓位时
> interest	String	计息适用于`跨币种保证金模式`/`组合保证金模式`
> twap	String	当前负债币种触发系统自动换币的风险 0、1、2、3、4、5其中之一，数字越大代表您的负债币种触发自动换币概率越高适用于`跨币种保证金模式`/`组合保证金模式`
> maxLoan	String	币种最大可借适用于`跨币种保证金模式`/`组合保证金模式` 的全仓
> eqUsd	String	币种权益美金价值
> borrowFroz	String	币种美金层面潜在借币占用保证金仅适用于`跨币种保证金模式`/`组合保证金模式`。在其他账户模式下为""。
> notionalLever	String	币种杠杆倍数适用于`现货和合约模式`
> spotIsoBal	String	现货逐仓余额，仅适用于现货带单/跟单。
> smtSyncEq	String	合约智能跟单权益默认为0，仅适用于跟单人。
> spotCopyTradingEq	String	现货智能跟单权益默认为0，仅适用于跟单人。
> spotBal	String	现货余额，单位为币种，比如 BTC。详情
> openAvgPx	String	现货开仓成本价单位 USD。详情
> accAvgPx	String	现货累计成本价单位 USD。详情
> spotUpl	String	现货未实现收益，单位 USD。详情
> spotUplRatio	String	现货未实现收益率。详情
> totalPnl	String	现货累计收益，单位 USD。详情
> totalPnlRatio	String	现货累计收益率。详情

获取子账户资金账户余额

获取子账户资金账户余额（适用于母账户）

限速：6次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/asset/subaccount/balances

请求示例

GET /api/v5/asset/subaccount/balances?subAcct=test1

import okx.SubAccount as SubAccount

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

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

subAccountAPI = SubAccount.SubAccountAPI(apikey, secretkey, passphrase, False, flag)

# 获取子账户资金账户余额
result = subAccountAPI.get_funding_balance(
    subAcct="hahawang1"
)
print(result)

请求参数

参数名	类型	是否必须	描述
subAcct	String	是	子账户名称
ccy	String	否	币种，如 `BTC` 支持多币种查询（不超过20个），币种之间半角逗号分隔

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
            "availBal": "37.11827078",
            "bal": "37.11827078",
            "ccy": "ETH",
            "frozenBal": "0"
        }
    ]
}

返回参数

参数名	类型	描述
ccy	String	币种，如 `BTC`
bal	String	余额
frozenBal	String	冻结余额（不可用）
availBal	String	可用余额

获取子账户最大可转余额

获取子账户最大可转余额（适用于母账户）。不指定币种会返回所有拥有的币种资产可划转数量。

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/account/subaccount/max-withdrawal

请求示例

GET /api/v5/account/subaccount/max-withdrawal?subAcct=test1

请求参数

参数名	类型	是否必须	描述
subAcct	String	是	子账户名称
ccy	String	否	币种，如 `BTC` 支持多币种查询（不超过20个），币种之间半角逗号分隔

返回结果

{
   "code":"0",
   "data":[
      {
         "ccy":"BTC",
         "maxWd":"3",
         "maxWdEx":"",
         "spotOffsetMaxWd":"3",
         "spotOffsetMaxWdEx":""
      },
      {
         "ccy":"ETH",
         "maxWd":"15",
         "maxWdEx":"",
         "spotOffsetMaxWd":"15",
         "spotOffsetMaxWdEx":""
      },
      {
         "ccy":"USDT",
         "maxWd":"10600",
         "maxWdEx":"",
         "spotOffsetMaxWd":"10600",
         "spotOffsetMaxWdEx":""
      }
   ],
   "msg":""
}

Response Parameters

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

查询子账户转账记录

仅适用于母账户

限速：6次/s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/asset/subaccount/bills

请求示例

GET /api/v5/asset/subaccount/bills

import okx.SubAccount as SubAccount

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

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

subAccountAPI = SubAccount.SubAccountAPI(apikey, secretkey, passphrase, False, flag)

# 查询子账户转账记录
result = subAccountAPI.bills()
print(result)

请求参数

参数名	类型	是否必须	描述
ccy	String	否	币种，如 BTC
type	String	否	划转类型 `0`：母账户转子账户 `1`：子账户转母账户
subAcct	String	否	子账户名称
after	String	否	查询在billId创建时间之前(不包含)的内容，值为时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
before	String	否	查询在billId创建时间之后(不包含)的内容，值为时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
      {
        "amt": "1.1",
        "billId": "89887685",
        "ccy": "USDT",
        "subAcct": "hahatest1",
        "ts": "1712560959000",
        "type": "0"
      }
    ]
}

返回参数

参数名	类型	描述
billId	String	账单ID
ccy	String	划转币种
amt	String	划转金额
type	String	账单类型
subAcct	String	子账户名称
ts	String	账单ID创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`

查询托管子账户转账记录

仅适用于交易团队母账户查看托管给自己的托管子账户转账记录

限速：6次/s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/asset/subaccount/managed-subaccount-bills

请求示例

GET /api/v5/asset/subaccount/managed-subaccount-bills

请求参数

参数名	类型	是否必须	描述
ccy	String	否	币种，如 `BTC`
type	String	否	划转类型 `0`：母账户转子账户 `1`：子账户转母账户
subAcct	String	否	子账户名称
subUid	String	否	子账户UID
after	String	否	查询在billId创建时间之前(不包含)的内容，值为时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
before	String	否	查询在billId创建时间之后(不包含)的内容，值为时间戳，Unix时间戳的毫秒数格式，如 `1597026383085`
limit	String	否	分页返回的结果集数量，最大为100，默认返回100条

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "billId": "12344",
        "type": "1",
        "ccy": "BTC",
        "amt": "2",
        "subAcct": "test-1",
        "subUid": "xxxxxx",
        "ts": "1597026383085"
    }]
}

返回参数

参数名	类型	描述
billId	String	账单ID
ccy	String	划转币种
amt	String	划转金额
type	String	账单类型
subAcct	String	子账户名称
subUid	String	子账户UID
ts	String	账单ID创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`

子账户间资金划转

母账户控制子账户与子账户之间划转（仅适用于母账户）

调用时，APIKey 需要有交易权限

限速：1次/s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/asset/subaccount/transfer

请求示例

POST /api/v5/asset/subaccount/transfer
body
{
    "ccy":"USDT",
    "amt":"1.5",
    "from":"6",
    "to":"6",
    "fromSubAccount":"test-1",
    "toSubAccount":"test-2"
}

import okx.SubAccount as SubAccount

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

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

subAccountAPI = SubAccount.SubAccountAPI(apikey, secretkey, passphrase, False, flag)

# 子账户间资金划转
result = subAccountAPI.subAccount_transfer(
    ccy="USDT",
    amt="10",
    froms="6",
    to="6",
    fromSubAccount="test-1",
    toSubAccount="test-2"
)
print(result)

请求参数

参数名	类型	是否必须	描述
ccy	String	是	币种
amt	String	是	划转数量
from	String	是	转出子账户类型 `6`：资金账户 `18`：交易账户
to	String	是	转入子账户类型 `6`：资金账户 `18`：交易账户
fromSubAccount	String	是	转出子账户的子账户名称
toSubAccount	String	是	转入子账户的子账户名称
loanTrans	Boolean	否	是否支持`跨币种保证金模式`或`组合保证金模式`下的借币转入/转出默认`false`
omitPosRisk	String	否	是否忽略仓位风险默认为`false` 仅适用于`组合保证金模式`

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "transId":"12345",
        }
    ]
}

返回参数

参数名	类型	描述
transId	String	划转ID

设置子账户主动转出权限

设置子账户转出权限（仅适用于母账户），默认可转出至母账户。

限速：1次/s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/users/subaccount/set-transfer-out

请求示例

POST /api/v5/users/subaccount/set-transfer-out
body
{
    "subAcct": "Test001,Test002",
    "canTransOut": true
}

import okx.SubAccount as SubAccount

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

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

subAccountAPI = SubAccount.SubAccountAPI(apikey, secretkey, passphrase, False, flag)

# 设置子账户主动转出权限
result = subAccountAPI.set_permission_transfer_out(
    subAcct="hahawang1",
    canTransOut=False
)
print(result)

请求参数

参数名	类型	是否必须	描述
subAcct	String	是	子账户名称，支持设置多个（不超过20个），子账户名称之间半角逗号分隔
canTransOut	Boolean	否	是否可以主动转出，默认为`true` `false`：不可转出 `true`：可以转出

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "subAcct": "Test001",
            "canTransOut": true
        },
        {
            "subAcct": "Test002",
            "canTransOut": true
        }
    ]
}

返回参数

参数名	类型	描述
subAcct	String	子账户名称
canTransOut	Boolean	是否可以主动转出 `false`：不可转出 `true`：可以转出

查看被托管的子账户列表

交易团队使用该接口查看当前托管中的子账户列表

限速：1次/s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/users/entrust-subaccount-list

请求示例

GET /api/v5/users/entrust-subaccount-list

import okx.SubAccount as SubAccount

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

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

subAccountAPI = SubAccount.SubAccountAPI(apikey, secretkey, passphrase, False, flag)

# 查看被托管的子账户列表
result = subAccountAPI.get_entrust_subaccount_list()
print(result)

请求参数

参数名	类型	是否必须	描述
subAcct	String	否	子账户名称

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
       {
          "subAcct":"test-1"
       },
       {
          "subAcct":"test-2"
       }
    ]
}

返回参数

参数名	类型	描述
subAcct	String	子账户名称

金融产品

链上赚币

仅资金账户中的资产支持申购。了解更多

GET / 查看项目

限速：3次/s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/finance/staking-defi/offers

请求示例

GET /api/v5/finance/staking-defi/offers

请求参数

参数	类型	是否必须	描述
productId	String	否	项目ID
protocolType	String	否	项目类型 `defi`：链上赚币
ccy	String	否	投资币种，如 `BTC`

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "DOT",
            "productId": "101",
            "protocol": "Polkadot",
            "protocolType": "defi",
            "term": "0",
            "apy": "0.1767",
            "earlyRedeem": false,
            "state": "purchasable",
            "investData": [
                {
                    "bal": "0",
                    "ccy": "DOT",
                    "maxAmt": "0",
                    "minAmt": "2"
                }
            ],
            "earningData": [
                {
                    "ccy": "DOT",
                    "earningType": "0"
                }
            ],
            "fastRedemptionDailyLimit": "",
            "redeemPeriod": [
                "28D",
                "28D"
            ]
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	币种名称，如 `BTC`
productId	String	项目ID
protocol	String	项目名称
protocolType	String	项目类型 `defi`：链上赚币
term	String	项目期限活期为0，其他则显示定期天数
apy	String	预估年化如果年化为`7%` ，则该字段为`0.07`
earlyRedeem	Boolean	项目是否支持提前赎回
investData	Array	目前用户可用来投资的目标币种信息
> ccy	String	投资币种，如`BTC`
> bal	String	可投数量
> minAmt	String	最小申购量
> maxAmt	String	最大可申购量
earningData	Array	收益信息
> ccy	String	收益币种，如`BTC`
> earningType	String	收益类型 `0`：预估收益 `1`：累计发放收益
state	String	项目状态 `purchasable`：可申购 `sold_out`：售罄 `stop`：暂停申购
redeemPeriod	Array of string	赎回期，形式为 [最小赎回时间,最大赎回时间] `H`：小时，`D`：天例 ["1H","24H"] 表示赎回期时1小时到24小时。 ["14D","14D"] 表示赎回期为14天。
fastRedemptionDailyLimit	String	快速赎回每日最高限额如果不支持快速赎回，则返回""

POST / 申购项目

限速：2次/s

限速规则：UserID

权限：交易

HTTP 请求

POST /api/v5/finance/staking-defi/purchase

请求示例

# 投资100ZIL30天的锁仓挖矿项目
POST /api/v5/finance/staking-defi/purchase
body 
{
    "productId":"1234",
    "investData":[
      {
        "ccy":"ZIL",
        "amt":"100"
      }
    ],
    "term":"30"
}

请求参数

参数	类型	是否必须	描述
productId	String	是	项目ID
investData	Array	是	投资信息
> ccy	String	是	投资币种，如 `BTC`
> amt	String	是	投资数量
term	String	可选	投资期限定期项目必须指定投资期限
tag	String	否	订单标签字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间

返回结果

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "ordId": "754147",
      "tag": ""
    }
  ]
}

返回参数

参数名	类型	描述
ordId	String	订单ID
tag	String	订单标签

POST / 赎回项目

限速：2次/s

限速规则：UserID

权限：交易

HTTP 请求

POST /api/v5/finance/staking-defi/redeem

请求示例

# 提前赎回项目投资
POST /api/v5/finance/staking-defi/redeem
body 
{
    "ordId":"754147",
    "protocolType":"defi",
    "allowEarlyRedeem":true
}

请求参数

参数	类型	是否必须	描述
ordId	String	是	订单ID
protocolType	String	是	项目类型 `defi`：链上赚币
allowEarlyRedeem	Boolean	否	是否提前赎回默认为`false`

返回结果

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "ordId": "754147",
      "tag": ""
    }
  ]
}

返回参数

参数名	类型	描述
ordId	String	订单ID
tag	String	订单标签

POST / 撤销项目申购/赎回

限速：2次/s

限速规则：UserID

权限：交易

HTTP 请求

POST /api/v5/finance/staking-defi/cancel

请求示例

POST /api/v5/finance/staking-defi/cancel
body 
{
    "ordId":"754147",
    "protocolType":"defi"
}

请求参数

参数	类型	是否必须	描述
ordId	String	是	订单ID
protocolType	String	是	项目类型 `defi`：链上赚币

返回结果

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "ordId": "754147",
      "tag": ""
    }
  ]
}

返回参数

参数名	类型	描述
ordId	String	订单ID
tag	String	订单标签

GET / 查看活跃订单

限速：3次/s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/finance/staking-defi/orders-active

请求示例

GET /api/v5/finance/staking-defi/orders-active

请求参数

参数	类型	是否必须	描述
productId	String	否	项目ID
protocolType	String	否	项目类型 `defi`：链上赚币
ccy	String	否	投资币种，如 `BTC`
state	String	否	订单状态 `8`: 待上车（预约中） `13`: 订单取消中 `9`: 上链中 `1`: 收益中 `2`: 赎回中

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
       {
            "ordId":"123456",
            "state":"1",
            "ccy": "GLMR",      
            "protocol": "glimmar",      
            "protocolType":"staking",  
            "term":"15",
            "apy":"0.5496",
            "investData":[
              {
                "ccy":"GLMR",
                "amt":"100"
              }
            ],
            "earningData": [
             {
                "ccy": "GLMR",
                "earningType":"1",         // 每日发放
                "earnings":"3"
             }
            ],
            "purchasedTime":"1597026383085",
            "tag": "",
            "estSettlementTime": "",
            "cancelRedemptionDeadline": "",
            "fastRedemptionData": []
        },
        {
            "ordId":"123457",
            "state":"1",
            "ccy": "USDT",      
            "protocol": "compond",      //DEFI-loan
            "protocolType":"defi", 
            "term":"0",
            "apy":"0.12",
            "investData":[
              {
                "ccy":"USDT",
                "amt":"20",
                "minAmt":"1",
                "maxAmt":""
              }
            ],
            "earningData": [
             {
                "ccy": "USDT",
                "earningType":"0",      // 赎回发放
                "earnings":"3"        //预估收益
             },
             {
                "ccy": "COMP",
                "earningType":"1",      // 每日发放
                "earnings":"3"        // 累计收益
             }
            ],
            "purchasedTime":"1597026383085",
            "tag": "",
            "estSettlementTime": "",
            "cancelRedemptionDeadline": "",
            "fastRedemptionData": []
        },
        {
            "ordId":"123458",
            "state":"1",
            "ccy": "ETH",      
            "protocol": "sushiswap",      //DEFI
            "protocolType":"defi",  
            "term":"0",
            "apy":"0.12",
            "investData":[
              {
                "ccy":"USDT",
                "amt":"100"
              },
              {
                "ccy":"ETH",
                "amt":"0.03"
              }
            ],
            "earningData": [
             {
                "ccy": "SUSHI",
                "earningType":"1",      // 每日发放
                "earnings":"3"        // 累计收益
             }
            ],
            "purchasedTime":"1597026383085",
            "tag": "",
            "estSettlementTime": "",
            "cancelRedemptionDeadline": "",
            "fastRedemptionData": []
        },
        {
            "ordId":"123458",
            "state":"3",
            "ccy": "LON",      
            "protocol": "tokenlon",      //DEFI-pos
            "protocolType":"defi",  
            "earningCcy": ["LON"],
            "term":"7",
            "apy":"0.12",
            "investData":[
              {
                "ccy":"LON",
                "amt":"1"
              }
            ],
            "earningData": [
             {
                "ccy": "LON",
                "earningType":"0",      // 赎回发放
                "earnings":"3"        // 累计收益
             }
            ],
            "purchasedTime":"1597026383085",
            "tag": "",
            "estSettlementTime": "",
            "cancelRedemptionDeadline": "",
            "fastRedemptionData": []
        }
    ]
}

返回参数

参数名	类型	描述
ccy	String	币种名称，如 `BTC`
ordId	String	订单ID
productId	String	项目ID
state	String	订单状态 8: 待上车（预约中） 13: 订单取消中 9: 上链中 1: 收益中 2: 赎回中
protocol	String	项目名称
protocolType	String	项目类型 `defi`：链上赚币
term	String	项目期限活期为0，其他则显示定期天数
apy	String	预估年化如果年化为7% ，则该字段为0.07 保留到小数点后4位（截位）
investData	Array of object	用户投资信息
> ccy	String	投资币种，如 `BTC`
> amt	String	已投资数量
earningData	Array of object	收益信息
> ccy	String	收益币种，如 `BTC`
> earningType	String	收益类型 `0`：预估收益 `1`：实际到账收益
> earnings	String	收益数量
fastRedemptionData	Array of object	快速赎回信息
> ccy	String	快速赎回币种，如 `BTC`
> redeemingAmt	String	赎回中的数量
purchasedTime	String	用户订单创建时间，值为时间戳，Unix时间戳为毫秒数格式，如 `1597026383085`
estSettlementTime	String	预估赎回到账时间
cancelRedemptionDeadline	String	撤销赎回申请截止时间
tag	String	订单标签

GET / 查看历史订单

限速：3次/s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/finance/staking-defi/orders-history

请求示例

GET /api/v5/finance/staking-defi/orders-history

请求参数

参数	类型	是否必须	描述
productId	String	否	项目ID
protocolType	String	否	项目类型 `defi`：链上赚币
ccy	String	否	投资币种，如 `BTC`
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的`ordId`
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的`ordId`
limit	String	否	返回结果的数量，默认100条，最大值为100条

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
       {
            "ordId": "1579252",
            "ccy": "DOT",
            "productId": "101",
            "state": "3",
            "protocol": "Polkadot",
            "protocolType": "defi",
            "term": "0",
            "apy": "0.1704",
            "investData": [
                {
                    "ccy": "DOT",
                    "amt": "2"
                }
            ],
            "earningData": [
                {
                    "ccy": "DOT",
                    "earningType": "0",
                    "realizedEarnings": "0"
                }
            ],
            "purchasedTime": "1712908001000",
            "redeemedTime": "1712914294000",
            "tag": ""
       }
    ]
}

返回参数

参数名	类型	描述
ccy	String	币种名称，如 `BTC`
ordId	String	订单ID
productId	String	项目ID
state	String	订单状态 3: 订单已完成（包含撤销和已赎回两种状态）
protocol	String	项目名称
protocolType	String	项目类型 `defi`：链上赚币
term	String	项目期限活期为0，其他则显示定期天数
apy	String	预估年化如果年化为7% ，则该字段为0.07 保留到小数点后4位（截位）
investData	Array	用户投资信息
> ccy	String	投资币种，如`BTC`
> amt	String	已投资数量
earningData	Array	收益信息
> ccy	String	收益币种，如`BTC`
> earningType	String	收益类型 `0`：预估收益 `1`：实际到账收益
> realizedEarnings	String	已赎回订单累计收益该字段只在订单处于赎回状态时有效
purchasedTime	String	用户订单创建时间，值为时间戳，Unix时间戳为毫秒数格式，如 `1597026383085`
redeemedTime	String	用户订单赎回时间，值为时间戳，Unix时间戳为毫秒数格式，如 `1597026383085`
tag	String	订单标签

ETH质押

ETH 质押，也称为以太坊质押，是参与以太坊区块链权益证明 (Proof of Stake, PoS) 共识机制的过程。
质押 ETH 即获 1:1 BETH 并赚取每日奖励，享受更高流动性
了解更多

GET / 获取产品信息

限速：3 次/s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/finance/staking-defi/eth/product-info

请求示例

GET /api/v5/finance/staking-defi/eth/product-info

返回结果

{
    "code": "0",
    "data": [
      {
        "fastRedemptionDailyLimit": "100"
      }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
fastRedemptionDailyLimit	String	快速赎回每日最高份额母账户和子账户共享同一个限额

POST / 申购

质押ETH获取BETH
仅资金账户中的资产支持ETH质押。

限速：2次/s

限速规则：UserID

权限：交易

HTTP 请求

POST /api/v5/finance/staking-defi/eth/purchase

请求示例

POST /api/v5/finance/staking-defi/eth/purchase
body 
{
    "amt":"100"
}

请求参数

参数	类型	是否必须	描述
amt	String	是	投资数量

返回结果

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

返回参数

code = 0代表请求已被成功处理

POST / 赎回

只能赎回资金账户中的 BETH 资产，交易账户中的 BETH 资产需要您先做资金划转到资金账户后赎回。

限速：2次/s

限速规则：UserID

权限：交易

HTTP 请求

POST /api/v5/finance/staking-defi/eth/redeem

请求示例

POST /api/v5/finance/staking-defi/eth/redeem
body 
{
    "amt":"10"
}

请求参数

参数	类型	是否必须	描述
amt	String	是	赎回数量

返回结果

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

返回参数

code = 0代表请求已被成功处理

GET / 获取余额

该余额是一个汇总账户BETH资产（含赎回中）的快照数据。

限速：6 次/s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/finance/staking-defi/eth/balance

请求示例

GET /api/v5/finance/staking-defi/eth/balance

请求参数

None

返回结果

{
    "code": "0",
    "data": [
      {
        "amt": "0.63926191",
        "ccy": "BETH",
        "latestInterestAccrual": "0.00006549",
        "totalInterestAccrual": "0.01490596",
        "ts": "1699257600000"
      }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	币种名称，如 `BETH`
amt	String	币种数量
latestInterestAccrual	String	最近收益
totalInterestAccrual	String	历史总收益
ts	String	快照时间，值为时间戳，Unix时间戳为毫秒数格式，如 `1597026383085`

GET / 获取申购赎回记录

限速：6 次/s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/finance/staking-defi/eth/purchase-redeem-history

请求示例

GET /api/v5/finance/staking-defi/eth/purchase-redeem-history?type=purchase

请求参数

参数	类型	是否必须	描述
type	String	是	类型 `purchase`：申购 `redeem`：赎回
status	String	否	状态 `pending`：处理中 `success`：成功处理 `failed`：处理失败
after	String	否	请求此`requestTime`之前（更旧的数据）的分页内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
before	String	否	请求此`requestTime`之后（更新的数据）的分页内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
limit	String	否	返回结果的数量，默认100条，最大值为100条

返回结果

{
    "code": "0",
    "data": [
        {
            "amt": "0.62666630",
            "completedTime": "1683413171000",
            "estCompletedTime": "",
            "redeemingAmt": "",
            "requestTime": "1683413171000",
            "status": "success",
            "type": "purchase"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
type	String	类型 `purchase`：申购 `redeem`：赎回
amt	String	申购/赎回的数量
redeemingAmt	String	赎回中的数量
status	String	状态 `pending`：处理中 `success`：成功处理 `failed`：处理失败
requestTime	String	发起申购/赎回请求的时间，值为时间戳，Unix时间戳为毫秒数格式，如 `1597026383085`
completedTime	String	赎回请求处理完成的时间，值为时间戳，Unix时间戳为毫秒数格式，如 `1597026383085`
estCompletedTime	String	预估完成赎回的时间，值为时间戳，Unix时间戳为毫秒数格式，如 `1597026383085`

GET / 获取历史收益率(公共)

公共接口无须鉴权

限速：6次/s

限速规则：IP

权限：读取

HTTP 请求

GET /api/v5/finance/staking-defi/eth/apy-history

请求示例

GET /api/v5/finance/staking-defi/eth/apy-history?days=2

请求参数

参数	类型	是否必须	描述
days	String	是	查询最近多少天内的数据，不超过365天

返回结果

{
    "code": "0",
    "data": [
        {
            "rate": "0.02690000",
            "ts": "1734195600000"
        },
        {
            "rate": "0.02840000",
            "ts": "1734109200000"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
rate	String	年化收益率，如 `0.01`代表`1%`
ts	String	时间，值为时间戳，Unix时间戳为毫秒数格式，如 `1597026383085`

SOL质押

通过质押 SOL 代币并将其委托给 Solana 网络上的验证者，您可以收到等值的 OKSOL 并获得每日 OKSOL 奖励。
在 Solana 上质押 SOL，即获 1:1 OKSOL，享受更高流动性
了解更多

POST / 申购

质押 SOL 获取 OKSOL
仅资金账户中的资产支持 SOL 质押。

限速：2次/s

限速规则：UserID

权限：交易

HTTP 请求

POST /api/v5/finance/staking-defi/sol/purchase

请求示例

POST /api/v5/finance/staking-defi/sol/purchase
body 
{
    "amt":"100"
}

请求参数

参数	类型	是否必须	描述
amt	String	是	投资数量

返回结果

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

返回参数

code = 0代表请求已被成功处理

POST / 赎回

只能赎回资金账户中的 OKSOL 资产，交易账户中的 OKSOL 资产需要您先做资金划转到资金账户后赎回。

限速：2次/s

限速规则：UserID

权限：交易

HTTP 请求

POST /api/v5/finance/staking-defi/sol/redeem

请求示例

POST /api/v5/finance/staking-defi/sol/redeem
body 
{
    "amt":"10"
}

请求参数

参数	类型	是否必须	描述
amt	String	是	赎回数量

返回结果

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

返回参数

code = 0代表请求已被成功处理

GET / 获取余额

该余额是一个汇总账户OKSOL资产（含赎回中）的实时数据。

限速：6 次/s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/finance/staking-defi/sol/balance

请求示例

GET /api/v5/finance/staking-defi/sol/balance

请求参数

None

返回结果

{
    "code": "0",
    "data": [
        {
            "amt": "0.01100012",
            "ccy": "OKSOL",
            "latestInterestAccrual": "0.00000012",
            "totalInterestAccrual": "0.00000012"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	币种名称，如 `OKSOL`
amt	String	币种数量
latestInterestAccrual	String	最近收益
totalInterestAccrual	String	历史总收益

GET / 获取申购赎回记录

限速：6 次/s

限速规则：UserID

权限：读取

HTTP 请求

GET /api/v5/finance/staking-defi/sol/purchase-redeem-history

请求示例

GET /api/v5/finance/staking-defi/sol/purchase-redeem-history?type=purchase

请求参数

参数	类型	是否必须	描述
type	String	是	类型 `purchase`：申购 `redeem`：赎回
status	String	否	状态 `pending`：处理中 `success`：成功处理 `failed`：处理失败
after	String	否	请求此`requestTime`之前（更旧的数据）的分页内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
before	String	否	请求此`requestTime`之后（更新的数据）的分页内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
limit	String	否	返回结果的数量，默认100条，最大值为100条

返回结果

{
    "code": "0",
    "data": [
        {
            "amt": "0.62666630",
            "completedTime": "1683413171000",
            "estCompletedTime": "",
            "redeemingAmt": "",
            "requestTime": "1683413171000",
            "status": "success",
            "type": "purchase"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
type	String	类型 `purchase`：申购 `redeem`：赎回
amt	String	申购/赎回的数量
redeemingAmt	String	赎回中的数量
status	String	状态 `pending`：处理中 `success`：成功处理 `failed`：处理失败
requestTime	String	发起申购/赎回请求的时间，值为时间戳，Unix时间戳为毫秒数格式，如 `1597026383085`
completedTime	String	赎回请求处理完成的时间，值为时间戳，Unix时间戳为毫秒数格式，如 `1597026383085`
estCompletedTime	String	预估完成赎回的时间，值为时间戳，Unix时间戳为毫秒数格式，如 `1597026383085`

GET / 获取历史收益率(公共)

公共接口无须鉴权

限速：6次/s

限速规则：IP

权限：读取

HTTP 请求

GET /api/v5/finance/staking-defi/sol/apy-history

请求示例

GET /api/v5/finance/staking-defi/sol/apy-history?days=2

请求参数

参数	类型	是否必须	描述
days	String	是	查询最近多少天内的数据，不超过365天

返回结果

{
    "code": "0",
    "data": [
        {
            "rate": "0.11280000",
            "ts": "1734192000000"
        },
        {
            "rate": "0.11270000",
            "ts": "1734105600000"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
rate	String	年化收益率，如 `0.01`代表`1%`
ts	String	时间，值为时间戳，Unix时间戳为毫秒数格式，如 `1597026383085`

活期简单赚币

活期简单赚币(余币宝)通过在借贷市场出借给杠杆交易用户获取收益。了解更多

GET / 获取余币宝余额

限速：6次/s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/finance/savings/balance

请求示例

GET /api/v5/finance/savings/balance?ccy=BTC

import okx.Funding as Funding

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

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

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# 获取余币宝余额
result = fundingAPI.get_saving_balance(
    ccy="USDC"
)
print(result)

请求参数

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

返回结果

{
    "code": "0",
    "msg":"",
    "data": [
        {
            "earnings": "0.0010737388791526",
            "redemptAmt": "",
            "rate": "0.0100000000000000",
            "ccy": "USDT",
            "amt": "11.0010737453457821",
            "loanAmt": "11.0010630707982819",
            "pendingAmt": "0.0000106745475002"
        }
    ]
}

返回参数

参数名	类型	描述
ccy	String	币种，如 `BTC`
amt	String	币种数量
earnings	String	币种持仓收益
rate	String	最新出借利率
loanAmt	String	已出借数量
pendingAmt	String	未出借数量
redemptAmt	String	~~赎回中的数量~~（已废弃）

POST / 余币宝申购/赎回

仅资金账户中的资产支持余币宝申购。

限速：6次/s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/finance/savings/purchase-redempt

请求示例

POST /api/v5/finance/savings/purchase-redempt
body
{
    "ccy":"BTC",
    "amt":"1",
    "side":"purchase",
    "rate":"0.01"
}

请求参数

参数名	类型	是否必须	描述
ccy	String	是	币种名称，如 `BTC`
amt	String	是	申购/赎回数量
side	String	是	操作类型 `purchase`：申购 `redempt`：赎回
rate	String	是	申购年利率仅适用于申购，新申购的利率会覆盖上次申购的利率参数取值范围在1%到365%之间

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "ccy":"BTC",
            "amt":"1",
            "side":"purchase",
            "rate":"0.01"
        }
    ]
}

返回参数

参数名	类型	描述
ccy	String	币种名称
amt	String	申购/赎回数量
side	String	操作类型
rate	String	申购年利率

POST / 设置余币宝借贷利率

限速：6次/s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/finance/savings/set-lending-rate

请求示例

POST /api/v5/finance/savings/set-lending-rate
body
{
    "ccy":"BTC",
    "rate":"0.02"
}

请求参数

参数名	类型	是否必须	描述
ccy	String	是	币种名称，如 `BTC`
rate	String	是	贷出年利率参数取值范围在1%到365%之间

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "ccy": "BTC",
        "rate": "0.02"
    }]
}

返回参数

参数名	类型	描述
ccy	String	币种名称，如 `BTC`
rate	String	贷出年利率

GET / 获取余币宝出借明细

返回最近一个月的数据

限速：6次/s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/finance/savings/lending-history

请求示例

GET /api/v5/finance/savings/lending-history

请求参数

参数	类型	是否必须	描述
ccy	String	否	币种，如 `BTC`
after	String	否	查询在此之前的内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
before	String	否	查询在此之后的内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
limit	String	否	分页返回的结果集数量，最大为 100，不填默认返回 100 条

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
            "ccy": "BTC",
            "amt": "0.01",
            "earnings": "0.001",
            "rate": "0.01",
            "ts": "1597026383085"
        },
        {
            "ccy": "ETH",
            "amt": "0.2",
            "earnings": "0.001",
            "rate": "0.01",
            "ts": "1597026383085"
        }
    ]
}

返回参数

参数名	类型	描述
ccy	String	币种，如 `BTC`
amt	String	出借数量
earnings	String	已赚取利息
rate	String	出借年利率
ts	String	出借时间，Unix时间戳的毫秒数格式，如 `1597026383085`

GET / 获取市场借贷信息（公共）

公共接口无须鉴权

限速：6次/s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/finance/savings/lending-rate-summary

请求示例

GET /api/v5/finance/savings/lending-rate-summary

请求参数

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

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "ccy": "BTC",
        "avgAmt": "10000",
        "avgAmtUsd": "10000000000",
        "avgRate": "0.03",
        "preRate": "0.02",
        "estRate": "0.01"
    }]
}

返回参数

参数名	类型	描述
ccy	String	币种，如 `BTC`
avgAmt	String	过去24小时平均借贷量
avgAmtUsd	String	过去24小时平均借贷美元价值
avgRate	String	过去24小时平均借出利率
preRate	String	上一次借贷年利率
estRate	String	下一次预估借贷年利率

GET / 获取市场借贷历史（公共）

公共接口无须鉴权
返回2021年12月14日后的记录

限速：6次/s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/finance/savings/lending-rate-history

请求示例

GET /api/v5/finance/savings/lending-rate-history

请求参数

参数	类型	是否必须	描述
ccy	String	否	币种，如 `BTC`
after	String	否	查询在此之前的内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
before	String	否	查询在此之后的内容，值为时间戳，Unix 时间戳为毫秒数格式，如 `1597026383085`
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条如果不指定`ccy`,会返回同一个`ts`下的全部数据，不受`limit`限制

返回结果

{
    "code": "0",
    "msg": "",
    "data": [{
        "ccy": "BTC",
        "amt": "0.01",
        "rate": "0.001",
        "ts": "1597026383085"
    }]
}

返回参数

参数名	类型	描述
ccy	String	币种，如 `BTC`
amt	String	市场总出借数量
rate	String	出借年利率
ts	String	时间，Unix时间戳的毫秒数格式，如 `1597026383085`

定期简单赚币

GET / 获取借币信息（公共）

获取借币信息和年化收益率

限速：3次/s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/finance/fixed-loan/lending-offers

请求示例

GET /api/v5/finance/fixed-loan/lending-offers

请求参数

参数名	类型	是否必须	描述
ccy	String	否	币种，如 `BTC`
term	String	否	借贷期限 `30D`：30天

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "BTC",
            "lendQuota": "0.5",
            "minLend": "0.02",
            "rate": "0.0058",
            "term": "30D"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	币种
term	String	借贷期限 `30D`：30天
rate	String	最新年化收益率，小数形式如 `0.01`代表`1%`
minLend	String	最小出借数量
lendQuota	String	出借限额

GET / 获取历史收益率（公共）

获取借币信息和年化收益率

限速：3次/s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/finance/fixed-loan/lending-apy-history

请求示例

GET /api/v5/finance/fixed-loan/lending-apy-history?ccy=USDT&term=30D

请求参数

参数名	类型	是否必须	描述
ccy	String	是	币种，如 `BTC`
term	String	是	借贷期限 `30D`：30天

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "rate": "0.0100",
            "ts": "1712559600000"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	币种
rate	String	年化收益率，小数形式如 `0.01`代表`1%`
ts	String	时间戳。Unix时间戳为毫秒数格式，如 `1597026383085`

GET / 获取借贷量（公共）

限速：3次/s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/finance/fixed-loan/pending-lending-volume

请求示例

GET /api/v5/finance/fixed-loan/pending-lending-volume?ccy=BTC&term=30D

请求参数

参数名	类型	是否必须	描述
ccy	String	是	币种，如 `BTC`
term	String	是	借贷期限 `30D`：30天

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "pendingVol": "1000",
            "rateRangeFrom": "0.001",
            "rateRangeTo": "0.031",
            "term": "30D"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	币种
term	String	借贷期限 `30D`：30天
rateRangeFrom	String	出借利率的最低值，小数形式如 `0.01`代表`1%`
rateRangeTo	String	出借利率的最高值，小数形式如 `0.01`代表`1%`
pendingVol	String	挂单数量

POST / 定期简单赚币申购

限速：2次/s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/finance/fixed-loan/lending-order

请求示例

POST /api/v5/finance/fixed-loan/lending-order
body
{
    "ccy": "USDT",
    "amt": "1",
    "rate": "0.01",
    "term": "30D",
    "autoRenewal": true
}

请求参数

参数	类型	是否必须	描述
ccy	String	是	出借币种，如 `BTC`
amt	String	是	出借数量
rate	String	是	出借利率，小数形式，如 `0.01` 代表 `1%`。
term	String	是	借贷期限
autoRenewal	Boolean	否	是否到期自动续借 `true`：自动续借 `false`：非自动续借默认为`false`

返回结果

{
    "code": "0",
    "data": [
        {
            "ordId":"2405162053378222"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ordId	String	订单ID

POST / 定期简单赚币修改订单

限速：2次/s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/finance/fixed-loan/amend-lending-order

请求示例

POST /api/v5/finance/fixed-loan/amend-lending-order
body
{
    "ordId":"2405162053378222",
    "changeAmt":"-100"
}

请求参数

参数	类型	是否必须	描述
ordId	String	是	订单ID
changeAmt	String	否	赎回数量，如 `-0.1`代表赎回`0.1`。
rate	String	否	出借利率，小数形式，如 `0.01` 代表 `1%`。
autoRenewal	Boolean	否	是否到期自动续借 `true`：自动续借 `false`：非自动续借

返回结果

{
    "code": "0",
    "data": [
        {
            "ordId":"2405162053378222"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ordId	String	订单ID

GET / 获取定期简单赚币订单信息

限速：3次/s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/finance/fixed-loan/lending-orders-list

请求示例

GET /api/v5/finance/fixed-loan/lending-orders-list

请求参数

参数	类型	是否必须	描述
ordId	String	否	订单ID
ccy	String	否	币种，如 `BTC`
state	String	否	状态 `pending`：匹配中 `earning`：赚币中 `expired`：逾期 `settled`：已结算
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的`ordId`
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的`ordId`
limit	String	否	返回结果的数量，最大为`100`，默认`100`条

返回结果

{
    "code": "0",
    "data": [
        {
            "amt": "10",
            "autoRenewal": true,
            "cTime": "1718955882000",
            "ccy": "USDT",
            "earningAmt": "0",
            "ordId": "2406211544415051",
            "pendingAmt": "10",
            "rate": "0.01",
            "settledTime": "",
            "startTime": "",
            "state": "pending",
            "term": "30D",
            "totalInterest": "0",
            "uTime": "1718955881000"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ordId	String	订单ID
state	String	状态
ccy	String	币种，如 `BTC`
amt	String	出借数量
rate	String	出借年化利率，小数形式，如 `0.01`代表`1%`
term	String	借贷期限 `30D`: 30天
autoRenewal	Boolean	是否自动续借 `true`：自动续借 `false`：非自动续借
totalInterest	String	总利息
pendingAmt	String	待匹配数量
earningAmt	String	赚币数量
startTime	String	开始赚币时间，Unix时间戳的毫秒数格式，如 `1597026383085`
settledTime	String	结算时间，Unix时间戳的毫秒数格式，如 `1597026383085`
cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`

GET / 获取定期简单赚币子订单信息

限速：2次/s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/finance/fixed-loan/lending-sub-orders

请求示例

GET /api/v5/finance/fixed-loan/lending-sub-orders?ordId=2405231639344615

请求参数

参数	类型	是否必须	描述
ordId	String	是	订单ID
state	String	否	状态 `earning`：赚币中 `expired`：逾期 `settled`：已结算
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的`subOrdId`
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的`subOrdId`
limit	String	否	返回结果的数量，最大为`100`，默认`100`条

返回结果

{
    "code": "0",
    "data": [
        {
            "accruedInterest": "",
            "amt": "100",
            "cTime": "1716453989000",
            "ccy": "USDT",
            "earlyTerminatedPenalty": "0.0209",
            "expiryTime": "1719045989000",
            "finalSettlementTime": "1721637989000",
            "ordId": "2405231639344615",
            "overdueInterest": "0",
            "rate": "0.01",
            "settledTime": "1716454032000",
            "state": "settled",
            "subOrdId": "2405231646292913",
            "term": "30D",
            "totalInterest": "0",
            "uTime": "1716454032000"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ordId	String	订单ID
subOrdId	String	子订单ID
state	String	子订单状态
ccy	String	子订单币种，如 `BTC`
amt	String	子订单出借数量
rate	String	子订单出借年化利率，小数形式，如 `0.01`代表`1%`
term	String	子订单借贷期限，如 `30D`
expiryTime	String	子订单到期时间，Unix时间戳的毫秒数格式，如 `1597026383085`
totalInterest	String	子订单总收益
accruedInterest	String	子订单应计利息
earlyTerminatedPenalty	String	子订单提前还币罚息
overdueInterest	String	子订单逾期罚息
finalSettlementTime	String	子订单强制偿还时间，Unix时间戳的毫秒数格式，如 `1597026383085`
settledTime	String	子订单实际结算时间，Unix时间戳的毫秒数格式，如 `1597026383085`
cTime	String	子订单创建时间，Unix时间戳的毫秒数格式，如 `1597026383085`
uTime	String	子订单更新时间，Unix时间戳的毫秒数格式，如 `1597026383085`

活期借币

欧易活期借币是一款高端借贷产品，用户无需变卖数字货币即可增加现金流。了解更多

GET / 可借币种列表

获取可借币种列表

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/finance/flexible-loan/borrow-currencies

请求示例

GET /api/v5/finance/flexible-loan/borrow-currencies

返回结果

{
    "code": "0",
    "data": [
        {
            "borrowCcy": "USDT"
        },
        {
            "borrowCcy": "USDC"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
borrowCcy	String	可借币种，如 `BTC`

GET / 可抵押资产

获取可抵押资产信息（仅支持资金账户中的资产）

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/finance/flexible-loan/collateral-assets

请求示例

GET /api/v5/finance/flexible-loan/collateral-assets

请求参数

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

返回结果

{
    "code": "0",
    "data": [
        {
            "assets": [
                {
                    "amt": "1.7921483143067599",
                    "ccy": "BTC",
                    "notionalUsd": "158292.621793314105231"
                },
                {
                    "amt": "1.9400755578876945",
                    "ccy": "ETH",
                    "notionalUsd": "6325.6652712507628946"
                },
                {
                    "amt": "63.9795959720319628",
                    "ccy": "USDT",
                    "notionalUsd": "64.3650372635940345"
                }
            ]
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
assets	Array of object	可抵押资产信息
> ccy	String	币种，如 `BTC`
> amt	String	可用数量
> notionalUsd	String	可抵押资产的美金价值

POST / 最大可借

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

POST /api/v5/finance/flexible-loan/max-loan

请求示例

POST /api/v5/finance/flexible-loan/max-loan
body
{
    "borrowCcy": "USDT"
}

请求参数

参数	类型	是否必须	描述
borrowCcy	String	是	借币币种，如 `USDT`
supCollateral	Array of object	否	补充抵押资产信息
> ccy	String	是	币种，如 `BTC`
> amt	String	是	数量

返回结果

{
    "code": "0",
    "data": [
        {
            "borrowCcy": "USDT",
            "maxLoan": "0.01113",
            "notionalUsd": "0.01113356",
            "remainingQuota": "3395000"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
borrowCcy	String	借币币种，如 `USDT`
maxLoan	String	最大可借数量
notionalUsd	String	最大可借美元价值
remainingQuota	String	剩余可借额度，单位为`borrowCcy`

GET / 抵押物最大可赎回数量

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/finance/flexible-loan/max-collateral-redeem-amount

请求示例

GET /api/v5/finance/flexible-loan/max-collateral-redeem-amount?ccy=USDT

请求参数

参数	类型	是否必须	描述
ccy	String	是	抵押物币种，如 `USDT`

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "maxRedeemAmt": "1"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	抵押物币种，如 `USDT`
maxRedeemAmt	String	抵押物最大可赎回数量

POST / 调整抵押物

限速：5次/2s

限速规则：UserID

权限：交易

HTTP请求

POST /api/v5/finance/flexible-loan/adjust-collateral

请求示例

POST /api/v5/finance/flexible-loan/adjust-collateral
body
{
    "type":"add",
    "collateralCcy": "BTC",
    "collateralAmt": "0.1"
}

请求参数

参数	类型	是否必须	描述
type	String	是	操作类型 `add`：补充抵押物 `reduce`：减少抵押物
collateralCcy	String	是	抵押物币种，如 `BTC`
collateralAmt	String	是	抵押物数量

返回结果

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

返回参数

code = 0 代表请求已被接受(不代表处理成功)

GET / 借贷信息

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/finance/flexible-loan/loan-info

请求示例

GET /api/v5/finance/flexible-loan/loan-info

返回结果

{
    "code": "0",
    "data": [
        {
            "collateralData": [
                {
                    "amt": "0.0000097",
                    "ccy": "COMP"
                },
                {
                    "amt": "0.78",
                    "ccy": "STX"
                },
                {
                    "amt": "0.001",
                    "ccy": "DOT"
                },
                {
                    "amt": "0.05357864",
                    "ccy": "LUNA"
                }
            ],
            "collateralNotionalUsd": "1.5078763",
            "curLTV": "0.5742",
            "liqLTV": "0.8374",
            "loanData": [
                {
                    "amt": "0.86590608",
                    "ccy": "USDC"
                }
            ],
            "loanNotionalUsd": "0.8661285",
            "marginCallLTV": "0.7374",
            "riskWarningData": {
                "instId": "",
                "liqPx": ""
            }
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
loanNotionalUsd	String	借币资产美金价值
loanData	Array of object	借币数据
> ccy	String	借贷币种
> amt	String	借贷数量
collateralNotionalUsd	String	抵押物美金价值
collateralData	Array of object	抵押资产数据
> ccy	String	抵押币种
> amt	String	抵押数量
riskWarningData	Object	风险预警信息
> instId	String	清算交易产品，如 `BTC-USDT` 仅当质押物和借币都只有一种时，该字段有效。其他情况返回""。
> liqPx	String	清算价格清算价格的单位为交易产品的计价币，如 `BTC-USDT`中的`USDT`。仅当质押物和借币都只有一种时，该字段有效。其他情况返回""。
curLTV	String	当前质押率，如 `0.1`代表`10%` 注：LTV(Loan-to-Value，贷款价值比)
marginCallLTV	String	预警质押率，如 `0.1`代表`10%` 您的质押率达到预警质押率时，系统将会提示您当前质押率过高，即将触发强平。
liqLTV	String	强平质押率，如 `0.1`代表`10%` 若您的借贷达到强平质押率并被强平，您将损失质押物及已完成的还款。

GET / 借贷历史

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/finance/flexible-loan/loan-history

请求示例

GET /api/v5/finance/flexible-loan/loan-history

请求参数

参数	类型	是否必须	描述
type	String	否	操作类型 `borrowed`：借入 `repaid`：还币 `collateral_locked`：锁定质押物 `collateral_released`：释放质押物 `forced_repayment_buy`：自动换币买入 `forced_repayment_sell`：自动换币卖出 `forced_liquidation`：强制平仓 `partial_liquidation`：强制减仓
after	String	否	请求此 ID 之前（更旧的数据）的分页内容，传的值为对应接口的`refId`（不包含）
before	String	否	请求此 ID 之后（更新的数据）的分页内容，传的值为对应接口的`refId`（不包含）
limit	String	否	返回结果的数量，最大为`100`，默认`100`条

返回结果

{
    "code": "0",
    "data": [
        {
            "amt": "-0.001",
            "ccy": "DOT",
            "refId": "17316594851045086",
            "ts": "1731659485000",
            "type": "collateral_locked"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
refId	String	对应记录ID
type	String	操作类型
ccy	String	币种，如 `BTC`
amt	String	数量
ts	String	操作发生时间，Unix 时间戳为毫秒数格式，如 `1597026383085`

GET / 计息记录

限速：5次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/finance/flexible-loan/interest-accrued

请求示例

GET /api/v5/finance/flexible-loan/interest-accrued

请求参数

参数	类型	是否必须	描述
ccy	String	否	借贷币种，如 `BTC`
after	String	否	请求此 ID 之前（更旧的数据）的分页内容，传的值为对应接口的`refId`（不包含）
before	String	否	请求此 ID 之后（更新的数据）的分页内容，传的值为对应接口的`refId`（不包含）
limit	String	否	返回结果的数量，最大为`100`，默认`100`条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDC",
            "interest": "0.00004054",
            "interestRate": "0.41",
            "loan": "0.86599309",
            "refId": "17319133035195744",
            "ts": "1731913200000"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
refId	String	对应记录ID
ccy	String	币种，如 `BTC`
loan	String	计息时负债
interest	String	利息
interestRate	String	小时利率，如 `0.01`代表`1%`
ts	String	计息时间，Unix 时间戳为毫秒数格式，如 `1597026383085`

节点

节点API为节点用户提供灵活的直客查询功能，输入您直客的UID即可获得其相关信息，赋能您的节点业务增长和直客日常管理。如需更多节点相关功能，或数据支持，请联系您的商务，我们会通过您的商务与您取得联系，提供更加完善的API支持。

REST API

获取被邀请人返佣信息

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/affiliate/invitee/detail

请求示例

GET /api/v5/affiliate/invitee/detail?uid=11111111

请求参数

参数名	类型	是否必须	描述
uid	String	是	被邀请人UID，仅支持使用被邀请人母账号的 UID 返回数据中涵盖了被邀请人母账户和子账户。

返回结果

{
    "msg": "",
    "code": "0",
    "data": [
        {
            "accFee": "0",
            "affiliateCode": "HIIIIII",
            "depAmt": "0",
            "firstTradeTime": "",
            "inviteeLevel": "2",
            "inviteeRebateRate": "0.39",
            "joinTime": "1712546713000",
            "kycTime": "",
            "level": "Lv1",
            "region": "越南",
            "totalCommission": "0",
            "volMonth": "0"
        }
    ]
}

返回参数

参数名	类型	描述
inviteeLv	String	被邀请人的节点层级直客返回`2`
joinTime	String	返佣关系建立的时间，Unix时间戳的毫秒数格式，如 `1597026383085`
inviteeRebateRate	String	返佣比例(小数形式)，如 `0.01`代表`1%`
totalCommission	String	总返佣数量，单位为`USDT`
firstTradeTime	String	首次交易时间（在最近的返佣关系建立之后） Unix时间戳的毫秒数格式，如 1597026383085 如果用户没有交易, 返回 ""
level	String	当前在平台上真实交易量的用户等级，例如 Lv1
depAmt	String	累计充值金额，单位为 USDT 如果没有充值, 返回 0
volMonth	String	当月累计交易量，单位为 USDT 如果没有交易, 返回 0
accFee	String	累计交易手续费，单位为 USDT 如果没有交易手续费，返回 0
kycTime	String	KYC2 认证时间. Unix时间戳的毫秒数格式，且精确到天如果没有通过 KYC2, 返回 ""
region	String	国家或地区，如"英国"
affiliateCode	String	节点邀请码

获取用户的节点返佣信息

该接口即将下线，建议使用获取被邀请人返佣信息

该接口用于节点查询用户的返佣信息

限速：20次/2s

限速规则：UserID

权限：读取

HTTP请求

GET /api/v5/users/partner/if-rebate

请求示例

GET /api/v5/users/partner/if-rebate?apiKey=86b02e93-67ab-497d-9970-8cce00a028c3

请求参数

参数名	类型	是否必须	描述
apiKey	String	是	用户的 API key，仅支持使用被邀请人母账号的 API key

返回结果

{
    "code": "0",
    "msg": "",
    "data": {
        "result": true,
        "type": "0"
    }
}

返回参数

参数名	类型	描述
result	Boolean	用户是否与当前节点有邀请关系。 `true`, `false`
type	String	是否有节点返佣 `0` 有节点返佣 `1` 没有节点返佣，因为调用该接口的账户不是节点身份 `2` 没有节点返佣，因为不存在邀请/召回关系，如：api key不存在 `4` 没有节点返佣，因为用户的手续费等级大于等于VIP6

Status

GET / Status

获取系统升级事件的状态。

由计划系统维护引起的短暂不可用（<5秒）和WebSocket闪断连接（用户可以立即重连）将不会公布。此类维护只会在市场波动性低的时期进行。

限速：1次/5s

权限：读取

HTTP请求

GET /api/v5/system/status

请求示例

GET /api/v5/system/status

GET /api/v5/system/status?state=canceled

import okx.Status as Status

flag = "0"  # 实盘:0 , 模拟盘：1
statusAPI = Status.StatusAPI(
    domain="https://www.okx.com",
    flag=flag,
)

# 获取系统升级事件的状态
result = statusAPI.status()
print(result)

请求参数

请求示例

参数名	类型	是否必须	描述
state	String	否	系统的状态 `scheduled`：等待中 `ongoing`：进行中 `pre_open`：预开放 `completed`：已完成 `canceled`：已取消当维护时间过长，会存在预开放时间，一般持续10分钟左右。不填写此参数，默认返回等待中、进行中和预开放的数据

返回结果

{
    "code": "0",
    "data": [
        {
            "begin": "1672823400000",
            "end": "1672823520000",
            "href": "",
            "preOpenBegin": "",
            "scheDesc": "",
            "serviceType": "8",
            "state": "completed",
            "maintType": "1",
            "env": "1",
            "system": "unified",
            "title": "Trading account system upgrade (in batches of accounts)"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
title	String	系统维护说明的标题
state	String	系统维护的状态
begin	String	系统维护的开始时间，Unix时间戳的毫秒数格式如：`1617788463867`
end	String	交易全面开放的时间，Unix时间戳的毫秒数格式如：`1617788463867` 在维护完成前，是预期结束时间；维护完成后，会变更为实际结束时间。
preOpenBegin	String	预开放开始的时间，开放撤单、Post Only 下单和资金转入功能的时间
href	String	系统维护详情的超级链接,若无返回值，默认值为空，如 ""
serviceType	String	服务类型 `0`：WebSocket `5`：交易服务 `6`：大宗交易 `7`：策略交易 `8`：交易服务 (按账户分批次) `9`：交易服务 (按产品分批次) `10`：价差交易 `11`：跟单交易 `99`：其他（如：停止部分产品交易）
system	String	系统 `unified`：交易账户
scheDesc	String	改期进度说明，如 `由 2021-01-26T16:30:00.000Z`改期到`2021-01-28T16:30:00.000Z`
maintType	String	维护类型 `1`：计划维护 `2`：临时维护 `3`：系统故障
env	String	环境 `1`：实盘 `2`：模拟盘

WS / Status 频道

获取系统维护的状态，当系统维护状态改变，改期，以及修改结束时间时推送。首次订阅：”推送最新一条的变化数据“；后续每次有状态变化，推送变化的内容。

由计划系统维护引起的短暂不可用（<5秒）和WebSocket闪断连接（用户可以立即重连）将不会公布。此类维护只会在市场波动性低的时期进行。

URL Path

/ws/v5/public

请求示例

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

请求参数

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

成功返回示例

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

失败返回示例

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

返回参数

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

推送示例

{
    "arg": {
        "channel": "status"
    },
    "data": [
        {
            "begin": "1672823400000",
            "end": "1672825980000",
            "href": "",
            "preOpenBegin": "",
            "scheDesc": "",
            "serviceType": "0",
            "state": "completed",
            "system": "unified",
            "maintType": "1",
            "env": "1",
            "title": "Trading account WebSocket system upgrade",
            "ts": "1672826038470"
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
data	Array	订阅的数据
> title	String	系统维护说明的标题
> state	String	系统的状态，`scheduled`:等待中 ; `ongoing`:进行中 ; `pre_open`:预开放；`completed`:已完成 `canceled`: 已取消当维护时间过长，会存在预开放时间，一般持续10分钟左右。
> begin	String	系统维护的开始时间，Unix时间戳的毫秒数格式如：`1617788463867`
> end	String	交易全面开放的时间，Unix时间戳的毫秒数格式如：`1617788463867` 在维护完成前，是预期结束时间；维护完成后，会变更为实际结束时间。
> preOpenBegin	String	预开放开始的时间，开放撤单、Post Only 下单和资金转入功能的时间
> href	String	系统维护详情的超级链接,若无返回值，默认值为空，如：“”
> serviceType	String	服务类型， `0`：WebSocket ; `5`：交易服务；`6`：大宗交易；`7`：策略交易；`8`：交易服务 (按账户分批次)；`9`：交易服务 (按产品分批次)；`10`：价差交易；`11`：跟单交易；`99`：其他（如：停止部分产品交易）
> system	String	系统，`unified`：交易账户
> scheDesc	String	改期进度说明，如： `由 2021-01-26T16:30:00.000Z 改期到 2021-01-28T16:30:00.000Z`
> maintType	String	维护类型。 `1`：计划维护；`2`：临时维护；`3`：系统故障
> env	String	环境。 `1`：实盘，`2`：模拟盘
> ts	String	事件变更的推送时间，Unix时间戳的毫秒数格式，如：`1617788463867`

公告

GET / 公告

获取公告信息，以发布时间倒序排序，公告更新不会影响排序。每页默认有 20 条公告

请求头中 Accept-Language 设置为 en-US 时返回英文公告；设置为 zh-CN 时返回中文公告

该接口鉴权是可选的：

当 HTTP 请求头中有 OK-ACCESS-KEY 时，该接口会被视为私有接口且鉴权是必须的
当 HTTP 请求头中没有 OK-ACCESS-KEY 时，该接口会被视为公共接口，不需要鉴权

当为公共接口时，响应根据请求 IP 进行限制
当为私有接口时，响应会根据居住国家进行限制

限速：5次/2s

限速规则：UserID(私有接口时) 或者 IP (公共接口时)

权限：读取

HTTP请求

GET /api/v5/support/announcements

请求示例

GET /api/v5/support/announcements

请求参数

请求示例

参数名	类型	是否必须	描述
annType	String	否	公告类型。仅支持传从"GET / 公告类型" 接口返回的公告类型不传时返回所有类型
page	String	否	查询页数. 默认为`1`

返回结果

{
    "code": "0",
    "data": [
        {
            "details": [
                {
                    "annType": "announcements-latest-announcements",
                    "pTime": "1726128000000",
                    "title": "OKX to delist KISHU margin trading pairs",
                    "url": "https://www.okx.com/help/okx-to-delist-kishu-margin-trading-pairs"
                },
                {
                    "annType": "announcements-latest-announcements",
                    "pTime": "1725967800000",
                    "title": "OKX completed MATIC token migration",
                    "url": "https://www.okx.com/help/okx-completed-matic-token-migration"
                }
            ],
            "totalPage": "90"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
totalPage	String	总的页数
details	String	公告列表
> title	String	公告标题
> annType	String	公告类型
> pTime	String	公告发布时间，Unix时间戳的毫秒数格式，如 `1597026383085`
> url	String	公告链接

GET / 公告类型

公共接口不需要鉴权

获取公告类型

限速：1次/2s

限速规则：IP

权限：读取

HTTP请求

GET /api/v5/support/announcement-types

请求示例

GET /api/v5/support/announcement-types

请求参数

请求示例

无

返回结果

{
    "code": "0",
    "data": [
        {
            "annType": "announcements-latest-announcements",
            "annTypeDesc": "Latest announcements"
        },
        {
            "annType": "announcements-latest-events",
            "annTypeDesc": "Latest events"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
annType	String	公告类型
annTypeDesc	String	公告类型描述

错误码

REST API

REST API 错误码从 50000 到 59999

公共

错误码从 50000 到 53999

通用类

错误码	HTTP 状态码	错误提示
0	200
1	200	操作全部失败
2	200	批量操作部分成功
50000	400	POST请求的body不能为空
50001	503	服务暂时不可用，请稍后重试
50002	400	JSON 语法错误
50004	400	接口请求超时（不代表请求成功或者失败，请检查请求结果）
50005	410	接口已下线或无法使用
50006	400	无效的 Content-Type，请使用“application/JSON”格式
50007	200	用户被冻结
50008	200	用户不存在
50009	200	用户处于爆仓冻结
50010	200	用户ID为空
50011	200	用户请求频率过快，超过该接口允许的限额。请参考 API 文档并限制请求
50011	429	请求频率太高
50012	200	账户状态无效，请检查帐户的状态
50013	429	当前系统繁忙，请稍后重试
50014	400	必填参数{param0}不能为空
50015	400	参数{param0}和{param1}不能同时为空
50016	400	参数{param0}和{param1}不匹配
50017	200	当前仓位处于自动减仓 (ADL) 冻结中，无法进行相关操作，请稍后重试
50018	200	{param0} 处于自动减仓 (ADL) 冻结中，无法进行相关操作，请稍后重试
50019	200	当前账户处于自动减仓 (ADL) 冻结中，无法进行相关操作，请稍后重试
50020	200	当前仓位处于强平冻结中，无法进行相关操作，请稍后重试
50021	200	{param0} 处于强平冻结中，无法进行相关操作，请稍后重试
50022	200	当前账户处于强平冻结中，无法进行相关操作，请稍后重试
50023	200	资金费冻结，无法进行相关操作，请稍后重试
50024	200	参数{param0}和{param1}不能同时存在
50025	200	参数{param0}传值个数超过最大限制{param1}
50026	500	系统错误，请稍后重试
50027	200	当前账户已被限制交易，请联系客服处理
50028	200	账户异常无法下单
50029	200	你的账户已经触发风控体系，禁止交易该标的，请检查您在欧易注册的电子邮件以便我们的客服联系
50030	200	您没有使用此 API 接口的权限
50032	200	您的账户已设置禁止该币种交易，请确认后重试
50033	200	您的账户已设置禁止该业务线交易，请确认后重试
50035	403	该接口要求APIKey必须绑定IP
50036	200	expTime 不能早于当前系统时间，请调整 expTime 后重试
50037	200	订单已过期
50038	200	模拟交易不支持该功能
50039	200	时间戳分页时，不支持使用before参数
50040	200	操作频繁，请稍后重试
50041	200	用户 ID 未被列入白名单列表，请联系客服
50044	200	必须指定一种broker类型
50047	200	{param0} 已经交割，对应的K线请使用{param1}查询
50048	200	切换对冲单元可能导致仓位风险水平升高，引起强制平仓。请调整仓位，使保证金处于安全状态。
50049	200	无仓位档位信息，该币种不支持杠杆交易
50050	200	您已开通期权交易服务，请勿重复开通
50051	200	由于您所在国家或地区的合规限制，您无法使用该功能
50052	200	根据当地的法律法规，您无法交易您选择的币种
50053	200	该功能只支持模拟盘
50055	200	资产重置失败，超过每日设置5次资产上限
50056	200	当前账户有交易挂单或持仓，请完成全部撤单/平仓后进行重置
50057	200	资产重置失败，请稍后重试
50058	200	该币种不支持资产重置
50059	200	继续下一步之前，请按照当地监管机构的要求完成额外步骤。您可以前往欧易网页端或 App 端了解详情。
50060	200	根据当地法律法规，您需要完成身份认证方可继续使用我们的服务。
50061	200	订单请求频率过快，超过账户允许的最高限额
50062	200	该功能暂不可用
50063	200	激活失败，您的体验金可能已过期或已激活
50064	200	借币系统暂不可用，请稍后再试
50067	200	当前接口不支持跨站交易功能

API 类

错误码	HTTP 状态码	错误提示
50100	400	Api 已被冻结，请联系客服处理
50101	401	APIKey 与当前环境不匹配
50102	401	请求时间戳过期
50103	401	请求头"OK-ACCESS-KEY"不能为空
50104	401	请求头"OK-ACCESS-PASSPHRASE"不能为空
50105	401	请求头"OK-ACCESS-PASSPHRASE"错误
50106	401	请求头"OK-ACCESS-SIGN"不能为空
50107	401	请求头"OK-ACCESS-TIMESTAMP"不能为空
50108	401	券商ID不存在
50109	401	券商域名不存在
50110	401	您的IP{param0}不在APIKey绑定IP名单中 (您可以将您的IP加入到APIKey绑定白名单中)
50111	401	无效的OK-ACCESS-KEY
50112	401	无效的OK-ACCESS-TIMESTAMP
50113	401	无效的签名
50114	401	无效的授权
50115	405	无效的请求类型
50116	200	Fast API 只能创建一个 API key
50118	200	如需将 API key 绑定 App，经纪商需要提供 IP 才能加入白名单
50119	200	API key 不存在
50120	200	API key 权限不足
50121	200	您无权通过该 IP 地址 ({param0}) 访问
50122	200	下单金额必须超过最低金额限制

交易类

错误码	HTTP 状态码	错误提示
51000	400	{param0}参数错误
51001	200	交易产品ID不存在
51002	200	交易产品ID不匹配指数
51003	200	ordId或clOrdId至少填一个
51004	200	下单失败，您在{instId} 逐仓的开平仓模式下，当前下单张数、同方向持有仓位以及同方向挂单张数之和，不能超过当前杠杆倍数允许的持仓上限{tierLimitQuantity}(张)，请调低杠杆或者使用新的子账户重新下单(当前杠杆：{leverage}×，当前下单张数：{size}张，同方向持有仓位：{posNumber}张，同方向挂单张数：{pendingNumber}张)。
51004	200	下单失败，您在{instId}全仓的开平仓模式下，当前下单张数、多空持有仓位以及多空挂单张数之和，不能超过当前杠杆倍数允许的持仓上限{tierLimitQuantity}(张)，请调低杠杆或者使用新的子账户重新下单(当前杠杆：{leverage}×，当前下单张数：{size}张，多空持有仓位{posLongShortNumber}张，多空挂单张数：{pendingLongShortNumber}张)。
51004	200	下单失败，您在{businessType}和交易品种{instFamily}的全仓开平仓模式下，当前下单张数、当前合约多空持有仓位、当前合约多空挂单张数以及其他合约占用额度之和，不能超过当前杠杆倍数允许的持仓上限{tierLimitQuantity}(张)，请调低杠杆或者使用新的子账户重新下单(当前杠杆：{leverage}×，当前下单张数：{size}张，当前合约多空持有仓位：{posLongShortNumber}张，当前合约多空挂单张数：{pendingLongShortNumber}张，其他合约占用额度：{otherQuote}张)。
51004	200	下单失败，您在{instId}的买卖模式下，当前买入张数、持有仓位、以及买入挂单张数之和，不能超过当前杠杆倍数允许的持仓上限{tierLimitQuantity}(张)，请调低杠杆或者使用新的子账户重新下单(当前杠杆：{leverage}×，当前买入张数：{size}张，持有仓位：{posNumber}张，买入挂单张数：{pendingNumber}张)。
51004	200	下单失败，您在{instId}的买卖模式下，当前卖出张数、持有仓位以及卖出挂单张数之和，不能超过当前杠杆倍数允许的持仓上限{tierLimitQuantity}(张)，请调低杠杆或者使用新的子账户重新下单(当前杠杆：{leverage}×，当前卖出张数：{size}张，持有仓位：{posNumber}张，卖出挂单张数：{pendingNumber}张)。
51004	200	下单失败，您在{businessType}和交易品种{instFamily}的全仓买卖模式下，当前买入张数、当前合约持有仓位、当前合约买入挂单张数以及其他合约占用额度之和，不能超过当前杠杆倍数允许的持仓上限{tierLimitQuantity}(张)，请调低杠杆或者使用新的子账户重新下单(当前杠杆：{leverage}×，当前买入张数：{size}张，当前合约持有仓位：{posNumber}张，当前合约买入挂单张数：{pendingNumber}张，其他合约占用额度：{otherQuota}张)。
51004	200	下单失败，您在{businessType}和交易品种{instFamily}的全仓买卖模式下，当前卖出张数、当前合约持有仓位、当前合约卖出挂单张数以及其他合约占用额度之和，不能超过当前杠杆倍数允许的持仓上限{tierLimitQuantity}(张)，请调低杠杆或者使用新的子账户重新下单(当前杠杆：{leverage}×，当前卖出张数：{size}张，当前合约持有仓位：{posNumber}张，当前合约卖出挂单张数：{pendingNumber}张，其他合约占用额度：{otherQuota}张)。
51004	200	修改订单失败，您在{instId} 逐仓的开平仓模式下，当前改单新增张数、同方向持有仓位以及同方向挂单张数之和，不能超过当前杠杆倍数允许的持仓上限{tierLimitQuantity}(张)，请调低杠杆或者使用新的子账户重新下单(当前杠杆：{leverage}×，当前改单新增张数：{size}张，同方向持有仓位：{posNumber}张，同方向挂单张数：{pendingNumber}张)。
51004	200	修改订单失败，您在{instId}全仓的开平仓模式下，当前改单新增张数、多空持有仓位以及多空挂单张数之和，不能超过当前杠杆倍数允许的持仓上限{tierLimitQuantity}(张)，请调低杠杆或者使用新的子账户重新下单(当前杠杆：{leverage}×，当前改单新增张数：{size}张，多空持有仓位{posLongShortNumber}张，多空挂单张数：{pendingLongShortNumber}张)。
51004	200	修改订单失败，您在{businessType}和交易品种{instFamily}的全仓开平仓模式下，当前改单新增张数、当前合约多空持有仓位、当前合约多空挂单张数以及其他合约占用额度之和，不能超过当前杠杆倍数允许的持仓上限{tierLimitQuantity}(张)，请调低杠杆或者使用新的子账户重新下单(当前杠杆：{leverage}×，当前改单新增张数：{size}张，当前合约多空持有仓位：{posLongShortNumber}张，当前合约多空挂单张数：{pendingLongShortNumber}张，其他合约占用额度：{otherQuote}张)。
51004	200	修改订单失败，您在{instId}的买卖模式下，修改当前买单新增张数、持有仓位、以及买入挂单张数之和，不能超过当前杠杆倍数允许的持仓上限{tierLimitQuantity}(张)，请调低杠杆或者使用新的子账户重新下单(当前杠杆：{leverage}×，修改当前买单新增张数：{size}张，持有仓位：{posNumber}张，买入挂单张数：{pendingNumber}张)。
51004	200	修改订单失败，您在{instId}的买卖模式下，修改当前卖单新增张数、持有仓位以及卖出挂单张数之和，不能超过当前杠杆倍数允许的持仓上限{tierLimitQuantity}(张)，请调低杠杆或者使用新的子账户重新下单(当前杠杆：{leverage}×，修改当前卖单新增张数：{size}张，持有仓位：{posNumber}张，卖出挂单张数：{pendingNumber}张)。
51004	200	修改订单失败，您在{businessType}和交易品种{instFamily}的全仓买卖模式下，修改当前买单新增张数、当前合约持有仓位、当前合约买入挂单张数以及其他合约占用额度之和，不能超过当前杠杆倍数允许的持仓上限{tierLimitQuantity}(张)，请调低杠杆或者使用新的子账户重新下单(当前杠杆：{leverage}×，修改当前买单新增张数：{size}张，当前合约持有仓位：{posNumber}张，当前合约买入挂单张数：{pendingNumber}张，其他合约占用额度：{otherQuota}张)。
51004	200	修改订单失败，您在{businessType}和交易品种{instFamily}的全仓买卖模式下，修改当前卖单新增张数、当前合约持有仓位、当前合约卖出挂单张数以及其他合约占用额度之和，不能超过当前杠杆倍数允许的持仓上限{tierLimitQuantity}(张)，请调低杠杆或者使用新的子账户重新下单(当前杠杆：{leverage}×，修改当前卖单新增张数：{size}张，当前合约持有仓位：{posNumber}张，当前合约卖出挂单张数：{pendingNumber}张，其他合约占用额度：{otherQuota}张)。
51005	200	委托数量大于单笔上限
51006	200	委托价格不在限价范围内（最高买入价：{param0}，最低卖出价：{param1}）
51007	200	委托失败，委托数量不可小于 1 张
51008	200	委托失败，账户 {param0} 可用余额不足
51008	200	委托失败，账户 {param0} 可用保证金不足
51008	200	委托失败，账户 {param0} 可用余额不足，且未开启自动借币
51008	200	委托失败，账户 {param0} 可用保证金不足，且未开启自动借币（PM模式也可以尝试IOC订单降低风险）
51008	200	委托失败，因为 {param0} 剩余的档位限额不足，导致可借不足（限价挂单以及当前下单需借：{param1}，剩余额度{param2}，限额 {param3}，已用额度{param4}）
51008	200	委托失败，因为 {param0} 剩余的限额（母账户限额+当前账户锁定的尊享借币额度）不足，导致可借不足（限价挂单以及当前下单需借 {param1}，剩余额度 {param2}，限额 {param3}，已用额度 {param4}）
51008	200	委托失败，因为 {param0} 剩余的币对限额不足，导致可借不足
51008	200	委托失败，因为 {param0} 剩余的借贷池限额不足，导致可借不足
51008	200	委托失败，账户资产不足，美金层面有效保证金小于 IMR（PM模式也可以尝试IOC订单降低风险）
51008	200	委托失败，delta 校验未通过，因为若成功下单，adjEq 的变化值将小于 IMR 的变化值。建议增加 adjEq 或减少 IMR 占用（PM模式也可以尝试IOC订单降低风险）
51009	200	下单功能被冻结，请联系客服进行处理
51010	200	当前账户模式不支持此操作
51011	200	ordId重复
51012	200	币种不存在
51014	200	指数不存在
51015	200	instId和instType不匹配
51016	200	clOrdId重复
51017	200	杠杆委托交易借币超出限额
51018	200	期权交易账户不能有净开空持仓
51019	200	期权全仓不能有净开多持仓
51020	200	委托数量必须超过单笔下限
51021	200	币对或合约待上线
51022	200	合约暂停中
51023	200	仓位不存在
51024	200	交易账户冻结
51024	200	根据服务条款，我们很遗憾地通知您，我们无法为您提供服务。如果您有任何问题，请联系我们的客服。
51024	200	根据您的要求，该账号已被冻结，如有问题请及时联系客服处理。
51024	200	您的账户近期做了相关安全设置变更，为保证您的资金安全，暂无法进行此操作，如有问题请您及时联系客服处理。
51024	200	您的账户已完成全部资产支取，为保证您的信息安全，该账户已永久冻结，若有问题，请您及时联系客服处理。
51024	200	您的认证信息疑似存在安全风险，为保证您的资金安全，暂无法进行此操作，请您及时联系客服处理。
51024	200	您的认证信息不符合年龄规定，为保证您的资金安全，暂无法进行此操作，请您及时联系客服处理。
51024	200	根据合规要求，您的认证国家或地区已禁止交易，您可以平掉所有仓位。如有问题请及时联系客服处理。
51024	200	您的认证信息疑似存在多次认证，为保证您的资金安全，暂无法进行此操作，请您及时联系客服处理。
51024	200	您的账户已被司法冻结，暂无法进行此操作，如有问题请您及时联系客服处理。
51024	200	无法进行此操作。请首先解决您现有的 C2C申诉。
51024	200	您的账户疑似存在合规风险，为保证您的资金安全，暂无法进行此操作，请您及时联系客服处理。
51024	200	根据您的交易需求，暂无法进行此操作，如有问题请及时联系客服处理。
51024	200	由于您的账户触发平台风控，暂无法进行此操作，有疑问请您联系客服。
51024	200	此账户暂无法使用，有任何疑问您可以联系客服。
51024	200	此账户提币功能暂无法使用，有任何疑问您可以联系客服。
51024	200	此账户资金账户划转功能暂无法使用，有任何疑问您可以联系客服。
51024	200	因您进行法币交易时违反了《平台法币交易规则》，故不再为您提供法币交易功能的相关服务，您账户的充币提币以及其他交易功能不受影响。
51024	200	请注意查收邮件内容，回复认证团队发送邮件，有任何问题，请联系认证团队。
51024	200	根据您的要求，该账号已被关闭，如有问题请及时联系客服处理。
51024	200	您的账户疑似存在安全风险，为保证您的资金安全，暂无法进行此操作，请您及时联系客服处理。
51024	200	您的账户疑似存在安全风险，暂无法兑换，请您及时联系客服处理
51024	200	您的账号已冻结，部分功能将被禁用，如您希望解除账号限制，请前往帮助中心联系平台客服。
51024	200	根据合规要求，您的认证国家或地区已禁止交易，您可以撤销已有的订单。如有问题请及时联系客服处理。
51024	200	您的认证国家为交易禁止国，根据合规要求，暂无法进行此操作，如有问题请您及时联系客服处理。
51024	200	根据当地法律法规，您所在的国家或地区无法使用该产品。如果您的常居住地不是本国家或地区，并持有有效身份证件，您可继续使用欧易的交易所产品。
51024	200	请注意您在建立托管交易子账户后的前30分钟内可能无法划转或进行交易，请耐心等待并稍后再试。
51024	200	此功能暂不可用，完成高级身份认证后即可正常使用
51024	200	由于您未能及时更新认证信息，您账户的充币与交易功能已受限。请尽快更新认证，以解除账户限制。
51024	200	超出限制的子账户不能开仓，只能减仓或平仓，请尝试使用其他账户进行交易。
51025	200	委托笔数超限
51026	200	交易产品类型不匹配指数（instType和uly不匹配）
51027	200	合约已到期
51028	200	合约交割中
51029	200	合约结算中
51030	200	资金费结算中
51031	200	委托价格不在平仓限价范围内
51032	200	市价全平中
51033	200	币对单笔交易已达限额
51034	200	成交速率超出您所设置的上限，请将做市商保护状态重置为 inactive 以继续交易。
51035	200	用户没有做市订单的下单权限
51036	200	仅 PM 账户的期权业务线支持 MMP 类型订单
51411	200	用户没有执行mass cancel的权限
51042	200	PM 账户模式下，期权仅支持持仓模式为全仓的 MMP 类型订单
51043	200	该逐仓仓位不存在
59509	200	用户没有重置做市商保护状态的权限
51037	200	当前账户风险状态，仅支持降低账户风险方向的IOC订单
51038	200	当前风险模块下已经存在降低账户风险方向的IOC类型订单
51039	200	PM账户下交割和永续的全仓不能调整杠杆倍数
51040	200	期权逐仓的买方不能调整保证金
51041	200	PM账户仅支持买卖模式
51044	200	当前订单类型{param0}， {param1}不支持设置止盈和止损
51046	200	止盈触发价格应该大于委托价格
51047	200	止损触发价格应该小于委托价格
51048	200	止盈触发价格应该小于委托价格
51049	200	止损触发价格应该大于委托价格
51050	200	止盈触发价格应该大于卖一价
51051	200	止损触发价格应该小于卖一价
51052	200	止盈触发价格应该小于买一价
51053	200	止损触发价格应该大于买一价
51054	500	请求超时，请稍候重试
51055	200	组合保证金模式暂不支持合约网格
51056	200	当前策略不支持该操作
51057	200	当前账户模式暂不支持此交易策略，请前往“交易设置 > 账户模式”进行切换
51058	200	该策略无仓位
51059	200	策略当前状态不支持此操作
51065	200	algoClOrdId 重复
51068	200	{param0} 已经在 algoClOrdId 和 attachAlgoClOrdId 中存在。
51069	200	不存在该{param0}相关的期权合约
51070	200	您当前尚未达到升级至该账户模式的要求，请先在官方网站或APP完成账户模式的升级。
51071	200	当前维护的标签维度倒计时全部撤单达到数量上限
51072	200	您当前身份为现货带单员，设置的带单币对买入时，tdMode 需要使用 spot_isolated
51073	200	您当前身份为现货带单员，卖出带单资产需要使用'/copytrading/close-subposition'接口
51074	200	仅现货带单员设置的带单币对支持使用 tdMode：spot_isolated
51076	200	分批止盈的每笔止盈止损订单仅支持单向止盈止损，slTriggerPx&slOrdPx 与 tpTriggerPx&tpOrdPx 只能填写一组
51077	200	现货和杠杆暂不支持多笔止盈和成交价止损
51078	200	您当前身份为带单交易员，不支持分批止盈
51079	200	同一笔订单上附带分批止盈的止盈委托单不能超过 {param0} 笔
51080	200	同一笔订单上附带分批止盈的止盈触发价类型 (tpTriggerPxType) 必须保持一致
51081	200	同一笔订单上附带分批止盈的止盈触发价 (tpTriggerPx) 不能相等
51082	200	同一笔订单上附带分批止盈，其中触发止盈的止盈委托价 (tpOrdPx) 只能是市价
51083	200	同一笔订单上附带分批止盈的止盈数量之和需要等于订单的委托数量
51084	200	同一笔订单上附带分批止盈的止损委托单不能超过 {param0} 笔
51085	200	附带止盈止损开启'开仓价止损'时 (amendPxOnTriggerType 设置为 1)，该笔订单上的止盈委托单必须大于等于 2 笔
51086	200	同一笔订单上附带止盈止损委托单不能超过 {param0} 笔
51538	200	若下单时使用了 attachAlgoOrds 参数，也需要使用 attachAlgoOrds 参数改单；若下单时没有使用 attachAlgoOrds 参数，则不支持使用 attachAlgoOrds 参数改单。
51539	200	修改同一笔订单上分批止盈中的止盈止损订单时，attachAlgoId 或者 attachAlgoClOrdId 的值不能重复
51527	200	改单失败，其中至少有一个附带的止盈止损订单不存在
51087	200	该币种取消上线，当前不支持交易
51088	200	对于同一个仓位，仅支持一笔全部平仓的止盈止损挂单
51089	200	在附带分批止盈时，止盈订单的数量不能为空
51090	200	对于绑定了限价止盈的止损订单，不允许修改其委托数量
51091	200	同一笔订单上附带分批止盈的止盈类型必须保持一致
51092	200	同一笔订单上附带分批止盈的止盈委托价不能相等
51093	200	同一笔订单上附带分批止盈，其中限价止盈的止盈委托价 (tpOrdPx) 不能为 –1 (市价)
51094	200	币币、杠杆和期权交易不支持限价止盈
51095	200	该接口下限价止盈订单时，也需要同时下一笔止损订单
51096	200	限价止盈时 cxlOnClosePos 需要为 true
51098	200	对于绑定了限价止盈的止损订单，不能添加新的止盈
51099	200	您当前身份为带单交易员，不支持下单限价止盈
51178	200	使用 attachAlgoClOrdId 时，tpTriggerPx&tpOrdPx 或者 slTriggerPx&slOrdPx 不能为空。
51100	200	下单失败，只减仓订单不能附带止盈止损。
51101	200	操作失败，单笔委托数量不能大于{maxSzPerOrder}(张)。
51102	200	操作失败，当前合约的累计挂单数量不能大于{maxNumberPerInstrument}(单)。
51103	200	操作失败，{businessType}的当前交易品种下，所有合约累计挂单数量不能大于{maxNumberPerInstFamily}(单)。
51104	200	操作失败，{businessType}的当前交易品种下，所有合约累计挂单张数不能大于{maxSzPerInstFamily} (张)。
51105	200	操作失败，当前合约的持仓张数和同方向挂单张数之和不能大于{maxPositionSzPerInstrument}(张)。
51106	200	操作失败，{businessType}的当前交易品种下，所有合约累计持仓张数和同方向挂单张数之和不能大于{maxPostionSzPerInstFamily51106}(张)。
51107	200	操作失败，{businessType}的当前交易品种下，所有合约累计持仓张数和双向挂单张数之和不能大于{maxPostionSzPerInstFamily51107}(张)。
51108	200	持仓量超过市价全平最大限制
51109	200	订单深度中无买一卖一价
51110	200	集合竞价开始后方可下限价单
51111	200	批量下单时，超过最大单数{param0}
51112	200	平仓张数大于该仓位的可平张数
51113	429	市价全平操作过于频繁
51116	200	委托价格或触发价格超过{param0}
51117	200	平仓单挂单单数超过限制
51120	200	下单数量不足{param0}张
51121	200	下单张数应为一手张数的倍数
51122	200	委托价格小于最小值{param0}
51124	200	价格发现期间您只可下限价单
51125	200	当前杠杆存在非只减仓挂单，请撤销所有非只减仓挂单后进行只减仓挂单
51126	200	当前杠杆存在只减仓挂单，请撤销所有只减仓挂单后进行非只减仓挂单
51127	200	仓位可用余额为0
51128	200	跨币种账户无法进行全仓杠杆交易
51129	200	持仓及买入订单价值已达到持仓限额，不允许继续买入
51130	200	逐仓杠杆保证金币种错误
51131	200	仓位可用余额不足
51132	200	仓位正资产小于最小交易单位
51133	200	跨币种全仓币币不支持只减仓功能
51134	200	平仓失败，您当前没有杠杆仓位，请关闭只减仓后继续
51135	200	您的平仓价格已触发限价，最高买入价格为{param0}
51136	200	您的平仓价格已触发限价，最低卖出价格为{param0}
51137	200	买单最高价为 {param0}，请调低价格
51138	200	卖单最低价为 {param0}，请调高价格
51139	200	现货模式下币币不支持只减仓功能
51142	200	盘口无有效报价，用USDT模式下单无法成交，请尝试切换到币种模式
51143	200	兑换数量不足
51147	200	交易期权需要在交易账户资产总价值大于2万美元的前提下，开通期权交易服务
51148	200	下单失败，当前订单若下单成功会造成只减仓订单反向开仓，请撤销或修改原有挂单再进行下单
51149	500	下单超时，请稍候重试
51150	200	交易数量或价格的精度超过限制
51152	200	一键借币模式下，不支持自动借币与自动还币和手动类型混合下单。
51155	200	由于您所在国家或地区的合规限制，您无法交易此币对或合约
51169	200	下单失败，当前合约无持仓，请先取消只减仓设置，再尝试下单
51170	200	下单失败，只减仓下单方向不能与持仓方向相同
51171	200	改单失败，当前订单若改单成功会造成只减仓订单反向开仓，请撤销或修改原有挂单再进行改单
51174	200	操作失败，当前 {param0} 的累计挂单数量已达上限 {param1} (单)
51175	200	参数 {param0}、{param1} 和 {param2} 不能同时为空
51176	200	参数 {param0}、{param1} 和 {param2} 只能填写一个
51177	200	当前期权订单的价格类型为{param0}，不支持修改{param1}
51179	200	现货模式下，不支持使用{param0}进行期权下单。
51180	200	{param0}的范围应为({param1}, {param2})
51181	200	使用{param0}下单，ordType 只能为限价单 (limit)
51182	200	当前账户期权价格类型 pxUsd 和 pxVol 的挂单数量之和，不能超过 {param0} 个
51185	200	单笔订单价值不能超过 {maxOrderValue} USD
51186	200	下单失败。在当前保证金模式下，您针对 {param0} 的杠杠倍数设置为 {param1}x，大于平台允许的最大杠杠倍数 {param2}x，请调低杠杆。
51187	200	下单失败，您在 {param0} {param1} 和当前保证金模式下，当前下单张数、持仓及挂单张数之和 {param2}，已超过平台上限 {param3} 张，请修改当前订单数量，或撤单、平仓。
51201	200	市价委托单笔价值不能超过 1,000,000 USDT
51202	200	市价单下单数量超出最大值
51203	200	普通委托数量超出最大限制{param0}
51204	200	限价委托单价格不能为空
51205	200	不支持只减仓操作
51206	200	请先撤销当前下单产品{param0}的只减仓挂单，避免反向开仓
51220	200	分润策略仅支持策略停止时卖币或停止时全部平仓
51221	200	请输入 0-30% 范围内的指定分润比例
51222	200	该策略不支持分润
51223	200	当前状态您不可以进行分润带单
51224	200	该币对不支持分润
51225	200	分润跟单策略不支持手动立即触发策略
51226	200	分润跟单策略不支持修改策略参数
51250	200	策略委托价格不在正确范围内
51251	200	创建冰山委托时，策略委托类型错误
51252	200	策略委托数量不在正确范围内
51253	200	冰山委托单笔均值超限
51254	200	冰山委托单笔均值错误
51255	200	冰山委托单笔委托超限
51256	200	冰山委托深度错误
51257	200	跟踪委托回调服务错误，回调幅度限制为{min}<x<={max}%
51258	200	跟踪委托失败，卖单激活价格需大于最新成交价格
51259	200	跟踪委托失败，买单激活价格需小于最新成交价格
51260	200	每个用户最多可同时持有{param0}笔未成交的跟踪委托
51261	200	每个用户最多可同时持有{param0}笔未成交的止盈止损
51262	200	每个用户最多可同时持有{param0}笔未成交的冰山委托
51263	200	每个用户最多可同时持有{param0}笔未成交的时间加权单
51264	200	时间加权单笔均值超限
51265	200	时间加权单笔上限错误
51267	200	时间加权扫单比例出错
51268	200	时间加权扫单范围出错
51269	200	时间加权委托间隔错误，应为{min}<=x<={max}
51270	200	时间加权委托深度限制为 0<x<=1%
51271	200	时间加权委托失败，扫单比例应该为 0<x<=100%
51272	200	时间加权委托失败，扫单范围应该为 0<x<=1%
51273	200	时间加权委托总量应为大于 0
51274	200	时间加权委托总数量需大于单笔上限
51275	200	止盈止损市价单笔委托数量不能超过最大限制
51276	200	止盈止损市价单不能指定价格
51277	200	止盈触发价格不能大于最新成交价
51278	200	止损触发价格不能小于最新成交价
51279	200	止盈触发价格不能小于最新成交价
51280	200	止损触发价格不能大于最新成交价
51281	200	计划委托不支持使用tgtCcy参数
51282	200	吃单价优于盘口的比例范围
51283	200	时间间隔的范围{param0}s~{param1}s
51284	200	单笔数量的范围{param0}~{param1}
51285	200	委托总量的范围{param0}~{param1}
51286	200	下单金额需大于等于{param0}
51287	200	当前策略不支持此交易品种
51288	200	策略正在停止中，请勿重复点击
51289	200	策略配置不存在，请稍后再试
51290	200	策略引擎正在升级，请稍后重试
51291	200	策略不存在或已停止
51292	200	策略类型不存在
51293	200	策略不存在
51294	200	该策略暂不能创建，请稍后再试
51295	200	PM账户不支持ordType为{param0}的策略委托单
51298	200	交割、永续合约的买卖模式下，不支持计划委托
51299	200	策略委托失败，用户最多可持有{param0}笔该类型委托
51300	200	止盈触发价格不能大于标记价格
51302	200	止损触发价格不能小于标记价格
51303	200	止盈触发价格不能小于标记价格
51304	200	止损触发价格不能大于标记价格
51305	200	止盈触发价格不能大于指数价格
51306	200	止损触发价格不能小于指数价格
51307	200	止盈触发价格不能小于指数价格
51308	200	止损触发价格不能大于指数价格
51309	200	集合竞价期间不能创建策略
51310	200	逐仓自主划转保证金模式不支持ordType为iceberg、twap的策略委托单
51311	200	移动止盈止损委托失败，回调幅度限制为{min}<x<={max}
51312	200	移动止盈止损委托失败，委托数量范围{min}<x<={max}
51313	200	逐仓自主划转模式不支持策略部分
51317	200	币币杠杆不支持计划委托
51327	200	closeFraction 仅适用于交割合约和永续合约
51328	200	closeFraction 仅适用于只减仓订单
51329	200	closeFraction 仅适用于买卖模式
51330	200	closeFraction 仅适用于止盈止损市价订单
51331	200	closeFraction仅限于平仓单
51332	200	组合保证金模式不支持closeFraction
51333	200	开平模式下的平仓单或买卖模式下的只减仓单无法附带止盈止损
51340	200	投入保证金需大于{0}{1}
51341	200	当前策略状态下暂不支持平仓
51342	200	已有平仓单，请稍后重试
51343	200	止盈价格需小于区间最低价格
51344	200	止损价格需大于区间最高价格
51345	200	策略类型不是网格策略
51346	200	最高价格不能低于最低价格
51347	200	暂无可提取利润
51348	200	止损价格需小于区间最低价格
51349	200	止盈价格需大于区间最高价格
51350	200	暂无可推荐参数
51351	200	单格收益必须大于0
51352	200	币对数量范围{pairNum1} - {pairNum2}
51353	200	存在重复币对{existingPair}
51354	200	币对比例总和需等于100%
51355	200	定投日期范围{date1} - {date2}
51356	200	定投时间范围{0}~{1}
51357	200	时区范围 {timezone1} - {timezone2}
51358	200	每个币种的投入金额需大于{amount}
51359	200	暂不支持定投该币种{0}
51370	200	杠杆倍数范围{0}~{1}
51380	200	市场行情不符合策略配置
51381	200	单网格利润率不在区间内
51382	200	策略不支持停止信号触发
51383	200	最小价格必须小于最新成交价
51384	200	信号触发价格必须大于最小价格
51385	200	止盈价必须大于最小价格
51386	200	最小价格必须大于1/2最新成交价
51387	200	止损价格应小于无限网格的区间最低价
51388	200	策略已在运行中
51389	200	触发价格需小于{0}
51390	200	触发价格需小于止盈价格
51391	200	触发价格需大于止损价格
51392	200	止盈价格需大于触发价格
51393	200	止损价格需小于触发价格
51394	200	触发价格需大于止盈价格
51395	200	触发价格需小于止损价格
51396	200	止盈价格需小于触发价格
51397	200	止损价格需大于触发价格
51398	200	当前行情满足停止条件，无法创建策略
51399	200	当前杠杆下最大可投入金额为 {amountLimit} {quoteCurrency}，请减少投入金额后再试。
51400	200	由于订单已完成、已撤销或不存在，撤单失败
51400	200	撤单失败，订单不存在（仅适用于价差速递）
51401	200	撤单失败，订单已撤销（仅适用于价差速递）
51402	200	撤单失败，订单已完成（仅适用于价差速递）
51403	200	撤单失败，该委托类型无法进行撤单操作
51404	200	价格发现第二阶段您不可撤单
51405	200	撤单失败，您当前没有未成交的订单
51406	400	撤单数量超过最大允许单数{param0}
51407	200	ordIds 和 clOrdIds 不能同时为空
51408	200	币对 id 或币对名称与订单信息不匹配
51409	200	币对 id 或币对名称不能同时为空
51410	200	撤单失败，订单已处于撤销中
51411	200	用户没有执行mass cancel的权限
51412	200	撤单超时，请稍后重试
51416	200	委托已触发，暂不支持撤单
51413	200	撤单失败，接口不支持该委托类型的撤单
51415	200	下单失败，现货交易仅支持设置最新价为触发价格，请更改触发价格并重试
51500	200	价格、数量、止盈/止损不能同时为空
51501	400	修改订单超过最大允许单数{param0}
51502	200	修改订单失败，账户 {param0} 可用余额不足
51502	200	修改订单失败，账户 {param0} 可用保证金不足
51502	200	修改订单失败，账户 {param0} 可用余额不足，且未开启自动借币
51502	200	修改订单失败，账户 {param0} 可用保证金不足，且未开启自动借币（PM模式也可以尝试IOC订单降低风险）
51502	200	修改订单失败，因为 {param0} 剩余的档位限额不足，导致可借不足（限价挂单以及当前下单需借：{param1}，剩余额度{param2}，限额 {param3}，已用额度{param4}。
51502	200	修改订单失败，因为 {param0} 剩余的档位限额不足，导致可借不足（限价挂单以及当前下单需借：{param1}，剩余额度{param2}，限额 {param3}，已用额度{param4}。
51502	200	修改订单失败，因为 {param0} 剩余的限额（主账户限额+当前账户锁定的尊享借币额度）不足，导致可借不足（限价挂单以及当前下单需借 {param1}，剩余额度 {param2}，限额 {param3}，已用额度 {param4}。
51502	200	修改订单失败，因为 {param0} 剩余的币对限额不足，导致可借不足
51502	200	修改订单失败，因为 {param0} 剩余的借贷池限额不足，导致可借不足
51502	200	修改订单失败，账户资产不足，美元层面有效保证金小于 IMR（PM模式也可以尝试IOC订单降低风险）
51502	200	修改订单失败，delta 校验未通过，因为若成功下单，adjEq 的变化值将小于 IMR 的变化值。建议增加 adjEq 或减少 IMR 占用（PM模式也可以尝试IOC订单降低风险）
51503	200	由于订单已完成、已撤销或不存在，改单失败
51503	200	由于订单不存在，改单失败（仅适用于价差速递）
51505	200	{instId} 不处于集合竞价阶段
51506	200	订单类型不支持改单
51508	200	集合竞价第一阶段和第二阶段不允许改单
51509	200	修改订单失败,订单已撤销（仅适用于价差速递）
51510	200	修改订单失败,订单已完成（仅适用于价差速递）
51511	200	操作失败，订单价格不满足Post Only条件
51512	200	批量修改订单失败。同一批量改单请求中不允许包含相同订单。
51513	200	对于正在处理的同一订单，改单请求次数不得超过3次
51514	200	修改订单失败，价格长度不能超过 32 个字符
51523	200	不允许在全部仓位止盈止损单上修改订单委托价格，请修改触发价格
51524	200	不允许在全部仓位止盈止损单上修改委托数量，请修改触发价格
51525	200	一键借币止盈止损单不支持修改
51526	200	改单失败，止盈止损单不支持增加或删除止盈/止损
51527	200	改单失败，止盈止损订单不存在
51528	200	止盈止损不支持修改触发类型
51529	200	改单失败，只有交割、永续合约单可以修改止盈止损
51530	200	改单失败，只减仓订单不能附带止盈止损
51531	200	改单失败，止盈止损单修改必须保留一个方向
51536	200	期权的 pxVol 或者 pxUsd 订单不支持修改订单数量
51537	200	非期权产品不支持使用 pxUsd 或者 pxVol
51543	200	修改币币或杠杆的止盈止损订单时，仅支持调整价格和数量。如需其他操作，请撤单后重新下单。
51600	200	查询订单的状态不存在
51601	200	订单状态和订单id不能同时存在
51602	200	订单状态或订单id必须存在一个
51603	200	查询订单不存在
51604	200	若想获取文件链接，请先申请下载文件
51605	200	只允许下载过去两年内的历史成交明细文件
51606	200	无法下载当前季度的历史成交明细
51607	200	您已申请下载文件，当前状态为进行中
51608	200	当前季度无历史成交明细
51610	200	只允许下载 2021 年第一季度以来的历史账单流水
51611	200	无法下载当前季度的账单流水
51620	200	您不是节点用户，没有相关权限
51621	200	该用户不是您的直客
51156	200	您当前身份为带单交易员。在开平仓模式下，对于带单合约标的不支持使用该接口平仓
51159	200	您当前身份为带单交易员，在买卖模式下，如需使用该接口下单，委托的方向必须与现有持仓和挂单保持一致
51162	200	您当前有 {instrument} 挂单，请撤单后重试
51163	200	您当前有 {instrument} 持仓，请平仓后重试
51165	200	{instrument}只减仓订单数量已达上限 {upLimit}，请撤销部分订单后重新下单。
51166	200	当前产品不支持带单
51167	200	下单失败，因为您存在大宗交易的委托订单，请撤销后重新下单
51168	200	下单失败，因为您存在只减仓类型的委托订单，请撤销后重新下单
51320	200	币种占比范围 {PercentNum1}%-{PercentNum2}%
51321	200	您正在带单。暂不支持使用套利、冰山或时间加权 (TWAP) 策略带单
51322	200	您当前身份为带单交易员。您的带单合约持仓已经市价全平，系统已撤销止盈止损委托并进行平仓
51323	200	您当前身份为带单交易员。您的带单合约仓位已设置止盈止损，请先撤销原有止盈止损订单
51324	200	您当前身份为带单交易员，并持有 {instrument} 仓位。平仓委托张数需要与可平张数一致
51325	200	您当前身份为带单交易员。下止盈止损单时，请选择市价作为委托价格
51326	200	您当前身份为带单交易员，下止盈止损单时，委托价格类型必须为市价
51326	200	您当前身份为带单交易员，下止盈止损单时，委托价格类型必须为市价
54000	200	暂不支持币币杠杆业务
54001	200	只有跨币种全仓账户才能设置自动借币
54004	200	下单或改单失败，因为批量订单中的一个订单失败了
54005	200	盘前交割合约请使用逐仓进行交易
54006	200	盘前交易合约用户持仓上限为{posLimit}张
54007	200	不支持该产品 {instId}
54008	200	该操作被“撤销 MMP 订单”接口限制。请通过该接口解除限制。
54009	200	{param0}的范围应为 [{param1}，{param2}]
54011	200	盘前交易合约交割前 1 小时内仅允许减少仓位数量，请修改或撤销订单

数据类

错误码	HTTP 状态码	错误提示
52000	200	没有最新行情信息

金融

错误码从 51700 到 51799

错误码	HTTP 状态码	错误提示
51720	200	赎回失败
51721	200	取消赎回失败
51722	200	赎回已到账
51723	200	不支持提前赎回
51724	200	当前状态不支持赎回
51725	200	当前状态不支持取消
51726	200	该项目不支持撤销申购/赎回
51727	200	最小申购数量为 {minUnit} {ccy}
51728	200	申购数量超过最大值
51729	200	该项目尚未到期
51730	200	该项目已售罄
51731	200	产品现在暂停申购
51732	200	用户KYC等级不符合要求
51733	200	用户被风险管理中
51734	200	不支持用户所属KYC国家
51735	200	不支持子帐户
51736	200	{ccy} 余额不足
51737	200	根据当地法律法规，您需要完成身份认证方可继续使用我们的服务。
51738	200	您的资金账户被冻结
51739	200	该功能暂不可用
51750	200	抵押物不能包含借贷币种资产
51751	200	币种 {ccy} 不支持借币
51752	200	币种 {ccy} 不支持抵押
51753	200	抵押物中不包含此资产
51754	200	当前没有负债，无需增加抵押物
51755	200	币种 {ccy} 被限制操作
51756	200	超过最大可赎回数量
51757	200	质押物数量不应低于 {minAmt}

闪兑

错误码从 52900 到 52999

错误码	HTTP 状态码	错误提示
52900	200	无效请求
52901	200	无效基准货币
52902	200	无效标价货币
52903	200	无效的报价数量
52904	200	无效的报价方向
52905	200	无效的报价
52907	200	订单找不到
52908	200	无效的订单ID
52909	200	客户自定义ID重复使用
52910	500	服务端暂时不可用，请稍后重试
52911	500	询价服务不可用，请稍后重试
52912	500	服务端超时
52913	200	拒绝交易
52914	200	交易账户可用资产不足
52915	200	询价量太大，流动性不足导致无法报价，请稍后重试
52916	200	资金账户余额不足
52917	200	询价数量不能低于下限
52918	200	询价数量不能超过上限
52919	200	闪兑交易参数{param}与报价不一致
52920	200	闪兑交易数量不能超过报价数量
52921	200	报价已交易，请重新询价
52922	200	报价已过期，请重新询价
52923	200	服务异常，请稍后重试
52924	200	下单过于频繁，请稍后重试
52925	200	客户自定义请求ID重复使用
52926	200	{param0}已过期
52927	200	没有报价
52928	200	数量应为下单数量精度的倍数

交割合约类

错误码从 55000 到 55999

错误码	HTTP 状态码	错误提示
55000	200	交割后30分钟内不能转出

永续合约类

暂无

期权合约类

暂无

资金类

错误码从 58000 到 58999

错误码	HTTP 状态码	错误提示
58002	200	请先开通余币宝服务
58003	200	余币宝不支持该币种
58004	200	账户冻结
58005	200	申购/赎回额度不可超过{0}
58006	200	币种{0}不支持当前操作
58007	200	资金接口服务异常，请稍后再试。
58008	200	您没有该币种资产
58009	200	币对不存在
58010	200	该链{0}暂不支持
58011	200	抱歉，由于当地法律法规，欧易无法为{region}未认证用户提供服务，请先认证身份以继续使用欧易
58012	200	抱歉，由于当地法律法规，欧易无法为{region}未认证用户提供服务，所以您无法向该用户转账
58013	200	暂不支持提币功能，请咨询客服了解详情
58014	200	暂不支持充值功能，请咨询客服了解详情
58015	200	暂不支持划转功能，请咨询客服了解详情
58016	200	仅交易团队主账户有权限调用此接口
58100	200	行权或结算中，暂无法转入或转出
58101	200	划转冻结
58102	429	已达到速率限制。请参考相应的 API 文档与节流请求
58103	200	该账户划转功能暂不可用，详情请联系客服
58104	200	您在法币区的交易异常，现已被限制划转功能，请您联系在线客服以解除限制
58105	200	您在法币区的交易异常，现已被限制划转功能，请您在网页或APP进行法币划转操作以完成身份验证
58106	200	美元可转校验未通过
58107	200	币种可转校验未通过
58110	200	您所交易过或者持仓的 {businessType} {instFamily} 产品触发市场风控，平台已暂停您的资金转出功能，请稍后重试。如需进一步的协助，请联系客服。
58111	200	永续合约正在收取资金费，暂时无法做资金划转，请稍后重试
58112	200	资金划转失败，请联系客服进行处理
58113	200	该币种不支持划转
58114	400	转账金额必须大于 0
58115	200	子账户不存在
58116	200	转出数量大于最大可转数量
58117	200	账户划转失败，请先处理负资产后再划转
58119	200	{0} 子账户没有转出权限，请先设置
58120	200	划转服务暂不可用，请稍后重试
58121	200	此次划转将导致您的仓位风险水平较高，进而可能引起爆仓。您需要重新调整划转金额，确保仓位处于安全水平后，再进行划转操作。
58122	200	您的一部分现货正用于仓位间的 Delta 对冲，若划转数量超过可用金额，可能会影响现有的现货对冲结构，进而导致维持保证金率增加，请留意您的风险水平。
58123	200	参数from与参数to不可相同
58124	200	资金划转中，划转id：{trId}，请通过接口(GET /api/v5/asset/transfer-state)获取最新状态
58125	200	不可交易资产仅支持子账户转主账户
58126	200	不可交易资产划转，只能在资金账户间互转
58127	200	主账户 API key 不支持当前 type 划转类型参数，请参考 API 文档描述
58128	200	子账户 API key 不支持当前 type 划转类型参数，请参考 API 文档描述
58129	200	{param}错误或{param}与type不匹配
58131	200	根据当地法律法规，欧易无法为未认证用户提供服务，请先完成身份认证再继续划转
58132	200	根据当地法律法规，我们无法为仅完成基本认证的用户提供服务，请先完成高级认证再继续划转
58200	200	该币种暂不支持从{0}提现至{1}，敬请谅解
58201	200	今日提现金额累计超过每日限额
58202	200	NEO最小提现数量为1，且提现数量必须为整数
58203	200	请先添加提现地址
58204	200	因您的账户活动触发风控，暂停提现。请联系客户支持寻求帮助。
58205	200	提现金额大于单笔提现最大金额
58206	200	提现金额小于单笔最小提现金额
58207	200	提币地址不在认证地址列表内 (带标签的提币地址格式为 “address:label”)
58208	200	提现失败，邮箱未绑定
58209	200	子账户不能充值或提现，请在主账户中进行提现。
58210	200	由于无法验证您的身份，提币操作未能成功。请通过欧易 App 或官网完成提币操作。
58212	200	提现手续费应填写为提币数量的{0}%
58213	200	内部转账地址不合法，必须是邮箱、手机号或者账户名
58214	200	{chainName}维护中，暂停提币
58215	200	提币申请ID不存在
58216	200	不允许执行该操作
58217	200	您当前的提现地址存在风险，暂时不能提现，详情请联系客服
58218	200	内部提现失败，请检查参数toAddr与areaCode
58219	200	为保障您的资金安全，修改手机号/邮箱/谷歌验证后24小时之内将无法提现
58220	200	提币请求已撤销
58221	200	toAddr参数格式有误，提币地址需要加上标签，格式应该为“地址:标签”
58222	200	无效的提币地址
58223	200	提币到此合约地址需要支付更高的手续费
58224	200	该类型币种暂不支持链上提币到 OKX 地址，请通过内部转账进行提币
58225	200	抱歉，由于当地法律法规，欧易无法为{region}未认证用户提供服务，所以您无法向该用户转账
58226	200	{chainName} 已下线，不支持提币
58227	200	不可交易资产提币只能全部提出
58228	200	不可交易资产提币要求 API key 必须绑定 IP
58229	200	资金账户手续费不足 {fee} USDT
58230	200	根据欧易的合规政策，您需要完成 Lv. 1 身份认证方可继续提币
58231	200	由于您的收款人尚未完成 Lv. 1 身份认证，内部转账暂时无法完成
58232	200	您已超出个人身份验证 (Lv.1) 的提币上限，请完成照片验证 (Lv. 2) ，即可提升提币限额
58233	200	根据当地法律法规，欧易无法为未认证用户提供服务，请先完成身份认证再继续提币
58234	200	根据当地法律法规，收款人必须完成身份认证方可收到您的转账
58235	200	根据当地法律法规，欧易无法为仅完成基本认证的用户提供服务，请先完成高级认证再继续提币
58236	200	根据当地法律法规，仅完成基础认证的收款人无法收取转账，您的收款人必须完成高级认证方可收到您的转账
58237	200	根据当地法律法规，请提供准确的接收方信息 (rcvrInfo)。对于交易所地址，请一并提供交易所信息和接收人的身份信息({recipientParameters})。
58238	200	提币到交易所地址需提供完整的接收方信息，包括交易所信息和接收人的身份信息
58240	200	根据当地法律法规，为保障用户安全，您需要完成身份认证方可继续使用我们的服务。若您不希望进行身份认证，请联系客服团队了解详情。我们致力于为用户提供一个安全的平台，感谢您的理解与支持。
58241	200	根据当地法律法规，内部转账功能暂时无法使用
58242	200	受收款人所在地法律法规限制，本次内部转账无法完成
58243	200	由于您的收款人尚未完成法币入金，对方不能接收本次转账
58244	200	请先完成法币入金，再进行您的操作
58248	200	根据当地法律法规限制，提币API已被暂时禁用。请使用OKX网页或OKX手机APP进行提币操作。
58249	200	该币种暂不支持 API 提币，请于欧易网页端或 App 端进行提币。
58252	200	为保障您的资产安全，首次进行 TRY 交易后，提币将在 48 小时内受到限制。
58300	200	创建充值地址超过上限
58301	200	充值地址不存在
58302	200	充值地址需要标签
58303	200	该链{chain}充值当前不可用
58304	200	创建invoice失败
58305	200	找不到充币地址，请完成身份认证并生成充币地址
58306	200	根据欧易的合规政策，您需要完成 Lv. 1 身份认证方可继续充币
58307	200	您已超出个人身份验证 (Lv.1) 的充币上限。超出充币上限的资产已被冻结，请完成照片验证 (Lv. 2) ，即可提升充币限额
58308	200	根据当地法律法规，欧易无法为未认证用户提供服务，请先完成身份认证再继续充币
58309	200	根据当地法律法规，欧易无法为仅完成基本认证的用户提供服务，请先完成高级认证再继续充币
58310	200	无法创建新的充币地址，请稍后重试
58350	200	您的余额不足
58351	200	invoice已经过期
58352	200	invoice无效
58353	200	充币数量需要在限额范围内
58354	200	单日达到生成invoice 10,000 个的上限
58355	200	用户没有使用此API接口的权限，请联系您的客户经理
58356	200	同节点账户不支持闪电网络充币或提币
58358	200	参数fromCcy与参数toCcy不可相同

账户类

错误码从 59000 到 59999

错误码	HTTP 状态码	错误提示
59000	200	设置失败，请在设置前关闭任何挂单或持仓
59001	200	当前存在借币，暂不可切换
59002	200	子账户设置失败，请在设置前关闭任何子账户挂单、持仓或策略
59004	200	只支持同一业务线下交易产品ID
59005	200	逐仓自主划转保证金模式，初次划入仓位的资产价值需大于 10,000 USDT
59006	200	此功能即将下线，无法切换到此模式
59101	200	杠杆倍数无法修改，请撤销所有逐仓挂单后进行杠杆倍数修改
59102	200	杠杆倍数超过最大杠杆倍数，请降低杠杆倍数
59103	200	杠杆倍数过低，账户中没有足够的可用保证金可以追加，请提高杠杆倍数
59104	200	杠杆倍数过高，借币仓位已超过该杠杆倍数的最大仓位，请降低杠杆倍数
59105	400	杠杆倍数设置不能小于{0}，请提高杠杆倍数
59106	200	您下单后仓位总张数所处档位的最高可用杠杆为{0}，请重新调整
59107	200	杠杆倍数无法修改，请撤销所有全仓挂单后修改杠杆倍数
59108	200	杠杆倍数过低，账户中保证金不足，请提高杠杆倍数
59109	200	调整后，账户权益小于所需保证金，请重新调整杠杆倍数
59110	200	该{0}对应的产品业务线不支持使用tgtCcy参数
59111	200	PM账户下衍生品全仓不支持杠杆查询
59112	200	当前存在逐仓/全仓挂单，请撤销所有逐仓挂单后进行杠杆倍数修改
59113	200	根据当地法律法规，您所在的地区无法使用保证金交易相关服务，如果您不是该地区居民，请进行KYC2身份认证
59114	200	根据当地法律法规，您所在的地区无法使用保证金交易相关服务
59117	200	所选币种数量不能超过 {param0} 个
59118	200	下单金额需大于 {param0}
59119	200	一键还债功能暂时关闭，请稍后重试
59120	200	一键兑换主流币功能暂时关闭，请稍后重试
59121	200	该批次正在处理中，请等待处理完
59122	200	该批次已经处理完
59123	200	{param0}币种下单金额需大于 {param1}
59124	200	{param0} 币种下单金额需小于 {param1}
59125	200	{param0} 不支持当前操作
59132	200	无法切换，请先撤销所有挂单，参考预检查接口并停止不兼容策略
59133	200	无法切换，资产未达目标账户模式的要求
59134	200	无法切换，请参考预检查接口并平掉不兼容的仓位
59135	200	无法切换，请参考预检查接口并调整带跟单关系
59136	200	无法切换，请预先设置全仓合约仓位的杠杆倍数
59137	200	设置失败，请为所有全仓合约仓位降低杠杆倍数到 {param0} 或以下
59138	200	无法切换，梯度档位校验失败
59139	200	无法切换，保证金校验失败
59200	200	账户余额不足
59201	200	账户余额是负数
59202	200	PM 账户下衍生品全仓不支持最大可开仓数量的查询
59300	200	追加保证金失败，指定仓位不存在
59301	200	调整保证金超过当前最大可调整数量
59302	200	当前仓位存在平仓挂单，请撤销平仓挂单后进行保证金修改
59303	200	可用保证金不足，请尝试增加保证金或减少借币数量
59304	200	借币币种权益不足，请至少留有一天的利息
59305	200	您当前没有进行尊享借币，无法设置尊享借币优先
59306	200	借币数量超过总额度，不可继续借币
59307	200	当前用户不满足尊享借币条件
59308	200	市场化借币额度不足，VIP还币失败
59309	200	还币数量超出已借数量，还币失败
59310	200	当前账户不支持尊享借币
59311	200	存在尊享借币，无法设置
59312	200	{币种}不支持尊享借币
59313	200	无法还币。在一键借币模式下，您目前没有 ${ccy} 借币（币对：${ccyPair}）
59314	200	当前用户该订单不是借币中，不允许还币
59315	200	VIP借币功能正在升级中,稍等10分钟之后再次操作
59316	200	当前用户该币种存在借币申请中的订单，不允许借币
59317	200	您当前币种 VIP 借币中的订单数量不能大于{maxNumber}(单)
59319	200	由于您的资金已被占用，您暂时无法偿还借贷，请解除占用状态再进行还币
59320	200	超出借贷限额
59321	200	您所在的地区不支持借币
59322	200	此订单无法执行当前操作
59323	200	借贷金额小于最低限额
59324	200	没有可用的借贷订单
59325	200	您需要偿还本单的全部借币金额
59326	200	出借数量应在 {minLend} ~ {lendQuota} 范围内
59327	200	由于您续借的金额不足以偿还您当前的借贷，您无法自动续借，请手动还款以避免高额逾期利息
59328	200	出借年化应在 {minRate} ~ {maxRate} 范围内
59329	200	无法降低负债。当前订单可直接还币
51152	200	一键借币模式下，不支持自动借币与自动还币和手动类型混合下单。
59401	200	持仓价值达到持仓限制
59402	200	查询条件中的instId的交易产品当前不是可交易状态，请填写单个instid逐个查询状态详情
59410	200	只有当借币交易启用且该币种支持借币交易时，您才可以进行借币
59411	200	无法手动借币，账户可用保证金不足
59412	200	无法手动借币，您输入的数量已超过借币限额
59413	200	该币种没有负债，无需还币
59414	200	无法手动借币，您输入的数量应大于或等于最小借币数量 {param0}
59500	200	仅主账户有操作权限
59501	200	每个账户最多可创建 50 个 API key
59502	200	此备注名已存在。请输入唯一的 API key 备注名称
59503	200	每个 API key 最多可以绑定 20 个 IP 地址
59504	200	子账户不支持提币功能，请在主账户中进行提币
59505	200	passphrase 格式不正确，支持6-32位字母和数字组合（区分大小写，不支持空格符号）
59506	200	API key 不存在
59507	200	转出账户和转入账户必须是同一个母账户下的2个不同的子账户
59508	200	{0}该子账户被冻结
59509	200	用户没有重置做市商保护状态的权限
59510	200	子账户不存在
59512	200	不支持为独立经纪商子账号设置主动转出权限，所有独立经纪商子账户默认有主动转出权限
59601	200	子账户名称已存在
59603	200	创建的子账户数量已达到上限
59604	200	仅母账APIkey有操作此接口的权限
59606	200	删除失败，请将子账户中的余额划转到母账户
59608	200	仅Broker账户有操作此接口的权限
59609	200	经纪商已经存在
59610	200	经纪商不存在
59611	200	经纪商状态是未审核
59612	200	时间参数格式转换失败
59613	200	当前未与子账户建立托管关系
59614	200	托管子账户不支持此操作
59615	200	起始日期和结束日期的时间间隔不能超过180天。
59616	200	起始日期不能大于结束日期
59617	200	子账户创建成功，账户等级设置失败
59618	200	创建子账户失败
59619	200	该接口不支持独立经纪商子账户，请使用为独立经纪商提供的专有接口。
59622	200	您正在创建独立经纪商 2 级子账号。该 1 级子账号不存在或有误，请先创建 1 级子账号或使用正确的 1 级子账号。
59623	200	独立经纪商 1 级子账号下存在 2 级子账号，请删除 2 级子账号后重试。
59648	200	调整后实际现货对冲占用数量不足，有潜在爆仓风险，请调整现货对冲占用数量
59649	200	关闭现货对冲占用模式可能会增加强制平仓的风险。请调整仓位，使保证金率处于安全状态。
59650	200	切换对冲单位可能会增加强制平仓的风险。请调整仓位，使保证金率处于安全状态。
59651	200	未开启现货对冲占用，无法设置现货对冲数量
59652	200	不支持为非杠杆币种设置现货对冲占用数量

大宗交易

错误码从 70000 开始

错误码	HTTP 状态码	错误提示
70000	200	询价单不存在
70001	200	报价单不存在
70002	200	大宗交易不存在
70003	200	公共的大宗交易不存在
70004	200	无效的产品ID {instId}
70005	200	组合交易的数量不能超过最大值
70006	200	不满足最小资产要求
70007	200	该产品类型 {instFamily} 的标的指数 {instType} 不存在
70008	200	MMP状态下操作失败。
70009	200	Data数组必须至少含有一个有效元素
70010	200	时间戳参数必须是Unix时间戳的毫秒格式
70011	200	产品类型 {instType} 存在重复设置
70012	200	同一个instType{instType}下的instFamily/instId{instId} 存在重复设置
70013	200	endTs必须大于等于beginTs
70014	200	不允许对所有产品类别设置includeAll=True.
70015	200	您在完成高级身份认证后才能交易此类产品
70016	200	交易产品设置中需选择至少一个交易品种
70100	200	组合交易中的产品ID重复
70101	200	clRfqId重复
70102	200	未指定对手方
70103	200	无效的对手方
70105	200	非全现货的RFQ总价值应该大于最小名义值{nonSpotMinNotional}
70106	200	下单数量小于最小交易数量
70107	200	对手方的数量不能超过最大值
70108	200	全现货的RFQ总价值应该大于最小名义值{spotMinNotional}
70109	200	所选产品无有效对手方
70200	200	不能取消处于{rfqState}状态的询价单
70203	200	取消失败，由于询价单数量超过限制数量{rfqLimit}
70207	200	取消失败，由于您没有询价挂单
70208	200	取消失败，由于服务暂时不可用，请稍后重试
70301	200	clQuoteId重复
70303	200	不能对处于{rfqState}状态的询价单报价
70304	200	价格应该是下单价格精度的整数倍
70305	200	买入价格不能高于报价
70306	200	报价的组合交易没有匹配{rfqId}的组合交易
70307	200	数量应该是下单数量精度的整数倍
70308	200	不允许对自己的询价单报价
70309	200	不允许对相同询价单进行同一方向的报价
70310	200	instId {instId} 报价不可以超过你预设的价格限制
70400	200	不能取消处于{quoteState}状态的报价单
70408	200	取消失败，由于报价单数量超过限制数量{quoteLimit}
70409	200	取消失败，由于您没有报价挂单
70501	200	询价单{rfqId}没有被{quoteId}报价
70502	200	组合交易没有匹配{rfqId}的组合交易
70503	200	执行腿的价值总和小于大宗交易的最小名义值
70504	200	执行失败，因为询价单的状态是{rfqState}
70505	200	执行失败，因为报价单的状态是{quoteState}
70506	200	腿的数量比例与原RFQ不一致
70507	200	部分执行尝试失败。须设置allowPartialExecution为`true`
70508	200	没有可用的产品设置。
70509	200	交易执行失败：对手方相关错误
70511	200	正在执行报价
75001	200	交易 ID 不存在
75002	200	{sprdId} : 目前无法下新订单或修改现有订单
75003	200	价格无效
56000	200	大宗交易不存在
56001	200	多腿的数量不能超过 {legLimit}
56002	200	执行和验证的多腿数量不匹配
56003	200	重复的clBlockTdId
56004	200	不允许自成交
56005	200	执行和验证的clBlockTdId 不匹配
56006	200	执行和验证的角色不能相同
56007	200	执行和验证的第{legNo}条腿不匹配
56008	200	重复的产品名称

跟单交易

错误码从 59200 到 59300

错误码	HTTP 状态码	错误提示
59128	200	您当前身份为带单交易员。您设置的带单合约 {instrument} 杠杆倍数不能超过 {num}×
59206	200	该带单交易员已无更多跟单空位
59216	200	仓位不存在，请稍后重试
59218	200	市价全平中...
59256	200	无法切换为买卖模式，请降低跟单人数至1人
59245	200	作为带单交易员，{param0} 单次下单张数应小于或等于 {param1}
59247	200	杠杆倍数过高，当前仓位已超过该杠杆倍数的最大仓位，请重新调整杠杆倍数
59260	200	您还不是现货带单交易员，请先在网页端/移动端完成申请
59262	200	您还不是合约带单交易员，请先完成申请
59641	200	由于您当前有定期借币，无法切换账户模式
59642	200	跟单和带单员只能使用现货或现货和合约模式
59643	200	当前存在现货跟单，暂不可切换
59263	200	仅白名单用户支持使用跟单功能，独立经纪商请联系 BD 进行处理
59264	200	不支持现货跟单
59267	200	取消失败，跟单关系不存在
59268	200	存在交易员未带单的产品
59269	200	该合约交易员不存在
59270	200	固定金额跟单时，最大跟单金额 (copyTotalAmt) 需要大于等于单笔跟单金额 (copyAmt)
59273	200	您还不是合约跟单用户，请先开始跟单
59275	200	操作失败，您正在申请成为交易员，无法跟单
59276	200	交易员正在退出，当前无法跟单
59277	200	到达跟单人数上限，不允许继续跟单
59278	200	正在处理您的停止跟单请求，请稍后再试
59279	200	您已设置跟单，请勿重复设置
59280	200	跟单关系不存在，请先进行首次设置
59282	200	仅主账号在白名单中的独立经纪商 ND 子账户支持使用该接口，请联系 BD 进行处理
59283	200	当前账户不在现货和合约模式
59284	200	超过本月 {param0} 次调整上限
59286	200	当前账户模式为现货模式，无法成为合约带单人
59287	200	请使用 {param0}-{param1} 范围内的分润比例
59288	200	您当前身份为带单交易员。您的账户正处于组合保证金模式，请切换至现货和合约模式或跨币种模式后重试
59130	200	最高止盈比例为 {num}%，请重新输入
59258	200	您当前身份为带单交易员，暂不支持该操作
59259	200	请输入在有效范围内的跟单比例
59285	200	您尚未进行过带单或跟单操作

策略交易

错误码从 55100 到 55999

错误码	HTTP 状态码	错误提示
55100	200	止盈百分比应在 {parameter1} ~ {parameter2} 的范围内
55101	200	止损百分比应在 {parameter1} ~ {parameter2} 的范围内
55102	200	止盈百分比需大于当前策略收益率
55103	200	止损百分比需小于当前策略收益率
55104	200	仅合约网格支持按收益率百分比止盈止损
55105	200	当前状态不支持加仓操作
55106	200	加仓金额应在 {parameter1} ~ {parameter2} 的范围内
55111	200	此信号名称正在使用中，请尝试新名称
55112	200	此信号不存在
55113	200	创建信号策略的杠杆倍数大于交易产品列的最大杠杆倍数
55116	200	每个交易对只能进行一笔追逐限价委托

WebSocket

WebSocket 错误消息均为英文，中文错误消息仅供参考

公共

错误码从 60000 到 64002

通用类

错误码	错误消息
60004	无效的 timestamp
60005	无效的 apiKey
60006	请求时间戳过期
60007	无效的签名
60008	当前服务不支持订阅{0}频道，请检查WebSocket地址
60009	登录失败
60011	用户需要登录
60012	不合法的请求
60013	无效的参数 args
60014	用户请求频率过快，超过该接口允许的限额
60018	错误的 URL 或者 {0} 不存在，请参考 API 文档使用正确的 URL，频道和参数
60019	无效的op{0}
60020	超出最大允许订阅的APIKey数量{0}
60021	该功能不支持多账户登录使用
60022	批量登录部分成功
60023	批量登录请求过于频繁
60024	passphrase不正确
60025	超出最大允许订阅的token数量{0}
60026	不支持APIKey和token同时登录
60027	参数{0}不可为空
60028	当前服务不支持此功能，请检查WebSocket地址
60029	该频道仅支持手续费等级为 VIP5 及以上的用户订阅使用
60030	books50-l2-tbt 深度频道仅支持手续费等级为 VIP4 及以上的用户订阅使用
60031	WebSocket地址不支持多账户和重复登录
60032	API key 不存在
63999	由于内部错误，登录失败，请稍后重试。
64000	订阅参数 uly 已失效，请您尽快将 uly 替换为 instFamily，更多详情可参考: https://www.okx.com/cn/help-center/changes-to-v5-api-websocket-subscription-parameter-and-url.
64001	该频道到已经迁移到了 '/business' URL，请使用新的 URL。更多详情可参考：https://www.okx.com/cn/help-center/changes-to-v5-api-websocket-subscription-parameter-and-url.
64002	"/business" URL 不支持该频道. 请使用"/private" URL(对于私有频道), 或者"/public" URL(对于公有频道)，更多详情可参考：https://www.okx.com/cn/help-center/changes-to-v5-api-websocket-subscription-parameter-and-url.
64003	用户交易费等级不支持访问该频道

关闭帧

状态码	文案
1009	用户订阅请求过大
4001	登录失败
4002	参数不合法
4003	登录账户多于100个
4004	空闲超时30秒
4005	写缓冲区满
4006	异常场景关闭
4007	API key已更新或删除，请重新连接
4008	总订阅频道数量超过最大限制
4009	该连接订阅频道数超限制

概览

API学习资源与技术支持

教程

Python包

客户服务

创建我的APIKey

生成APIKey

REST 请求验证

发起请求

签名

WebSocket

概述

连接

连接限制

登录

请求参数

返回参数

订阅

取消订阅

通知

账户模式

实盘交易

模拟盘交易

模拟盘交互式浏览器

基本信息

交易时效性

REST API

WebSocket

限速

交易相关API

子账户限速

基于成交比率的子账户限速

最佳实践

做市商申请

经纪商申请

交易账户

REST API

获取交易产品基础信息

限速：20次/2s

限速规则：UserID + InstType

权限：读取

HTTP请求

请求参数

返回参数

查看账户余额

限速：10次/2s

限速规则：UserID

权限：读取

HTTP请求

请求参数

返回参数

查看持仓信息

限速：10次/2s

限速规则：UserID

权限：读取

HTTP请求

请求参数

返回参数

查看历史持仓信息

限速：10次/2s

限速规则：UserID

权限：读取

HTTP请求

请求参数

返回参数

查看账户持仓风险

限速：10次/2s

限速规则：UserID

权限：读取

HTTP请求

请求参数

返回参数

账单流水查询（近七天）

限速：5次/s

限速规则：UserID

权限：读取

HTTP请求

请求参数

返回参数

账单流水查询（近三月）