概览
欢迎查看 V5 API文档。我们提供完整的REST和WebSocket API以满足您的交易需求。
API学习资源与技术支持
教程
- 学习使用V5 API交易: V5 API使用指南
- 学习使用Python交易现货: Python 现货交易教程
- 学习使用Python交易衍生品: Python 衍生品交易教程
Python包
- 使用Python SDK更简单地上手: Python SDK
- 轻松上手Python做市商代码 Python 做市商代码示例
客户服务
- 官方Telegram社群: https://t.me/OKXAPI
- 订阅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.715ZOK-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 频道的最大连接数为 20 个。每个 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":"LTC-USD-200327"
},
{
"channel":"candle1m",
"instId":"LTC-USD-200327"
}
]
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| op | String | 是 | 操作，subscribe |
| args | Array | 是 | 请求订阅的频道列表 |
| > channel | String | 是 | 频道名 |
| > instType | String | 否 | 产品类型SPOT：币币 MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权ANY：全部 |
| > instFamily | String | 否 | 交易品种 适用于 交割/永续/期权 |
| > instId | String | 否 | 产品ID |
返回示例
{
"event": "subscribe",
"arg": {
"channel": "tickers",
"instId": "LTC-USD-200327"
},
"connId": "a4d3ae55"
}
返回参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| event | String | 是 | 事件，subscribe error |
| arg | Object | 否 | 订阅的频道 |
| > channel | String | 是 | 频道名 |
| > instType | String | 否 | 产品类型SPOT：币币MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION ： 期权ANY：全部 |
| > instFamily | String | 否 | 交易品种 适用于 交割/永续/期权 |
| > instId | String | 否 | 产品ID |
| code | String | 否 | 错误码 |
| msg | String | 否 | 错误消息 |
| connId | String | 是 | WebSocket连接ID |
取消订阅
可以取消一个或者多个频道
请求格式说明
{
"op": "unsubscribe",
"args": ["< SubscriptionTopic > "]
}
请求示例
{
"op": "unsubscribe",
"args":
[
{
"channel" : "tickers",
"instId":"LTC-USD-200327"
},
{
"channel" : "candle1m",
"instId":"LTC-USD-200327"
}
]
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| op | String | 是 | 操作，unsubscribe |
| args | Array | 是 | 取消订阅的频道列表 |
| > channel | String | 是 | 频道名 |
| > instType | String | 否 | 产品类型SPOT：币币MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权ANY：全部 |
| > instFamily | String | 否 | 交易品种 适用于 交割/永续/期权 |
| > instId | String | 否 | 产品ID |
返回示例
{
"event": "unsubscribe",
"arg": {
"channel": "tickers",
"instId": "LTC-USD-200327"
},
"connId": "a4d3ae55"
}
返回参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| event | String | 是 | 事件，unsubscribe error |
| arg | Object | 否 | 取消订阅的频道 |
| > channel | String | 是 | 频道名 |
| > instType | String | 否 | 产品类型SPOT：币币MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权ANY：全部 |
| > instFamily | String | 否 | 交易品种 适用于 交割/永续/期权 |
| > instId | String | 否 | 产品ID |
| code | String | 否 | 错误码 |
| msg | String | 否 | 错误消息 |
| connId | String | 是 | WebSocket连接ID |
账户模式
为了方便您的交易体验，请在开始交易前设置适当的账户模式。
交易账户交易系统提供四个账户模式，分别为现货模式、现货和合约模式、跨币种保证金模式以及组合保证金模式。
账户模式的首次设置，需要在网页或手机app上进行。
实盘交易
实盘API交易地址如下：
- REST：
https://tr.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
交易时效性
由于网络延时或者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
对于与交易相关的 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（母账户）：
- BTC-USDT-SWAP 交易量为100 USDT，订单数量为10;
- XRP-USDT 交易量为20 USDT，订单数量为15;
- 子账户成交比率 = (100+20) / (10 * 1 + 15 * 0.1) = 10.4
- 账户 B (子账户)：
- BTC-USDT-SWAP 交易量为200 USDT，订单数量为100;
- XRP-USDT 交易量为20 USDT，订单数量为30;
- 子账户成交比率 = (200+20) / (100 * 1 + 30 * 0.1) = 2.13
- 账户 C (子账户)：
- BTC-USDT-SWAP 交易量为300 USDT，订单数量为100;
- XRP-USDT 交易量为20 USDT，订单数量为45;
- 子账户成交比率 = (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
- 账户限速
- 账户 A = max(10.4, 3.01) = 10.4 -> 2500订单请求/2秒
- 账户 B = max(2.13, 3.01) = 3.01 -> 1750订单请求/2秒
- 账户 C = max(3.06, 3.01) = 3.06 -> 1750订单请求/2秒
最佳实践
如果您需要的请求速率高于我们的限速，您可以设置不同的子账户来批量请求限速。 我们建议使用此方法来限制或间隔请求，以最大化每个帐户的限速并避免断开连接或拒绝请求。
交易账户
账户功能模块下的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": [
{
"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 |
| expTime | String | 产品下线时间 适用于 币币/杠杆/交割/永续/期权，对于 交割/期权，为交割/行权日期；亦可以为产品下线时间，有变动就会推送。 |
| lever | String | 该instId支持的最大杠杆倍数，不适用于币币、期权 |
| tickSz | String | 下单价格精度，如 0.0001对于期权来说，是梯度中的最小下单价格精度，如果想要获取期权价格梯度，请使用"获取期权价格梯度"接口 |
| lotSz | String | 下单数量精度 合约的数量单位是 张，现货的数量单位是交易货币 |
| minSz | String | 最小下单数量 合约的数量单位是 张，现货的数量单位是交易货币 |
| ctType | String | 合约类型linear：正向合约inverse：反向合约仅适用于 交割/永续 |
| state | String | 产品状态live：交易中 suspend：暂停中preopen：预上线，如：交割和期权的新合约在 live 之前，会有 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",
"fixedBal": "0",
"frozenBal": "158.573",
"imr": "",
"interest": "0",
"isoEq": "0",
"isoLiab": "0",
"isoUpl": "0",
"liab": "0",
"maxLoan": "0",
"mgnRatio": "",
"mmr": "",
"notionalLever": "",
"ordFrozen": "0",
"spotInUseAmt": "",
"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 | 币种逐仓负债额 适用于 跨币种保证金模式/组合保证金模式 |
| > 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 | 现货对冲占用数量 适用于 组合保证金模式 |
| > spotIsoBal | String | 现货逐仓余额 仅适用于现货带单/跟单 适用于 现货模式/现货和合约模式 |
| > spotBal | String | 现货余额 ，单位为 币种，比如 BTC。点击了解更多 |
| > openAvgPx | Array | 现货开仓成本价 单位 USD。 点击了解更多 |
| > accAvgPx | Array | 现货累计成本价 单位 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 | 是 | 是 | 是 | 是 |
账单流水查询（近七天）
帐户资产流水是指导致帐户余额增加或减少的行为。本接口可以查询最近7天的账单数据。
限速：5次/s
限速规则：UserID
HTTP请求
GET /api/v5/account/bills
请求示例
GET /api/v5/account/bills
GET /api/v5/account/bills?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_account_bills()
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 否 | 产品类型SPOT：币币 |
| ccy | String | 否 | 账单币种 |
| type | String | 否 | 账单类型1：划转2：交易 |
| subType | String | 否 | 账单子类型1：买入2：卖出11：转入12：转出 |
| after | String | 否 | 请求此id之前（更旧的数据）的分页内容，传的值为对应接口的billId |
| before | String | 否 | 请求此id之后（更新的数据）的分页内容，传的值为对应接口的billId |
| begin | String | 否 | 筛选的开始时间戳，Unix 时间戳为毫秒数格式，如 1597026383085 |
| end | String | 否 | 筛选的结束时间戳，Unix 时间戳为毫秒数格式，如 1597027383085 |
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 |
返回结果
{
"code": "0",
"msg": "",
"data": [{
"bal": "8694.2179403378290202",
"balChg": "0.0219338232210000",
"billId": "623950854533513219",
"ccy": "USDT",
"clOrdId": "",
"execType": "T",
"fee": "-0.000021955779",
"fillFwdPx": "",
"fillIdxPx": "27104.1",
"fillMarkPx": "",
"fillMarkVol": "",
"fillPxUsd": "",
"fillPxVol": "",
"fillTime": "1695033476166",
"from": "",
"instId": "BTC-USDT",
"instType": "SPOT",
"interest": "0",
"mgnMode": "isolated",
"notes": "",
"ordId": "623950854525124608",
"pnl": "0",
"posBal": "0",
"posBalChg": "0",
"px": "27105.9",
"subType": "1",
"sz": "0.021955779",
"tag": "",
"to": "",
"tradeId": "586760148",
"ts": "1695033476167",
"type": "2"
}]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instType | String | 产品类型 |
| billId | String | 账单ID |
| type | String | 账单类型 |
| subType | String | 账单子类型 |
| ts | String | 余额更新完成的时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| balChg | String | 账户层面的余额变动数量 |
| posBalChg | String | 仓位层面的余额变动数量 |
| bal | String | 账户层面的余额数量 |
| posBal | String | 仓位层面的余额数量 |
| sz | String | 数量 |
| px | String | 价格，与 subType 相关1：买入 2：卖出 |
| ccy | String | 账户余额币种 |
| pnl | String | 收益 |
| fee | String | 手续费 正数代表平台返佣 ，负数代表平台扣除 |
| mgnMode | String | 保证金模式isolated：逐仓cross：全仓账单不是由仓位变化产生的，该字段返回 "" |
| instId | String | 产品ID，如 BTC-USDT |
| ordId | String | 订单ID 当type为 2：交易 时，返回相应订单id 无订单时，该字段返回 "" |
| execType | String | 流动性方向T：takerM：maker |
| from | String | 转出账户6：资金账户18：交易账户仅适用于 资金划转，不是资金划转时，返回 "" |
| to | String | 转入账户6：资金账户18：交易账户仅适用于 资金划转，不是资金划转时，返回 "" |
| notes | String | 备注 |
| interest | String | 利息 |
| tag | String | 订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。 |
| fillTime | String | 最新成交时间 |
| tradeId | String | 最新成交ID |
| clOrdId | String | 客户自定义订单ID |
| fillIdxPx | String | 交易执行时的指数价格 对于交叉现货币对，返回 baseCcy-USDT 的指数价格。 例如LTC-ETH，该字段返回LTC-USDT的指数价格。 |
| fillMarkPx | String | 成交时的标记价格，仅适用于交割/永续/期权 |
| fillPxVol | String | 成交时的隐含波动率，仅适用于期权，其他业务线返回空字符串"" |
| fillPxUsd | String | 成交时的期权价格，以USD为单位，仅适用于期权，其他业务线返回空字符串"" |
| fillMarkVol | String | 成交时的标记波动率，仅适用于期权，其他业务线返回空字符串"" |
| fillFwdPx | String | 成交时的远期价格，仅适用于期权，其他业务线返回空字符串"" |
账单流水查询（近三月）
帐户资产流水是指导致帐户余额增加或减少的行为。本接口可以查询最近3个月的账单数据。
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/bills-archive
请求示例
GET /api/v5/account/bills-archive
GET /api/v5/account/bills-archive?instType=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_account_bills_archive()
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 否 | 产品类型SPOT：币币 |
| ccy | String | 否 | 账单币种 |
| type | String | 否 | 账单类型1：划转2：交易6：保证金划转 |
| subType | String | 否 | 账单子类型1：买入2：卖出11：转入12：转出236：兑换主流币用户账户转入237：兑换主流币用户账户转出 |
| after | String | 否 | 请求此id之前（更旧的数据）的分页内容，传的值为对应接口的billId |
| before | String | 否 | 请求此id之后（更新的数据）的分页内容，传的值为对应接口的billId |
| begin | String | 否 | 筛选的开始时间戳，Unix 时间戳为毫秒数格式，如 1597026383085 |
| end | String | 否 | 筛选的结束时间戳，Unix 时间戳为毫秒数格式，如 1597027383085 |
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 |
返回结果
{
"code": "0",
"msg": "",
"data": [{
"bal": "8694.2179403378290202",
"balChg": "0.0219338232210000",
"billId": "623950854533513219",
"ccy": "USDT",
"clOrdId": "",
"execType": "T",
"fee": "-0.000021955779",
"fillFwdPx": "",
"fillIdxPx": "27104.1",
"fillMarkPx": "",
"fillMarkVol": "",
"fillPxUsd": "",
"fillPxVol": "",
"fillTime": "1695033476166",
"from": "",
"instId": "BTC-USDT",
"instType": "SPOT",
"interest": "0",
"mgnMode": "isolated",
"notes": "",
"ordId": "623950854525124608",
"pnl": "0",
"posBal": "0",
"posBalChg": "0",
"px": "27105.9",
"subType": "1",
"sz": "0.021955779",
"tag": "",
"to": "",
"tradeId": "586760148",
"ts": "1695033476167",
"type": "2"
}]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instType | String | 产品类型 |
| billId | String | 账单ID |
| type | String | 账单类型 |
| subType | String | 账单子类型 |
| ts | String | 余额更新完成的时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| balChg | String | 账户层面的余额变动数量 |
| posBalChg | String | 仓位层面的余额变动数量 |
| bal | String | 账户层面的余额数量 |
| posBal | String | 仓位层面的余额数量 |
| sz | String | 数量 |
| px | String | 价格，与 subType 相关1：买入 2：卖出 |
| ccy | String | 账户余额币种 |
| pnl | String | 收益 |
| fee | String | 手续费 正数代表平台返佣 ，负数代表平台扣除 |
| mgnMode | String | 保证金模式isolated：逐仓 cross：全仓无仓位类型字段，该字段返回 "" |
| instId | String | 产品ID，如 BTC-USDT |
| ordId | String | 订单ID 当type为 2：交易时，返回相应订单id。无订单时，该字段返回 "" |
| execType | String | 流动性方向T：takerM：maker |
| from | String | 转出账户6：资金账户18：交易账户仅适用于 资金划转，不是资金划转时，返回 "" |
| to | String | 转入账户6：资金账户18：交易账户仅适用于 资金划转，不是资金划转时，返回 "" |
| notes | String | 备注 |
| interest | String | 利息 |
| tag | String | 订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。 |
| fillTime | String | 最新成交时间 |
| tradeId | String | 最新成交ID |
| clOrdId | String | 客户自定义订单ID |
| fillIdxPx | String | 交易执行时的指数价格 对于交叉现货币对，返回 baseCcy-USDT 的指数价格。 例如LTC-ETH，该字段返回LTC-USDT的指数价格。 |
| fillMarkPx | String | 成交时的标记价格，仅适用于 交割/永续/期权 |
| fillPxVol | String | 成交时的隐含波动率，仅适用于期权，其他业务线返回空字符串"" |
| fillPxUsd | String | 成交时的期权价格，以USD为单位，仅适用于期权，其他业务线返回空字符串"" |
| fillMarkVol | String | 成交时的标记波动率，仅适用于期权，其他业务线返回空字符串"" |
| fillFwdPx | String | 成交时的远期价格，仅适用于期权，其他业务线返回空字符串"" |
查看账户配置
查看当前账户的配置信息。
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/config
请求示例
GET /api/v5/account/config
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 查看账户配置
result = accountAPI.get_account_config()
print(result)
请求参数
无
返回结果
{
"code": "0",
"data": [
{
"acctLv": "2",
"acctStpMode": "cancel_maker",
"autoLoan": false,
"ctIsoMode": "automatic",
"discountType": "1",
"enableSpotBorrow": false,
"greeksType": "PA",
"ip": "",
"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：提币 |
| discountType | String | 当前账户所在的币种折扣率类型0: 原先的币种折算率规则，默认值1: 新的币种折算率规则用来确认当前账户所在的币种折扣率类型。当新的币种折算率规则全面生效后，接口将不再返回该字段，建议提前做好兼容。 |
| liquidationGear | String | 强平提醒的保证金率水平3 代表，保证金率达到 300% 时，每隔 1 小时 app 和 ”爆仓风险预警推送频道“会推送通知0 代表不提醒 |
| enableSpotBorrow | Boolean | 现货模式下是否支持借币true：支持false：不支持 |
| spotBorrowAutoRepay | Boolean | 现货模式下是否支持自动还币true：支持false：不支持 |
获取最大可下单数量
获取最大可下单数量，可对应下单时的 "sz" 字段
限速：20次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/max-size
请求示例
GET /api/v5/account/max-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)
# 获取最大可买卖/开仓数量
result = accountAPI.get_max_order_size(
instId="BTC-USDT",
tdMode="cash"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 是 | 产品ID，如 BTC-USDT支持同一业务线下的多产品ID查询（不超过5个），半角逗号分隔 |
| tdMode | String | 是 | 交易模式cash：非保证金 |
| px | String | 否 | 委托价格 当指定多个产品ID查询时，忽略该参数，当未填写处理 |
返回结果
{
"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币币最大可用数量
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 | 是 | 交易模式cash：非保证金 |
返回结果
{
"code": "0",
"msg": "",
"data": [{
"instId": "BTC-USDT",
"availBuy": "100",
"availSell": "1"
}]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instId | String | 产品ID |
| availBuy | String | 最大买入可用数量 |
| availSell | 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：币币 |
| instId | String | 否 | 产品ID，如 BTC-USDT仅适用于instType为 币币 |
返回结果
{
"code": "0",
"msg": "",
"data": [{
"category": "1", //已废弃
"delivery": "",
"exercise": "",
"instType": "SPOT",
"level": "lv1",
"maker": "-0.0008",
"makerU": "",
"makerUSDC": "",
"taker": "-0.001",
"takerU": "",
"takerUSDC": "",
"ts": "1608623351857",
"fiat": []
}
]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| level | String | 手续费等级 |
| taker | String | 对于币币，为 USDT 交易区的吃单手续费率 |
| maker | String | 对于币币，为 USDT 交易区的挂单手续费率 |
| takerU | String | USDT 合约吃单手续费率，仅适用于交割/永续 |
| makerU | String | USDT 合约挂单手续费率，仅适用于交割/永续 |
| delivery | String | 交割手续费率 |
| exercise | String | 行权手续费率 |
| instType | String | 产品类型 |
| takerUSDC | String | 对于币币，为 USDⓈ&Crypto 交易区的吃单手续费率 |
| makerUSDC | String | 对于币币，为 USDⓈ&Crypto 交易区的挂单手续费率 |
| ts | String | 数据返回时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| category | String | |
| fiat | Array | 法币费率 |
| > ccy | String | 法币币种 |
| > taker | String | 吃单手续费率 |
| > maker | String | 挂单手续费率 |
WebSocket
账户频道
获取账户信息，首次订阅按照订阅维度推送数据，此外，当下单、撤单、成交等事件触发时，推送数据以及按照订阅维度定时推送数据
该频道的并发连接受到如下规则限制：WebSocket 连接限制
服务地址
/ws/v5/private (需要登录)
请求示例：单个
{
"op": "subscribe",
"args": [{
"channel": "account",
"ccy": "BTC"
}]
}
请求示例
{
"op": "subscribe",
"args": [
{
"channel": "account",
"extraParams": "
{
\"updateInterval\": \"0\"
}
"
}
]
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| op | String | 是 | 操作subscribeunsubscribe |
| 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 | 是 | 事件subscribeunsubscribeerror |
| 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",
"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，仅适用于跟单人 |
| >> spotBal | String | 现货余额 ，单位为 币种，比如 BTC。点击了解更多 |
| >> openAvgPx | Array | 现货开仓成本价 单位 USD。 点击了解更多 |
| >> accAvgPx | Array | 现货累计成本价 单位 USD。 点击了解更多 |
| >> spotUpl | String | 现货未实现收益，单位 USD。 点击了解更多 |
| >> spotUplRatio | String | 现货未实现收益率。点击了解更多 |
| >> totalPnl | String | 现货累计收益，单位 USD。 点击了解更多 |
| >> totalPnlRatio | String | 现货累计收益率。点击了解更多 |
撮合交易
交易
交易功能模块下的API接口需要身份验证。
POST / 下单
只有当您的账户有足够的资金才能下单。
限速：60次/2s
限速规则：UserID + Instrument ID
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 | 是 | 交易模式cash：非保证金 |
| clOrdId | String | 否 | 客户自定义订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 |
| tag | String | 否 | 订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。 |
| side | String | 是 | 订单方向buy：买sell：卖 |
| ordType | String | 是 | 订单类型market：市价单limit：限价单 post_only：只做maker单 fok：全部成交或立即取消 ioc：立即成交并取消剩余 |
| sz | String | 是 | 委托数量 |
| px | String | 可选 | 委托价格，仅适用于limit、post_only、fok、ioc类型的订单 |
| tgtCcy | String | 否 | 市价单委托数量sz的单位，仅适用于币币市价订单base_ccy: 交易货币quote_ccy：计价货币买单默认 quote_ccy， 卖单默认base_ccy |
| banAmend | Boolean | 否 | 是否禁止币币市价改单，true 或 false，默认false 为true时，余额不足时，系统不会改单，下单会失败，仅适用于币币市价单 |
| stpId | String | 否 | 用户自定义1<=x<=999999999的整数 |
| stpMode | String | 否 | 自成交保护模式 默认为 cancel maker cancel_maker,cancel_taker,cancel_bothCancel both不支持FOK |
| attachAlgoOrds | Array of object | 否 | 下单附带止盈止损信息 |
| > attachAlgoClOrdId | String | 否 | 下单附带止盈止损时，客户自定义的策略订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 订单完全成交，下止盈止损委托单时，该值会传给 algoClOrdId |
| > tpTriggerPx | String | 可选 | 止盈触发价，如果填写此参数，必须填写 止盈委托价 |
| > tpOrdPx | String | 可选 | 止盈委托价，如果填写此参数，必须填写 止盈触发价 委托价格为-1时，执行市价止盈 |
| > slTriggerPx | String | 可选 | 止损触发价，如果填写此参数，必须填写 止损委托价 |
| > slOrdPx | String | 可选 | 止损委托价，如果填写此参数，必须填写 止损触发价 委托价格为-1时，执行市价止损 |
| > tpTriggerPxType | String | 否 | 止盈触发价类型last：最新价格默认为 last |
| > slTriggerPxType | String | 否 | 止损触发价类型last：最新价格格默认为 last |
| > sz | String | 可选 | 数量。仅适用于“多笔止盈”的止盈订单，且对于“多笔止盈”的止盈订单必填 |
| > amendPxOnTriggerType | String | 否 | 是否启用开仓价止损，仅适用于分批止盈的止损订单，第一笔止盈触发时，止损触发价格是否移动到开仓均价止损0：不开启，默认值 1：开启，且止损触发价不能为空 |
返回结果
{
"code":"0",
"msg":"",
"data":[
{
"clOrdId":"oktswap6",
"ordId":"12345689",
"tag":"",
"sCode":"0",
"sMsg":""
}
],
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| code | String | 结果代码，0表示成功 |
| msg | String | 错误信息，代码为0时，该字段为空 |
| data | String | 包含结果的对象数组 |
| > ordId | String | 订单ID |
| > clOrdId | String | 客户自定义订单ID |
| > tag | String | 订单标签 |
| > sCode | String | 事件执行结果的code，0代表成功 |
| > sMsg | String | 事件执行失败或成功时的msg |
| inTime | String | REST网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123返回的时间是请求验证后的时间。 |
| outTime | String | REST网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
POST / 批量下单
每次最多可以批量提交20个新订单。请求参数应该按数组格式传递，会依次委托订单。
限速：300个/2s
限速规则：UserID + Instrument ID
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 | 是 | 交易模式cash：非保证金 |
| clOrdId | String | 否 | 客户自定义订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 |
| tag | String | 否 | 订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。 |
| side | String | 是 | 订单方向buy：买sell：卖 |
| ordType | String | 是 | 订单类型market：市价单limit：限价单 post_only：只做maker单 fok：全部成交或立即取消 ioc：立即成交并取消剩余 |
| sz | String | 是 | 委托数量 |
| px | String | 可选 | 委托价格，仅适用于limit、post_only、fok、ioc类型的订单 |
| tgtCcy | String | 否 | 市价单委托数量sz的单位，仅适用于币币市价订单base_ccy: 交易货币 ；quote_ccy：计价货币买单默认 quote_ccy， 卖单默认base_ccy |
| banAmend | Boolean | 否 | 是否禁止币币市价改单，true 或 false，默认false 为true时，余额不足时，系统不会改单，下单会失败，仅适用于币币市价单 |
| stpId | String | 否 | 用户自定义1<=x<=999999999的整数 |
| stpMode | String | 否 | 自成交保护模式 默认为 cancel maker cancel_maker,cancel_taker,cancel_bothCancel both不支持FOK |
| attachAlgoOrds | Array of object | 否 | 下单附带止盈止损信息 |
| > attachAlgoClOrdId | String | 否 | 下单附带止盈止损时，客户自定义的策略订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 订单完全成交，下止盈止损委托单时，该值会传给 algoClOrdId |
| > tpTriggerPx | String | 可选 | 止盈触发价，如果填写此参数，必须填写 止盈委托价 |
| > tpOrdPx | String | 可选 | 止盈委托价，如果填写此参数，必须填写 止盈触发价 委托价格为-1时，执行市价止盈 |
| > slTriggerPx | String | 可选 | 止损触发价，如果填写此参数，必须填写 止损委托价 |
| > slOrdPx | String | 可选 | 止损委托价，如果填写此参数，必须填写 止损触发价 委托价格为-1时，执行市价止损 |
| > tpTriggerPxType | String | 否 | 止盈触发价类型last：最新价格默认为 last |
| > slTriggerPxType | String | 否 | 止损触发价类型last：最新价格默认为 last |
| > sz | String | 可选 | 数量。仅适用于“多笔止盈”的止盈订单，且对于“多笔止盈”的止盈订单必填 |
| > amendPxOnTriggerType | String | 否 | 是否启用开仓价止损，仅适用于分批止盈的止损订单，第一笔止盈触发时，止损触发价格是否移动到开仓均价止损0：不开启，默认值 1：开启，且止损触发价不能为空 |
返回结果
{
"code":"0",
"msg":"",
"data":[
{
"clOrdId":"oktswap6",
"ordId":"12345689",
"tag":"",
"sCode":"0",
"sMsg":""
},
{
"clOrdId":"oktswap7",
"ordId":"12344",
"tag":"",
"sCode":"0",
"sMsg":""
}
],
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| code | String | 结果代码，0表示成功 |
| msg | String | 错误信息，代码为0时，该字段为空 |
| data | String | 包含结果的对象数组 |
| > ordId | String | 订单ID |
| > clOrdId | String | 客户自定义订单ID |
| > tag | String | 订单标签 |
| > sCode | String | 事件执行结果的code，0代表成功 |
| > sMsg | String | 事件执行失败或成功时的msg |
| inTime | String | REST网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 返回的时间是请求验证后的时间。 |
| outTime | String | REST网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
POST / 撤单
撤销之前下的未完成订单。
限速：60次/2s
限速规则：UserID + Instrument ID
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",
"sCode":"0",
"sMsg":""
}
],
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| code | String | 结果代码，0表示成功 |
| msg | String | 错误信息，代码为0时，该字段为空 |
| data | String | 包含结果的对象数组 |
| > ordId | String | 订单ID |
| > clOrdId | String | 客户自定义订单ID |
| > sCode | String | 事件执行结果的code，0代表成功 |
| > sMsg | String | 事件执行失败时的msg |
| inTime | String | REST网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 返回的时间是请求验证后的时间。 |
| outTime | String | REST网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
POST / 批量撤单
撤销未完成的订单，每次最多可以撤销20个订单。请求参数应该按数组格式传递。
限速：300个/2s
限速规则：UserID + instrumentID
HTTP请求
POST /api/v5/trade/cancel-batch-orders
请求示例
POST /api/v5/trade/cancel-batch-orders
body
[
{
"instId":"BTC-USDT",
"ordId":"12312"
},
{
"instId":"BTC-USDT",
"ordId":"1212"
}
]
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 是 | 产品ID，如 BTC-USDT |
| ordId | String | 可选 | 订单ID， ordId和clOrdId必须传一个，若传两个，以ordId为主 |
| clOrdId | String | 可选 | 用户自定义ID |
返回结果
{
"code":"0",
"msg":"",
"data":[
{
"clOrdId":"okt6",
"ordId":"12345689",
"sCode":"0",
"sMsg":""
},
{
"clOrdId":"okt7",
"ordId":"12344",
"sCode":"0",
"sMsg":""
}
]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ordId | String | 订单ID |
| clOrdId | String | 客户自定义订单ID |
| sCode | String | 事件执行结果的code，0代表成功 |
| sMsg | String | 事件执行失败时的msg |
POST / 修改订单
修改当前未成交的挂单
限速：60次/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 | 否 | 当订单修改失败时，该订单是否需要自动撤销。默认为falsefalse：不自动撤单true：自动撤单 |
| ordId | String | 可选 | 订单IDordId和clOrdId必须传一个，若传两个，以ordId为主 |
| clOrdId | String | 可选 | 用户自定义order ID |
| reqId | String | 否 | 用户自定义修改事件ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 |
| newSz | String | 可选 | 修改的新数量，对于部分成交订单，该数量应包含已成交数量。 |
| newPx | String | 可选 | 修改后的新价格 |
| attachAlgoOrds | Array of object | 否 | 下单附带止盈止损信息 |
| > attachAlgoId | String | 可选 | 附带止盈止损的订单ID，由系统生成，改单时，可用来标识该笔附带止盈止损订单。下止盈止损委托单时，该值不会传给 algoId |
| > attachAlgoClOrdId | String | 可选 | 下单附带止盈止损时，客户自定义的策略订单ID |
| > newTpTriggerPx | String | 可选 | 止盈触发价 如果止盈触发价或者委托价为0，那代表删除止盈。只适用于交割和永续合约。 |
| > newTpOrdPx | String | 可选 | 止盈委托价 委托价格为-1时，执行市价止盈。只适用于交割和永续合约。 |
| > newSlTriggerPx | String | 可选 | 止损触发价 如果止损触发价或者委托价为0，那代表删除止损。只适用于交割和永续合约。 |
| > newSlOrdPx | String | 可选 | 止损委托价 委托价格为-1时，执行市价止损。 只适用于交割和永续合约。 |
| > newTpTriggerPxType | String | 可选 | 止盈触发价类型last：最新价格index：指数价格mark：标记价格只适用于 交割/永续如果要新增止盈，该参数必填 |
| > newSlTriggerPxType | String | 可选 | 止损触发价类型last：最新价格index：指数价格mark：标记价格只适用于 交割/永续如果要新增止损，该参数必填 |
| > sz | String | 可选 | 新的张数。仅适用于“多笔止盈”的止盈订单且必填 |
| > amendPxOnTriggerType | String | 否 | 是否启用开仓价止损，仅适用于分批止盈的止损订单0：不开启，默认值1：开启 |
返回结果
{
"code":"0",
"msg":"",
"data":[
{
"clOrdId":"",
"ordId":"12344",
"reqId":"b12344",
"sCode":"0",
"sMsg":""
}
],
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| code | String | 结果代码，0表示成功 |
| msg | String | 错误信息，代码为0时，该字段为空 |
| data | String | 包含结果的对象数组 |
| > ordId | String | 订单ID |
| > clOrdId | String | 用户自定义ID |
| > reqId | String | 用户自定义修改事件ID |
| > sCode | String | 事件执行结果的code，0代表成功 |
| > sMsg | String | 事件执行失败时的msg |
| inTime | String | REST网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 返回的时间是请求验证后的时间。 |
| outTime | String | REST网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
POST / 批量修改订单
修改未完成的订单，一次最多可批量修改20个订单。请求参数应该按数组格式传递。
限速：300个/2s
限速规则：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 | 否 | 当订单修改失败时，该订单是否需要自动撤销。默认为falsefalse：不自动撤单true：自动撤单 |
| ordId | String | 可选 | 订单ID， ordId和clOrdId必须传一个，若传两个，以ordId为主 |
| clOrdId | String | 可选 | 用户自定义order ID |
| reqId | String | 否 | 用户自定义修改事件ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 |
| newSz | String | 可选 | 修改的新数量，对于部分成交订单，该数量应包含已成交数量。 |
| newPx | String | 可选 | 修改后的新价格 |
| attachAlgoOrds | Array of object | 否 | 下单附带止盈止损信息 |
| > attachAlgoId | String | 可选 | 附带止盈止损的订单ID，由系统生成，改单时，可用来标识该笔附带止盈止损订单。下止盈止损委托单时，该值不会传给 algoId |
| > attachAlgoClOrdId | String | 可选 | 下单附带止盈止损时，客户自定义的策略订单ID |
| > newTpTriggerPx | String | 可选 | 止盈触发价 如果止盈触发价或者委托价为0，那代表删除止盈。只适用于交割和永续合约。 |
| > newTpOrdPx | String | 可选 | 止盈委托价 委托价格为-1时，执行市价止盈。只适用于交割和永续合约。 |
| > newSlTriggerPx | String | 可选 | 止损触发价 如果止损触发价或者委托价为0，那代表删除止损。只适用于交割和永续合约。 |
| > newSlOrdPx | String | 可选 | 止损委托价 委托价格为-1时，执行市价止损。 只适用于交割和永续合约。 |
| > newTpTriggerPxType | String | 可选 | 止盈触发价类型last：最新价格index：指数价格mark：标记价格只适用于 交割/永续如果要新增止盈，该参数必填 |
| > newSlTriggerPxType | String | 可选 | 止损触发价类型last：最新价格index：指数价格mark：标记价格只适用于 交割/永续如果要新增止损，该参数必填 |
| > sz | String | 可选 | 新的张数。仅适用于“多笔止盈”的止盈订单且必填 |
| > amendPxOnTriggerType | String | 否 | 是否启用开仓价止损，仅适用于分批止盈的止损订单0：不开启，默认值1：开启“开仓价止损” |
返回结果
{
"code":"0",
"msg":"",
"data":[
{
"clOrdId":"oktswap6",
"ordId":"12345689",
"reqId":"b12344",
"sCode":"0",
"sMsg":""
},
{
"clOrdId":"oktswap7",
"ordId":"12344",
"reqId":"b12344",
"sCode":"0",
"sMsg":""
}
],
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| code | String | 结果代码，0表示成功 |
| msg | String | 错误信息，代码为0时，该字段为空 |
| data | String | 包含结果的对象数组 |
| > ordId | String | 订单ID |
| > clOrdId | String | 用户自定义ID |
| > reqId | String | 用户自定义修改事件ID |
| > sCode | String | 事件执行结果的code，0代表成功 |
| > sMsg | String | 事件执行失败时的msg |
| inTime | String | REST网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 返回的时间是请求验证后的时间。 |
| outTime | String | REST网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
GET / 获取订单信息
查订单信息
限速：60次/2s
限速规则：UserID + Instrument ID
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：币币 |
| 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 |
| > tpTriggerPx | String | 止盈触发价 |
| > tpTriggerPxType | String | 止盈触发价类型last：最新价格index：指数价格mark：标记价格 |
| > tpOrdPx | String | 止盈委托价 |
| > slTriggerPx | String | 止损触发价 |
| > slTriggerPx | String | 止损触发价类型last：最新价格index：指数价格mark：标记价格 |
| > slOrdPx | String | 止损委托价 |
| > sz | String | 张数。仅适用于“多笔止盈”的止盈订单 |
| > amendPxOnTriggerType | String | 是否启用开仓价止损，仅适用于分批止盈的止损订单0：不开启，默认值 1：开启 |
| linkedAlgoOrd | Object | 止损订单信息，仅适用于包含限价止盈单的双向止盈止损订单，触发后生成的普通订单 |
| > algoId | Object | 策略订单唯一标识 |
| stpId | String | 如果自成交保护不适用则返回"" |
| stpMode | String | 自成交保护模式 |
| feeCcy | String | 交易手续费币种 |
| fee | String | 手续费与返佣 对于币币和杠杆，为订单交易累计的手续费，平台向用户收取的交易手续费，为负数。如： -0.01 对于交割、永续和期权，为订单交易累计的手续费和返佣 |
| rebateCcy | String | 返佣金币种 |
| source | String | 订单来源6：计划委托策略触发后的生成的普通单7：止盈止损策略触发后的生成的普通单13：策略委托单触发后的生成的普通单25：移动止盈止损策略触发后的生成的普通单 |
| 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，策略订单触发时有值，否则为"" |
| 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：币币 |
| instId | String | 否 | 产品ID，如 BTC-USDT |
| ordType | String | 否 | 订单类型market：市价单limit：限价单post_only：只做maker单fok：全部成交或立即取消ioc：立即成交并取消剩余 |
| 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 |
| > tpTriggerPx | String | 止盈触发价 |
| > tpTriggerPxType | String | 止盈触发价类型last：最新价格index：指数价格mark：标记价格 |
| > tpOrdPx | String | 止盈委托价 |
| > slTriggerPx | String | 止损触发价 |
| > slTriggerPxType | String | 止损触发价类型last：最新价格index：指数价格mark：标记价格 |
| > slOrdPx | String | 止损委托价 |
| > sz | String | 张数。仅适用于“多笔止盈”的止盈订单 |
| > amendPxOnTriggerType | String | 是否启用开仓价止损，仅适用于分批止盈的止损订单0：不开启，默认值 1：开启 |
| stpId | String | 如果自成交保护不适用则返回"" |
| stpMode | String | 自成交保护模式 |
| feeCcy | String | 交易手续费币种 |
| fee | String | 手续费与返佣 对于币币和杠杆，为订单交易累计的手续费，平台向用户收取的交易手续费，为负数。如： -0.01 对于交割、永续和期权，为订单交易累计的手续费和返佣 |
| rebateCcy | String | 返佣金币种 |
| source | String | 订单来源6：计划委托策略触发后的生成的普通单7：止盈止损策略触发后的生成的普通单13：策略委托单触发后的生成的普通单25：移动止盈止损策略触发后的生成的普通单 |
| 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，策略订单触发时有值，否则为"" |
| 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：币币 |
| instId | String | 否 | 产品ID，如 BTC-USDT |
| ordType | String | 否 | 订单类型market：市价单limit：限价单 post_only：只做maker单fok：全部成交或立即取消ioc：立即成交并取消剩余 |
| state | String | 否 | 订单状态canceled：撤单成功filled：完全成交mmp_canceled：做市商保护机制导致的自动撤单 |
| after | String | 否 | 请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的ordId |
| before | String | 否 | 请求此ID之后（更新的数据）的分页内容，传的值为对应接口的ordId |
| begin | String | 否 | 筛选的开始时间戳，Unix 时间戳为毫秒数格式，如 1597026383085 |
| end | String | 否 | 筛选的结束时间戳，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": "",
"linkedAlgoOrd": {
"algoId": ""
},
"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"
}
],
"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 |
| > 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 | 如果自成交保护不适用则返回"" |
| stpMode | String | 自成交保护模式 |
| feeCcy | String | 交易手续费币种 |
| fee | String | 手续费与返佣 对于币币和杠杆，为订单交易累计的手续费，平台向用户收取的交易手续费，为负数。如： -0.01 对于交割、永续和期权，为订单交易累计的手续费和返佣 |
| rebateCcy | String | 返佣金币种 |
| source | String | 订单来源6：计划委托策略触发后的生成的普通单7：止盈止损策略触发后的生成的普通单13：策略委托单触发后的生成的普通单25：移动止盈止损策略触发后的生成的普通单 |
| 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，策略订单触发时有值，否则为"" |
| 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：期权 |
| instId | String | 否 | 产品ID，如BTC-USDT |
| ordType | String | 否 | 订单类型market：市价单limit：限价单 post_only：只做maker单 fok：全部成交或立即取消ioc：立即成交并取消剩余 |
| state | String | 否 | 订单状态canceled：撤单成功filled：完全成交mmp_canceled：做市商保护机制导致的自动撤单 |
| after | String | 否 | 请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的ordId |
| before | String | 否 | 请求此ID之后（更新的数据）的分页内容，传的值为对应接口的ordId |
| begin | String | 否 | 筛选的开始时间戳，Unix 时间戳为毫秒数格式，如 1597026383085 |
| end | String | 否 | 筛选的结束时间戳，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"
}
],
"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 | 如果自成交保护不适用则返回"" |
| attachAlgoOrds | Array of object | 下单附带止盈止损信息 |
| > attachAlgoId | String | 附带止盈止损的订单ID，改单时，可用来标识该笔附带止盈止损订单。下止盈止损委托单时，该值不会传给 algoId |
| > attachAlgoClOrdId | String | 下单附带止盈止损时，客户自定义的策略订单ID |
| > tpTriggerPx | String | 止盈触发价 |
| > tpTriggerPxType | String | 止盈触发价类型last：最新价格index：指数价格mark：标记价格 |
| > tpOrdPx | String | 止盈委托价 |
| > slTriggerPx | String | 止损触发价 |
| > slTriggerPxType | String | 止损触发价类型last：最新价格index：指数价格mark：标记价格 |
| > slOrdPx | String | 止损委托价 |
| > sz | String | 张数。仅适用于“多笔止盈”的止盈订单 |
| > amendPxOnTriggerType | String | 是否启用开仓价止损，仅适用于分批止盈的止损订单0：不开启，默认值 1：开启 |
| stpMode | String | 自成交保护模式 |
| feeCcy | String | 交易手续费币种 |
| fee | String | 手续费与返佣 对于币币和杠杆，为订单交易累计的手续费，平台向用户收取的交易手续费，为负数。如： -0.01 对于交割、永续和期权，为订单交易累计的手续费和返佣 |
| rebateCcy | String | 返佣金币种 |
| rebate | String | 返佣金额，仅适用于币币和杠杆，平台向达到指定lv交易等级的用户支付的挂单奖励（返佣），如果没有返佣金，该字段为“”。手续费返佣为正数，如：0.01 |
| pnl | String | 收益，适用于有成交的平仓订单，其他情况均为0 |
| source | String | 订单来源6：计划委托策略触发后的生成的普通单7：止盈止损策略触发后的生成的普通单13：策略委托单触发后的生成的普通单25：移动止盈止损策略触发后的生成的普通单 |
| 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，策略订单触发时有值，否则为"" |
| 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：币币 |
| instId | String | 否 | 产品 ID，如BTC-USDT |
| ordId | String | 否 | 订单 ID |
| after | String | 否 | 请求此 ID 之前（更旧的数据）的分页内容，传的值为对应接口的 billId |
| before | String | 否 | 请求此 ID 之后（更新的数据）的分页内容，传的值为对应接口的 billId |
| begin | String | 否 | 筛选的开始时间戳，Unix 时间戳为毫秒数格式，如 1597026383085 |
| end | String | 否 | 筛选的结束时间戳，Unix 时间戳为毫秒数格式，如 1597027383085 |
| limit | String | 否 | 返回结果的数量，最大为100，默认100条 |
返回结果
{
"code": "0",
"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",
"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 |
| tag | String | 订单标签 |
| fillPx | String | 最新成交价格 |
| fillSz | String | 最新成交数量 |
| fillIdxPx | String | 交易执行时的指数价格 对于交叉现货币对，返回 baseCcy-USDT 的指数价格。 例如LTC-ETH，该字段返回 LTC-USDT 的指数价格。 |
| fillPnl | String | 最新成交收益，适用于有成交的平仓订单。其他情况均为0。 |
| fillPxVol | String | 成交时的隐含波动率，仅适用于期权，其他业务线返回空字符串"" |
| fillPxUsd | String | 成交时的期权价格，以USD为单位，仅适用于期权，其他业务线返回空字符串"" |
| fillMarkVol | String | 成交时的标记波动率，仅适用于期权，其他业务线返回空字符串"" |
| fillFwdPx | String | 成交时的远期价格，仅适用于期权，其他业务线返回空字符串"" |
| fillMarkPx | String | 成交时的标记价格，仅适用于 交割/永续/期权 |
| side | String | 订单方向 buy：买 sell：卖 |
| posSide | String | 持仓方向 long：多 short：空 买卖模式返回 net |
| execType | String | 流动性方向 T：taker M：maker不适用于系统订单比如强平和ADL |
| feeCcy | String | 交易手续费币种或者返佣金币种 |
| fee | String | 手续费金额或者返佣金额，手续费扣除为‘负数’，如-0.01；手续费返佣为‘正数’，如 0.01 |
| ts | String | 成交明细产生时间，Unix时间戳的毫秒数格式，如1597026383085 |
| fillTime | String | 成交时间，与订单频道的fillTime相同 |
| 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：币币 |
| instId | String | 否 | 产品 ID，如BTC-USDT |
| ordId | String | 否 | 订单 ID |
| after | String | 否 | 请求此 ID 之前（更旧的数据）的分页内容，传的值为对应接口的billId |
| before | String | 否 | 请求此 ID 之后（更新的数据）的分页内容，传的值为对应接口的billId |
| begin | String | 否 | 筛选的开始时间戳，Unix 时间戳为毫秒数格式，如 1597026383085 |
| end | String | 否 | 筛选的结束时间戳，Unix 时间戳为毫秒数格式，如 1597027383085 |
| limit | String | 否 | 返回结果的数量，最大为100，默认100条 |
返回结果
{
"code": "0",
"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",
"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 |
| tag | String | 订单标签 |
| fillPx | String | 最新成交价格 |
| fillSz | String | 最新成交数量 |
| fillIdxPx | String | 交易执行时的指数价格 对于交叉现货币对，返回 baseCcy-USDT 的指数价格。 例如LTC-ETH，该字段返回LTC-USDT的指数价格。 |
| fillPnl | String | 最新成交收益，适用于有成交的平仓订单。其他情况均为0。 |
| fillPxVol | String | 成交时的隐含波动率，仅适用于期权，其他业务线返回空字符串"" |
| fillPxUsd | String | 成交时的期权价格，以USD为单位，仅适用于期权，其他业务线返回空字符串"" |
| fillMarkVol | String | 成交时的标记波动率，仅适用于期权，其他业务线返回空字符串"" |
| fillFwdPx | String | 成交时的远期价格，仅适用于期权，其他业务线返回空字符串"" |
| fillMarkPx | String | 成交时的标记价格，仅适用于 交割/永续/期权 |
| side | String | 订单方向buy：买sell：卖 |
| posSide | String | 持仓方向long：多short：空买卖模式返回 net |
| execType | String | 流动性方向T：takerM：maker不适用于系统订单比如强平和ADL |
| feeCcy | String | 交易手续费币种或者返佣金币种 |
| fee | String | 手续费金额或者返佣金额 手续费扣除为‘负数’，如 -0.01手续费返佣为‘正数’，如 0.01 |
| ts | String | 成交明细产生时间，Unix时间戳的毫秒数格式，如1597026383085 |
| fillTime | String | 成交时间，与订单频道的fillTime相同 |
| feeRate | String | 手续费费率。 该字段仅对 币币和杠杆返回 |
POST / 申请成交明细（近两年）
申请近2年的历史成交成交明细信息，不包括最近三个月。
限速：10 次/天
限速规则：UserID
权限：读取
HTTP 请求
POST /api/v5/trade/fills-archive
请求示例
POST /api/v5/trade/fills-archive
body
{
"year":"2023",
"quarter":"Q1"
}
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| year | String | 是 | 4位数字的年份，如 2023 |
| quarter | String | 是 | 季度，有效值 Q1 Q2 Q3 Q4 |
返回结果
{
"code": "0",
"data": [
{
"result": "true",
"ts": "1646892328000"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| result | String | 是否已经存在该区间的下载链接true：已存在，可以通过"获取返佣明细下载链接"接口获取false：不存在，正在生成，请30个小时后查看下载链接 |
| ts | String | 服务端首次收到请求的时间，Unix时间戳的毫秒数格式，如 1597026383085 |
GET / 获取成交明细（近两年）
获取近2年的历史成交明细信息
限速：10 次/2s
限速规则：UserID
权限：读取
HTTP 请求
GET /api/v5/trade/fills-archive
请求示例
GET /api/v5/trade/fills-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：进行中 |
解压后CSV里的字段说明
| 参数名 | 类型 | 描述 |
|---|---|---|
| instType | String | 产品类型 |
| instId | String | 产品 ID |
| tradeId | String | 最新成交 ID |
| ordId | String | 订单 ID |
| clOrdId | String | 用户自定义订单ID |
| billId | String | 账单 ID |
| tag | String | 订单标签 |
| fillPx | String | 最新成交价格 |
| fillSz | String | 最新成交数量 |
| side | String | 订单方向buy：买sell：卖 |
| posSide | String | 持仓方向long：多short：空买卖模式返回 net |
| execType | String | 流动性方向T：takerM：maker不适用于系统订单比如强平和ADL |
| feeCcy | String | 交易手续费币种或者返佣金币种 |
| fee | String | 手续费金额或者返佣金额 手续费扣除为‘负数’，如 -0.01手续费返佣为‘正数’，如 0.01 |
| ts | String | 成交明细产生时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| subType | 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)
请求参数
无
返回结果
{
"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 | 是 | 兑换的主流币 只选择一个币种，且不能和小币支付币种重复 |
返回结果
{
"code": "0",
"data": [
{
"fillFromSz": "6.5807127",
"fillToSz": "0.17171580105126",
"fromCcy": "ADA",
"status": "running",
"toCcy": "OKB",
"uTime": "1661419684687"
},
{
"fillFromSz": "2.997",
"fillToSz": "0.1683755161661844",
"fromCcy": "USDC",
"status": "running",
"toCcy": "OKB",
"uTime": "1661419684687"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| status | String | 当前兑换进度/状态 running: 进行中 filled: 已完成 failed: 失败 |
| fromCcy | String | 小币支付币种 |
| toCcy | String | 兑换的主流币 |
| fillFromSz | String | 小币偿还币种支付数量 |
| fillToSz | String | 兑换的主流币成交数量 |
| uTime | String | 交易时间戳，Unix时间戳为毫秒数格式，如 1597026383085 |
GET / 获取一键兑换主流币历史记录
查询一键兑换主流币的历史记录与进度状态。
限速：1次/2s
限速规则：UserID
HTTP 请求
GET /api/v5/trade/easy-convert-history
请求示例
GET /api/v5/trade/easy-convert-history
import okx.Trade as Trade
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘: 0, 模拟盘: 1
tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)
# 获取一键兑换主流币历史记录
result = tradeAPI.get_easy_convert_history()
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| after | String | 否 | 查询在此之前的内容，值为时间戳，Unix时间戳为毫秒数格式，如1597026383085 |
| before | String | 否 | 查询在此之后的内容，值为时间戳，Unix时间戳为毫秒数格式，如1597026383085 |
| limit | String | 否 | 返回的结果集数量，默认为100，最大为100 |
返回结果
{
"code": "0",
"data": [
{
"fillFromSz": "0.1761712511667539",
"fillToSz": "6.7342205900000000",
"fromCcy": "OKB",
"status": "filled",
"toCcy": "ADA",
"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 |
POST / 倒计时全部撤单
在倒计时结束后，取消所有挂单。适用于所有撮合交易产品（不包括价差交易）。
限速：1次/s
限速规则：UserID
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 | No | 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的用户，返回当前时间戳 |
WS / 订单频道
获取订单信息，首次订阅不推送，只有当下单、撤单等事件触发时，推送数据
服务地址
/ws/v5/private (需要登录)
请求示例：
{
"op": "subscribe",
"args": [{
"channel": "orders",
"instType": "ANY"
}]
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| op | String | 是 | 操作subscribeunsubscribe |
| args | Array | 是 | 请求订阅的频道列表 |
| > channel | String | 是 | 频道名orders |
| > instType | String | 是 | 产品类型ANY：全部 |
| > instId | String | 否 | 产品ID |
成功返回示例：
{
"event": "subscribe",
"arg": {
"channel": "orders",
"instType": "ANY"
},
"connId": "a4d3ae55"
}
失败返回示例
{
"event": "error",
"code": "60012",
"msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"orders\", \"instType\" : \"FUTURES\"}]}",
"connId": "a4d3ae55"
}
返回参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| event | String | 是 | 事件subscribeunsubscribeerror |
| arg | Object | 否 | 订阅的频道 |
| > channel | String | 是 | 频道名 |
| > instType | String | 是 | 产品类型ANY：全部 |
| > instId | String | 否 | 产品ID |
| code | String | 否 | 错误码 |
| msg | String | 否 | 错误消息 |
| connId | String | 是 | WebSocket连接ID |
推送示例：单个
{
"arg": {
"channel": "orders",
"instType": "ANY",
"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": "",
"uTime": "1654084353264"
}
]
}
推送数据参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| arg | Object | 订阅成功的频道 |
| > channel | String | 频道名 |
| > uid | String | 用户标识 |
| > instType | String | 产品类型 |
| > instFamily | String | 交易品种 |
| > instId | String | 产品ID |
| data | Array | 订阅的数据 |
| > instType | String | 产品类型 |
| > instId | String | 产品ID |
| > ccy | String | 保证金币种，仅适用于现货和合约模式下的全仓币币杠杆订单 |
| > ordId | String | 订单ID |
| > clOrdId | String | 由用户设置的订单ID来识别您的订单 |
| > tag | String | 订单标签 |
| > px | String | 委托价格，对于期权，以币(如BTC, ETH)为单位 |
| > pxUsd | String | 期权价格，以USD为单位 仅适用于期权，其他业务线返回空字符串"" |
| > pxVol | String | 期权订单的隐含波动率 仅适用于期权，其他业务线返回空字符串"" |
| > pxType | String | 期权的价格类型 px：代表按价格下单，单位为币 (请求参数 px 的数值单位是BTC或ETH) pxVol：代表按pxVol下单 pxUsd：代表按照pxUsd下单，单位为USD (请求参数px 的数值单位是USD) |
| > sz | String | 原始委托数量，币币/币币杠杆，以币为单位；交割/永续/期权 ，以张为单位 |
| > notionalUsd | String | 委托单预估美元价值 |
| > fillNotionalUsd | String | 委托单已成交的美元价值 |
| > ordType | String | 订单类型 market：市价单 limit：限价单 post_only：只做maker单 fok：全部成交或立即取消单ioc：立即成交并取消剩余单 optimal_limit_ioc：市价委托立即成交并取消剩余（仅适用交割、永续）mmp：做市商保护(仅适用于组合保证金账户模式下的期权订单)mmp_and_post_only：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单) op_fok：期权简选（全部成交或立即取消） |
| > side | String | 订单方向，buy sell |
| > posSide | String | 持仓方向long：开平仓模式开多short：开平仓模式开空net：买卖模式 |
| > tdMode | String | 交易模式 保证金模式 isolated：逐仓 cross：全仓 非保证金模式 cash：现金 |
| > tgtCcy | String | 市价单委托数量sz的单位base_ccy: 交易货币 quote_ccy：计价货币 |
| > fillPx | String | 最新成交价格 |
| > tradeId | String | 最新成交ID |
| > fillSz | String | 最新成交数量 对于 币币和杠杆，单位为交易货币，如 BTC-USDT, 单位为 BTC；对于市价单，无论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 |
| >> tpTriggerPx | String | 止盈触发价 |
| >> tpTriggerPxType | String | 止盈触发价类型last：最新价格index：指数价格mark：标记价格 |
| >> tpOrdPx | String | 止盈委托价 |
| >> slTriggerPx | String | 止损触发价 |
| >> slTriggerPxType | String | 止损触发价类型last：最新价格index：指数价格mark：标记价格 |
| >> slOrdPx | String | 止损委托价 |
| >> sz | String | 张数。仅适用于“多笔止盈”的止盈订单 |
| >> amendPxOnTriggerType | String | 是否启用开仓价止损，仅适用于分批止盈的止损订单0：不开启，默认值 1：开启 |
| > stpId | String | 如果自成交保护不适用则返回"" |
| > stpMode | String | 自成交保护模式 |
| > feeCcy | String | 交易手续费币种 币币/币币杠杆：如果是买的话，收取的就是交易币；如果是卖的话，收取的就是计价币。交割/永续/期权 收取的就是保证金 |
| > fee | String | 订单交易累计的手续费与返佣 对于币币和杠杆，为订单交易累计的手续费，平台向用户收取的交易手续费，为负数。如： -0.01 对于交割、永续和期权，为订单交易累计的手续费和返佣 |
| > rebateCcy | String | 返佣金币种 ，如果没有返佣金，该字段为“” |
| > rebate | String | 返佣累计金额，仅适用于币币和杠杆，平台向达到指定lv交易等级的用户支付的挂单奖励（返佣），如果没有返佣金，该字段为“” |
| > pnl | String | 收益，适用于有成交的平仓订单，其他情况均为0 对于合约全仓爆仓，将包含相应强平惩罚金 |
| > source | String | 订单来源6：计划委托策略触发后的生成的普通单7：止盈止损策略触发后的生成的普通单13：策略委托单触发后的生成的普通单25：移动止盈止损策略触发后的生成的普通单 |
| > 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 订单匹配的订单数量超过最大限制 |
| > amendSource | String | 订单修改的来源1: 用户主动改单，改单成功2: 用户主动改单，并且当前这笔订单被只减仓修改，改单成功3: 用户主动下单，并且当前这笔订单被只减仓修改，改单成功4: 用户当前已存在的挂单（非当前操作的订单），被只减仓修改，改单成功5：期权 px, pxVol 或 pxUsd 的跟随变动导致的改单，比如 iv=60，USD，px 锚定iv=60 时，USD, px 产生变动时的改单 |
| > category | String | 订单种类分类normal：普通委托订单种类 twap：TWAP订单种类adl：ADL订单种类full_liquidation：爆仓订单种类partial_liquidation：减仓订单种类delivery：交割ddh：对冲减仓类型订单 |
| > uTime | String | 订单更新时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| > cTime | String | 订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| > reqId | String | 修改订单时使用的request ID，如果没有修改，该字段为"" |
| > amendResult | String | 修改订单的结果-1：失败0：成功1：自动撤单（修改请求返回成功但最终改单失败导致自动撤销）2: 自动改单成功，仅适用于期权pxUsd和pxVol订单的自动改单 通过API修改订单时，如果 cxlOnFail设置为true且修改返回结果为失败时，则返回 ""通过API修改订单时，如果修改返回结果为成功但修改最终失败后，当 cxlOnFail设置为false时返回 -1;当cxlOnFail设置为true时则返回1通过Web/APP修改订单时，如果修改失败后，则返回 -1 |
| > reduceOnly | String | 是否只减仓，true 或 false |
| > quickMgnType | String | 一键借币类型，仅适用于杠杆逐仓的一键借币模式manual：手动，auto_borrow：自动借币，auto_repay：自动还币 |
| > algoClOrdId | String | 客户自定义策略订单ID。策略订单触发，且策略单有algoClOrdId时有值，否则为"", |
| > algoId | String | 策略委托单ID，策略订单触发时有值，否则为"" |
| > lastPx | String | 最新成交价 |
| > code | String | 错误码，默认为0 |
| > msg | String | 错误消息，默认为"" |
WS / 下单
只有当您的账户有足够的资金才能下单。一旦下单，您的账户资金将在订单生命周期内被冻结。被冻结的资金以及数量取决于订单指定的类型和参数
限速：60次/2s
限速规则：UserID + Instrument ID
请求示例
{
"id": "1512",
"op": "order",
"args": [{
"side": "buy",
"instId": "BTC-USDT",
"tdMode": "cash",
"ordType": "market",
"sz": "100"
}]
}
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| id | String | 是 | 消息的唯一标识 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。 |
| op | String | 是 | 支持的业务操作order |
| args | Array | 是 | 请求参数 |
| > instId | String | 是 | 产品ID，如 BTC-USDT |
| > tdMode | String | 是 | 交易模式cash：现金 |
| > clOrdId | String | 否 | 由用户设置的订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 |
| > tag | String | 否 | 订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-16位之间。 |
| > side | String | 是 | 订单方向buysell |
| > ordType | String | 是 | 订单类型market：市价单limit：限价单 post_only：只做maker单fok：全部成交或立即取消ioc：立即成交并取消剩余 |
| > sz | String | 是 | 委托数量 |
| > px | String | 可选 | 委托价格，仅适用于limit、post_only、fok、ioc类型的订单 |
| > tgtCcy | String | 否 | 币币市价单委托数量sz的单位base_ccy: 交易货币quote_ccy：计价货币仅适用于 币币市价订单默认买单为 quote_ccy，卖单为base_ccy |
| > banAmend | Boolean | 否 | 是否禁止币币市价改单，true 或 false，默认false 为true时，余额不足时，系统不会改单，下单会失败，仅适用于币币市价单 |
| > stpId | String | 否 | 用户自定义1<=x<=999999999的整数 |
| > stpMode | String | 否 | 自成交保护模式 默认为 cancel maker cancel_maker,cancel_taker,cancel_bothCancel both不支持FOK |
| expTime | String | 否 | 请求有效截止时间。Unix时间戳的毫秒数格式，如 1597026383085 |
成功返回示例
{
"id": "1512",
"op": "order",
"data": [{
"clOrdId": "",
"ordId": "12345689",
"tag": "",
"sCode": "0",
"sMsg": ""
}],
"code": "0",
"msg": "",
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
失败返回示例
{
"id": "1512",
"op": "order",
"data": [{
"clOrdId": "",
"ordId": "",
"tag": "",
"sCode": "5XXXX",
"sMsg": "not exist"
}],
"code": "1",
"msg": "",
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
格式错误返回示例
{
"id": "1512",
"op": "order",
"data": [],
"code": "60013",
"msg": "Invalid args",
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| id | String | 消息的唯一标识 |
| op | String | 业务操作 |
| code | String | 代码 |
| msg | String | 消息 |
| data | Array | 请求成功后返回的数据 |
| > ordId | String | 订单ID |
| > clOrdId | String | 由用户设置的订单ID |
| > tag | String | 订单标签 |
| > sCode | String | 订单状态码，0 代表成功 |
| > sMsg | String | 订单状态消息 |
| inTime | String | WebSocket 网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
| outTime | String | WebSocket 网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
WS / 批量下单
批量进行下单操作，每次可批量交易不同类型的产品，最多可下单20个
限速：300个/2s
限速规则：UserID + Instrument ID
请求示例
{
"id": "1513",
"op": "batch-orders",
"args": [{
"side": "buy",
"instId": "BTC-USDT",
"tdMode": "cash",
"ordType": "market",
"sz": "100"
}, {
"side": "buy",
"instId": "BTC-USD-200925",
"tdMode": "cash",
"ordType": "limit",
"sz": "1"
}]
}
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| id | String | 是 | 消息的唯一标识 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。 |
| op | String | 是 | 支持的业务操作batch-orders |
| args | Array | 是 | 请求参数 |
| > instId | String | 是 | 产品ID，如 BTC-USDT |
| > tdMode | String | 否 | 交易模式cash：现金 |
| > clOrdId | String | 否 | 用户提供的订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 |
| > tag | String | 否 | 订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-16位之间。 |
| > side | String | 是 | 订单方向buysell |
| > ordType | String | 是 | 订单类型market：市价单 limit：限价单post_only：只做maker单 fok：全部成交或立即取消单 ioc：立即成交并取消剩余单 |
| > sz | String | 是 | 委托数量 |
| > px | String | 可选 | 委托价格，仅适用于limit、post_only、fok、ioc类型的订单 |
| > tgtCcy | String | 否 | 币币市价单委托数量sz的单位base_ccy: 交易货币 ；quote_ccy：计价货币仅适用于 币币市价订单默认买单为 quote_ccy，卖单为base_ccy |
| > banAmend | Boolean | 否 | 是否禁止币币市价改单，true 或 false，默认false 为true时，余额不足时，系统不会改单，下单会失败，仅适用于币币市价单 |
| > stpId | String | 否 | 用户自定义1<=x<=999999999的整数 |
| > stpMode | String | 否 | 自成交保护模式 默认为 cancel maker cancel_maker,cancel_taker, cancel_bothCancel both不支持FOK |
| expTime | String | 否 | 请求有效截止时间。Unix时间戳的毫秒数格式，如 1597026383085 |
全部成功返回示例
{
"id": "1513",
"op": "batch-orders",
"data": [{
"clOrdId": "",
"ordId": "12345689",
"tag": "",
"sCode": "0",
"sMsg": ""
}, {
"clOrdId": "",
"ordId": "12344",
"tag": "",
"sCode": "0",
"sMsg": ""
}],
"code": "0",
"msg": "",
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
部分成功返回示例
{
"id": "1513",
"op": "batch-orders",
"data": [{
"clOrdId": "",
"ordId": "12345689",
"tag": "",
"sCode": "0",
"sMsg": ""
}, {
"clOrdId": "",
"ordId": "",
"tag": "",
"sCode": "5XXXX",
"sMsg": "Insufficient margin"
}],
"code": "2",
"msg": "",
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
全部失败返回示例
{
"id": "1513",
"op": "batch-orders",
"data": [{
"clOrdId": "oktswap6",
"ordId": "",
"tag": "",
"sCode": "5XXXX",
"sMsg": "Insufficient margin"
}, {
"clOrdId": "oktswap7",
"ordId": "",
"tag": "",
"sCode": "5XXXX",
"sMsg": "Insufficient margin"
}],
"code": "1",
"msg": "",
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
格式错误返回示例
{
"id": "1513",
"op": "batch-orders",
"data": [],
"code": "60013",
"msg": "Invalid args",
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
返回参数
| 参数 | 类型 | 描述 |
|---|---|---|
| id | String | 消息的唯一标识 |
| op | String | 业务操作 |
| code | String | 代码 |
| msg | String | 消息 |
| data | Array | 请求成功后返回的数据 |
| > ordId | String | 订单ID |
| > clOrdId | String | 由用户设置的订单ID |
| > tag | String | 订单标签 |
| > sCode | String | 订单状态码，0 代表成功 |
| > sMsg | String | 事件执行失败或成功时的msg |
| inTime | String | WebSocket 网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
| outTime | String | WebSocket 网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
WS / 撤单
撤销当前未完成订单
限速：60次/2s
限速规则：UserID + Instrument ID
请求示例
{
"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 | 可选 | 订单IDordId和clOrdId必须传一个，若传两个，以ordId为主 |
| > clOrdId | String | 可选 | 用户提供的订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度要在1-32位之间。 |
成功返回示例
{
"id": "1514",
"op": "cancel-order",
"data": [{
"clOrdId": "",
"ordId": "2510789768709120",
"sCode": "0",
"sMsg": ""
}],
"code": "0",
"msg": "",
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
失败返回示例
{
"id": "1514",
"op": "cancel-order",
"data": [{
"clOrdId": "",
"ordId": "2510789768709120",
"sCode": "5XXXX",
"sMsg": "Order not exist"
}],
"code": "1",
"msg": "",
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
格式错误返回示例
{
"id": "1514",
"op": "cancel-order",
"data": [],
"code": "60013",
"msg": "Invalid args",
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
返回参数
| 参数 | 类型 | 描述 |
|---|---|---|
| id | String | 消息的唯一标识 |
| op | String | 业务操作 |
| code | String | 代码 |
| msg | String | 消息 |
| data | Array | 请求成功后返回的数据 |
| > ordId | String | 订单ID |
| > clOrdId | String | 由用户设置的订单ID |
| > sCode | String | 订单状态码，0 代表成功 |
| > sMsg | String | 订单状态消息 |
| inTime | String | WebSocket 网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
| outTime | String | WebSocket 网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
WS / 批量撤单
批量进行撤单操作，每次可批量撤销不同类型的产品，最多撤销20个
限速：300个/2s
限速规则：UserID + Instrument ID
请求示例
{
"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 | 可选 | 订单IDordId和clOrdId必须传一个，若传两个，以ordId为主 |
| > clOrdId | String | 可选 | 用户提供的订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度要在1-32位之间。 |
全部成功返回示例
{
"id": "1515",
"op": "batch-cancel-orders",
"data": [{
"clOrdId": "oktswap6",
"ordId": "2517748157541376",
"sCode": "0",
"sMsg": ""
}, {
"clOrdId": "oktswap7",
"ordId": "2517748155771904",
"sCode": "0",
"sMsg": ""
}],
"code": "0",
"msg": "",
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
部分成功的返回示例
{
"id": "1515",
"op": "batch-cancel-orders",
"data": [{
"clOrdId": "oktswap6",
"ordId": "2517748157541376",
"sCode": "0",
"sMsg": ""
}, {
"clOrdId": "oktswap7",
"ordId": "2517748155771904",
"sCode": "5XXXX",
"sMsg": "order not exist"
}],
"code": "2",
"msg": "",
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
全部失败的返回示例
{
"id": "1515",
"op": "batch-cancel-orders",
"data": [{
"clOrdId": "oktswap6",
"ordId": "2517748157541376",
"sCode": "5XXXX",
"sMsg": "order not exist"
}, {
"clOrdId": "oktswap7",
"ordId": "2517748155771904",
"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 |
| > sCode | String | 订单状态码，0 代表成功 |
| > sMsg | String | 订单状态消息 |
| inTime | String | WebSocket 网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
| outTime | String | WebSocket 网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
WS / 改单
修改当前未成交的订单
限速：60次/2s
限速规则：UserID + Instrument ID
请求示例
{
"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 | 否 | 当订单修改失败时，该订单是否需要自动撤销。默认为falsefalse：不自动撤单true：自动撤单 |
| > ordId | String | 可选 | 订单ID ordId和clOrdId必须传一个，若传两个，以 ordId为主 |
| > clOrdId | String | 可选 | 用户提供的订单ID |
| > reqId | String | 否 | 用户提供的reqId 如果提供，那在返回参数中返回reqId，方便找到相应的修改请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 |
| > newSz | String | 可选 | 请求修改的新数量newSz和newPx不可同时为空。对于部分成交订单，该数量应包含已成交数量。 |
| > newPx | String | 可选 | 修改后的新价格 |
| expTime | String | 否 | 请求有效截止时间。Unix时间戳的毫秒数格式，如 1597026383085 |
成功返回示例
{
"id": "1512",
"op": "amend-order",
"data": [{
"clOrdId": "",
"ordId": "2510789768709120",
"reqId": "b12344",
"sCode": "0",
"sMsg": ""
}],
"code": "0",
"msg": "",
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
失败返回示例
{
"id": "1512",
"op": "amend-order",
"data": [{
"clOrdId": "",
"ordId": "2510789768709120",
"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 |
| > reqId | String | 用户提供的reqId 如果用户在请求中提供reqId，则返回相应reqId |
| > sCode | String | 订单状态码，0 代表成功 |
| > sMsg | String | 订单状态消息 |
| inTime | String | WebSocket 网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
| outTime | String | WebSocket 网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
WS / 批量改单
批量进行改单操作，每次可批量修改不同类型的产品，最多改20个
限速：300个/2s
限速规则：UserID + Instrument ID
请求示例
{
"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 | 否 | 当订单修改失败时，该订单是否需要自动撤销。默认为falsefalse：不自动撤单true：自动撤单 |
| > ordId | String | 可选 | 订单IDordId和clOrdId必须传一个，若传两个，以ordId为主 |
| > clOrdId | String | 可选 | 用户提供的订单ID |
| > reqId | String | 否 | 用户提供的请求ID 如果提供，那在返回参数中返回reqId，方便找到相应的修改请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 |
| > newSz | String | 可选 | 修改后的新数量newSz和newPx不可同时为空。对于部分成交订单，该数量应包含已成交数量。 |
| > newPx | String | 可选 | 修改后的新价格 |
| expTime | String | 否 | 请求有效截止时间。Unix时间戳的毫秒数格式，如 1597026383085 |
全部成功返回示例
{
"id": "1513",
"op": "batch-amend-orders",
"data": [{
"clOrdId": "oktswap6",
"ordId": "12345689",
"reqId": "b12344",
"sCode": "0",
"sMsg": ""
}, {
"clOrdId": "oktswap7",
"ordId": "12344",
"reqId": "b12344",
"sCode": "0",
"sMsg": ""
}],
"code": "0",
"msg": "",
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
全部失败返回示例
{
"id": "1513",
"op": "batch-amend-orders",
"data": [{
"clOrdId": "",
"ordId": "12345689",
"reqId": "b12344",
"sCode": "5XXXX",
"sMsg": "order not exist"
}, {
"clOrdId": "oktswap7",
"ordId": "",
"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",
"reqId": "b12344",
"sCode": "0",
"sMsg": ""
}, {
"clOrdId": "oktswap7",
"ordId": "",
"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 |
| > reqId | String | 用户提供的请求ID 如果用户在请求中提供reqId，则返回相应reqId |
| > sCode | String | 订单状态码，0 代表成功 |
| > sMsg | String | 订单状态消息 |
| inTime | String | WebSocket 网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
| outTime | String | WebSocket 网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
策略交易
POST / 策略委托下单
提供单向止盈止损委托、双向止盈止损委托、计划委托、移动止盈止损委托
限速：20次/2s
限速规则：UserID + Instrument ID
HTTP请求
POST /api/v5/trade/order-algo
请求示例
# 止盈止损策略下单
POST /api/v5/trade/order-algo
body
{
"instId":"BTC-USDT",
"tdMode":"cash",
"side":"buy",
"ordType":"conditional",
"sz":"2",
"tpTriggerPx":"15",
"tpOrdPx":"18"
}
# 计划委托策略下单
POST /api/v5/trade/order-algo
body
{
"instId": "BTC-USDT",
"tdMode": "cash",
"side": "buy",
"ordType": "trigger",
"sz": "10",
"triggerPx": "100",
"orderPx": "-1"
}
# 移动止盈止损策略下单
POST /api/v5/trade/order-algo
body
{
"instId": "BTC-USDT",
"tdMode": "cash",
"side": "buy",
"ordType": "move_order_stop",
"sz": "10",
"callbackRatio": "0.05"
}
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 | 是 | 交易模式cash：非保证金 |
| side | String | 是 | 订单方向buy：买sell：卖 |
| ordType | String | 是 | 订单类型conditional：单向止盈止损oco：双向止盈止损trigger：计划委托move_order_stop：移动止盈止损 |
| sz | String | 是 | 委托数量 |
| tgtCcy | String | 否 | 委托数量的类型base_ccy: 交易货币 ；quote_ccy：计价货币仅适用于 币币单向止盈止损市价买单默认买为 计价货币，卖为交易货币 |
| algoClOrdId | String | 否 | 客户自定义策略订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 |
| tag | String | 否 | 订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间 |
止盈止损
了解更多 止盈止损
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| tpTriggerPx | String | 否 | 止盈触发价，如果填写此参数，必须填写止盈委托价 |
| tpTriggerPxType | String | 否 | 止盈触发价类型last：最新价格默认为 last |
| tpOrdPx | String | 否 | 止盈委托价，如果填写此参数，必须填写止盈触发价 委托价格为-1时，执行市价止盈 |
| slTriggerPx | String | 否 | 止损触发价，如果填写此参数，必须填写止损委托价 |
| slTriggerPxType | String | 否 | 止损触发价类型last：最新价格默认为 last |
| slOrdPx | String | 否 | 止损委托价，如果填写此参数，必须填写止损触发价 委托价格为 -1时，执行市价止损 |
计划委托
了解更多 计划委托
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| triggerPx | String | 是 | 计划委托触发价格 |
| orderPx | String | 是 | 委托价格 委托价格为 -1时，执行市价委托 |
| triggerPxType | String | 否 | 计划委托触发价格类型last：最新价格默认为 last |
移动止盈止损
了解更多 移动止盈止损
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| callbackRatio | String | 可选 | 回调幅度的比例，如 "0.05"代表"5%"callbackRatio和callbackSpread只能传入一个 |
| callbackSpread | String | 可选 | 回调幅度的价距 |
| activePx | String | 否 | 激活价格 激活价格是移动止盈止损的激活条件，当市场最新成交价达到或超过激活价格，委托被激活。激活后系统开始计算止盈止损的实际触发价格。如果不填写激活价格，即下单后就被激活。 |
返回结果
{
"code":"0",
"msg":"",
"data":[
{
"algoId":"12345689",
"clOrdId": "",
"algoClOrdId": "",
"sCode":"0",
"sMsg":"",
"tag":""
}
]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| algoId | String | 策略委托单ID |
| clOrdId | String | |
| algoClOrdId | String | 客户自定义策略订单ID |
| sCode | String | 事件执行结果的code，0代表成功 |
| sMsg | String | 事件执行失败时的msg |
| tag | String | 订单标签 |
POST / 撤销策略委托订单
撤销除了策略委托订单，每次最多可以撤销10个策略委托单
限速：20次/2s
限速规则：UserID + Instrument ID
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",
"msg":"",
"data":[
{
"algoId":"1234",
"sCode":"0",
"sMsg":""
}
]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| algoId | String | 订单ID |
| sCode | String | 事件执行结果的code，0代表成功 |
| sMsg | String | 事件执行失败时的msg |
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 | 可选 | 策略委托单IDalgoId和algoClOrdId必须传一个，若传两个，以algoId为主 |
| algoClOrdId | String | 可选 | 客户自定义策略订单IDalgoId和algoClOrdId必须传一个，若传两个，以algoId为主 |
| cxlOnFail | Boolean | 否 | 当订单修改失败时，该订单是否需要自动撤销。默认为falsefalse：不自动撤单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：标记价格 |
返回结果
{
"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 |
GET / 获取策略委托单信息
限速：20次/2s
限速规则：UserID
HTTP请求
GET /api/v5/trade/order-algo
请求示例
GET /api/v5/trade/order-algo?algoId=1753184812254216192
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| algoId | String | 可选 | 策略委托单IDalgoId和algoClOrdId必须传一个，若传两个，以algoId为主 |
| algoClOrdId | String | 可选 | 客户自定义策略订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 |
返回结果
{
"code": "0",
"data": [
{
"activePx": "",
"actualPx": "",
"actualSide": "",
"actualSz": "",
"algoClOrdId": "",
"algoId": "681187161907138560",
"amendPxOnTriggerType": "",
"attachAlgoOrds": [],
"cTime": "1708679675244",
"uTime": "1708679675245",
"callbackRatio": "0.05",
"callbackSpread": "",
"ccy": "",
"clOrdId": "",
"closeFraction": "",
"failCode": "",
"instId": "BTC-USDT",
"instType": "SPOT",
"last": "50962.7",
"lever": "",
"linkedOrd": {
"ordId": ""
},
"moveTriggerPx": "53423.160",
"ordId": "",
"ordIdList": [],
"ordPx": "",
"ordType": "move_order_stop",
"posSide": "net",
"pxLimit": "",
"pxSpread": "",
"pxVar": "",
"quickMgnType": "",
"reduceOnly": "false",
"side": "buy",
"slOrdPx": "",
"slTriggerPx": "",
"slTriggerPxType": "",
"state": "live",
"sz": "10",
"szLimit": "",
"tag": "",
"tdMode": "cash",
"tgtCcy": "",
"timeInterval": "",
"tpOrdPx": "",
"tpTriggerPx": "",
"tpTriggerPxType": "",
"triggerPx": "",
"triggerPxType": "",
"triggerTime": "",
"isTradeBorrowMode": "true"
}
],
"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：不自动借币 仅适用于计划委托、移动止盈止损和 时间加权策略 |
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：币币 |
| instId | String | 否 | 产品ID，BTC-USDT |
| ordType | String | 是 | 订单类型conditional：单向止盈止损oco：双向止盈止损 trigger：计划委托move_order_stop：移动止盈止损 |
| after | String | 否 | 请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的algoId |
| before | String | 否 | 请求此ID之后（更新的数据）的分页内容，传的值为对应接口的algoId |
| limit | String | 否 | 返回结果的数量，最大为100，默认100条 |
| algoClOrdId | String | 否 | 客户自定义策略订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 |
返回结果
{
"code": "0",
"data": [
{
"activePx": "",
"actualPx": "",
"actualSide": "buy",
"actualSz": "0",
"algoClOrdId": "",
"algoId": "681096944655273984",
"amendPxOnTriggerType": "",
"attachAlgoOrds": [],
"cTime": "1708658165774",
"callbackRatio": "",
"callbackSpread": "",
"ccy": "",
"clOrdId": "",
"closeFraction": "",
"failCode": "",
"instId": "BTC-USDT",
"instType": "SPOT",
"last": "51014.6",
"lever": "",
"moveTriggerPx": "",
"ordId": "",
"ordIdList": [],
"ordPx": "-1",
"ordType": "trigger",
"posSide": "net",
"pxLimit": "",
"pxSpread": "",
"pxVar": "",
"quickMgnType": "",
"reduceOnly": "false",
"side": "buy",
"slOrdPx": "",
"slTriggerPx": "",
"slTriggerPxType": "",
"state": "live",
"sz": "10",
"szLimit": "",
"tag": "",
"tdMode": "cash",
"tgtCcy": "",
"timeInterval": "",
"tpOrdPx": "",
"tpTriggerPx": "",
"tpTriggerPxType": "",
"triggerPx": "100",
"triggerPxType": "last",
"triggerTime": "0"
}
],
"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：标记价格默认为 last |
| > tpOrdPx | String | 止盈委托价，如果填写此参数，必须填写止盈触发价委托价格为 -1时，执行市价止盈 |
| > slTriggerPx | String | 止损触发价，如果填写此参数，必须填写止损委托价 |
| > slTriggerPxType | String | 止损触发价类型last：最新价格index：指数价格mark：标记价格默认为 last |
| > slOrdPx | String | 止损委托价，如果填写此参数，必须填写止损触发价委托价格为 -1时，执行市价止损 |
| cTime | String | 订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085 |
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：双向止盈止损trigger：计划委托move_order_stop：移动止盈止损 |
| state | String | 可选 | 订单状态effective：已生效canceled：已经撤销order_failed：委托失败state和algoId必填且只能填其一 |
| algoId | String | 可选 | 策略委托单ID |
| instType | String | 否 | 产品类型SPOT：币币 |
| instId | String | 否 | 产品ID，BTC-USDT |
| after | String | 否 | 请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的algoId |
| before | String | 否 | 请求此ID之后（更新的数据）的分页内容，传的值为对应接口的algoId |
| limit | String | 否 | 返回结果的数量，最大为100，默认100条 |
返回结果
{
"code": "0",
"data": [
{
"activePx": "",
"actualPx": "",
"actualSide": "buy",
"actualSz": "0",
"algoClOrdId": "",
"algoId": "681096944655273984",
"amendPxOnTriggerType": "",
"attachAlgoOrds": [],
"cTime": "1708658165774",
"callbackRatio": "",
"callbackSpread": "",
"ccy": "",
"clOrdId": "",
"closeFraction": "",
"failCode": "",
"instId": "BTC-USDT",
"instType": "SPOT",
"last": "51014.6",
"lever": "",
"moveTriggerPx": "",
"ordId": "",
"ordIdList": [],
"ordPx": "-1",
"ordType": "trigger",
"posSide": "net",
"pxLimit": "",
"pxSpread": "",
"pxVar": "",
"quickMgnType": "",
"reduceOnly": "false",
"side": "buy",
"slOrdPx": "",
"slTriggerPx": "",
"slTriggerPxType": "",
"state": "canceled",
"sz": "10",
"szLimit": "",
"tag": "",
"tdMode": "cash",
"tgtCcy": "",
"timeInterval": "",
"tpOrdPx": "",
"tpTriggerPx": "",
"tpTriggerPxType": "",
"triggerPx": "100",
"triggerPxType": "last",
"triggerTime": ""
}
],
"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：标记价格默认为 last |
| > tpOrdPx | String | 止盈委托价，如果填写此参数，必须填写止盈触发价委托价格为 -1时，执行市价止盈 |
| > slTriggerPx | String | 止损触发价，如果填写此参数，必须填写止损委托价 |
| > slTriggerPxType | String | 止损触发价类型last：最新价格index：指数价格mark：标记价格默认为 last |
| > slOrdPx | String | 止损委托价，如果填写此参数，必须填写止损触发价委托价格为 -1时，执行市价止损 |
| cTime | String | 订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085 |
WS / 策略委托订单频道
获取策略委托订单，首次订阅不推送，只有当下单、撤单等事件触发时，推送数据
服务地址
/ws/v5/business (需要登录)
请求示例：单个
{
"op": "subscribe",
"args": [{
"channel": "orders-algo",
"instType": "SPOT"
}]
}
请求示例
{
"op": "subscribe",
"args": [{
"channel": "orders-algo",
"instType": "SPOT"
}]
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| op | String | 是 | 操作subscribeunsubscribe |
| args | Array | 是 | 请求订阅的频道列表 |
| > channel | String | 是 | 频道名orders-algo |
| > instType | String | 是 | 产品类型SPOT：币币ANY：全部 |
| > instId | String | 否 | 产品ID |
成功返回示例：单个
{
"event": "subscribe",
"arg": {
"channel": "orders-algo",
"instType": "SPOT"
},
"connId": "a4d3ae55"
}
成功返回示例
{
"event": "subscribe",
"arg": {
"channel": "orders-algo",
"instType": "SPOT"
},
"connId": "a4d3ae55"
}
失败返回示例
{
"event": "error",
"code": "60012",
"msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"orders-algo\", \"instType\" : \"FUTURES\"}]}",
"connId": "a4d3ae55"
}
返回参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| event | String | 是 | 事件subscribeunsubscribeerror |
| arg | Object | 否 | 订阅的频道 |
| > channel | String | 是 | 频道名 |
| > instType | String | 是 | 产品类型SPOT：币币ANY：全部 |
| > instId | String | 否 | 产品ID |
| code | String | 否 | 错误码 |
| msg | String | 否 | 错误消息 |
| connId | String | 是 | WebSocket连接ID |
推送示例：单个
{
"arg": {
"channel": "orders-algo",
"uid": "77982378738415879",
"instType": "SPOT"
},
"data": [{
"actualPx": "0",
"actualSide": "",
"actualSz": "0",
"algoClOrdId": "",
"algoId": "581878926302093312",
"attachAlgoOrds": [],
"amendResult": "",
"cTime": "1685002746818",
"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"
}]
}
推送数据参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| 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 | 订单方向buysell |
| > 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：部分委托失败 |
| > 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 |
| > cTime | String | 订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| > 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：标记价格默认为 last |
| >> tpOrdPx | String | 止盈委托价，如果填写此参数，必须填写止盈触发价委托价格为 -1时，执行市价止盈 |
| >> slTriggerPx | String | 止损触发价，如果填写此参数，必须填写止损委托价 |
| >> slTriggerPxType | String | 止损触发价类型last：最新价格index：指数价格mark：标记价格默认为 last |
| >> slOrdPx | String | 止损委托价，如果填写此参数，必须填写止损触发价委托价格为 -1时，执行市价止损 |
行情数据
行情数据功能模块下的API接口不需要身份验证。
GET / 获取所有产品行情信息
获取产品行情信息
限速：20次/2s
限速规则：IP
HTTP请求
GET /api/v5/market/tickers
请求示例
GET /api/v5/market/tickers?instType=SPOT
import okx.MarketData as MarketData
flag = "0" # 实盘:0 , 模拟盘：1
marketDataAPI = MarketData.MarketAPI(flag=flag)
# 获取所有产品行情信息
result = marketDataAPI.get_tickers(
instType="SPOT"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 是 | 产品类型SPOT：币币 |
返回结果
{
"code":"0",
"msg":"",
"data":[
{
"instType": "SPOT",
"instId": "BTC-USDT",
"last": "51230",
"lastSz": "0.18531491",
"askPx": "51229.4",
"askSz": "2.1683067",
"bidPx": "51229.3",
"bidSz": "0.28249897",
"open24h": "51635.7",
"high24h": "52080",
"low24h": "50936",
"volCcy24h": "539658490.410419122",
"vol24h": "10476.2229261",
"ts": "1708669508505",
"sodUtc0": "51290.1",
"sodUtc8": "51602.4"
}
]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instType | String | 产品类型 |
| instId | String | 产品ID |
| last | String | 最新成交价 |
| lastSz | String | 最新成交的数量 |
| 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-USDT
import okx.MarketData as MarketData
flag = "0" # 实盘:0 , 模拟盘：1
marketDataAPI = MarketData.MarketAPI(flag=flag)
# 获取单个产品行情信息
result = marketDataAPI.get_ticker(
instId="BTC-USDT"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 是 | 产品ID，如 BTC-USDT |
返回结果
{
"code": "0",
"msg": "",
"data": [
{
"instType": "SPOT",
"instId": "BTC-USDT",
"last": "51240",
"lastSz": "0.49011124",
"askPx": "51240",
"askSz": "0.64278176",
"bidPx": "51239.9",
"bidSz": "1.68139044",
"open24h": "51695.6",
"high24h": "52080",
"low24h": "50936",
"volCcy24h": "539533972.680195094",
"vol24h": "10474.12353007",
"ts": "1708669925904",
"sodUtc0": "51290.1",
"sodUtc8": "51602.4"
}
]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instType | String | 产品类型 |
| instId | String | 产品ID |
| last | String | 最新成交价 |
| lastSz | String | 最新成交的数量 |
| 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 / 获取交易产品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单位是USDT |
| 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单位是USDT。 |
| 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 / 获取平台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 | 接口返回数据时间 |
WS / 行情频道
获取产品的最新成交价、买一价、卖一价和24小时交易量等信息。
最快100ms推送一次，没有触发事件时不推送，触发推送的事件有：成交、买一卖一发生变动。
服务地址
/ws/v5/public
请求示例
{
"op": "subscribe",
"args": [{
"channel": "tickers",
"instId": "BTC-USDT"
}]
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| op | String | 是 | 操作subscribeunsubscribe |
| 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 | 是 | 事件subscribeunsubscribeerror |
| 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 | 最新成交的数量 |
| > 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秒推送一次数据。
服务地址
/ws/v5/business
请求示例
{
"op": "subscribe",
"args": [{
"channel": "candle1D",
"instId": "BTC-USDT"
}]
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| op | String | 是 | 操作subscribeunsubscribe |
| args | Array | 是 | 请求订阅的频道列表 |
| > channel | String | 是 | 频道名candle3Mcandle1Mcandle1Wcandle1Dcandle2Dcandle3Dcandle5Dcandle12Hcandle6Hcandle4Hcandle2Hcandle1Hcandle30mcandle15mcandle5mcandle3mcandle1mcandle1scandle3Mutccandle1Mutccandle1Wutccandle1Dutccandle2Dutccandle3Dutccandle5Dutccandle12Hutccandle6Hutc |
| > 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 | 是 | 事件subscribeunsubscribeerror |
| 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单位是USDT。 |
| > 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 | 是 | 操作subscribeunsubscribe |
| 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 | 是 | 事件subscribeunsubscribeerror |
| 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 | 成交方向buysell |
| > ts | String | 成交时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| > count | String | 聚合的订单匹配数量 |
WS / 全部交易频道
获取最近的成交数据，有成交数据就推送，每次推送仅包含一条成交数据。
URL Path
/ws/v5/business
请求示例
{
"op": "subscribe",
"args": [{
"channel": "trades-all",
"instId": "BTC-USDT"
}]
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| op | String | 是 | 操作subscribeunsubscribe |
| 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 | 是 | 事件subscribeunsubscribeerror |
| 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 | 成交方向buysell |
| > 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 | 是 | 操作subscribeunsubscribe |
| args | Array | 是 | 请求订阅的频道列表 |
| > channel | String | 是 | 频道名booksbooks5bbo-tbtbooks-l2-tbtbooks50-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 | 是 | 事件subscribeunsubscribeerror |
| 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
}
]
}
公共数据
公共数据功能模块下的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：币币 |
| instId | String | 否 | 产品ID |
返回结果
{
"code":"0",
"msg":"",
"data":[
{
"alias": "",
"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",
"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 |
| 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：预上线，如：交割和期权的新合约在 live 之前，会有 preopen 状态test：测试中（测试产品，不可交易） |
| maxLmtSz | String | 限价单的单笔最大委托数量 合约的数量单位是 张，现货的数量单位是交易货币 |
| maxMktSz | String | 市价单的单笔最大委托数量 合约的数量单位是 张，现货的数量单位是USDT |
| maxLmtAmt | String | 限价单的单笔最大美元价值 |
| maxMktAmt | String | 市价单的单笔最大美元价值 仅适用于 币币/币币杠杆 |
| maxTwapSz | String | 时间加权单的单笔最大委托数量 合约的数量单位是 张，现货的数量单位是交易货币 |
| maxIcebergSz | String | 冰山委托的单笔最大委托数量 合约的数量单位是 张，现货的数量单位是交易货币 |
| maxTriggerSz | String | 计划委托委托的单笔最大委托数量 合约的数量单位是 张，现货的数量单位是交易货币 |
| maxStopSz | String | 止盈止损市价委托的单笔最大委托数量 合约的数量单位是 张，现货的数量单位是USDT |
获取系统时间
获取系统时间
限速：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 |
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 | 人民币兑美元汇率 |
获取经济日历数据
获取过去三个月的宏观经济日历数据。三个月前的历史数据仅开放给交易费等级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
产品频道
服务地址
/ws/v5/public
请求示例
{
"op": "subscribe",
"args": [
{
"channel" : "instruments",
"instType": "SPOT"
}
]
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| op | String | 是 | 操作subscribeunsubscribe |
| args | Array | 是 | 请求订阅的频道列表 |
| > channel | String | 是 | 频道名instruments |
| > instType | String | 是 | 产品类型SPOT：币币 |
成功返回示例
{
"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 | 是 | 事件subscribeunsubscribeerror |
| 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": "",
"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",
"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 | 上线日期，仅适用于 交割/永续/期权 |
| > 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：预上线，如：交割和期权的新合约在上线之前，会有 preopen 状态test：测试中（测试产品，不可交易） |
| > maxLmtSz | String | 限价单的单笔最大委托数量 合约的数量单位是 张，现货的数量单位是交易货币 |
| > maxMktSz | String | 市价单的单笔最大委托数量 合约的数量单位是 张，现货的数量单位是USDT |
| > maxTwapSz | String | 时间加权单的单笔最大委托数量 合约的数量单位是 张，现货的数量单位是交易货币 |
| > maxIcebergSz | String | 冰山委托的单笔最大委托数量 合约的数量单位是 张，现货的数量单位是交易货币 |
| > maxTriggerSz | String | 计划委托委托的单笔最大委托数量 合约的数量单位是 张，现货的数量单位是交易货币 |
| > maxStopSz | String | 止盈止损市价委托的单笔最大委托数量 合约的数量单位是 张，现货的数量单位是USDT |
经济日历频道
获取最新经济日历数据。 该频道仅开放给交易费等级VIP1及以上的用户。
服务地址
/ws/v5/business (需要登录)
请求示例
{
"op": "subscribe",
"args": [
{
"channel": "economic-calendar"
}
]
}
请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| op | String | 是 | 操作subscribeunsubscribe |
| args | Array | 是 | 请求订阅的频道列表 |
| > channel | String | 是 | 频道名economic-calendar |
成功返回示例
{
"event": "subscribe",
"arg": {
"channel": "economic-calendar"
}
}
失败返回示例
{
"event": "error",
"code": "60012",
"msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"mark-price\", \"instId\" : \"LTC-USD-190628\"}]}"
}
返回参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| event | String | 是 | 操作subscribeunsubscribeerror |
| 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 | 推送时间 |
资金账户
资金功能模块下的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": [
{
"canDep": true,
"canInternal": true,
"canWd": true,
"ccy": "BTC",
"chain": "BTC-Bitcoin",
"depQuotaFixed": "",
"depQuoteDailyLayer2":"",
"logoLink": "https://static.coinall.ltd/cdn/oksupport/asset/currency/icon/btc.png",
"mainNet": true,
"maxFee": "0.0004",
"maxFeeForCtAddr": "0.0004",
"maxWd": "500",
"minDep": "0.00005",
"minDepArrivalConfirm": "1",
"minFee": "0.0002",
"minFeeForCtAddr": "0.0002",
"minWd": "0.001",
"minWdUnlockConfirm": "3",
"name": "Bitcoin",
"needTag": false,
"usedDepQuotaFixed": "",
"usedWdQuota": "0",
"wdQuota": "200",
"wdTickSz": "8"
}
]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ccy | String | 币种名称，如 BTC |
| name | String | 币种名称，不显示则无对应名称 |
| logoLink | String | 币种Logo链接 |
| chain | String | 币种链信息 有的币种下有多个链，必须要做区分，如 USDT下有USDT-ERC20，USDT-TRC20多个链 |
| canDep | Boolean | 当前是否可充值false：不可链上充值true：可以链上充值 |
| canWd | Boolean | 当前是否可提币false：不可链上提币true：可以链上提币 |
| canInternal | Boolean | 当前是否可内部转账false：不可内部转账true：可以内部转账 |
| minDep | String | 币种单笔最小充值量 |
| minWd | String | 币种单笔最小链上提币量 |
| maxWd | String | 币种单笔最大链上提币量 |
| wdTickSz | String | 提币精度,表示小数点后的位数。提币手续费精度与提币精度保持一致。 内部转账提币精度为小数点后8位。 |
| wdQuota | String | 过去24小时内提币额度（包含链上提币和内部转账），单位为USD |
| usedWdQuota | String | 过去24小时内已用提币额度，单位为USD |
| minFee | String | 普通地址最小提币手续费数量 适用于 链上提币 |
| maxFee | String | 普通地址最大提币手续费数量 适用于 链上提币 |
| minFeeForCtAddr | String | 合约地址最小提币手续费数量 适用于 链上提币 |
| maxFeeForCtAddr | String | 合约地址最大提币手续费数量 适用于 链上提币 |
| 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",
"canWd": true,
"ccy": "CELT",
"chain": "CELT-OKTC",
"ctAddr": "f403fb",
"fee": "2",
"logoLink": "https://static.coinall.ltd/cdn/assets/imgs/221/460DA8A592400393.png",
"minWd": "0.1",
"name": "",
"needTag": false,
"wdAll": false,
"wdTickSz": "8"
},
{
"bal": "0.001",
"canWd": true,
"ccy": "MEME",
"chain": "MEME-ERC20",
"ctAddr": "09b760",
"fee": "5",
"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 | 提币固定手续费，单位是USDT。提币手续费精度为小数点后8位。 |
| 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 |
返回结果
{
"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：活动送出61：[闪兑] 数字货币间兑换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：跨链兑换136：ETH2.0质押 系统账户增加ETH（用于上链）137：ETH2.0申购138：ETH2.0兑换139：ETH2.0收益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：[活期借币] 多币种借贷锁定质押物214：[活期借币] 多币种质押物返还用户216：[活期借币] 多币种借贷划转到用户帐户218：[活期借币] 多币种借贷还款220：已下架数字货币221：提币手续费支出222：提币手续费退款223：合约带单分润225：鲨鱼鳍申购226：鲨鱼鳍回款227：鲨鱼鳍收益228：鲨鱼鳍退款229：空投发放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：系统转入小额资产 |
| 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",
"fee":"0.0005",
"dest":"4",
"ccy":"BTC",
"chain":"BTC-Bitcoin",
"toAddr":"17DKe3kkkkiiiiTvAKKi2vMPbm1Bz3CMKw"
}
# 内部转账
POST /api/v5/asset/withdrawal
body
{
"amt":"10",
"fee":"0",
"dest":"3",
"ccy":"USDT",
"areaCode":"86",
"toAddr":"15651000000"
}
# 特定主体用户需要提供接收方信息
POST /api/v5/asset/withdrawal
body
{
"amt":"1",
"fee":"0.0005",
"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