概览
欢迎查看 V5 API文档。我们提供完整的REST和WebSocket API以满足您的交易需求。
- 在 my.okx.com 完成注册的用户，请访问 https://my.okx.com/docs-v5/zh/ 获取 V5 API 文档。
API学习资源与技术支持
教程
- 学习使用V5 API交易: V5 API使用指南
- 学习使用Python交易现货: Python 现货交易教程
- 学习使用Python交易衍生品: Python 衍生品交易教程
Python包
- 使用Python SDK更简单地上手: Python SDK
- 轻松上手Python做市商代码 Python 做市商代码示例
客户服务
- 官方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://www.okx.com - WebSocket公共频道：
wss://ws.okx.com:8443/ws/v5/public - WebSocket私有频道：
wss://ws.okx.com:8443/ws/v5/private - WebSocket业务频道：
wss://ws.okx.com:8443/ws/v5/business
AWS 地址如下：
- REST：
https://aws.okx.com - WebSocket公共频道：
wss://wsaws.okx.com:8443/ws/v5/public - WebSocket私有频道：
wss://wsaws.okx.com:8443/ws/v5/private - WebSocket业务频道：
wss://wsaws.okx.com:8443/ws/v5/business
模拟盘交易
目前可以进行V5 API的模拟盘交易，部分功能不支持如提币、充值、申购赎回等。
模拟盘API交易地址如下：
- REST：
https://www.okx.com - WebSocket公共频道：
wss://wspap.okx.com:8443/ws/v5/public - WebSocket私有频道：
wss://wspap.okx.com:8443/ws/v5/private - WebSocket业务频道：
wss://wspap.okx.com:8443/ws/v5/business
模拟盘的账户与欧易的账户是互通的，如果您已经有欧易账户，可以直接登录。
模拟盘API交易需要在模拟盘上创建APIKey：
登录欧易账户—>交易—>模拟交易—>个人中心—>创建模拟盘APIKey—>开始模拟交易
请求头示例
Content-Type: application/json
OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418
OK-ACCESS-SIGN: leaVRETrtaoEQ3yI9qEtI1CZ82ikZ4xSG5Kj8gnl3uw=
OK-ACCESS-PASSPHRASE: 1****6
OK-ACCESS-TIMESTAMP: 2020-03-28T12:21:41.274Z
x-simulated-trading: 1
模拟盘交互式浏览器
该功能接口用户需先登录，接口只会请求模拟环境
Parameters 面板中点击
Try it out按钮，编辑请求参数。点击
Execute按钮发送请求。Responses 面板中查看请求结果。
立即体验 交互式浏览器
基本信息
交易所层面的下单规则如下：
- 未成交订单（包括 post only，limit和处理中的taker单）的最大挂单数：4,000个
单个交易产品未成交订单的最大挂单数为500个，被计入到 500 笔挂单数量限制的订单类型包括：
- 限价委托 (Limit)
- 市价委托 (Market)
- 只挂单 (Post only)
- 全部成交或立即取消 (FOK)
- 立即成交并取消剩余 (IOC)
- 市价委托立即成交并取消剩余 (optimal limit IOC)
- 止盈止损 (TP/SL)
- 以下类型的订单触发的限价和市价委托：
- 止盈止损 (TP/SL)
- 计划委托 (Trigger)
- 移动止盈止损 (Trailing stop)
- 套利下单 (Arbitrage)
- 冰山策略 (Iceberg)
- 时间加权策略 (TWAP)
- 定投 (Recurring buy)
价差订单最大挂单数：所有价差订单挂单合计500个
策略委托订单最大挂单数：
- 止盈止损：100个 每个Instrument ID
- 计划委托：500个
- 移动止盈止损：50个
- 冰山委托：100个
- 时间加权委托：20个
网格策略最大个数：
- 现货网格：100个
- 合约网格：100个
交易限制规则如下：
- 当taker订单匹配的maker订单数量超过最大限制1000笔时，taker订单将被取消
- 限价单仅成交与1000笔maker订单相对应的部分，并取消剩余；
- 全部成交或立即取消（FOK）订单将直接被取消。
返回数据规则如下：
当返回数据中，有
code，且没有sCode字段时，code和msg代表请求结果或者报错原因；当返回中有
sCode字段时，代表请求结果或者报错原因的是sCode和sMsg，而不是code和msg。
交易品种instFamily参数说明：
- 与uly没有区别：
- 如："BTC-USD-SWAP"的instFamily和uly均为BTC-USD，"BTC-USDC-SWAP"的instFamily和uly均为为BTC-USDC。
- 若请求参数指定uly为"BTC-USD"，会包含"BTC-USD"币本位合约的数据
- 若请求参数指定instFamily为"BTC-USD"，也只会包含"BTC-USD"币本位合约的数据。
- 如："BTC-USD-SWAP"的instFamily和uly均为BTC-USD，"BTC-USDC-SWAP"的instFamily和uly均为为BTC-USDC。
- 您可以通过"获取交易产品基础信息"接口获取交易产品对应的instFamily。
交易时效性
由于网络延时或者OKX服务器繁忙会导致订单无法及时处理。如果您对交易时效性有较高的要求，可以灵活设置请求有效截止时间expTime以达到你的要求。
（批量）下单，（批量）改单接口请求中如果包含expTime，如果服务器当前系统时间超过expTime，则该请求不会被服务器处理。
你应跟我们服务器系统时间同步。请用获取系统时间来获取系统时间。
REST API
请求头中设置如下参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| expTime | String | 否 | 请求有效截止时间。Unix时间戳的毫秒数格式，如 1597026383085 |
目前支持如下接口：
请求示例
curl -X 'POST' \
'https://www.okx.com/api/v5/trade/order' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'OK-ACCESS-KEY: *****' \
-H 'OK-ACCESS-SIGN: *****'' \
-H 'OK-ACCESS-TIMESTAMP: *****'' \
-H 'OK-ACCESS-PASSPHRASE: *****'' \
-H 'expTime: 1597026383085' \ // 有效截止时间
-d '{
"instId": "BTC-USDT",
"tdMode": "cash",
"side": "buy",
"ordType": "limit",
"px": "1000",
"sz": "0.01"
}'
WebSocket
请求中设置如下参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| expTime | String | 否 | 请求有效截止时间。Unix时间戳的毫秒数格式，如 1597026383085 |
目前支持如下接口：
请求示例
{
"id": "1512",
"op": "order",
"expTime":"1597026383085", // 有效截止时间
"args": [{
"side": "buy",
"instId": "BTC-USDT",
"tdMode": "isolated",
"ordType": "market",
"sz": "100"
}]
}
限速
我们的 REST 和 WebSocket API 使用限速来保护我们的 API 免受恶意使用，因此我们的交易平台可以可靠和公平地运行。
当请求因限速而被我们的系统拒绝时，系统会返回错误代码 50011（用户请求频率过快，超过该接口允许的限额。请参考 API 文档并限制请求）。
每个接口的限速都不同。 您可以从接口详细信息中找到每个接口的限制。 限速定义详述如下：
WebSocket 登录和订阅限速基于连接。
公共未经身份验证的 REST 限速基于 IP 地址。
私有 REST 限速基于 User ID（子帐户具有单独的 User ID）。
WebSocket 订单管理限速基于 User ID（子账户具有单独的 User ID）。
交易相关API
对于与交易相关的 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秒
最佳实践
如果您需要的请求速率高于我们的限速，您可以设置不同的子账户来批量请求限速。 我们建议使用此方法来限制或间隔请求，以最大化每个帐户的限速并避免断开连接或拒绝请求。
做市商申请
满足以下任意条件的用户即可申请加入欧易做市商计划：
- 交易等级VIP2及以上
- 其他交易所达标做市商（需审核）
感兴趣的各方可以使用此表格联系我们：https://okx.typeform.com/contact-sales
为鼓励做市商为平台提供更好的流动性，可以享受更优的交易手续费，同时也承担相应的做市责任。具体做市责任及手续费申请成功后提供相关资料。
经纪商申请
如果您的业务平台提供数字货币服务，您就可以申请加入欧易经纪商项目，成为欧易的经纪商合作伙伴，享受专属的经纪商服务，并通过用户在欧易产生的交易手续费赚取高额返佣。
经纪商业务包含且不限：聚合交易平台、交易机器人、跟单平台、交易策略提供方、量化策略机构、资管平台等。
具体经纪商业务文档及产品服务在申请成功后提供相关资料。
交易账户
账户功能模块下的API接口需要身份验证。
REST API
获取交易产品基础信息
获取当前账户可交易产品的信息列表。
限速：20次/2s
限速规则：UserID + InstType
HTTP请求
GET /api/v5/account/instruments
请求示例
GET /api/v5/account/instruments?instType=SPOT
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
result = accountAPI.get_instruments(instType="SPOT")
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 是 | 产品类型SPOT：币币MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权 |
| uly | String | 可选 | 标的指数，仅适用于交割/永续/期权，期权必填 |
| instFamily | String | 否 | 交易品种，仅适用于交割/永续/期权 |
| instId | String | 否 | 产品ID |
返回结果
{
"code": "0",
"data": [
{
"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",
"smtSyncEq": "0",
"fixedBal": "0",
"frozenBal": "158.573",
"imr": "",
"interest": "0",
"isoEq": "0",
"isoLiab": "0",
"isoUpl": "0",
"liab": "0",
"maxLoan": "0",
"mgnRatio": "",
"mmr": "",
"notionalLever": "",
"ordFrozen": "0",
"rewardBal": "0",
"spotInUseAmt": "",
"clSpotInUseAmt": "",
"maxSpotInUse": "",
"spotIsoBal": "0",
"stgyEq": "150",
"twap": "0",
"uTime": "1705449605015",
"upl": "-7.545600000000006",
"uplLiab": "0",
"spotBal": "",
"openAvgPx": "",
"accAvgPx": "",
"spotUpl": "",
"spotUplRatio": "",
"totalPnl": "",
"totalPnlRatio": ""
}
],
"imr": "8.57068529",
"isoEq": "0",
"mgnRatio": "143682.59776662575",
"mmr": "0.3428274116",
"notionalUsd": "85.7068529",
"ordFroz": "0",
"totalEq": "55837.43556134779",
"uTime": "1705474164160",
"upl": "-7.543562688000006",
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| uTime | String | 账户信息的更新时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| totalEq | String | 美金层面权益 |
| isoEq | String | 美金层面逐仓仓位权益 适用于 现货和合约模式/跨币种保证金模式/组合保证金模式 |
| adjEq | String | 美金层面有效保证金 适用于 跨币种保证金模式/组合保证金模式 |
| ordFroz | String | 美金层面全仓挂单占用保证金 仅适用于 跨币种保证金模式 |
| imr | String | 美金层面占用保证金 适用于 跨币种保证金模式/组合保证金模式 |
| mmr | String | 美金层面维持保证金 适用于 跨币种保证金模式/组合保证金模式 |
| borrowFroz | String | 账户美金层面潜在借币占用保证金 仅适用于 跨币种保证金模式/组合保证金模式。在其他账户模式下为""。 |
| mgnRatio | String | 美金层面保证金率 适用于 跨币种保证金模式/组合保证金模式 |
| notionalUsd | String | 以美金价值为单位的持仓数量，即仓位美金价值 适用于 跨币种保证金模式/组合保证金模式 |
| upl | String | 账户层面全仓未实现盈亏（美元单位） 适用于 跨币种保证金模式/组合保证金模式 |
| details | Array | 各币种资产详细信息 |
| > ccy | String | 币种 |
| > eq | String | 币种总权益 |
| > cashBal | String | 币种余额 |
| > uTime | String | 币种余额信息的更新时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| > isoEq | String | 币种逐仓仓位权益 适用于 现货和合约模式/跨币种保证金模式/组合保证金模式 |
| > availEq | String | 可用保证金 适用于 现货和合约模式/跨币种保证金模式/组合保证金模式 |
| > disEq | String | 美金层面币种折算权益 |
| > fixedBal | String | 抄底宝、逃顶宝功能的币种冻结金额 |
| > availBal | String | 可用余额 |
| > frozenBal | String | 币种占用金额 |
| > ordFrozen | String | 挂单冻结数量 适用于 现货模式/现货和合约模式/跨币种保证金模式 |
| > liab | String | 币种负债额 值为正数，如 21625.64适用于 跨币种保证金模式/组合保证金模式 |
| > upl | String | 未实现盈亏 适用于 现货和合约模式/跨币种保证金模式/组合保证金模式 |
| > uplLiab | String | 由于仓位未实现亏损导致的负债 适用于 跨币种保证金模式/组合保证金模式 |
| > crossLiab | String | 币种全仓负债额 适用于 跨币种保证金模式/组合保证金模式 |
| > isoLiab | String | 币种逐仓负债额 适用于 跨币种保证金模式/组合保证金模式 |
| > rewardBal | String | 体验金余额 |
| > mgnRatio | String | 币种全仓保证金率，衡量账户内某项资产风险的指标 适用于 现货和合约模式且有全仓仓位时 |
| > imr | String | 币种维度全仓占用保证金 适用于 现货和合约模式且有全仓仓位时 |
| > mmr | String | 币种维度全仓维持保证金 适用于 现货和合约模式且有全仓仓位时 |
| > interest | String | 计息，应扣未扣利息 值为正数，如 9.01适用于 跨币种保证金模式/组合保证金模式 |
| > twap | String | 当前负债币种触发系统自动换币的风险0、1、2、3、4、5 其中之一，数字越大代表您的负债币种触发自动换币概率越高适用于 跨币种保证金模式/组合保证金模式 |
| > maxLoan | String | 币种最大可借 适用于 跨币种保证金模式/组合保证金模式 的全仓 |
| > eqUsd | String | 币种权益美金价值 |
| > borrowFroz | String | 币种美金层面潜在借币占用保证金 仅适用于 跨币种保证金模式/组合保证金模式。在其他账户模式下为""。 |
| > notionalLever | String | 币种杠杆倍数 适用于 现货和合约模式 |
| > stgyEq | String | 策略权益 |
| > isoUpl | String | 逐仓未实现盈亏 适用于 现货和合约模式/跨币种保证金模式/组合保证金模式 |
| > spotInUseAmt | String | 现货对冲占用数量 适用于 组合保证金模式 |
| > clSpotInUseAmt | String | 用户自定义现货占用数量 适用于 组合保证金模式 |
| > maxSpotInUse | String | 系统计算得到的最大可能现货占用数量 适用于 组合保证金模式 |
| > spotIsoBal | String | 现货逐仓余额 仅适用于现货带单/跟单 适用于 现货模式/现货和合约模式 |
| > smtSyncEq | String | 智能跟单权益 默认为0，仅适用于跟单人 |
| > 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 | 是 | 是 | ||
| mgnRatio | 是 | 是 | ||
| notionalUsd | 是 | 是 | ||
| upl | 是 | 是 | ||
| details | ||||
| > ccy | 是 | 是 | 是 | 是 |
| > eq | 是 | 是 | 是 | 是 |
| > cashBal | 是 | 是 | 是 | 是 |
| > uTime | 是 | 是 | 是 | 是 |
| > isoEq | 是 | 是 | 是 | |
| > availEq | 是 | 是 | 是 | |
| > disEq | 是 | 是 | 是 | 是 |
| > availBal | 是 | 是 | 是 | 是 |
| > frozenBal | 是 | 是 | 是 | 是 |
| > ordFrozen | 是 | 是 | 是 | 是 |
| > liab | 是 | 是 | ||
| > upl | 是 | 是 | 是 | |
| > uplLiab | 是 | 是 | ||
| > crossLiab | 是 | 是 | ||
| > isoLiab | 是 | 是 | ||
| > mgnRatio | 是 | |||
| > interest | 是 | 是 | ||
| > twap | 是 | 是 | ||
| > maxLoan | 是 | 是 | ||
| > eqUsd | 是 | 是 | 是 | 是 |
| > notionalLever | 是 | |||
| > stgyEq | 是 | 是 | 是 | 是 |
| > isoUpl | 是 | 是 | 是 | |
| > spotInUseAmt | 是 | |||
| > spotIsoBal | 是 | 是 | ||
| > imr | 是 | |||
| > mmr | 是 | |||
| > smtSyncEq | 是 | 是 | 是 | 是 |
| > spotBal | 是 | 是 | 是 | 是 |
| > openAvgPx | 是 | 是 | 是 | 是 |
| > accAvgPx | 是 | 是 | 是 | 是 |
| > spotUpl | 是 | 是 | 是 | 是 |
| > spotUplRatio | 是 | 是 | 是 | 是 |
| > totalPnl | 是 | 是 | 是 | 是 |
| > totalPnlRatio | 是 | 是 | 是 | 是 |
查看持仓信息
获取该账户下拥有实际持仓的信息。账户为买卖模式会显示净持仓（net），账户为开平仓模式下会分别返回开多（long）或开空（short）的仓位。按照仓位创建时间倒序排列。
限速：10次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/positions
请求示例
# 查看BTC-USDT的持仓信息
GET /api/v5/account/positions?instId=BTC-USDT
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 查看持仓信息
result = accountAPI.get_positions()
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 否 | 产品类型MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权instType和instId同时传入的时候会校验instId与instType是否一致。 |
| instId | String | 否 | 交易产品ID，如：BTC-USDT-SWAP支持多个 instId查询（不超过10个），半角逗号分隔 |
| posId | String | 否 | 持仓ID 支持多个 posId查询（不超过20个）。存在有效期的属性，自最近一次完全平仓算起，满30天 posId 以及整个仓位会被清除。 |
返回结果
{
"code": "0",
"data": [
{
"adl": "1",
"availPos": "0.00190433573",
"avgPx": "62961.4",
"baseBal": "",
"baseBorrowed": "",
"baseInterest": "",
"bePx": "",
"bizRefId": "",
"bizRefType": "",
"cTime": "1724740225685",
"ccy": "BTC",
"clSpotInUseAmt": "",
"closeOrderAlgo": [],
"deltaBS": "",
"deltaPA": "",
"fee": "",
"fundingFee": "",
"gammaBS": "",
"gammaPA": "",
"idxPx": "62890.5",
"imr": "",
"instId": "BTC-USDT",
"instType": "MARGIN",
"interest": "0",
"last": "62892.9",
"lever": "5",
"liab": "-99.9998177776581948",
"liabCcy": "USDT",
"liqPenalty": "",
"liqPx": "53615.448336593756",
"margin": "0.000317654",
"markPx": "62891.9",
"maxSpotInUseAmt": "",
"mgnMode": "isolated",
"mgnRatio": "9.404143929947395",
"mmr": "0.0000318005395854",
"notionalUsd": "119.756628017499",
"optVal": "",
"pendingCloseOrdLiabVal": "0",
"pnl": "",
"pos": "0.00190433573",
"posCcy": "BTC",
"posId": "1752810569801498626",
"posSide": "net",
"quoteBal": "",
"quoteBorrowed": "",
"quoteInterest": "",
"realizedPnl": "",
"spotInUseAmt": "",
"spotInUseCcy": "",
"thetaBS": "",
"thetaPA": "",
"tradeId": "785524470",
"uTime": "1724742632153",
"upl": "-0.0000033452492717",
"uplLastPx": "-0.0000033199677697",
"uplRatio": "-0.0105311101755551",
"uplRatioLastPx": "-0.0104515220008934",
"usdPx": "",
"vegaBS": "",
"vegaPA": ""
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instType | String | 产品类型 |
| mgnMode | String | 保证金模式cross：全仓isolated：逐仓 |
| posId | String | 持仓ID |
| posSide | String | 持仓方向long：开平仓模式开多，pos为正 short：开平仓模式开空，pos为正net：买卖模式（交割/永续/期权：pos为正代表开多，pos为负代表开空。币币杠杆时，pos均为正，posCcy为交易货币时，代表开多；posCcy为计价货币时，代表开空。） |
| pos | String | 持仓数量，逐仓自主划转模式下，转入保证金后会产生pos为0的仓位 |
| baseBal | String | 币币杠杆（逐仓一键借币模式） |
| quoteBal | String | 币币杠杆（逐仓一键借币模式） |
| baseBorrowed | String | 币币杠杆（逐仓一键借币模式） |
| baseInterest | String | 币币杠杆（逐仓一键借币模式） |
| quoteBorrowed | String | 币币杠杆（逐仓一键借币模式） |
| quoteInterest | String | 币币杠杆（逐仓一键借币模式） |
| posCcy | String | 仓位资产币种，仅适用于币币杠杆仓位 |
| availPos | String | 可平仓数量，适用于 币币杠杆,交割/永续（开平仓模式），期权对于杠杆仓位，平仓时，杠杆还清负债后，余下的部分会视为币币交易，如果想要减少币币交易的数量，可通过"获取最大可用数量"接口获取只减仓的可用数量。 |
| avgPx | String | 开仓平均价 |
| upl | String | 未实现收益（以标记价格计算） |
| uplRatio | String | 未实现收益率（以标记价格计算 |
| uplLastPx | String | 以最新成交价格计算的未实现收益，主要做展示使用，实际值还是 upl |
| uplRatioLastPx | String | 以最新成交价格计算的未实现收益率 |
| instId | String | 产品ID，如 BTC-USDT-SWAP |
| lever | String | 杠杆倍数，不适用于期权以及组合保证金模式下的全仓仓位 |
| liqPx | String | 预估强平价 不适用于 期权 |
| markPx | String | 最新标记价格 |
| imr | String | 初始保证金，仅适用于全仓 |
| margin | String | 保证金余额，可增减，仅适用于逐仓 |
| mgnRatio | String | 保证金率 |
| mmr | String | 维持保证金 |
| liab | String | 负债额，仅适用于币币杠杆 |
| liabCcy | String | 负债币种，仅适用于币币杠杆 |
| interest | String | 利息，已经生成的未扣利息 |
| tradeId | String | 最新成交ID |
| optVal | String | 期权市值，仅适用于期权 |
| pendingCloseOrdLiabVal | String | 逐仓杠杆负债对应平仓挂单的数量 |
| notionalUsd | String | 以美金价值为单位的持仓数量 |
| adl | String | 信号区 分为5档，从1到5，数字越小代表adl强度越弱 |
| ccy | String | 占用保证金的币种 |
| last | String | 最新成交价 |
| idxPx | String | 最新指数价格 |
| usdPx | String | 保证金币种的市场最新美金价格 仅适用于期权 |
| bePx | String | 盈亏平衡价 |
| deltaBS | String | 美金本位持仓仓位delta，仅适用于期权 |
| deltaPA | String | 币本位持仓仓位delta，仅适用于期权 |
| gammaBS | String | 美金本位持仓仓位gamma，仅适用于期权 |
| gammaPA | String | 币本位持仓仓位gamma，仅适用于期权 |
| thetaBS | String | 美金本位持仓仓位theta，仅适用于期权 |
| thetaPA | String | 币本位持仓仓位theta，仅适用于期权 |
| vegaBS | String | 美金本位持仓仓位vega，仅适用于期权 |
| vegaPA | String | 币本位持仓仓位vega，仅适用于期权 |
| spotInUseAmt | String | 现货对冲占用数量 适用于 组合保证金模式 |
| spotInUseCcy | String | 现货对冲占用币种，如 BTC适用于 组合保证金模式 |
| clSpotInUseAmt | String | 用户自定义现货占用数量 适用于 组合保证金模式 |
| maxSpotInUseAmt | String | 系统计算得到的最大可能现货占用数量 适用于 组合保证金模式 |
| realizedPnl | String | 已实现收益 仅适用于 交割/永续/期权realizedPnl=pnl+fee+fundingFee+liqPenalty |
| pnl | String | 平仓订单累计收益额 |
| fee | String | 累计手续费金额，正数代表平台返佣 ，负数代表平台扣除 |
| fundingFee | String | 累计资金费用 |
| liqPenalty | String | 累计爆仓罚金，有值时为负数。 |
| closeOrderAlgo | Array | 平仓策略委托订单。调用策略委托下单，且closeFraction=1 时，该数组才会有值。 |
| > algoId | String | 策略委托单ID |
| > slTriggerPx | String | 止损触发价 |
| > slTriggerPxType | String | 止损触发价类型last：最新价格index：指数价格mark：标记价格 |
| > tpTriggerPx | String | 止盈委托价 |
| > tpTriggerPxType | String | 止盈触发价类型last：最新价格index：指数价格mark：标记价格 |
| > closeFraction | String | 策略委托触发时，平仓的百分比。1 代表100% |
| cTime | String | 持仓创建时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| uTime | String | 最近一次持仓更新时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| bizRefId | String | 外部业务id，e.g. 体验券id |
| bizRefType | String | 外部业务类型 |
查看历史持仓信息
获取最近3个月有更新的仓位信息，按照仓位更新时间倒序排列。组合保证金账户模式不支持查询历史持仓。
限速：10次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/positions-history
请求示例
GET /api/v5/account/positions-history
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 查看历史持仓信息
result = accountAPI.get_positions_history()
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 否 | 产品类型MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权 |
| instId | String | 否 | 交易产品ID，如：BTC-USD-SWAP |
| mgnMode | String | 否 | 保证金模式cross：全仓，isolated：逐仓 |
| type | String | 否 | 最近一次平仓的类型1：部分平仓;2：完全平仓;3：强平;4：强减; 5：ADL自动减仓; 状态叠加时，以最新的平仓类型为准状态为准。 |
| posId | String | 否 | 持仓ID。存在有效期的属性，自最近一次完全平仓算起，满30天 posId 会失效，之后的仓位，会使用新的 posId。 |
| after | String | 否 | 查询仓位更新 (uTime) 之前的内容，值为时间戳，Unix 时间戳为毫秒数格式，如 1597026383085 |
| before | String | 否 | 查询仓位更新 (uTime) 之后的内容，值为时间戳，Unix 时间戳为毫秒数格式，如 1597026383085 |
| limit | String | 否 | 分页返回结果的数量，最大为100，默认100条，uTime 相同的记录均会在当前请求中全部返回 |
返回结果
{
"code": "0",
"data": [
{
"cTime": "1654177169995",
"ccy": "BTC",
"closeAvgPx": "29786.5999999789081085",
"closeTotalPos": "1",
"instId": "BTC-USD-SWAP",
"instType": "SWAP",
"lever": "10.0",
"mgnMode": "cross",
"openAvgPx": "29783.8999999995535393",
"openMaxPos": "1",
"realizedPnl": "0.001",
"fee": "-0.0001",
"fundingFee": "0",
"liqPenalty": "0",
"pnl": "0.0011",
"pnlRatio": "0.000906447858888",
"posId": "452587086133239818",
"posSide": "long",
"direction": "long",
"triggerPx": "",
"type": "1",
"uTime": "1654177174419",
"uly": "BTC-USD"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instType | String | 产品类型 |
| instId | String | 交易产品ID |
| mgnMode | String | 保证金模式cross：全仓，isolated：逐仓 |
| type | String | 最近一次平仓的类型1：部分平仓;2：完全平仓;3：强平;4：强减; 5：ADL自动减仓; 状态叠加时，以最新的平仓类型为准状态为准。 |
| cTime | String | 仓位创建时间 |
| uTime | String | 仓位更新时间 |
| openAvgPx | String | 开仓均价 |
| closeAvgPx | String | 平仓均价 |
| posId | String | 仓位ID |
| openMaxPos | String | 最大持仓量 |
| closeTotalPos | String | 累计平仓量 |
| realizedPnl | String | 已实现收益 仅适用于 交割/永续/期权realizedPnl=pnl+fee+fundingFee+liqPenalty |
| fee | String | 累计手续费金额，正数代表平台返佣 ，负数代表平台扣除 |
| fundingFee | String | 累计资金费用 |
| liqPenalty | String | 累计爆仓罚金，有值时为负数。 |
| pnl | String | 平仓收益额 |
| pnlRatio | String | 平仓收益率 |
| posSide | String | 持仓模式方向long：开平仓模式开多short：开平仓模式开空net：买卖模式 |
| lever | String | 杠杆倍数 |
| direction | String | 持仓方向 long：多 short：空仅适用于 币币杠杆/交割/永续/期权 |
| triggerPx | String | 触发标记价格，type 为3,4,5时有值，为1, 2 时为空"" |
| uly | String | 标的指数 |
| ccy | String | 占用保证金的币种 |
查看账户持仓风险
查看账户整体风险。
限速：10次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/account-position-risk
请求示例
GET /api/v5/account/account-position-risk
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 查看账户特定风险状态
result = accountAPI.get_account_position_risk()
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 否 | 产品类型MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权 |
返回结果
{
"code":"0",
"data":[
{
"adjEq":"174238.6793649711331679",
"balData":[
{
"ccy":"BTC",
"disEq":"78846.7803721021362242",
"eq":"1.3863533369419636"
},
{
"ccy":"USDT",
"disEq":"73417.2495112863300127",
"eq":"73323.395564963177146"
}
],
"posData":[
{
"baseBal": "0.4",
"ccy": "",
"instId": "BTC-USDT",
"instType": "MARGIN",
"mgnMode": "isolated",
"notionalCcy": "0",
"notionalUsd": "0",
"pos": "0",
"posCcy": "",
"posId": "310388685292318723",
"posSide": "net",
"quoteBal": "0"
}
],
"ts":"1620282889345"
}
],
"msg":""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ts | String | 获取账户信息数据的时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| adjEq | String | 美金层面有效保证金 适用于 跨币种保证金模式 和组合保证金模式 |
| balData | Array | 币种资产信息 |
| > ccy | String | 币种 |
| > eq | String | 币种总权益 |
| > disEq | String | 美金层面币种折算权益 |
| posData | Array | 持仓详细信息 |
| > instType | String | 产品类型 |
| > mgnMode | String | 保证金模式cross：全仓isolated：逐仓 |
| > posId | String | 持仓ID |
| > instId | String | 产品ID，如 BTC-USDT-SWAP |
| > pos | String | 以张为单位的持仓数量，逐仓自主划转模式下，转入保证金后会产生pos为0的仓位 |
| > baseBal | String | 币币杠杆（逐仓一键借币模式） |
| > quoteBal | String | 币币杠杆（逐仓一键借币模式） |
| > posSide | String | 持仓方向long：开平仓模式开多short：开平仓模式开空net：买卖模式（交割/永续/期权：pos为正代表开多，pos为负代表开空。币币杠杆：posCcy为交易货币时，代表开多；posCcy为计价货币时，代表开空。） |
| > posCcy | String | 仓位资产币种，仅适用于币币杠杆仓位 |
| > ccy | String | 占用保证金的币种 |
| > notionalCcy | String | 以币为单位的持仓数量 |
| > notionalUsd | String | 以美金价值为单位的持仓数量 |
账单流水查询（近七天）
帐户资产流水是指导致帐户余额增加或减少的行为。本接口可以查询最近7天的账单数据。
限速：5次/s
限速规则：UserID
HTTP请求
GET /api/v5/account/bills
请求示例
GET /api/v5/account/bills
GET /api/v5/account/bills?instType=MARGIN
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘：0 , 模拟盘：1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 查看账户账单详情 （近七日内）
result = accountAPI.get_account_bills()
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 否 | 产品类型SPOT：币币MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权 |
| instId | String | 否 | 产品ID，如 BTC-USDT |
| ccy | String | 否 | 账单币种 |
| mgnMode | String | 否 | 仓位类型isolated：逐仓cross：全仓 |
| ctType | String | 否 | 合约类型linear：正向合约inverse：反向合约仅 交割/永续有效 |
| type | String | 否 | 账单类型1：划转2：交易3：交割4：自动换币5：强平6：保证金划转7：扣息8：资金费9：自动减仓10：穿仓补偿11：系统换币12：策略划拨13：对冲减仓14：大宗交易15：一键借币22：一键还债24：价差交易26：结构化产品250：跟单人分润支出251：跟单人分润退还 |
| subType | String | 否 | 账单子类型1：买入2：卖出 3：开多 4：开空 5：平多 6：平空 9：市场借币扣息 11：转入 12：转出 14：尊享借币扣息 160：手动追加保证金 161：手动减少保证金 162：自动追加保证金 114：自动换币买入115：自动换币卖出 118：系统换币转入 119：系统换币转出 100：强减平多 101：强减平空 102：强减买入 103：强减卖出 104：强平平多 105：强平平空 106：强平买入 107：强平卖出 108：穿仓补偿 109：强平惩罚费110：强平换币转入 111：强平换币转出 125：自动减仓平多 126：自动减仓平空 127：自动减仓买入 128：自动减仓卖出 131：对冲买入 132：对冲卖出 170：到期行权（实值期权买方） 171：到期被行权（实值期权卖方） 172：到期作废（非实值期权的买方和卖方） 112：交割平多 113：交割平空 117：交割/行权穿仓补偿 173：资金费支出 174：资金费收入 200：系统转入 201：手动转入 202：系统转出 203：手动转出 204：大宗交易买 205：大宗交易卖 206：大宗交易开多 207：大宗交易开空 208：大宗交易平多 209：大宗交易平空 210：一键借币的手动借币 211：一键借币的手动还币 212：一键借币的自动借币 213：一键借币的自动还币220：USDT 买期权转入 221：USDT 买期权转出 16：强制还币 17：强制借币还息 224：还债转入 225：还债转出236：兑换主流币用户账户转入237：兑换主流币用户账户转出250：永续分润支出251：永续分润退还280：现货分润支出281：现货分润退还284: 跟单自动转入285: 跟单手动转入286: 跟单自动转出287: 跟单手动转出270：价差交易买271：价差交易卖272：价差交易开多273：价差交易开空274：价差交易平多275：价差交易平空290：系统转出小额资产293：固定借币扣息294：固定借币利息退款295：固定借币逾期利息296：结构化下单转出297：结构化下单转入298：结构化结算转出299：结构化结算转入306：手动借币307：自动借币308：手动还币309：自动还币312：自动折抵 |
| after | String | 否 | 请求此id之前（更旧的数据）的分页内容，传的值为对应接口的billId |
| before | String | 否 | 请求此id之后（更新的数据）的分页内容，传的值为对应接口的billId |
| begin | String | 否 | 筛选的开始时间戳 ts，Unix 时间戳为毫秒数格式，如 1597026383085 |
| end | String | 否 | 筛选的结束时间戳 ts，Unix 时间戳为毫秒数格式，如 1597027383085 |
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 |
返回结果
{
"code": "0",
"msg": "",
"data": [{
"bal": "8694.2179403378290202",
"balChg": "0.0219338232210000",
"billId": "623950854533513219",
"ccy": "USDT",
"clOrdId": "",
"execType": "T",
"fee": "-0.000021955779",
"fillFwdPx": "",
"fillIdxPx": "27104.1",
"fillMarkPx": "",
"fillMarkVol": "",
"fillPxUsd": "",
"fillPxVol": "",
"fillTime": "1695033476166",
"from": "",
"instId": "BTC-USDT",
"instType": "SPOT",
"interest": "0",
"mgnMode": "isolated",
"notes": "",
"ordId": "623950854525124608",
"pnl": "0",
"posBal": "0",
"posBalChg": "0",
"px": "27105.9",
"subType": "1",
"sz": "0.021955779",
"tag": "",
"to": "",
"tradeId": "586760148",
"ts": "1695033476167",
"type": "2"
}]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instType | String | 产品类型 |
| billId | String | 账单ID |
| type | String | 账单类型 |
| subType | String | 账单子类型 |
| ts | String | 余额更新完成的时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| balChg | String | 账户层面的余额变动数量 |
| posBalChg | String | 仓位层面的余额变动数量 |
| bal | String | 账户层面的余额数量 |
| posBal | String | 仓位层面的余额数量 |
| sz | String | 数量 |
| px | String | 价格，与 subType 相关1：买入 2：卖出 3：开多 4：开空 5：平多 6：平空 204：大宗交易买 205：大宗交易卖 206：大宗交易开多 207：大宗交易开空 208：大宗交易平多 209：大宗交易平空 114：自动换币买入 115：自动换币卖出100：强减平多 101：强减平空 102：强减买入 103：强减卖出 104：强平平多 105：强平平空 106：强平买入 107：强平卖出 16：强制还币 17：强制借币还息 110：强平换币转入 111：强平换币转出112：交割平多 113：交割平空170：到期行权 171：到期被行权 172：到期作废173：资金费支出 174：资金费收入 |
| ccy | String | 账户余额币种 |
| pnl | String | 收益 |
| fee | String | 手续费 正数代表平台返佣 ，负数代表平台扣除 手续费规则 |
| mgnMode | String | 保证金模式isolated：逐仓 cross：全仓账单不是由仓位变化产生的，该字段返回 "" |
| instId | String | 产品ID，如 BTC-USDT |
| ordId | String | 订单ID 当type为 2/5/9时，返回相应订单id无订单时，该字段返回 "" |
| execType | String | 流动性方向T：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 | 交易执行时的指数价格 d 对于交叉现货币对，返回 baseCcy-USDT 的指数价格。 例如 LTC-ETH，该字段返回 LTC-USDT 的指数价格。 |
| fillMarkPx | String | 成交时的标记价格，仅适用于 交割/永续/期权 |
| fillPxVol | String | 成交时的隐含波动率，仅适用于 期权，其他业务线返回空字符串"" |
| fillPxUsd | String | 成交时的期权价格，以USD为单位，仅适用于期权，其他业务线返回空字符串"" |
| fillMarkVol | String | 成交时的标记波动率，仅适用于期权，其他业务线返回空字符串"" |
| fillFwdPx | String | 成交时的远期价格，仅适用于期权，其他业务线返回空字符串"" |
账单流水查询（近三月）
帐户资产流水是指导致帐户余额增加或减少的行为。本接口可以查询最近3个月的账单数据。
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/bills-archive
请求示例
GET /api/v5/account/bills-archive
GET /api/v5/account/bills-archive?instType=MARGIN
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 查看账户账单详情 （近三个月内）
result = accountAPI.get_account_bills_archive()
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 否 | 产品类型SPOT：币币MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权 |
| instId | String | 否 | 产品ID，如 BTC-USDT |
| ccy | String | 否 | 账单币种 |
| mgnMode | String | 否 | 仓位类型isolated：逐仓cross：全仓 |
| ctType | String | 否 | 合约类型linear：正向合约inverse：反向合约仅 交割/永续有效 |
| type | String | 否 | 账单类型1：划转2：交易3：交割4：自动换币5：强平6：保证金划转7：扣息8：资金费9：自动减仓10：穿仓补偿11：系统换币12：策略划拨13：对冲减仓14：大宗交易15：一键借币22：一键还债24：价差交易26：结构化产品250：跟单人分润支出251：跟单人分润退还 |
| subType | String | 否 | 账单子类型1：买入2：卖出 3：开多 4：开空 5：平多 6：平空 9：市场借币扣息 11：转入 12：转出 14：尊享借币扣息 160：手动追加保证金 161：手动减少保证金 162：自动追加保证金 114：自动换币买入115：自动换币卖出 118：系统换币转入 119：系统换币转出 100：强减平多 101：强减平空 102：强减买入 103：强减卖出 104：强平平多 105：强平平空 106：强平买入 107：强平卖出 108：穿仓补偿 109：强平惩罚费110：强平换币转入 111：强平换币转出 125：自动减仓平多 126：自动减仓平空 127：自动减仓买入 128：自动减仓卖出 131：对冲买入 132：对冲卖出 170：到期行权（实值期权买方） 171：到期被行权（实值期权卖方） 172：到期作废（非实值期权的买方和卖方） 112：交割平多 113：交割平空 117：交割/行权穿仓补偿 173：资金费支出 174：资金费收入 200：系统转入 201：手动转入 202：系统转出 203：手动转出 204：大宗交易买 205：大宗交易卖 206：大宗交易开多 207：大宗交易开空 208：大宗交易平多 209：大宗交易平空 210：一键借币的手动借币 211：一键借币的手动还币 212：一键借币的自动借币 213：一键借币的自动还币220：USDT 买期权转入 221：USDT 买期权转出 16：强制还币 17：强制借币还息 224：还债转入 225：还债转出236：兑换主流币用户账户转入237：兑换主流币用户账户转出250：永续分润支出251：永续分润退还280：现货分润支出281：现货分润退还284: 跟单自动转入285: 跟单手动转入286: 跟单自动转出287: 跟单手动转出270：价差交易买271：价差交易卖272：价差交易开多273：价差交易开空274：价差交易平多275：价差交易平空290：系统转出小额资产293：固定借币扣息294：固定借币利息退款295：固定借币逾期利息296：结构化下单转出297：结构化下单转入298：结构化结算转出299：结构化结算转入306：手动借币307：自动借币308：手动还币309：自动还币312：自动折抵 |
| after | String | 否 | 请求此id之前（更旧的数据）的分页内容，传的值为对应接口的billId |
| before | String | 否 | 请求此id之后（更新的数据）的分页内容，传的值为对应接口的billId |
| begin | String | 否 | 筛选的开始时间戳 ts，Unix 时间戳为毫秒数格式，如 1597026383085 |
| end | String | 否 | 筛选的结束时间戳 ts，Unix 时间戳为毫秒数格式，如 1597027383085 |
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 |
返回结果
{
"code": "0",
"msg": "",
"data": [{
"bal": "8694.2179403378290202",
"balChg": "0.0219338232210000",
"billId": "623950854533513219",
"ccy": "USDT",
"clOrdId": "",
"execType": "T",
"fee": "-0.000021955779",
"fillFwdPx": "",
"fillIdxPx": "27104.1",
"fillMarkPx": "",
"fillMarkVol": "",
"fillPxUsd": "",
"fillPxVol": "",
"fillTime": "1695033476166",
"from": "",
"instId": "BTC-USDT",
"instType": "SPOT",
"interest": "0",
"mgnMode": "isolated",
"notes": "",
"ordId": "623950854525124608",
"pnl": "0",
"posBal": "0",
"posBalChg": "0",
"px": "27105.9",
"subType": "1",
"sz": "0.021955779",
"tag": "",
"to": "",
"tradeId": "586760148",
"ts": "1695033476167",
"type": "2"
}]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instType | String | 产品类型 |
| billId | String | 账单ID |
| type | String | 账单类型 |
| subType | String | 账单子类型 |
| ts | String | 余额更新完成的时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| balChg | String | 账户层面的余额变动数量 |
| posBalChg | String | 仓位层面的余额变动数量 |
| bal | String | 账户层面的余额数量 |
| posBal | String | 仓位层面的余额数量 |
| sz | String | 数量 |
| px | String | 价格，与 subType 相关1：买入2：卖出3：开多4：开空5：平多6：平空204：大宗交易买205：大宗交易卖206：大宗交易开多207：大宗交易开空208：大宗交易平多209：大宗交易平空114：自动换币买入115：自动换币卖出100：强减平多 101：强减平空 102：强减买入 103：强减卖出 104：强平平多 105：强平平空 106：强平买入 107：强平卖出 16：强制还币 17：强制借币还息 110：强平换币转入 111：强平换币转出112：交割平多 113：交割平空170：到期行权 171：到期被行权 172：到期作废173：资金费支出 174：资金费收入 |
| ccy | String | 账户余额币种 |
| pnl | String | 收益 |
| fee | String | 手续费 正数代表平台返佣 ，负数代表平台扣除 手续费规则 |
| mgnMode | String | 保证金模式isolated：逐仓cross：全仓无仓位类型字段，该字段返回 "" |
| instId | String | 产品ID，如 BTC-USDT |
| ordId | String | 订单ID 当type为 2/5/9时，返回相应订单id无订单时，该字段返回 "" |
| execType | String | 流动性方向T：takerM：maker |
| from | String | 转出账户6：资金账户18：交易账户仅适用于 资金划转，不是资金划转时，返回 "" |
| to | String | 转入账户6：资金账户18：交易账户仅适用于 资金划转，不是资金划转时，返回 "" |
| notes | String | 备注 |
| interest | String | 利息 |
| tag | String | 订单标签 |
| fillTime | String | 最新成交时间 |
| tradeId | String | 最新成交ID |
| clOrdId | String | 客户自定义订单ID |
| fillIdxPx | String | 交易执行时的指数价格 对于交叉现货币对，返回 baseCcy-USDT 的指数价格。 例 LTC-ETH，该字段返回 LTC-USDT 的指数价格。 |
| fillMarkPx | String | 成交时的标记价格，仅适用于 交割/永续/期权 |
| fillPxVol | String | 成交时的隐含波动率，仅适用于 期权，其他业务线返回空字符串"" |
| fillPxUsd | String | 成交时的期权价格，以USD为单位，仅适用于 期权，其他业务线返回空字符串"" |
| fillMarkVol | String | 成交时的标记波动率，仅适用于 期权，其他业务线返回空字符串"" |
| fillFwdPx | String | 成交时的远期价格，仅适用于 期权，其他业务线返回空字符串"" |
申请账单流水（自 2021 年）
申请自 2021 年 2 月 1 日以来的账单数据，不包括当前季度。
限速：12 次/天
限速规则：UserID
权限：读取
HTTP 请求
POST /api/v5/account/bills-history-archive
请求示例
POST /api/v5/account/bills-history-archive
body
{
"year":"2023",
"quarter":"Q1"
}
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| year | String | 是 | 4位数字的年份，如 2023 |
| quarter | String | 是 | 季度，有效值 Q1 Q2 Q3 Q4 |
返回结果
{
"code": "0",
"data": [
{
"result": "true",
"ts": "1646892328000"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| result | String | 是否已经存在该区间的下载链接true：已存在，可以通过"获取账单流水（自 2021 年）"接口获取false：不存在，正在生成，请30个小时后查看下载链接 |
| ts | String | 服务端首次收到请求的时间，Unix时间戳的毫秒数格式，如 1597026383085 |
获取账单流水（自 2021 年）
获取自 2021 年 2 月 1 日以来的账单数据
限速：10 次/2s
限速规则：UserID
权限：读取
HTTP 请求
GET /api/v5/account/bills-history-archive
请求示例
GET /api/v5/account/bills-history-archive?year=2023&quarter=Q4
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| year | String | 是 | 4位数字的年份，如 2023 |
| quarter | String | 是 | 季度，有效值 Q1 Q2 Q3 Q4 |
返回结果
{
"code": "0",
"data": [
{
"fileHref": "http://xxx",
"state": "finished",
"ts": "1646892328000"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| fileHref | String | 文件链接 |
| ts | String | 下载链接生成时间，Unix时间戳的毫秒数格式 ，如 1597026383085 |
| state | String | 下载链接状态finished：已生成ongoing：进行中failed：生成失败，请重新生成 |
解压后CSV里的字段说明
| 参数名 | 类型 | 描述 |
|---|---|---|
| instType | String | 产品类型 |
| billId | String | 账单ID |
| subType | String | 账单子类型 |
| ts | String | 余额更新完成的时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| balChg | String | 账户层面的余额变动数量 |
| posBalChg | String | 仓位层面的余额变动数量 |
| bal | String | 账户层面的余额数量 |
| posBal | String | 仓位层面的余额数量 |
| sz | String | 数量 |
| px | String | 价格，与 subType 相关1：买入2：卖出3：开多4：开空5：平多6：平空204：大宗交易买205：大宗交易卖206：大宗交易开多207：大宗交易开空208：大宗交易平多209：大宗交易平空114：自动换币买入115：自动换币卖出100：强减平多 101：强减平空 102：强减买入 103：强减卖出 104：强平平多 105：强平平空 106：强平买入 107：强平卖出 16：强制还币 17：强制借币还息 110：强平换币转入 111：强平换币转出112：交割平多 113：交割平空170：到期行权 171：到期被行权 172：到期作废173：资金费支出 174：资金费收入 |
| ccy | String | 账户余额币种 |
| pnl | String | 收益 |
| fee | String | 手续费 正数代表平台返佣 ，负数代表平台扣除 手续费规则 |
| mgnMode | String | 保证金模式isolated：逐仓cross：全仓无仓位类型字段，该字段返回 "" |
| instId | String | 产品ID，如 BTC-USDT |
| ordId | String | 订单ID 无订单时，该字段返回 "" |
| execType | String | 流动性方向T：takerM：maker |
| interest | String | 利息 |
| tag | String | 订单标签 |
| fillTime | String | 最新成交时间 |
| tradeId | String | 最新成交ID |
| clOrdId | String | 客户自定义订单ID |
| fillIdxPx | String | 交易执行时的指数价格 对于交叉现货币对，返回 baseCcy-USDT 的指数价格。 例 LTC-ETH，该字段返回 LTC-USDT 的指数价格。 |
| fillMarkPx | String | 成交时的标记价格，仅适用于 交割/永续/期权 |
| fillPxVol | String | 成交时的隐含波动率，仅适用于 期权，其他业务线返回空字符串"" |
| fillPxUsd | String | 成交时的期权价格，以USD为单位，仅适用于 期权，其他业务线返回空字符串"" |
| fillMarkVol | String | 成交时的标记波动率，仅适用于 期权，其他业务线返回空字符串"" |
| fillFwdPx | String | 成交时的远期价格，仅适用于 期权，其他业务线返回空字符串"" |
查看账户配置
查看当前账户的配置信息。
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/config
请求示例
GET /api/v5/account/config
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 查看账户配置
result = accountAPI.get_account_config()
print(result)
请求参数
无
返回结果
{
"code": "0",
"data": [
{
"acctLv": "2",
"acctStpMode": "cancel_maker",
"autoLoan": false,
"ctIsoMode": "automatic",
"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：不支持 |
设置持仓模式
现货和合约模式和跨币种保证金模式：交割和永续合约支持开平仓模式和买卖模式。买卖模式只会有一个方向的仓位；开平仓模式可以分别持有多、空2个方向的仓位。
组合保证金模式：交割和永续仅支持买卖模式
限速：5次/2s
限速规则：UserID
HTTP请求
POST /api/v5/account/set-position-mode
请求示例
POST /api/v5/account/set-position-mode
body
{
"posMode":"long_short_mode"
}
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 设置持仓模式
result = accountAPI.set_position_mode(
posMode="long_short_mode"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| posMode | String | 是 | 持仓方式long_short_mode：开平仓模式 net_mode：买卖模式仅适用 交割/永续 |
返回结果
{
"code": "0",
"msg": "",
"data": [{
"posMode": "long_short_mode"
}]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| posMode | String | 持仓方式 |
设置杠杆倍数
一个产品可以有如下10种杠杆倍数的设置场景：
- 在
逐仓交易模式下，设置币币杠杆的杠杆倍数（币对层面）； 现货模式账户已开通借币功能，在全仓交易模式下，设置币币杠杆的杠杆倍数（币种层面）；现货和合约模式账户在全仓交易模式下，设置币币杠杆的杠杆倍数（币对层面）；跨币种保证金模式账户在全仓交易模式下，设置币币杠杆的杠杆倍数（币种层面）；组合保证金模式账户在全仓交易模式下，设置币币杠杆的杠杆倍数（币种层面）；- 在
全仓交易模式下，设置交割的杠杆倍数（指数层面）； - 在
逐仓交易模式、买卖持仓模式下，设置交割的杠杆倍数（合约层面）； - 在
逐仓交易模式、开平仓持仓模式下，设置交割的杠杆倍数（合约与持仓方向层面）； - 在
全仓交易模式下，设置永续的杠杆倍数（合约层面）； - 在
逐仓交易模式、买卖持仓模式下，设置永续的杠杆倍数（合约层面）； - 在
逐仓交易模式、开平仓持仓模式下，设置永续的杠杆倍数（合约与持仓方向层面）；
注意请求参数 posSide 仅在交割/永续的开平仓持仓模式下才需要填写（参见场景8和11）。
请参阅右侧对应的每个案例的请求示例。
限速：20次/2s
限速规则：UserID
HTTP请求
POST /api/v5/account/set-leverage
请求示例
# 1.在`逐仓`交易模式下，设置`币币杠杆`的杠杆倍数（币对层面）
POST /api/v5/account/set-leverage
body
{
"instId":"BTC-USDT",
"lever":"5",
"mgnMode":"isolated"
}
# 2.`现货模式`账户已开通借币功能，在`全仓`交易模式下，设置`币币杠杆`的杠杆倍数（币种层面）
POST /api/v5/account/set-leverage
body
{
"ccy":"BTC",
"lever":"5",
"mgnMode":"cross"
}
# 3.`现货和合约模式`账户在`全仓`交易模式下，设置`币币杠杆`的杠杆倍数（币对层面）
POST /api/v5/account/set-leverage
body
{
"instId":"BTC-USDT",
"lever":"5",
"mgnMode":"cross"
}
# 4.`跨币种保证金模式`账户在`全仓`交易模式下，设置`币币杠杆`的杠杆倍数（币种层面）
POST /api/v5/account/set-leverage
body
{
"ccy":"BTC",
"lever":"5",
"mgnMode":"cross"
}
# 5. `组合保证金模式`账户在`全仓`交易模式下，设置`币币杠杆`的杠杆倍数（币种层面）
POST /api/v5/account/set-leverage
body
{
"ccy":"BTC",
"lever":"5",
"mgnMode":"cross"
}
# 6.在`全仓`交易模式下，设置`交割`的杠杆倍数（指数层面）
POST /api/v5/account/set-leverage
body
{
"instId":"BTC-USDT-200802",
"lever":"5",
"mgnMode":"cross"
}
# 7.在`逐仓`交易模式、`买卖`持仓模式下，设置`交割`的杠杆倍数（合约层面）
POST /api/v5/account/set-leverage
body
{
"instId":"BTC-USDT-200802",
"lever":"5",
"mgnMode":"isolated"
}
# 8.在`逐仓`交易模式、`开平仓`持仓模式下，设置`交割`的杠杆倍数（合约与头寸层面）
POST /api/v5/account/set-leverage
body
{
"instId":"BTC-USDT-200802",
"lever":"5",
"posSide":"long",
"mgnMode":"isolated"
}
# 9.在`全仓`交易模式下，设置`永续`的杠杆倍数（合约层面）
POST /api/v5/account/set-leverage
body
{
"instId":"BTC-USDT-SWAP",
"lever":"5",
"mgnMode":"cross"
}
# 10.在`逐仓`交易模式、`买卖`持仓模式下，设置`永续`的杠杆倍数（合约层面）
POST /api/v5/account/set-leverage
body
{
"instId":"BTC-USDT-SWAP",
"lever":"5",
"mgnMode":"isolated"
}
# 11.在`逐仓`交易模式、`开平仓`持仓模式下，设置`永续`的杠杆倍数（合约与头寸层面）
POST /api/v5/account/set-leverage
body
{
"instId":"BTC-USDT-SWAP",
"lever":"5",
"posSide":"long",
"mgnMode":"isolated"
}
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 在逐仓交易模式下，设置币币杠杆的杠杆倍数（币对层面）
result = accountAPI.set_leverage(
instId="BTC-USDT",
lever="5",
mgnMode="isolated"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 可选 | 产品ID：币对、合约 全仓下， instId和ccy至少要传一个；如果两个都传，默认使用instId |
| ccy | String | 可选 | 保证金币种，用于设置开启自动借币模式下币种维度的杠杆。 仅适用于 现货模式/跨币种保证金模式/组合保证金模式的全仓币币杠杆。设置自动借币的杠杆倍数时必填 |
| lever | String | 是 | 杠杆倍数 |
| mgnMode | String | 是 | 保证金模式isolated：逐仓 cross：全仓如果 ccy有效传值，该参数值只能为cross。 |
| posSide | String | 可选 | 持仓方向long：开平仓模式开多short：开平仓模式开空仅适用于逐仓 交割/永续在开平仓模式且保证金模式为逐仓条件下必填 |
返回结果
{
"code": "0",
"msg": "",
"data": [{
"lever": "30",
"mgnMode": "isolated",
"instId": "BTC-USDT-SWAP",
"posSide": "long"
}]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| lever | String | 杠杆倍数 |
| mgnMode | String | 保证金模式isolated：逐仓 cross：全仓 |
| instId | String | 产品ID |
| posSide | String | 持仓方向 |
获取最大可下单数量
获取最大可下单数量，可对应下单时的 "sz" 字段
限速：20次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/max-size
请求示例
GET /api/v5/account/max-size?instId=BTC-USDT&tdMode=isolated
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 获取最大可买卖/开仓数量
result = accountAPI.get_max_order_size(
instId="BTC-USDT",
tdMode="isolated"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 是 | 产品ID，如 BTC-USDT支持同一业务线下的多产品ID查询（不超过5个），半角逗号分隔 |
| tdMode | String | 是 | 交易模式cross：全仓isolated：逐仓cash：非保证金spot_isolated：现货逐仓 |
| ccy | String | 可选 | 保证金币种，仅适用于现货和合约模式下的全仓杠杆订单 |
| px | String | 否 | 委托价格 当不填委托价时，交割和永续会取当前限价计算，其他业务线会按当前最新成交价计算 当指定多个产品ID查询时，忽略该参数，当未填写处理 |
| leverage | String | 否 | 开仓杠杆倍数 默认为当前杠杆倍数 仅适用于 币币杠杆/交割/永续 |
| unSpotOffset | Boolean | 否 | true：禁止现货对冲，false：允许现货对冲默认为 false仅适用于 组合保证金模式开启现货对冲模式下有效，否则忽略此参数。 |
返回结果
{
"code": "0",
"msg": "",
"data": [{
"ccy": "BTC",
"instId": "BTC-USDT",
"maxBuy": "0.0500695098559788",
"maxSell": "64.4798671570072269"
}]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instId | String | 产品ID |
| ccy | String | 保证金币种 |
| maxBuy | String | 币币/币币杠杆：最大可买的交易币数量现货和合约模式下的全仓杠杆订单，为交易币数量交割/永续/期权：最大可开多的合约张数 |
| maxSell | String | 币币/币币杠杆：最大可卖的计价币数量现货和合约模式下的全仓杠杆订单，为交易币数量交割/永续/期权：最大可开空的合约张数 |
获取最大可用余额/保证金
币币和逐仓时为可用余额，全仓时为可用保证金
限速：20次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/max-avail-size
请求示例
# 获取BTC-USDT全仓币币杠杆指定BTC作为保证金最大可用数量
GET /api/v5/account/max-avail-size?instId=BTC-USDT&tdMode=cross&ccy=BTC
# 获取BTC-USDT币币最大可用数量
GET /api/v5/account/max-avail-size?instId=BTC-USDT&tdMode=cash
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 获取BTC-USDT币币最大可用数量
result = accountAPI.get_max_avail_size(
instId="BTC-USDT",
tdMode="cash"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 是 | 产品ID，如 BTC-USDT支持多产品ID查询（不超过5个），半角逗号分隔 |
| tdMode | String | 是 | 交易模式cross：全仓isolated：逐仓cash：非保证金spot_isolated：现货逐仓 |
| ccy | String | 可选 | 保证金币种，仅适用于现货和合约模式下的全仓杠杆订单 |
| reduceOnly | Boolean | 否 | 是否为只减仓模式，仅适用于币币杠杆 |
| px | String | 否 | 平仓价格，默认为市价。 仅适用于杠杆只减仓 |
| unSpotOffset | Boolean | 否 | true：禁止现货对冲，false：允许现货对冲默认为 false仅适用于 组合保证金模式开启现货对冲模式下有效，否则忽略此参数。 |
| quickMgnType | String | 否 | manual：手动，auto_borrow：自动借币，auto_repay：自动还币 默认是 manual：手动 |
返回结果
{
"code": "0",
"msg": "",
"data": [{
"instId": "BTC-USDT",
"availBuy": "100",
"availSell": "1"
}]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instId | String | 产品ID |
| availBuy | String | 最大买入可用余额/保证金 |
| availSell | String | 最大卖出可用余额/保证金 |
调整保证金
增加或者减少逐仓保证金。减少保证金可能会导致实际杠杆倍数发生变化。
限速：20次/2s
限速规则：UserID
HTTP请求
POST /api/v5/account/position/margin-balance
请求示例
POST /api/v5/account/position/margin-balance
body
{
"instId":"BTC-USDT-SWAP",
"posSide":"short",
"type":"add",
"amt":"1"
}
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 调整保证金
result = accountAPI.adjustment_margin(
instId="BTC-USDT-SWAP",
posSide="short",
type= "add",
amt="1"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 是 | 产品ID |
| posSide | String | 是 | 持仓方向，默认值是netlong：开平仓模式开多short：开平仓模式开空net：买卖模式 |
| type | String | 是 | 增加/减少保证金add：增加 reduce：减少 |
| amt | String | 是 | 增加或减少的保证金数量 |
| ccy | String | 可选 | 增加或减少的保证金的币种， 仅适用于逐仓一键借币模式下的币币杠杆，且必填 |
返回结果
{
"code": "0",
"data": [
{
"amt": "0.3",
"ccy": "BTC",
"instId": "BTC-USDT",
"leverage": "",
"posSide": "net",
"type": "add"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instId | String | 产品ID |
| posSide | String | 持仓方向 |
| amt | String | 已增加/减少的保证金数量 |
| type | String | 增加/减少保证金 |
| leverage | String | 调整保证金后的实际杠杆倍数 |
| ccy | String | 增加或减少的保证金的币种 |
获取杠杆倍数
限速：20次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/leverage-info
请求示例
GET /api/v5/account/leverage-info?instId=BTC-USDT-SWAP&mgnMode=cross
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 获取杠杆倍数
result = accountAPI.get_leverage(
instId="BTC-USDT-SWAP",
mgnMode="cross"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 可选 | 产品ID 支持多个instId查询，半角逗号分隔。instId个数不超过20个。 |
| ccy | String | 可选 | 币种，用于币种维度的杠杆。 仅适用于 现货模式/跨币种保证金模式/组合保证金模式的全仓币币杠杆。支持多ccy查询，半角逗号分隔。ccy个数不超过20个。 |
| mgnMode | String | 是 | 保证金模式isolated：逐仓 cross：全仓 |
返回结果
{
"code": "0",
"msg": "",
"data": [{
"ccy":"",
"instId": "BTC-USDT-SWAP",
"mgnMode": "cross",
"posSide": "long",
"lever": "10"
},{
"ccy":"",
"instId": "BTC-USDT-SWAP",
"mgnMode": "cross",
"posSide": "short",
"lever": "10"
}]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instId | String | 产品ID |
| ccy | String | 币种，用于币种维度的杠杆。 仅适用于 现货模式/跨币种保证金模式/组合保证金模式的全仓币币杠杆。 |
| mgnMode | String | 保证金模式 |
| posSide | String | 持仓方向long：开平仓模式开多short：开平仓模式开空net：买卖模式开平仓模式下会返回两个方向的杠杆倍数 |
| lever | String | 杠杆倍数 |
获取杠杆倍数预估信息
获取指定杠杆倍数下，相关的预估信息。
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/adjust-leverage-info
请求示例
GET /api/v5/account/adjust-leverage-info?instType=MARGIN&mgnMode=isolated&lever=3&instId=BTC-USDT
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 是 | 产品类型MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约 |
| mgnMode | String | 是 | 保证金模式isolated：逐仓 cross：全仓 |
| lever | String | 是 | 杠杆倍数 |
| instId | String | 可选 | 产品 ID，如 BTC-USDT 必填的场景有：交割永续，逐仓杠杆，以及 现货和合约模式下全仓杠杆。 |
| ccy | String | 可选 | 保证金币种，如 BTC现货和合约模式/跨币种保证金模式/组合保证金模式的全仓杠杆时必填。 |
| posSide | String | 否 | 持仓方向net: 默认值，代表买卖模式long: 开平模式下的多仓short：开平模式下的空仓仅适用交割、永续。 |
返回结果
{
"code": "0",
"data": [
{
"estAvailQuoteTrans": "",
"estAvailTrans": "1.1398040558348279",
"estLiqPx": "",
"estMaxAmt": "10.6095865868904898",
"estMgn": "0.0701959441651721",
"estQuoteMaxAmt": "176889.6871254563042714",
"estQuoteMgn": "",
"existOrd": false,
"maxLever": "10",
"minLever": "0.01"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| estAvailQuoteTrans | String | 对应杠杆倍数下，计价货币预估可转出的保证金数量 全仓时，为交易账户最大可转出 逐仓时，为逐仓仓位可减少的保证金。 仅适用于 杠杆 |
| estAvailTrans | String | 对应杠杆倍数下，预估可转出的保证金数量 全仓时，为交易账户最大可转出 逐仓时，为逐仓仓位可减少的保证金 对于 杠杆，单位为交易货币不适用于 交割, 永续的逐仓，调大杠杆的场景 |
| estLiqPx | String | 对应杠杆倍数下的预估强平价，仅在有仓位时有值 |
| estMgn | String | 对应杠杆倍数下，仓位预估所需的保证金数量 对于杠杆仓位，为所需交易货币保证金 对于交割或永续仓位，为仓位所需保证金 |
| estQuoteMgn | String | 对应杠杆倍数下，仓位预估所需的计价货币保证金数量 |
| estMaxAmt | String | 对于杠杆，为对应杠杆倍数下，交易货币预估最大可借 对于交割和永续，为对应杠杆倍数下，预估的最大可开张数 |
| estQuoteMaxAmt | String | 对应杠杆倍数下，杠杆计价货币预估最大可借 |
| existOrd | Boolean | 当前是否存在挂单 true：存在挂单false：不存在挂单 |
| maxLever | String | 最大杠杆倍数 |
| minLever | String | 最小杠杆倍数 |
获取交易产品最大可借
限速：20 次/2s
限速规则：UserID
HTTP 请求
GET /api/v5/account/max-loan
请求示例
# 现货模式用户已经开通了借币情况下最大可借
GET /api/v5/account/max-loan?instId=BTC-USDT&mgnMode=cross
# 现货和合约模式逐仓账户获取币币杠杆最大可借
GET /api/v5/account/max-loan?instId=BTC-USDT&mgnMode=isolated
# 现货和合约模式全仓账户获取币币杠杆最大可借（指定保证金为BTC）
GET /api/v5/account/max-loan?instId=BTC-USDT&mgnMode=cross&mgnCcy=BTC
# 跨币种全仓账户获取币币杠杠最大可借
GET /api/v5/account/max-loan?instId=BTC-USDT&mgnMode=cross
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 现货和合约模式全仓账户获取币币杠杆最大可借（指定保证金为BTC）
result = accountAPI.get_max_loan(
instId="BTC-USDT",
mgnMode="cross",
mgnCcy="BTC"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 是 | 产品 ID，如 BTC-USDT支持多产品ID查询（不超过5个），半角逗号分隔 |
| mgnMode | String | 是 | 仓位类型isolated：逐仓cross：全仓 |
| mgnCcy | String | 可选 | 保证金币种，如 BTC现货和合约模式币币杠杆全仓情况下必须指定保证金币种 |
返回结果
{
"code": "0",
"msg": "",
"data": [
{
"instId": "BTC-USDT",
"mgnMode": "isolated",
"mgnCcy": "",
"maxLoan": "0.1",
"ccy": "BTC",
"side": "sell"
},
{
"instId": "BTC-USDT",
"mgnMode": "isolated",
"mgnCcy": "",
"maxLoan": "0.2",
"ccy": "USDT",
"side": "buy"
}
]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instId | String | 产品 ID |
| mgnMode | String | 仓位类型 |
| mgnCcy | String | 保证金币种 |
| maxLoan | String | 最大可借 |
| ccy | String | 币种 |
| side | String | 订单方向 |
获取当前账户交易手续费费率
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/trade-fee
请求示例
# 获取币币BTC-USDT交易手续费率
GET /api/v5/account/trade-fee?instType=SPOT&instId=BTC-USDT
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 获取当前账户交易手续费费率
result = accountAPI.get_fee_rates(
instType="SPOT",
instId="BTC-USDT"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 是 | 产品类型SPOT：币币MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权 |
| instId | String | 否 | 产品ID，如 BTC-USDT仅适用于instType为 币币/币币杠杆 |
| uly | String | 否 | 标的指数 适用于 交割/永续/期权，如 BTC-USD |
| instFamily | String | 否 | 交易品种 适用于 交割/永续/期权，如 BTC-USD |
| ruleType | String | 是 | 交易规则类型normal：普通交易pre_market：盘前交易ruleType不能与instId/instFamily/uly同时传入 |
返回结果
{
"code": "0",
"msg": "",
"data": [{
"category": "1", //已废弃
"delivery": "",
"exercise": "",
"instType": "SPOT",
"level": "lv1",
"maker": "-0.0008",
"makerU": "",
"makerUSDC": "",
"taker": "-0.001",
"takerU": "",
"takerUSDC": "",
"ruleType": "normal",
"ts": "1608623351857",
"fiat": []
}
]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| level | String | 手续费等级 |
| taker | String | 对于币币/杠杆，为 USDT 交易区的吃单手续费率； 对于永续，交割和期权合约，为币本位合约费率 |
| maker | String | 对于币币/杠杆，为 USDT 交易区的挂单手续费率； 对于永续，交割和期权合约，为币本位合约费率 |
| takerU | String | USDT 合约吃单手续费率，仅适用于交割/永续 |
| makerU | String | USDT 合约挂单手续费率，仅适用于交割/永续 |
| delivery | String | 交割手续费率 |
| exercise | String | 行权手续费率 |
| instType | String | 产品类型 |
| takerUSDC | String | 对于币币/杠杆，为 USDⓈ&Crypto 交易区的吃单手续费率； 对于永续和交割合约，为 USDC 合约费率 |
| makerUSDC | String | 对于币币/杠杆，为 USDⓈ&Crypto 交易区的挂单手续费率； 对于永续和交割合约，为 USDC 合约费率 |
| ruleType | String | 交易规则类型normal：普通交易pre_market：盘前交易 |
| ts | String | 数据返回时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| category | String | |
| fiat | Array | 法币费率 |
| > ccy | String | 法币币种 |
| > taker | String | 吃单手续费率 |
| > maker | String | 挂单手续费率 |
获取计息记录
获取计息记录，仅能获取最近一年内的数据。
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/interest-accrued
请求示例
GET /api/v5/account/interest-accrued
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 获取计息记录
result = accountAPI.get_interest_accrued()
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| type | String | 否 | 借币类型1：尊享借币2：市场借币默认为 市场借币 |
| ccy | String | 否 | 借贷币种，如 BTC仅适用于 市场借币仅适用于 币币杠杆 |
| instId | String | 否 | 产品ID，如 BTC-USDT仅适用于 市场借币 |
| mgnMode | String | 否 | 保证金模式cross：全仓isolated：逐仓仅适用于 市场借币 |
| after | String | 否 | 请求此时间戳之前（更旧的数据）的分页内容，Unix时间戳的毫秒数格式，如 1597026383085 |
| before | String | 否 | 请求此时间戳之后（更新的数据）的分页内容，Unix时间戳的毫秒数格式，如 1597026383085 |
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 |
返回结果
{
"code": "0",
"data": [
{
"ccy": "USDT",
"instId": "",
"interest": "0.0003960833333334",
"interestRate": "0.0000040833333333",
"liab": "97",
"mgnMode": "",
"ts": "1637312400000",
"type": "1"
},
{
"ccy": "USDT",
"instId": "",
"interest": "0.0004083333333334",
"interestRate": "0.0000040833333333",
"liab": "100",
"mgnMode": "",
"ts": "1637049600000",
"type": "1"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| type | String | 类型1：尊享借币2：市场借币 |
| ccy | String | 借贷币种，如 BTC |
| instId | String | 产品ID，如 BTC-USDT-SWAP仅适用于 市场借币 |
| mgnMode | String | 保证金模式cross：全仓isolated：逐仓 |
| interest | String | 利息 |
| interestRate | String | 计息利率(小时) |
| liab | String | 计息负债 |
| ts | String | 计息时间，Unix时间戳的毫秒数格式，如 1597026383085 |
获取用户当前市场借币利率
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/interest-rate
请求示例
GET /api/v5/account/interest-rate
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 获取用户当前市场借币利率
result = accountAPI.get_interest_rate()
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| ccy | String | 否 | 币种 |
返回结果
{
"code":"0",
"msg":"",
"data":[
{
"ccy":"BTC",
"interestRate":"0.0001"
},
{
"ccy":"LTC",
"interestRate":"0.0003"
}
]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| interestRate | String | 市场借币利率(当前小时) |
| ccy | String | 币种 |
期权greeks的PA/BS切换
设置greeks的展示方式。
限速：5次/2s
限速规则：UserID
HTTP请求
POST /api/v5/account/set-greeks
请求示例
POST /api/v5/account/set-greeks
body
{
"greeksType":"PA"
}
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 期权greeks的PA/BS切换
result = accountAPI.set_greeks(greeksType="PA")
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| greeksType | String | 是 | 希腊字母展示方式PA：币本位，BS：美元本位 |
返回结果
{
"code": "0",
"msg": "",
"data": [{
"greeksType": "PA"
}]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| greeksType | String | 当前希腊字母展示方式 |
逐仓交易设置
可以通过该接口设置币币杠杆和交割、永续的逐仓仓位保证金的划转模式
限速：5次/2s
限速规则：UserID
HTTP请求
POST /api/v5/account/set-isolated-mode
请求示例
POST /api/v5/account/set-isolated-mode
body
{
"isoMode":"automatic",
"type":"MARGIN"
}
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 逐仓交易设置
result = accountAPI.set_isolated_mode(
isoMode="automatic",
type="MARGIN"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| isoMode | String | 是 | 逐仓保证金划转模式automatic：开仓自动划转 |
| type | String | 是 | 业务线类型MARGIN：币币杠杆CONTRACTS：合约 |
返回结果
{
"code": "0",
"data": [
{
"isoMode": "automatic"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| isoMode | String | 逐仓保证金划转模式automatic：开仓自动划转 |
查看账户最大可转余额
当指定币种时会返回该币种的交易账户到资金账户的最大可划转数量，不指定币种会返回所有拥有的币种资产可划转数量。
限速：20次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/max-withdrawal
请求示例
GET /api/v5/account/max-withdrawal
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 查看账户最大可转余额
result = accountAPI.get_max_withdrawal()
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| ccy | String | 否 | 币种，如 BTC支持多币种查询（不超过20个），币种之间半角逗号分隔 |
返回结果
{
"code": "0",
"msg": "",
"data": [{
"ccy": "BTC",
"maxWd": "124",
"maxWdEx": "125",
"spotOffsetMaxWd": "",
"spotOffsetMaxWdEx": ""
},
{
"ccy": "ETH",
"maxWd": "10",
"maxWdEx": "12",
"spotOffsetMaxWd": "",
"spotOffsetMaxWdEx": ""
}
]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ccy | String | 币种 |
| maxWd | String | 最大可划转数量（不包含 跨币种保证金模式/组合保证金模式 借币金额） |
| maxWdEx | String | 最大可划转数量（包含 跨币种保证金模式/组合保证金模式 借币金额） |
| spotOffsetMaxWd | String | 现货对冲不支持借币最大可转数量 仅适用于 组合保证金模式 |
| spotOffsetMaxWdEx | String | 现货对冲支持借币的最大可转数量 仅适用于 组合保证金模式 |
查看账户特定风险状态
仅适用于PM账户
限速：10次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/risk-state
请求示例
GET /api/v5/account/risk-state
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 查看账户持仓风险
result = accountAPI.get_account_position_risk()
print(result)
返回结果
{
"code": "0",
"data": [
{
"atRisk": false,
"atRiskIdx": [],
"atRiskMgn": [],
"ts": "1635745078794"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| atRisk | String | 自动借币模式下的账户风险状态 true： 当前账户为特定风险状态 false： 当前不是特定风险状态 |
| atRiskIdx | Array | 衍生品的risk unit列表 |
| atRiskMgn | Array | 杠杆的risk unit列表 |
| ts | String | 接口数据返回时间 ，Unix时间戳的毫秒数格式，如 1597026383085 |
一键借币模式手动借币还币
请注意，该接口将很快被弃用。
限速：5次/2s
限速规则：UserID
HTTP请求
POST /api/v5/account/quick-margin-borrow-repay
请求示例
POST /api/v5/account/quick-margin-borrow-repay
body
{
"instId":"BTC-USDT",
"ccy":"USDT",
"side":"borrow",
"amt":"100"
}
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 是 | 产品ID，如BTC-USDT |
| ccy | String | 是 | 借贷币种，如 BTC |
| side | String | 是 | borrow：借币，repay：还币 |
| amt | String | 是 | 借/还币的数量 |
返回结果
{
"code": "0",
"data": [
{
"amt": "100",
"instId":"BTC-USDT",
"ccy": "USDT",
"side": "borrow"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instId | String | 产品ID，如BTC-USDT |
| ccy | String | 借贷币种，如 BTC |
| side | String | borrow：借币，repay：还币 |
| amt | String | 借/还币的数量 |
获取一键借币还币历史
获取最多3个月内的记录
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/quick-margin-borrow-repay-history
请求示例
GET /api/v5/account/quick-margin-borrow-repay-history
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 否 | 产品ID，如 BTC-USDT |
| ccy | String | 否 | 借贷币种，如 BTC |
| side | String | 否 | borrow：借币，repay：还币 |
| after | String | 否 | 请求此 ID 之前（更旧的数据）的分页内容，传的值为对应接口的refId |
| before | String | 否 | 请求此 ID 之后（更新的数据）的分页内容，传的值为对应接口的refId |
| begin | String | 否 | 筛选的开始时间戳，Unix 时间戳为毫秒数格式，如 1597026383085 |
| end | String | 否 | 筛选的结束时间戳，Unix 时间戳为毫秒数格式，如 1597027383085 |
| limit | String | 否 | 返回结果的数量，最大为100，默认100条 |
返回结果
{
"code": "0",
"data": [
{
"instId": "BTC-USDT",
"ccy": "USDT",
"side": "borrow",
"accBorrowed": "0.01",
"amt": "0.005",
"refId": "1637310691470124",
"ts": "1637310691470"
},
{
"instId": "BTC-USDT",
"ccy": "USDT",
"side": "borrow",
"accBorrowed": "0.01",
"amt": "0.005",
"refId": "1637310691470123",
"ts": "1637310691400"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instId | String | 产品ID，如 BTC-USDT |
| ccy | String | 借贷币种，如 BTC |
| side | String | borrow：借币，repay：还币 |
| accBorrowed | String | 累计借币 |
| amt | String | 借/还币的数量 |
| refId | String | 对应记录ID，借币或还币的ID |
| ts | String | 借/还币时间 |
尊享借币还币
单个币种的借币订单数量最多为20个
限速：6次/s
限速规则：UserID
HTTP请求
POST /api/v5/account/borrow-repay
请求示例
POST /api/v5/account/borrow-repay
body
{
"ccy":"USDT",
"side":"borrow",
"amt":"100"
}
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 尊享借币还币
result = accountAPI.borrow_repay(
ccy="USDT",
side="borrow",
amt="100"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| ccy | String | 是 | 借贷币种，如 BTC |
| side | String | 是 | borrow：借币，repay：还币 |
| amt | String | 是 | 借/还币的数量 |
| ordId | String | 可选 | 借币订单ID，还币时，该字段必填 |
返回结果
{
"code": "0",
"data": [
{
"amt": "70809.316200",
"ccy": "USDT",
"ordId": "544199684697214976",
"side": "borrow",
"state": "1"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ccy | String | 借贷币种，如 BTC |
| side | String | borrow：借币，repay：还币 |
| amt | String | 已借/还币的数量 |
| ordId | String | 借币订单ID |
| state | String | 订单状态1:借币申请中2:借币中3:还币申请中4:已还币5:借币失败 |
获取尊享借币还币历史
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/borrow-repay-history
请求示例
GET /api/v5/account/borrow-repay-history
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 获取尊享借币还币历史
result = accountAPI.get_borrow_repay_history()
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| ccy | String | 否 | 借贷币种，如 BTC |
| after | String | 否 | 请求此时间戳之前（更旧的数据）的分页内容，Unix时间戳的毫秒数格式，如 1597026383085 |
| before | String | 否 | 请求此时间戳之后（更新的数据）的分页内容，Unix时间戳的毫秒数格式，如 1597026383085 |
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 |
返回结果
{
"code": "0",
"data": [
{
"ccy": "USDT",
"tradedLoan": "102",
"ts": "1637310691470",
"type": "2",
"usedLoan": "97"
},
{
"ccy": "USDT",
"tradedLoan": "102",
"ts": "1637050435058",
"type": "2",
"usedLoan": "199"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ccy | String | 借贷币种，如 BTC |
| type | String | 类型1：借币2：还币3：扣息失败系统还币 |
| tradedLoan | String | 借/还币数量 |
| usedLoan | String | 当前账户已借额度 |
| ts | String | 借/还币时间 |
获取尊享借币计息记录
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/vip-interest-accrued
请求示例
GET /api/v5/account/vip-interest-accrued
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| ccy | String | 否 | 借贷币种，如 BTC，仅适用于币币杠杆 |
| ordId | String | 否 | 借币订单ID |
| after | String | 否 | 请求此时间戳之前（更旧的数据）的分页内容，Unix时间戳的毫秒数格式，如 1597026383085 |
| before | String | 否 | 请求此时间戳之后（更新的数据）的分页内容，Unix时间戳的毫秒数格式，如 1597026383085 |
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 |
返回结果
{
"code": "0",
"data": [
{
"ccy": "USDT",
"interest": "0.0003960833333334",
"interestRate": "0.0000040833333333",
"liab": "97",
"ordId": "16373124000001235",
"ts": "1637312400000"
},
{
"ccy": "USDT",
"interest": "0.0004083333333334",
"interestRate": "0.0000040833333333",
"liab": "100",
"ordId": "16370496000001234",
"ts": "1637049600000"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ordId | String | 借币订单ID |
| ccy | String | 借贷币种，如 BTC |
| interest | String | 利息 |
| interestRate | String | 计息利率(小时) |
| liab | String | 计息负债 |
| ts | String | 计息时间，Unix时间戳的毫秒数格式，如 1597026383085 |
获取尊享借币扣息记录
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/vip-interest-deducted
请求示例
GET /api/v5/account/vip-interest-deducted
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| ordId | String | 否 | 借币订单ID |
| ccy | String | 否 | 借贷币种，如 BTC，仅适用于币币杠杆 |
| after | String | 否 | 请求此时间戳之前（更旧的数据）的分页内容，Unix时间戳的毫秒数格式，如 1597026383085 |
| before | String | 否 | 请求此时间戳之后（更新的数据）的分页内容，Unix时间戳的毫秒数格式，如 1597026383085 |
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 |
返回结果
{
"code": "0",
"data": [
{
"ccy": "USDT",
"interest": "0.0003960833333334",
"interestRate": "0.0000040833333333",
"liab": "97",
"ordId": "16373124000001235",
"ts": "1637312400000"
},
{
"ccy": "USDT",
"interest": "0.0004083333333334",
"interestRate": "0.0000040833333333",
"liab": "100",
"ordId": "16370496000001234",
"ts": "1637049600000"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ordId | String | 借币订单ID |
| ccy | String | 借贷币种，如 BTC |
| interest | String | 利息 |
| interestRate | String | 计息利率(小时) |
| liab | String | 计息负债 |
| ts | String | 计息时间，Unix时间戳的毫秒数格式，如 1597026383085 |
尊享借币订单列表
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/vip-loan-order-list
请求示例
GET /api/v5/account/vip-loan-order-list
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| ordId | String | 否 | 借币订单ID |
| state | String | 否 | 订单状态 1:借币申请中 2:借币中 3:还币申请中 4:已还币 5:借币失败 |
| ccy | String | 否 | 借贷币种，如 BTC |
| after | String | 否 | 请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的ordId |
| before | String | 否 | 请求此ID之后（更新的数据）的分页内容，传的值为对应接口的ordId |
| limit | String | 否 | 返回结果的数量，最大为100，默认100条 |
返回结果
{
"code": "0",
"msg": "",
"data": [
{
"borrowAmt": "1.5000000000000000",
"ccy": "USDT",
"curRate": "0.0000169999999992",
"dueAmt": "0.0000000000000000",
"nextRefreshTime": "1688172235000",
"ordId": "584301085292781568",
"origRate": "0.0000169999999992",
"repayAmt": "1.5000000000000000",
"state": "4",
"ts": "1685580235000"
}
]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ts | String | 订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| nextRefreshTime | String | 下一次理论刷新时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| ccy | String | 借贷币种，如 BTC |
| ordId | String | 订单ID |
| state | String | 订单状态 1:借币申请中 2:借币中 3:还币申请中 4:已还币 5:业务异常，借币失败 |
| origRate | String | 订单原始利率 |
| curRate | String | 借贷币种当前年利率 |
| dueAmt | String | 待还数量 |
| borrowAmt | String | 借币数量 |
| repayAmt | String | 还币数量 |
尊享借币订单详情
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/vip-loan-order-detail
请求示例
GET /api/v5/account/vip-loan-order-detail?ordId=697717437869338879
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| ordId | String | 是 | 借币订单ID |
| ccy | String | 否 | 借贷币种，如 BTC |
| before | String | 否 | 请求此时间戳之后（更新的数据）的分页内容，Unix时间戳的毫秒数格式，如 1597026383085 |
| after | String | 否 | 请求此时间戳之前（更旧的数据）的分页内容，Unix时间戳的毫秒数格式，如 1597026383085 |
| limit | String | 否 | 返回结果的数量，最大为100，默认100条 |
返回结果
{
"code": "0",
"msg": "",
"data": [
{
"amt": "1.5000000000000000",
"ccy": "USDT",
"failReason": "",
"rate": "0.0000000000000000",
"ts": "1685580264572",
"type": "2"
}
]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ts | String | 操作时间 |
| ccy | String | 借贷币种，如 BTC |
| type | String | 操作类型 1:借币 2:还币 3:系统还币 4:利率刷新 |
| rate | String | 订单当前利率（日利率） |
| amt | String | 借还数量 |
| failReason | String | 失败原因 |
获取借币利率与限额
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/interest-limits
请求示例
GET /api/v5/account/interest-limits?type=1&ccy=BTC
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 获取借币利率与限额
result = accountAPI.get_interest_limits(
type="1",
ccy="BTC"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| type | String | 否 | 借币类型1：尊享借币2：市场借币默认为 市场借币 |
| ccy | String | 否 | 借贷币种，如 BTC |
返回结果
{
"code": "0",
"data": [
{
"debt": "97.06402000000000000000000000000000",
"interest": "",
"nextDiscountTime": "1637312400000",
"nextInterestTime": "1637312400000",
"loanAlloc": "",
"records": [
{
"availLoan": "0.0000000000000000",
"ccy": "BTC",
"interest": "",
"loanQuota": "600.0000000000000000",
"posLoan": "0",
"rate": "0.00199200",
"avgRate": "0.00199200",
"surplusLmt": "600.0000000000000000",
"surplusLmtDetails":{
"allAcctRemainingQuota": "600.00",
"curAcctRemainingQuota": "600.00",
"platRemainingQuota": "600.00"
},
"usedLmt": "0",
"usedLoan": "0.0000000000000000"
}
]
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| debt | String | 当前负债，单位为USDT |
| interest | String | 当前记息，单位为USDT仅适用于 市场借币 |
| nextDiscountTime | String | 下次扣息时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| nextInterestTime | String | 下次计息时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| loanAlloc | String | 当前交易账户尊享借币可用额度的比率（百分比） 1. 范围为[0, 100]. 精度为 0.01% (2位小数) 2. 0 代表母账户没有为子账户分配； 3. "" 代表母子账户共享 |
| records | Array | 各币种详细信息 |
| > ccy | String | 借贷币种，如 BTC |
| > rate | String | 日利率 |
| > loanQuota | String | 母账户维度借币限额 如果已配置可用额度，该字段代表当前交易账户的借币限额 |
| > surplusLmt | String | 母子账户剩余可借 如果已配置可用额度，该字段代表当前交易账户的剩余可借 |
| > surplusLmtDetails | Object | 母子账户剩余可借额度详情，母子账户剩余可借额度的值取该数组中的最小值，可以用来判断是什么原因导致可借额度不足 仅适用于 尊享借币 |
| >> allAcctRemainingQuota | String | 母子账户剩余额度 |
| >> curAcctRemainingQuota | String | 当前账户剩余额度 仅适用于为子账户分配限额的场景 |
| >> platRemainingQuota | String | 平台剩余额度，当平台剩余额度大于curAcctRemainingQuota或者allAcctRemainingQuota时，会显示大于某个值，如">1000" |
| > usedLmt | String | 母子账户已借额度 如果已配置可用额度，该字段代表当前交易账户的已借额度 |
| > interest | String | 已计未扣利息 仅适用于 市场借币 |
| > posLoan | String | 当前账户负债占用（锁定额度内） 仅适用于 尊享借币 |
| > availLoan | String | 当前账户剩余可用（锁定额度内） 仅适用于 尊享借币 |
| > usedLoan | String | 当前账户已借额度 仅适用于 尊享借币 |
| > avgRate | String | 币种已借平均(小时)利率，仅适用于尊享借币 |
获取固定借币限额
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/fixed-loan/borrowing-limit
请求示例
GET /api/v5/account/fixed-loan/borrowing-limit
请求参数
无
返回结果
{
"code": "0",
"data": [
{
"availRepay": "1110.9884",
"borrowed": "60895.1139",
"details": [
{
"availBorrow": "0.0566",
"borrowed": "0",
"ccy": "BTC",
"minBorrow": "0.1433",
"used": "0"
},
{
"availBorrow": "0",
"borrowed": "0",
"ccy": "LTC",
"minBorrow": "114.582",
"used": "0"
},
{
"availBorrow": "10",
"borrowed": "0",
"ccy": "ETH",
"minBorrow": "2.6666",
"used": "0"
},
{
"availBorrow": "248727.5",
"borrowed": "61115",
"ccy": "USDT",
"minBorrow": "9999.5679",
"used": "60000"
}
],
"totalAvailBorrow": "289336.6564",
"totalBorrowLmt": "22843016.1921",
"ts": "1716368077071",
"used": "59784.1256"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| totalBorrowLmt | String | （母子账户）借币限额 |
| totalAvailBorrow | String | （母子账户）剩余可借 |
| borrowed | String | （当前账户）已借 |
| used | String | （当前账户）已使用额度 |
| availRepay | String | （当前账户）可还额度 |
| details | Array of object | 币种维度借币信息 |
| > ccy | String | 币种，如 BTC |
| > used | String | 当前币种已使用额度 |
| > borrowed | String | 当前币种已借 |
| > availBorrow | String | 当前币种剩余可借 |
| > minBorrow | String | 当前币种最小借币数量 |
| ts | String | 数据返回时间，Unix时间戳的毫秒数格式，如 1597026383085 |
获取固定借币询价
限速：2次/s
限速规则：UserID
HTTP请求
GET /api/v5/account/fixed-loan/borrowing-quote
请求示例
# 新订单询价
GET /api/v5/account/fixed-loan/borrowing-quote?type=normal&ccy=BTC&maxRate=0.1&amt=0.1&term=30D
# 续借询价
GET /api/v5/account/fixed-loan/borrowing-quote?type=reborrow&ordId=2405162053378222
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| type | String | 是 | 类型normal：普通reborrow：续借 |
| ccy | String | 可选 | 币种，如 BTC当 type=normal，该字段必填。 |
| amt | String | 可选 | 借币数量 当 type=normal，该字段必填。 |
| maxRate | String | 可选 | 借币利率，小数形式，如 0.01 代表 1%。当 type=normal，该字段必填。 |
| term | String | 可选 | 借贷期限30D：30天当 type=normal，该字段必填。 |
| ordId | String | 可选 | 订单ID 当 type=reborrow，该字段必填。 |
返回结果
{
"code": "0",
"data": [
{
"ccy": "BTC",
"estAvailBorrow": "0.0215",
"estInterest": "0.00017716",
"estRate": "0.1",
"penaltyInterest": "",
"term": "30D",
"ts": "1714963101596"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ccy | String | 币种，如 BTC |
| term | String | 借贷期限30D：30天 |
| estAvailBorrow | String | 预估可借 |
| estRate | String | 预估可借利率 |
| estInterest | String | 预估利息 |
| penaltyInterest | String | 罚息 适用于 type=reborrow |
| ts | String | 数据返回时间，Unix时间戳的毫秒数格式，如 1597026383085 |
固定借币下单
对于新的借币订单，属于IOC(立即成交并取消剩余)类型。对于续借订单，属于FOK(全部成交或立即取消)类型。
订单簿信息可以参考 获取借贷量。
限速：2次/s
限速规则：UserID
HTTP请求
POST /api/v5/account/fixed-loan/borrowing-order
请求示例
POST /api/v5/account/fixed-loan/borrowing-order
body
{
"ccy": "BTC",
"amt": "0.1",
"maxRate": "0.01",
"term": "30D",
"reborrow": true,
"reborrowRate": "0.01"
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| ccy | String | 是 | 币种，如 BTC |
| amt | String | 是 | 借币数量 |
| maxRate | String | 是 | 借币利率，小数形式，如 0.01 代表 1%。 |
| term | String | 是 | 借贷期限 |
| reborrow | Boolean | 否 | 是否到期自动续借 默认为 false |
| reborrowRate | String | 否 | 自动续借利率, 小数形式，如 0.01 代表 1%。如果 reborrow为true，该字段必填。 |
返回结果
{
"code": "0",
"data": [
{
"ordId":"2405162053378222"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ordId | String | 订单ID |
修改固定借币订单
限速：2次/s
限速规则：UserID
HTTP请求
POST /api/v5/account/fixed-loan/amend-borrowing-order
请求示例
POST /api/v5/account/fixed-loan/amend-borrowing-order
body
{
"ordId": "2405162053378222",
"reborrow": true,
"renewMaxRate": "0.01"
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| ordId | String | 是 | 借币订单ID |
| reborrow | Boolean | 否 | 是否到期自动续借 默认为 false |
| renewMaxRate | String | 否 | 自动续借利率, 小数形式，如 0.01 代表 1%。如果 reborrow为true，该字段必填。 |
返回结果
{
"code": "0",
"data": [
{
"ordId":"2405162053378222"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ordId | String | 借币订单ID |
固定借币手动续借
限速：2次/s
限速规则：UserID
HTTP请求
POST /api/v5/account/fixed-loan/manual-reborrow
请求示例
POST /api/v5/account/fixed-loan/manual-reborrow
body
{
"ordId": "2405162053378222",
"maxRate": "0.01"
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| ordId | String | 是 | 借币订单ID |
| maxRate | String | 是 | 手动续借可接受最大利率, 小数形式，如 0.01 代表 1%。 |
返回结果
{
"code": "0",
"data": [
{
"ordId":"2405162053378222"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ordId | String | 订单ID |
固定借币手动还币
限速：2次/s
限速规则：UserID
HTTP请求
POST /api/v5/account/fixed-loan/repay-borrowing-order
请求示例
POST /api/v5/account/fixed-loan/repay-borrowing-order
body
{
"ordId": "2405162053378222"
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| ordId | String | 是 | 借币订单ID |
返回结果
{
"code": "0",
"data": [
{
"ordId":"2405162053378222"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ordId | String | 订单ID |
固定借币转市场借币
限速：2次/s
限速规则：UserID
HTTP请求
POST /api/v5/account/fixed-loan/convert-to-market-loan
请求示例
POST /api/v5/account/fixed-loan/convert-to-market-loan
body
{
"ordId": "2409141848234868"
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| ordId | String | 是 | 借币订单ID |
返回结果
{
"code": "0",
"data": [
{
"ordId":"2409141848234868"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ordId | String | 借币订单ID |
固定借币减少负债
提供为订单“设置待还币状态/取消待还币状态”功能。
限速：2次/s
限速规则：UserID
HTTP请求
POST /api/v5/account/fixed-loan/reduce-liabilities
请求示例
POST /api/v5/account/fixed-loan/reduce-liabilities
body
{
"ordId": "2409141802194350",
"pendingRepay": true
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| ordId | String | 是 | 借币订单ID |
| pendingRepay | String | 是 | true：设置订单为待还币状态false：取消订单待还币状态 |
返回结果
{
"code": "0",
"data": [
{
"ordId": "2409141802194350",
"pendingRepay": true
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ordId | String | 借币订单ID |
| pendingRepay | String | true：设置订单为待还币状态false：取消订单待还币状态 |
获取固定借币订单信息
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/fixed-loan/borrowing-orders-list
请求示例
GET /api/v5/account/fixed-loan/borrowing-orders-list
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| ordId | String | No | 订单ID |
| ccy | String | No | 币种，如 BTC |
| state | String | No | 状态1：借币中2：借币成功3：已还币4：申请失败5：已逾期6：还币中7：续借中8：待还币 (详情参考 固定借币减少负债) |
| after | String | No | 请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的ordId |
| before | String | No | 请求此ID之后（更新的数据）的分页内容，传的值为对应接口的ordId |
| limit | String | No | 返回结果的数量，最大为100，默认100条 |
返回结果
{
"code": "0",
"data": [
{
"accruedInterest": "0.0065753424657534",
"actualBorrowAmt": "0",
"cTime": "1720701491000",
"ccy": "ETH",
"curRate": "0",
"deadlinePenaltyInterest": "1723271891000",
"earlyRepayPenaltyInterest": "",
"expiryTime": "1723293491000",
"failedReason": "1",
"forceRepayTime": "1725885491000",
"ordId": "2407112038109533",
"overduePenaltyInterest": "",
"potentialPenaltyInterest": "",
"reborrow": false,
"reborrowRate": "",
"reqBorrowAmt": "8",
"settleReason": "",
"state": "4",
"term": "30D",
"uTime": "1720701490000"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ccy | String | 币种，如 BTC |
| ordId | String | 订单ID |
| term | String | 借贷期限30D: 30天 |
| state | String | 状态1：借币中2：借币成功3：已还币4：申请失败5：已逾期6：还币中7：续借中8：待还币 (详情参考 固定借币减少负债) |
| failedReason | String | 借币失败原因1：当前没有匹配订单2：无法支付预付利息-1：其他原因 |
| settleReason | String | 订单结束原因1：订单到期2：提前展期（续借）3：提前释放额度 |
| curRate | String | 当前订单的借币年利率 |
| accruedInterest | String | 应计利息 |
| reqBorrowAmt | String | 原始借币数量 |
| actualBorrowAmt | String | 实际借币数量 |
| reborrow | Boolean | 是否自动续借true：自动续借false：非自动续借 |
| reborrowRate | String | 自动续借利率，小时形式，如 0.01代表1% |
| expiryTime | String | 到期时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| forceRepayTime | String | 强制还币时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| deadlinePenaltyInterest | String | 罚息截止时间（在此时间之后提前还币将不会产生罚息），Unix时间戳的毫秒数格式，如 1597026383085 |
| potentialPenaltyInterest | String | 提前还币带来的潜在罚息 |
| overduePenaltyInterest | String | 逾期利息 |
| earlyRepayPenaltyInterest | String | 提前还币产生的实际罚息 |
| cTime | String | 订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| uTime | String | 订单更新时间，Unix时间戳的毫秒数格式，如 1597026383085 |
仓位创建器
计算用户的模拟头寸或当前头寸的投资组合保证金信息，一次请求最多可添加200个虚拟仓位和200个虚拟虚拟资产
限速：2次/2s
限速规则：UserID
权限：读取
HTTP请求
POST /api/v5/account/position-builder
请求示例
# 真实与虚拟的仓位与资产一起计算
POST /api/v5/account/position-builder
body
{
"inclRealPosAndEq": false,
"simPos":[
{
"pos":"-10",
"instId":"BTC-USDT-SWAP"
},
{
"pos":"10",
"instId":"LTC-USDT-SWAP"
}
],
"simAsset":[
{
"ccy": "USDT",
"amt": "100"
}
],
"spotOffsetType":"1",
"greeksType":"CASH"
}
# 只计算已有真实仓位
POST /api/v5/account/position-builder
body
{
"inclRealPosAndEq": true
}
# 只计算虚拟仓位
POST /api/v5/account/position-builder
body
{
"inclRealPosAndEq": false,
"simPos":[
{
"pos":"10",
"instId":"BTC-USDT-SWAP"
},
{
"pos":"10",
"instId":"LTC-USDT-SWAP"
}
]
}
import okx.Account as Account
# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # Production trading:0 , demo trading:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
result = accountAPI.position_builder(
inclRealPosAndEq=True,
simPos=[
{
"pos": "10",
"instId": "BTC-USDT-SWAP"
},
{
"pos": "10",
"instId": "LTC-USDT-SWAP"
}
]
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| inclRealPosAndEq | Boolean | 否 | 是否代入已有仓位和资产 默认为 true |
| spotOffsetType | String | 否 | 现货对冲模式1：现货对冲模式U模式2：现货对冲模式币模式3：衍生品模式默认是 3 |
| simPos | Array of object | 否 | 模拟仓位列表 |
| > instId | String | 否 | 交易产品ID，如 BTC-USDT-SWAP适用于 SWAP/FUTURES/OPTION |
| > pos | String | 否 | 持仓量 |
| simAsset | Array of object | 否 | 模拟资产 当 inclRealPosAndEq为true，只考虑真实资产，会忽略虚拟资产 |
| > ccy | String | 否 | 币种，如 BTC |
| > amt | String | 否 | 币种数量 可以为负，代表减少币种资产 |
| greeksType | String | 否 | 希腊值类型BS：BS模型PA：币本位CASH：美元现金等价默认是 BS |
返回结果
{
"code": "0",
"data": [
{
"assets": [
{
"availEq": "2.92259509161",
"borrowImr": "0",
"borrowMmr": "0",
"ccy": "BTC",
"spotInUse": "0"
},
{
"availEq": "1",
"borrowImr": "0",
"borrowMmr": "0",
"ccy": "ETH",
"spotInUse": "0"
},
{
"availEq": "-76819.72721896428",
"borrowImr": "9612.484308105535",
"borrowMmr": "1920.4931804741072",
"ccy": "USDT",
"spotInUse": "0"
},
{
"availEq": "100.000001978",
"borrowImr": "0",
"borrowMmr": "0",
"ccy": "OKB",
"spotInUse": "0"
},
{
"availEq": "1.1618286584225905",
"borrowImr": "0",
"borrowMmr": "0",
"ccy": "USDC",
"spotInUse": "0"
}
],
"borrowMmr": "1919.9362374517698",
"derivMmr": "61.63384859899599",
"eq": "50503.83298678435",
"marginRatio": "24.513003004865656",
"riskUnitData": [
{
"delta": "0.010000438961223",
"gamma": "0",
"imr": "79.93948582424999",
"indexUsd": "0.99971",
"mmr": "61.49191217249999",
"mr1": "61.49191217249999",
"mr1FinalResult": {
"pnl": "-61.49191217249999",
"spotShock": "-0.15",
"volShock": "up"
},
"mr1Scenarios": {
"volSame": {
"0": "0",
"-0.05": "-20.497304057499974",
"-0.1": "-40.99460811500002",
"0.1": "40.99460811500002",
"0.15": "61.49191217249999",
"0.05": "20.497304057499974",
"-0.15": "-61.49191217249999"
},
"volShockDown": {
"0": "0",
"-0.05": "-20.497304057499974",
"-0.1": "-40.99460811500002",
"0.1": "40.99460811500002",
"0.15": "61.49191217249999",
"0.05": "20.497304057499974",
"-0.15": "-61.49191217249999"
},
"volShockUp": {
"0": "0",
"-0.05": "-20.497304057499974",
"-0.1": "-40.99460811500002",
"0.1": "40.99460811500002",
"0.15": "61.49191217249999",
"0.05": "20.497304057499974",
"-0.15": "-61.49191217249999"
}
},
"mr2": "0",
"mr3": "0",
"mr4": "0",
"mr5": "0",
"mr6": "61.49191217249999",
"mr6FinalResult": {
"pnl": "-122.98382434499997",
"spotShock": "-0.3"
},
"mr7": "1.8448113495150003",
"portfolios": [
{
"amt": "10",
"delta": "0.010000438961223",
"gamma": "0",
"instId": "BTC-USDT-SWAP",
"instType": "SWAP",
"isRealPos": false,
"notionalUsd": "409.968",
"theta": "0",
"vega": "0"
}
],
"riskUnit": "BTC-USDT",
"theta": "0",
"vega": "0"
},
{
"delta": "0.009998760367833",
"gamma": "0",
"imr": "0.1845173544448",
"indexUsd": "0.99971",
"mmr": "0.141936426496",
"mr1": "0.141936426496",
"mr1FinalResult": {
"pnl": "-0.141936426496",
"spotShock": "-0.2",
"volShock": "up"
},
"mr1Scenarios": {
"volSame": {
"0": "0",
"-0.07": "-0.0496777492736",
"-0.2": "-0.141936426496",
"0.07": "0.0496777492736",
"0.2": "0.141936426496",
"0.14": "0.0993554985472",
"-0.14": "-0.0993554985472"
},
"volShockDown": {
"0": "0",
"-0.07": "-0.0496777492736",
"-0.2": "-0.141936426496",
"0.07": "0.0496777492736",
"0.2": "0.141936426496",
"0.14": "0.0993554985472",
"-0.14": "-0.0993554985472"
},
"volShockUp": {
"0": "0",
"-0.07": "-0.0496777492736",
"-0.2": "-0.141936426496",
"0.07": "0.0496777492736",
"0.2": "0.141936426496",
"0.14": "0.0993554985472",
"-0.14": "-0.0993554985472"
}
},
"mr2": "0",
"mr3": "0",
"mr4": "0",
"mr5": "0",
"mr6": "0.141936426496",
"mr6FinalResult": {
"pnl": "-0.283872852992",
"spotShock": "-0.4"
},
"mr7": "0.004967159106",
"portfolios": [
{
"amt": "10",
"delta": "0.009998760367833",
"gamma": "0",
"instId": "LTC-USDT-SWAP",
"instType": "SWAP",
"isRealPos": false,
"notionalUsd": "0.7098000000000001",
"theta": "0",
"vega": "0"
}
],
"riskUnit": "LTC-USDT",
"theta": "0",
"vega": "0"
}
],
"totalImr": "9689.820690834878",
"totalMmr": "1981.5700860507657",
"ts": "1705915813386"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| eq | String | 账户有效保证金 |
| totalMmr | String | 账户维持保证金，单位为USD |
| totalImr | String | 账户初始保证金占用，单位为USD |
| borrowMmr | String | 账户借币维持保证金，单位为USD |
| derivMmr | String | 账户衍生品维持保证金，单位为USD |
| marginRatio | String | 账户全仓保证金率 |
| ts | String | 账户信息的更新时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| assets | Array of object | 资产信息 |
| > ccy | String | 币种，如 BTC |
| > availEq | String | 币种权益 |
| > spotInUse | String | 现货对冲占用 |
| > borrowMmr | String | 借币维持保证金，单位为USD |
| > borrowImr | String | 借币初始保证金，单位为USD |
| riskUnitData | Array of object | Risk unit 相关信息 |
| > riskUnit | String | 账户内的 risk unit，如 BTC-USDT |
| > indexUsd | String | Risk unit 指数对应的美元价值 |
| > mmr | String | Risk unit 维度的维持保证金，单位为USD |
| > imr | String | Risk unit 维度的初始保证金，单位为USD |
| > mr1 | String | 现货和波动率变化风险 (适用于所有衍生品，以及在现货对冲模式下的现货) |
| > mr2 | String | 时间价值风险 (仅适用于期权) |
| > mr3 | String | 波动率跨期风险 (仅适用于期权) |
| > mr4 | String | 基差风险 (适用于所有衍生品) |
| > mr5 | String | 利率风险 (仅适用于期权) |
| > mr6 | String | 极端市场波动风险 (适用于所有衍生品，以及在现货对冲模式下的现货) |
| > mr7 | String | 减仓成本 (适用于所有衍生品) |
| > mr1Scenarios | Object | MR1 的压力测试场景分析 |
| >> volShockDown | Object | 波动率向下时，不同价格波动比率下的压力测试盈亏 值为 { change: value, ...} change：价格波动比率（百分比），如 0.01 代表 1%value：压力测试下的盈亏，单位为USD如 {"-0.15":"-2333.23", ...} |
| >> volSame | Object | 波动率不变时，不同价格波动比率下的压力测试盈亏 值为 { change: value, ...} change：价格波动比率（百分比），如 0.01 代表 1%value：压力测试下的盈亏，单位为USD如 {"-0.15":"-2333.23", ...} |
| >> volShockUp | Object | 波动率向上时，不同价格波动比率下的压力测试盈亏 值为 { change: value, ...} change：价格波动比率（百分比），如 0.01 代表 1%value：压力测试下的盈亏，单位为USD如 {"-0.15":"-2333.23", ...} |
| > mr1FinalResult | Object | MR1 最大亏损场景 |
| >> pnl | String | MR1 最大亏损压测盈亏，单位为 USD |
| >> spotShock | String | MR1 最大亏损的价格波动（百分比），如 0.01 代表 1% |
| >> volShock | String | MR1 最大亏损波动率趋势down：波动率向下unchange：波动率不变up：波动率向上 |
| > mr6FinalResult | String | MR6 最大亏损场景 |
| >> pnl | String | MR6 最大亏损压测盈亏，单位为 USD |
| >> spotShock | String | MR6 最大亏损的价格波动（百分比），如 0.01 代表 1% |
| > delta | String | (Risk unit 维度) 合约价格随标的价格变动的比例 当标的价格变动 x 时，合约价格变动约为此 Delta 数值乘以 x |
| > gamma | String | (Risk unit 维度) 标的价格对 Delta 值的影响程度 当标的价格变动 x% 时，期权 Delta 值的变动约为此 Gamma 数值乘以 x% |
| > theta | String | (Risk unit 维度) 距离到期日时间缩短 1 天，该合约价格的变化量 |
| > vega | String | (Risk unit 维度) 标的波动率增加 1%，该合约价格的变化量 |
| > portfolios | Array of object | 资产组合 |
| >> instId | String | 产品ID，如 BTC-USDT-SWAP |
| >> instType | String | 产品类型SPOT：现货SWAP：永续合约FUTURES：交割合约OPTION：期权 |
| >> amt | String | instType为SPOT，代表现货对冲占用instType为SWAP/FUTURES/OPTION，代表仓位数量。 |
| >> notionalUsd | String | 美金价值 |
| >> delta | String | instType为SPOT，代表资产数量。instType为SWAP/FUTURES/OPTION，代表(产品层面) 合约价格随标的价格变动的比例。 |
| >> gamma | String | (产品层面) 标的价格对 Delta 值的影响程度instType为SPOT，返回"" |
| >> theta | String | (产品层面) 距离到期日时间缩短 1 天，该合约价格的变化量instType为SPOT，返回"" |
| >> vega | String | (产品层面) 标的波动率增加 1%，该合约价格的变化量instType为SPOT，返回"" |
| >> isRealPos | Boolean | 是否为真实仓位instType为SWAP/FUTURES/OPTION，该字段有效，其他都默认返回false |
设置现货对冲占用
用户自定义现货对冲占用数量，不代表实际现货对冲占用数量。仅适用于组合保证金模式。
限速：10次/2s
限速规则：UserID
HTTP请求
POST /api/v5/account/set-riskOffset-amt
请求示例
# 设置现货对冲占用
POST /api/v5/account/set-riskOffset-amt
{
"ccy": "BTC",
"clSpotInUseAmt": "0.5"
}
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| ccy | String | Yes | 币种，如BTC |
| clSpotInUseAmt | String | Yes | 用户自定义现货对冲数量 |
返回示例
{
"code": "0",
"msg": "",
"data": [
{
"ccy": "BTC",
"clSpotInUseAmt": "0.5"
}
]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ccy | String | 币种，如BTC |
| clSpotInUseAmt | String | 用户自定义现货对冲数量 |
查看账户Greeks
获取账户资产的greeks信息。
限速：10次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/greeks
请求示例
# 获取账户中所有资产的greeks
GET /api/v5/account/greeks
# 获取账户中BTC的greeks
GET /api/v5/account/greeks?ccy=BTC
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 查看账户Greeks
result = accountAPI.get_greeks()
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| ccy | String | 否 | 币种，如 BTC |
返回结果
{
"code":"0",
"data":[
{
"thetaBS": "",
"thetaPA":"",
"deltaBS":"",
"deltaPA":"",
"gammaBS":"",
"gammaPA":"",
"vegaBS":"",
"vegaPA":"",
"ccy":"BTC",
"ts":"1620282889345"
}
],
"msg":""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| deltaBS | String | 美金本位账户资产delta |
| deltaPA | String | 币本位账户资产delta |
| gammaBS | String | 美金本位账户资产gamma，仅适用于期权 |
| gammaPA | String | 币本位账户资产gamma，仅适用于期权 |
| thetaBS | String | 美金本位账户资产theta，仅适用于期权 |
| thetaPA | String | 币本位账户资产theta，仅适用于期权 |
| vegaBS | String | 美金本位账户资产vega，仅适用于期权 |
| vegaPA | String | 币本位账户资产vega，仅适用于期权 |
| ccy | String | 币种 |
| ts | String | 获取greeks的时间，Unix时间戳的毫秒数格式，如 1597026383085 |
获取组合保证金模式仓位限制
仅支持获取组合保证金模式下，交割、永续和期权的全仓仓位限制。
限速：10次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/position-tiers
请求示例
# 查看BTC-USDT在组合保证金模式下的全仓限制
GET /api/v5/account/position-tiers?instType=SWAP&uly=BTC-USDT
import okx.Account as Account
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘:0 , 模拟盘:1
accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)
# 获取组合保证金模式仓位限制
result = accountAPI.get_account_position_tiers(
instType="SWAP",
uly="BTC-USDT"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 是 | 产品类型SWAP：永续合约FUTURES：交割合约OPTION：期权 |
| uly | String | 可选 | 标的指数，如 BTC-USDT，支持多个查询（不超过3个），uly之间半角逗号分隔适用于 交割/永续/期权uly与instFamily必须传一个,若传两个，以instFamily为主 |
| instFamily | String | 可选 | 交易品种，如 BTC-USDT，支持多个查询（不超过5个），instFamily之间半角逗号分隔适用于 交割/永续/期权uly与instFamily必须传一个,若传两个，以instFamily为主 |
返回结果
{
"code": "0",
"data": [
{
"instFamily": "BTC-USD",
"maxSz": "10000",
"posType": "",
"uly": "BTC-USDT"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| uly | String | 标的指数 适用于 交割/永续/期权 |
| instFamily | String | 交易品种 适用于 交割/永续/期权 |
| maxSz | String | 最大持仓量 |
| posType | String | 限仓类型，仅适用于组合保证金模式下的期权全仓。1：所有合约挂单 + 持仓张数，2：所有合约总挂单张数，3：所有合约总挂单单数，4：同方向合约挂单 + 持仓张数，5：单一合约总挂单单数，6：单一合约挂单 + 持仓张数，7：单笔挂单张数" |
设置组合保证金账户风险对冲模式
设置组合保证金账户风险对冲模式
限速：10次/2s
限速规则：UserID
HTTP请求
POST /api/v5/account/set-riskOffset-type
请求示例
POST /api/v5/account/set-riskOffset-type
body
{
"type":"1"
}
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| type | String | 是 | 风险对冲模式1：现货对冲(USDT)2：现货对冲(币)3：衍生品对冲4：现货对冲(USDC) |
返回结果
{
"code": "0",
"msg": "",
"data": [{
"type":"1"
}]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| type | String | 风险对冲模式1：现货对冲(USDT)2：现货对冲(币)3：衍生品对冲4：现货对冲(USDC) |
开通期权交易
限速：5次/2s
限速规则：UserID
HTTP请求
POST /api/v5/account/activate-option
请求示例
POST /api/v5/account/activate-option
请求参数
无
返回结果
{
"code": "0",
"msg": "",
"data": [{
"ts": "1600000000000"
}]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ts | String | 开通时间 |
设置自动借币
仅适用于跨币种保证金模式和组合保证金模式
限速：5次/2s
限速规则：UserID
HTTP请求
POST /api/v5/account/set-auto-loan
请求示例
POST /api/v5/account/set-auto-loan
body
{
"autoLoan":true,
}
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| autoLoan | Boolean | 否 | 是否自动借币 有效值为 true, false默认为 true |
返回结果
{
"code": "0",
"msg": "",
"data": [{
"autoLoan": true
}]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| autoLoan | Boolean | 是否自动借币 |
设置账户模式
账户模式的首次设置，需要在网页或手机app上进行。
限速：5次/2s
限速规则：UserID
HTTP请求
POST /api/v5/account/set-account-level
请求示例
POST /api/v5/account/set-account-level
body
{
"acctLv":"1"
}
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| acctLv | String | 是 | 账户模式1: 现货模式2: 现货和合约模式 3: 跨币种保证金模式 4: 组合保证金模式 |
返回结果
{
"code":"0",
"msg":"",
"data" :[
{
"acctLv":"1"
}
]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| acctLv | String | 账户模式 |
重置 MMP 状态
一旦 MMP 被触发，可以使用该接口解冻。
仅适用于组合保证金账户模式下的期权订单，且有 MMP 权限。
限速：5次/2s
限速规则：UserID
HTTP请求
POST /api/v5/account/mmp-reset
请求示例
POST /api/v5/account/mmp-reset
body
{
"instType":"OPTION",
"instFamily":"BTC-USD"
}
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 否 | 交易产品类型OPTION:期权默认为期权 |
| instFamily | String | 是 | 交易品种 |
返回结果
{
"code":"0",
"msg":"",
"data":[
{
"result":true
}
]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| result | Boolean | 重置结果true:将做市商保护状态重置为了 inactive 状态false：重置失败 |
设置 MMP
可以使用该接口进行 MMP 的配置。
仅适用于组合保证金账户模式下的期权订单，且有 MMP 权限。
限速：2次/10s
限速规则：UserID
HTTP请求
POST /api/v5/account/mmp-config
请求示例
POST /api/v5/account/mmp-config
body
{
"instFamily":"BTC-USD",
"timeInterval":"5000",
"frozenInterval":"2000",
"qtyLimit": "100"
}
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instFamily | String | 是 | 交易品种 |
| timeInterval | String | 是 | 时间窗口 (毫秒)。 "0" 代表停用 MMP |
| frozenInterval | String | 是 | 冻结时间长度 (毫秒)。 "0" 代表一直冻结，直到调用 "重置 MMP 状态" 接口解冻 |
| qtyLimit | String | 是 | 成交数量的上限 需大于 0 |
返回结果
{
"code": "0",
"msg": "",
"data": [
{
"frozenInterval":"2000",
"instFamily":"BTC-USD",
"qtyLimit": "100",
"timeInterval":"5000"
}
]
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instFamily | String | 交易品种 |
| timeInterval | String | 时间窗口 (毫秒) |
| frozenInterval | String | 冻结时间长度 (毫秒) |
| qtyLimit | String | 成交张数的上限 |
查看 MMP 配置
可以使用该接口获取 MMP 的配置信息。
仅适用于组合保证金账户模式下的期权订单，且有 MMP 权限。
限速：5次/2s
限速规则：UserID
HTTP请求
GET /api/v5/account/mmp-config
请求示例
GET /api/v5/account/mmp-config?instFamily=BTC-USD
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instFamily | String | 否 | 交易品种 |
返回结果
{
"code": "0",
"data": [
{
"frozenInterval": "2000",
"instFamily": "ETH-USD",
"mmpFrozen": true,
"mmpFrozenUntil": "2326882",
"qtyLimit": "10",
"timeInterval": "5000"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instFamily | String | 交易品种 |
| mmpFrozen | Boolean | 是否 MMP 被触发. true 或者 false |
| mmpFrozenUntil | String | 如果配置了frozenInterval且mmpFrozen = true，则为不再触发MMP时的时间窗口（单位为ms），否则为“” |
| timeInterval | String | 时间窗口 (毫秒) |
| frozenInterval | String | 冻结时间长度 (毫秒)。 "0" 代表一直冻结，直到调用 "重置 MMP 状态" 接口解冻 |
| qtyLimit | 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 | 现货累计收益率。点击了解更多 |
持仓频道
获取持仓信息，首次订阅按照订阅维度推送数据，此外，当下单、撤单等事件触发时，推送数据以及按照订阅维度定时推送数据
该频道的并发连接受到如下规则限制：WebSocket 连接限制
服务地址
/ws/v5/private (需要登录)
请求示例：单个
{
"op": "subscribe",
"args": [{
"channel": "positions",
"instType": "FUTURES",
"instFamily": "BTC-USD",
"instId": "BTC-USD-200329"
}]
}
请求示例
{
"op": "subscribe",
"args": [
{
"channel": "positions",
"instType": "ANY",
"extraParams": "
{
\"updateInterval\": \"0\"
}
"
}
]
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| op | String | 是 | 操作subscribeunsubscribe |
| args | Array | 是 | 请求订阅的频道列表 |
| > channel | String | 是 | 频道名positions |
| > instType | String | 是 | 产品类型MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权ANY：全部 |
| > instFamily | String | 否 | 交易品种 适用于 交割/永续/期权 |
| > instId | String | 否 | 产品ID |
| > extraParams | String | 否 | 额外配置 |
| >> updateInterval | int | 否 | 0: 仅根据持仓事件推送数据2000, 3000, 4000: 根据持仓事件推送，且根据设置的时间间隔定时推送（ms）若不添加该字段或将其设置为上述合法值以外的其他值，数据将根据事件推送并大约每 5 秒定期推送一次。 使用该字段需严格遵守以下格式。 "extraParams": " { \"updateInterval\": \"0\" } " |
成功返回示例：单个
{
"event": "subscribe",
"arg": {
"channel": "positions",
"instType": "FUTURES",
"instFamily": "BTC-USD",
"instId": "BTC-USD-200329"
},
"connId": "a4d3ae55"
}
成功返回示例
{
"event": "subscribe",
"arg": {
"channel": "positions",
"instType": "ANY"
},
"connId": "a4d3ae55"
}
失败返回示例
{
"event": "error",
"code": "60012",
"msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"positions\", \"instType\" : \"FUTURES\"}]}",
"connId": "a4d3ae55"
}
返回参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| event | String | 是 | 事件，subscribe unsubscribe error |
| arg | Object | 否 | 订阅的频道 |
| > channel | String | 是 | 频道名 |
| > instType | String | 是 | 产品类型MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权 ANY：全部 |
| > instFamily | String | 否 | 交易品种 适用于 交割/永续/期权 |
| > instId | String | 否 | 产品ID |
| code | String | 否 | 错误码 |
| msg | String | 否 | 错误消息 |
| connId | String | 是 | WebSocket连接ID |
推送示例：单个
{
"arg":{
"channel":"positions",
"uid": "77982378738415879",
"instType":"FUTURES"
},
"data":[
{
"adl":"1",
"availPos":"1",
"avgPx":"2566.31",
"cTime":"1619507758793",
"ccy":"ETH",
"deltaBS":"",
"deltaPA":"",
"gammaBS":"",
"gammaPA":"",
"imr":"",
"instId":"ETH-USD-210430",
"instType":"FUTURES",
"interest":"0",
"idxPx":"2566.13",
"last":"2566.22",
"lever":"10",
"liab":"",
"liabCcy":"",
"liqPx":"2352.8496681818233",
"markPx":"2353.849",
"margin":"0.0003896645377994",
"mgnMode":"isolated",
"mgnRatio":"11.731726509588816",
"mmr":"0.0000311811092368",
"notionalUsd":"2276.2546609009605",
"optVal":"",
"pTime":"1619507761462",
"pendingCloseOrdLiabVal":"0.1",
"pos":"1",
"baseBorrowed": "",
"baseInterest": "",
"quoteBorrowed": "",
"quoteInterest": "",
"posCcy":"",
"posId":"307173036051017730",
"posSide":"long",
"spotInUseAmt": "",
"clSpotInUseAmt": "",
"maxSpotInUseAmt": "",
"spotInUseCcy": "",
"bizRefId": "",
"bizRefType": "",
"thetaBS":"",
"thetaPA":"",
"tradeId":"109844",
"uTime":"1619507761462",
"upl":"-0.0000009932766034",
"uplLastPx":"-0.0000009932766034",
"uplRatio":"-0.0025490556801078",
"uplRatioLastPx":"-0.0025490556801078",
"vegaBS":"",
"vegaPA":"",
"realizedPnl":"0.001",
"pnl":"0.0011",
"fee":"-0.0001",
"fundingFee":"0",
"liqPenalty":"0",
"closeOrderAlgo":[
{
"algoId":"123",
"slTriggerPx":"123",
"slTriggerPxType":"mark",
"tpTriggerPx":"123",
"tpTriggerPxType":"mark",
"closeFraction":"0.6"
},
{
"algoId":"123",
"slTriggerPx":"123",
"slTriggerPxType":"mark",
"tpTriggerPx":"123",
"tpTriggerPxType":"mark",
"closeFraction":"0.4"
}
]
}
]
}
推送示例
{
"arg": {
"channel": "positions",
"uid": "77982378738415879",
"instType": "ANY"
},
"data": [{
"adl":"1",
"availPos":"1",
"avgPx":"2566.31",
"cTime":"1619507758793",
"ccy":"ETH",
"deltaBS":"",
"deltaPA":"",
"gammaBS":"",
"gammaPA":"",
"imr":"",
"instId":"ETH-USD-210430",
"instType":"FUTURES",
"interest":"0",
"idxPx":"2566.13",
"last":"2566.22",
"usdPx":"",
"bePx":"2353.949",
"lever":"10",
"liab":"",
"liabCcy":"",
"liqPx":"2352.8496681818233",
"markPx":"2353.849",
"margin":"0.0003896645377994",
"mgnMode":"isolated",
"mgnRatio":"11.731726509588816",
"mmr":"0.0000311811092368",
"notionalUsd":"2276.2546609009605",
"optVal":"",
"pendingCloseOrdLiabVal":"0.1",
"pTime":"1619507761462",
"pos":"1",
"baseBorrowed": "",
"baseInterest": "",
"quoteBorrowed": "",
"quoteInterest": "",
"posCcy":"",
"posId":"307173036051017730",
"posSide":"long",
"spotInUseAmt": "",
"clSpotInUseAmt": "",
"maxSpotInUseAmt": "",
"spotInUseCcy": "",
"bizRefId": "",
"bizRefType": "",
"thetaBS":"",
"thetaPA":"",
"tradeId":"109844",
"uTime":"1619507761462",
"upl":"-0.0000009932766034",
"uplLastPx":"-0.0000009932766034",
"uplRatio":"-0.0025490556801078",
"uplRatioLastPx":"-0.0025490556801078",
"vegaBS":"",
"vegaPA":"",
"realizedPnl":"0.001",
"pnl":"0.0011",
"fee":"-0.0001",
"fundingFee":"0",
"liqPenalty":"0",
"closeOrderAlgo":[
{
"algoId":"123",
"slTriggerPx":"123",
"slTriggerPxType":"mark",
"tpTriggerPx":"123",
"tpTriggerPxType":"mark",
"closeFraction":"0.6"
},
{
"algoId":"123",
"slTriggerPx":"123",
"slTriggerPxType":"mark",
"tpTriggerPx":"123",
"tpTriggerPxType":"mark",
"closeFraction":"0.4"
}
]
}, {
"adl":"1",
"availPos":"1",
"avgPx":"2566.31",
"cTime":"1619507758793",
"ccy":"ETH",
"deltaBS":"",
"deltaPA":"",
"gammaBS":"",
"gammaPA":"",
"imr":"",
"instId":"ETH-USD-SWAP",
"instType":"SWAP",
"interest":"0",
"idxPx":"2566.13",
"last":"2566.22",
"usdPx":"",
"bePx":"2353.949",
"lever":"10",
"liab":"",
"liabCcy":"",
"liqPx":"2352.8496681818233",
"markPx":"2353.849",
"margin":"0.0003896645377994",
"mgnMode":"isolated",
"mgnRatio":"11.731726509588816",
"mmr":"0.0000311811092368",
"notionalUsd":"2276.2546609009605",
"optVal":"",
"pendingCloseOrdLiabVal":"0.1",
"pTime":"1619507761462",
"pos":"1",
"baseBorrowed": "",
"baseInterest": "",
"quoteBorrowed": "",
"quoteInterest": "",
"posCcy":"",
"posId":"307173036051017730",
"posSide":"long",
"spotInUseAmt": "",
"clSpotInUseAmt": "",
"maxSpotInUseAmt": "",
"spotInUseCcy": "",
"bizRefId": "",
"bizRefType": "",
"thetaBS":"",
"thetaPA":"",
"tradeId":"109844",
"uTime":"1619507761462",
"upl":"-0.0000009932766034",
"uplLastPx":"-0.0000009932766034",
"uplRatio":"-0.0025490556801078",
"uplRatioLastPx":"-0.0025490556801078",
"vegaBS":"",
"vegaPA":"",
"realizedPnl":"0.001",
"pnl":"0.0011",
"fee":"-0.0001",
"fundingFee":"0",
"liqPenalty":"0",
"closeOrderAlgo":[
{
"algoId":"123",
"slTriggerPx":"123",
"slTriggerPxType":"mark",
"tpTriggerPx":"123",
"tpTriggerPxType":"mark",
"closeFraction":"0.6"
},
{
"algoId":"123",
"slTriggerPx":"123",
"slTriggerPxType":"mark",
"tpTriggerPx":"123",
"tpTriggerPxType":"mark",
"closeFraction":"0.4"
}
]
}]
}
推送数据参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| arg | Object | 订阅成功的频道 |
| > channel | String | 频道名 |
| > uid | String | 用户标识 |
| > instType | String | 产品类型 |
| > instFamily | String | 交易品种 |
| > instId | String | 产品ID |
| data | Array | 订阅的数据 |
| > instType | String | 产品类型 |
| > mgnMode | String | 保证金模式， cross：全仓 isolated：逐仓 |
| > posId | String | 持仓ID |
| > posSide | String | 持仓方向long：开平仓模式开多short：开平仓模式开空net：买卖模式（交割/永续/期权：pos为正代表开多，pos为负代表开空。币币杠杆：posCcy为交易货币时，代表开多；posCcy为计价货币时，代表开空。） |
| > pos | String | 持仓数量，逐仓自主划转模式下，转入保证金后会产生pos为0的仓位 |
| > baseBal | String | 币币杠杆（逐仓一键借币模式） |
| > quoteBal | String | 币币杠杆（逐仓一键借币模式） |
| > baseBorrowed | String | 币币杠杆（逐仓一键借币模式） |
| > baseInterest | String | 币币杠杆（逐仓一键借币模式） |
| > quoteBorrowed | String | 币币杠杆（逐仓一键借币模式） |
| > quoteInterest | String | 币币杠杆（逐仓一键借币模式） |
| > posCcy | String | 持仓数量币种，仅适用于币币杠杆 |
| > availPos | String | 可平仓数量，适用于 币币杠杆,交割/永续（开平仓模式），期权对于杠杆仓位，平仓时，杠杆还清负债后，余下的部分会视为币币交易，如果想要减少币币交易的数量，可通过"获取最大可用数量"接口获取只减仓的可用数量。 |
| > avgPx | String | 开仓平均价 |
| > upl | String | 未实现收益（以标记价格计算） |
| > uplRatio | String | 未实现收益率（以标记价格计算 |
| > uplLastPx | String | 以最新成交价格计算的未实现收益，主要做展示使用，实际值还是 upl |
| > uplRatioLastPx | String | 以最新成交价格计算的未实现收益率 |
| > instId | String | 产品ID，如 BTC-USDT-SWAP |
| > lever | String | 杠杆倍数，不适用于期权卖方 |
| > liqPx | String | 预估强平价 不适用于 期权 |
| > markPx | String | 最新标记价格 |
| > imr | String | 初始保证金，仅适用于全仓 |
| > margin | String | 保证金余额，仅适用于逐仓，可增减 |
| > mgnRatio | String | 保证金率 |
| > mmr | String | 维持保证金 |
| > liab | String | 负债额，仅适用于币币杠杆 |
| > liabCcy | String | 负债币种，仅适用于币币杠杆 |
| > interest | String | 利息，已经生成未扣利息 |
| > tradeId | String | 最新成交ID |
| > notionalUsd | String | 以美金价值为单位的持仓数量 |
| > optVal | String | 期权价值，仅适用于期权 |
| > pendingCloseOrdLiabVal | String | 逐仓杠杆负债对应平仓挂单的数量 |
| > adl | String | 信号区，分为5档，从1到5，数字越小代表adl强度越弱 |
| > bizRefId | String | 外部业务id，e.g. 体验券id |
| > bizRefType | String | 外部业务类型 |
| > ccy | String | 占用保证金的币种 |
| > last | String | 最新成交价 |
| > idxPx | String | 最新指数价格 |
| > usdPx | String | 保证金币种的市场最新美金价格 仅适用于期权 |
| > bePx | String | 盈亏平衡价 |
| > deltaBS | String | 美金本位持仓仓位delta，仅适用于期权 |
| > deltaPA | String | 币本位持仓仓位delta，仅适用于期权 |
| > gammaBS | String | 美金本位持仓仓位gamma，仅适用于期权 |
| > gammaPA | String | 币本位持仓仓位gamma，仅适用于期权 |
| > thetaBS | String | 美金本位持仓仓位theta，仅适用于期权 |
| > thetaPA | String | 币本位持仓仓位theta，仅适用于期权 |
| > vegaBS | String | 美金本位持仓仓位vega，仅适用于期权 |
| > vegaPA | String | 币本位持仓仓位vega，仅适用于期权 |
| > spotInUseAmt | String | 现货对冲占用数量 适用于 组合保证金模式 |
| > clSpotInUseAmt | String | 用户自定义现货占用数量 适用于 组合保证金模式 |
| > maxSpotInUseAmt | String | 系统计算得到的最大可能现货占用数量 适用于 组合保证金模式 |
| > spotInUseCcy | String | 现货对冲占用币种，如 BTC适用于 组合保证金模式 |
| > realizedPnl | String | 已实现收益 仅适用于 交割/永续/期权realizedPnl=pnl+fee+fundingFee+liqPenalty |
| > pnl | String | 平仓订单累计收益额 |
| > fee | String | 累计手续费金额，正数代表平台返佣 ，负数代表平台扣除 |
| > fundingFee | String | 累计资金费用 |
| > liqPenalty | String | 累计爆仓罚金，有值时为负数。 |
| > closeOrderAlgo | Array | 平仓策略委托订单。调用策略委托下单，且closeFraction=1 时，该数组才会有值。 |
| >> algoId | String | 策略委托单ID |
| >> slTriggerPx | String | 止损触发价 |
| >> slTriggerPxType | String | 止损触发价类型last：最新价格index：指数价格mark：标记价格 |
| >> tpTriggerPx | String | 止盈委托价 |
| >> tpTriggerPxType | String | 止盈触发价类型last：最新价格index：指数价格mark：标记价格 |
| >> closeFraction | String | 策略委托触发时，平仓的百分比。1 代表100% |
| > cTime | String | 持仓创建时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| > uTime | String | 最近一次持仓更新时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| > pTime | String | 持仓信息的推送时间，Unix时间戳的毫秒数格式，如 1597026383085 |
账户余额和持仓频道
获取账户余额和持仓信息，首次订阅按照订阅维度推送数据，此外，当成交、资金划转等事件触发时，推送数据。
该频道适用于尽快获取账户现金余额和仓位资产变化的信息。
该频道的并发连接受到如下规则限制：WebSocket 连接限制
服务地址
/ws/v5/private (需要登录)
请求示例
{
"op": "subscribe",
"args": [{
"channel": "balance_and_position"
}]
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| op | String | 是 | 操作subscribeunsubscribe |
| args | Array | 是 | 请求订阅的频道列表 |
| > channel | String | 是 | 频道名balance_and_position |
成功返回示例
{
"event": "subscribe",
"arg": {
"channel": "balance_and_position"
},
"connId": "a4d3ae55"
}
失败返回示例
{
"event": "error",
"code": "60012",
"msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"balance_and_position\"}]}",
"connId": "a4d3ae55"
}
返回参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| event | String | 是 | 事件subscribeunsubscribeerror |
| arg | Object | 否 | 订阅的频道 |
| > channel | String | 是 | 频道名balance_and_position |
| code | String | 否 | 错误码 |
| msg | String | 否 | 错误消息 |
| connId | String | 是 | WebSocket连接ID |
推送示例
{
"arg": {
"channel": "balance_and_position",
"uid": "77982378738415879"
},
"data": [{
"pTime": "1597026383085",
"eventType": "snapshot",
"balData": [{
"ccy": "BTC",
"cashBal": "1",
"uTime": "1597026383085"
}],
"posData": [{
"posId": "1111111111",
"tradeId": "2",
"instId": "BTC-USD-191018",
"instType": "FUTURES",
"mgnMode": "cross",
"posSide": "long",
"pos": "10",
"ccy": "BTC",
"posCcy": "",
"avgPx": "3320",
"uTime": "1597026383085"
}],
"trades": [{
"instId": "BTC-USD-191018",
"tradeId": "2",
}]
}]
}
推送数据参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| arg | Object | 请求订阅的频道 |
| > channel | String | 频道名 |
| > uid | String | 用户标识 |
| data | Array | 订阅的数据 |
| > pTime | String | 推送时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| > eventType | String | 事件类型snapshot：首推快照delivered：交割exercised：行权transferred：划转filled：成交liquidation：强平claw_back：穿仓补偿adl：ADL自动减仓funding_fee：资金费adjust_margin：调整保证金set_leverage：设置杠杆interest_deduction：扣息 |
| > balData | String | 余额数据 |
| >> ccy | String | 币种 |
| >> cashBal | String | 币种余额 |
| >> uTime | String | 币种余额信息的更新时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| > posData | String | 持仓数据 |
| >> posId | String | 持仓ID |
| >> tradeId | String | 最新成交ID |
| >> instId | String | 交易产品ID，如 BTC-USD-180213 |
| >> instType | String | 交易产品类型MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权 |
| >> mgnMode | String | 保证金模式isolated, cross |
| >> avgPx | String | 开仓平均价 |
| >> ccy | String | 占用保证金的币种 |
| >> posSide | String | 持仓方向long，short，net |
| >> pos | String | 持仓数量，逐仓自主划转模式下，转入保证金后会产生pos为0的仓位 |
| >> baseBal | String | 适用于 币币杠杆（逐仓一键借币模式） |
| >> quoteBal | String | 适用于 币币杠杆（逐仓一键借币模式） |
| >> posCcy | String | 持仓数量币种 只适用于币币杠杆仓位。当是交割、永续、期权持仓时，该字段返回“” |
| >> uTime | String | 仓位信息的更新时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| > trades | Array | 成交数据 |
| >> instId | String | 产品ID，如 BTC-USDT |
| >> tradeId | String | 最新成交ID |
爆仓风险预警推送频道
此推送频道仅作为风险提示，不建议作为策略交易的风险判断。
在行情剧烈波动的情况下，可能会出现此消息推送的同时仓位已经被强平的可能性。
预警会在某一个逐仓仓位有风险时推送。预警会在所有全仓仓位有风险时推送。
该频道的并发连接受到如下规则限制：WebSocket 连接限制
服务地址
/ws/v5/private (需要登录)
请求示例
{
"op": "subscribe",
"args": [{
"channel": "liquidation-warning",
"instType": "ANY"
}]
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| op | String | 是 | 操作subscribeunsubscribe |
| args | Array | 是 | 请求订阅的频道列表 |
| > channel | String | 是 | 频道名liquidation-warning |
| > instType | String | 是 | 产品类型MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权ANY：全部 |
| > instFamily | String | 否 | 交易品种 适用于 交割/永续/期权 |
| > instId | String | 否 | 产品ID |
成功返回示例：单个
{
"event": "subscribe",
"arg": {
"channel": "liquidation-warning",
"instType": "FUTURES",
"instFamily": "BTC-USD",
"instId": "BTC-USD-200329"
},
"connId": "a4d3ae55"
}
失败返回示例
{
"event": "error",
"code": "60012",
"msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"liquidation-warning\", \"instType\" : \"FUTURES\"}]}",
"connId": "a4d3ae55"
}
返回参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| event | String | 是 | 事件subscribeunsubscribeerror |
| arg | Object | 否 | 订阅的频道 |
| > channel | String | 是 | 频道名 ，liquidation-warning |
| > instType | String | 是 | 产品类型MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权 ANY：全部 |
| > instFamily | String | 否 | 交易品种 适用于 交割/永续/期权 |
| > instId | String | 否 | 产品ID |
| code | String | 否 | 错误码 |
| msg | String | 否 | 错误消息 |
| connId | String | 是 | WebSocket连接ID |
推送示例：单个
{
"arg":{
"channel":"liquidation-warning",
"uid": "77982378738415879",
"instType":"FUTURES"
},
"data":[
{
"cTime":"1619507758793",
"ccy":"ETH",
"instId":"ETH-USD-210430",
"instType":"FUTURES",
"lever":"10",
"markPx":"2353.849",
"mgnMode":"isolated",
"mgnRatio":"11.731726509588816",
"pTime":"1619507761462",
"pos":"1",
"posCcy":"",
"posId":"307173036051017730",
"posSide":"long",
"uTime":"1619507761462",
}
]
}
推送数据参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| arg | Object | 订阅成功的频道 |
| > channel | String | 频道名 |
| > uid | String | 用户标识 |
| > instType | String | 产品类型 |
| > instFamily | String | 交易品种 |
| > instId | String | 产品ID |
| data | Array | 订阅的数据 |
| > instType | String | 产品类型 |
| > mgnMode | String | 保证金模式， cross：全仓 isolated：逐仓 |
| > posId | String | 持仓ID |
| > posSide | String | 持仓方向long：开平仓模式开多short：开平仓模式开空net：买卖模式（交割/永续/期权：pos为正代表开多，pos为负代表开空。币币杠杆：posCcy为交易货币时，代表开多；posCcy为计价货币时，代表开空。） |
| > pos | String | 持仓数量 |
| > posCcy | String | 持仓数量币种，仅适用于币币杠杆 |
| > instId | String | 产品ID，如 BTC-USDT-SWAP |
| > lever | String | 杠杆倍数，不适用于期权卖方 |
| > markPx | String | 标记价格 |
| > mgnRatio | String | 保证金率 |
| > ccy | String | 占用保证金的币种 |
| > cTime | String | 持仓创建时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| > uTime | String | 最近一次持仓更新时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| > pTime | String | 持仓信息的推送时间，Unix时间戳的毫秒数格式，如 1597026383085 |
账户greeks频道
获取账户资产的greeks信息，首次订阅按照订阅维度推送数据，此外，当增加或者减少币种余额、持仓数量等事件触发时，推送数据以及按照订阅维度定时推送数据
该频道的并发连接受到如下规则限制：WebSocket 连接限制
服务地址
/ws/v5/private (需要登录)
请求示例：单个
{
"op": "subscribe",
"args": [{
"channel": "account-greeks",
"ccy": "BTC"
}]
}
请求示例
{
"op": "subscribe",
"args": [{
"channel": "account-greeks"
}]
}
请求参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| op | String | 是 | 操作subscribeunsubscribe |
| args | Array | 是 | 请求订阅的频道列表 |
| > channel | String | 是 | 频道名account-greeks |
| > ccy | String | 否 | 币种 |
成功返回示例：单个
{
"event": "subscribe",
"arg": {
"channel": "account-greeks",
"ccy": "BTC"
},
"connId": "a4d3ae55"
}
成功返回示例
{
"event": "subscribe",
"arg": {
"channel": "account-greeks"
},
"connId": "a4d3ae55"
}
失败返回示例
{
"event": "error",
"code": "60012",
"msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"account-greeks\", \"ccy\" : \"BTC\"}]}",
"connId": "a4d3ae55"
}
返回参数
| 参数 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| event | String | 是 | 事件subscribeunsubscribeerror |
| arg | Object | 否 | 订阅的频道 |
| > channel | String | 是 | 频道名account-greeks |
| > ccy | String | 否 | 币种 |
| code | String | 否 | 错误码 |
| msg | String | 否 | 错误消息 |
| connId | String | 是 | WebSocket连接ID |
推送示例：单个
{
"arg": {
"channel": "account-greeks",
"uid": "77982378738415879",
"ccy": "BTC"
},
"data": [
{
"thetaBS": "",
"thetaPA":"",
"deltaBS":"",
"deltaPA":"",
"gammaBS":"",
"gammaPA":"",
"vegaBS":"",
"vegaPA":"",
"ccy":"BTC",
"ts":"1620282889345"
}
]
}
推送示例
{
"arg": {
"channel": "account-greeks",
"uid": "77982378738415879",
"ccy": "BTC"
},
"data": [
{
"thetaBS": "",
"thetaPA":"",
"deltaBS":"",
"deltaPA":"",
"gammaBS":"",
"gammaPA":"",
"vegaBS":"",
"vegaPA":"",
"ccy":"BTC",
"ts":"1620282889345"
},
{
"thetaBS": "",
"thetaPA":"",
"deltaBS":"",
"deltaPA":"",
"gammaBS":"",
"gammaPA":"",
"vegaBS":"",
"vegaPA":"",
"ccy":"USDT",
"ts":"1620282889345"
}
]
}
推送数据参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| arg | Object | 请求订阅的频道 |
| > channel | String | 频道名 |
| > uid | String | 用户标识 |
| data | Array | 订阅的数据 |
| > deltaBS | String | 美金本位账户资产delta |
| > deltaPA | String | 币本位账户资产delta |
| > gammaBS | String | 美金本位账户资产gamma，仅适用于期权 |
| > gammaPA | String | 币本位账户资产gamma，仅适用于期权 |
| > thetaBS | String | 美金本位账户资产theta，仅适用于期权 |
| > thetaPA | String | 币本位账户资产theta，仅适用于期权 |
| > vegaBS | String | 美金本位账户资产vega，仅适用于期权 |
| > vegaPA | String | 币本位账户资产vega，仅适用于期权 |
| > ccy | String | 币种 |
| > ts | String | 获取greeks的时间，Unix时间戳的毫秒数格式，如 1597026383085 |
撮合交易
交易
交易功能模块下的API接口需要身份验证。
POST / 下单
只有当您的账户有足够的资金才能下单。
限速：60次/2s
跟单交易带单产品的限速：4次/2s
限速规则（期权以外）：UserID + Instrument ID
限速规则（只限期权）：UserID + Instrument Family
该接口限速同时受到 子账户限速 及 基于成交比率的子账户限速 限速规则的影响。
HTTP请求
POST /api/v5/trade/order
请求示例
# 币币下单
POST /api/v5/trade/order
body
{
"instId":"BTC-USDT",
"tdMode":"cash",
"clOrdId":"b15",
"side":"buy",
"ordType":"limit",
"px":"2.15",
"sz":"2"
}
import okx.Trade as Trade
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘: 0, 模拟盘: 1
tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)
# 现货模式限价单
result = tradeAPI.place_order(
instId="BTC-USDT",
tdMode="cash",
clOrdId="b15",
side="buy",
ordType="limit",
px="2.15",
sz="2"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 是 | 产品ID，如 BTC-USDT |
| tdMode | String | 是 | 交易模式 保证金模式： isolated：逐仓 ；cross：全仓 非保证金模式： cash：非保证金spot_isolated：现货逐仓(仅适用于现货带单) ，现货带单时，tdMode 的值需要指定为spot_isolated |
| ccy | String | 否 | 保证金币种，仅适用于现货和合约模式下的全仓杠杆订单 |
| clOrdId | String | 否 | 客户自定义订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 |
| tag | String | 否 | 订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。 |
| side | String | 是 | 订单方向buy：买， sell：卖 |
| posSide | String | 可选 | 持仓方向 在开平仓模式下必填，且仅可选择 long 或 short。 仅适用交割、永续。 |
| ordType | String | 是 | 订单类型 market：市价单limit：限价单 post_only：只做maker单 fok：全部成交或立即取消 ioc：立即成交并取消剩余 optimal_limit_ioc：市价委托立即成交并取消剩余（仅适用交割、永续）mmp：做市商保护(仅适用于组合保证金账户模式下的期权订单)mmp_and_post_only：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单) |
| sz | String | 是 | 委托数量 |
| px | String | 可选 | 委托价格，仅适用于limit、post_only、fok、ioc、mmp、mmp_and_post_only类型的订单期权下单时，px/pxUsd/pxVol 只能填一个 |
| pxUsd | String | 可选 | 以USD价格进行期权下单 仅适用于期权 期权下单时 px/pxUsd/pxVol 必填一个，且只能填一个 |
| pxVol | String | 可选 | 以隐含波动率进行期权下单，例如 1 代表 100% 仅适用于期权 期权下单时 px/pxUsd/pxVol 必填一个，且只能填一个 |
| reduceOnly | Boolean | 否 | 是否只减仓，true 或 false，默认false仅适用于 币币杠杆，以及买卖模式下的交割/永续仅适用于 现货和合约模式和跨币种保证金模式 |
| tgtCcy | String | 否 | 市价单委托数量sz的单位，仅适用于币币市价订单base_ccy: 交易货币 ；quote_ccy：计价货币买单默认 quote_ccy， 卖单默认base_ccy |
| banAmend | Boolean | 否 | 是否禁止币币市价改单，true 或 false，默认false 为true时，余额不足时，系统不会改单，下单会失败，仅适用于币币市价单 |
| quickMgnType | String | 否 | manual：手动，auto_borrow：自动借币，auto_repay：自动还币 默认是 manual：手动 |
| stpId | String | 否 | 用户自定义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时，执行市价止盈 |
| > tpOrdKind | String | 否 | 止盈订单类型condition: 条件单limit: 限价单默认为 condition |
| > slTriggerPx | String | 可选 | 止损触发价，如果填写此参数，必须填写 止损委托价 |
| > slOrdPx | String | 可选 | 止损委托价，如果填写此参数，必须填写 止损触发价 委托价格为-1时，执行市价止损 |
| > tpTriggerPxType | String | 否 | 止盈触发价类型last：最新价格index：指数价格mark：标记价格默认为 last |
| > slTriggerPxType | String | 否 | 止损触发价类型last：最新价格index：指数价格mark：标记价格默认为 last |
| > sz | String | 可选 | 数量。仅适用于“多笔止盈”的止盈订单，且对于“多笔止盈”的止盈订单必填 |
| > amendPxOnTriggerType | String | 否 | 是否启用开仓价止损，仅适用于分批止盈的止损订单，第一笔止盈触发时，止损触发价格是否移动到开仓均价止损0：不开启，默认值 1：开启，且止损触发价不能为空 |
返回结果
{
"code":"0",
"msg":"",
"data":[
{
"clOrdId":"oktswap6",
"ordId":"12345689",
"tag":"",
"ts":"1695190491421",
"sCode":"0",
"sMsg":""
}
],
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| code | String | 结果代码，0表示成功 |
| msg | String | 错误信息，代码为0时，该字段为空 |
| data | String | 包含结果的对象数组 |
| > ordId | String | 订单ID |
| > clOrdId | String | 客户自定义订单ID |
| > tag | String | 订单标签 |
| > ts | String | 系统完成订单请求处理的时间戳，Unix时间戳的毫秒数格式，如 1597026383085 |
| > sCode | String | 事件执行结果的code，0代表成功 |
| > sMsg | String | 事件执行失败或成功时的msg |
| inTime | String | REST网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 返回的时间是请求验证后的时间。 |
| outTime | String | REST网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
POST / 批量下单
每次最多可以批量提交20个新订单。请求参数应该按数组格式传递，会依次委托订单。
限速：300个/2s
跟单交易带单产品的限速：4个/2s
限速规则（期权以外）：UserID + Instrument ID
限速规则（只限期权）：UserID + Instrument Family
该接口限速同时受到 子账户限速 及 基于成交比率的子账户限速 限速规则的影响。
HTTP请求
POST /api/v5/trade/batch-orders
请求示例
# 币币批量下单
POST /api/v5/trade/batch-orders
body
[
{
"instId":"BTC-USDT",
"tdMode":"cash",
"clOrdId":"b15",
"side":"buy",
"ordType":"limit",
"px":"2.15",
"sz":"2"
},
{
"instId":"BTC-USDT",
"tdMode":"cash",
"clOrdId":"b16",
"side":"buy",
"ordType":"limit",
"px":"2.15",
"sz":"2"
}
]
import okx.Trade as Trade
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘: 0, 模拟盘: 1
tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)
# 批量下单
place_orders_without_clOrdId = [
{"instId": "BTC-USDT", "tdMode": "cash", "clOrdId": "b15", "side": "buy", "ordType": "limit", "px": "2.15", "sz": "2"},
{"instId": "BTC-USDT", "tdMode": "cash", "clOrdId": "b16", "side": "buy", "ordType": "limit", "px": "2.15", "sz": "2"}
]
result = tradeAPI.place_multiple_orders(place_orders_without_clOrdId)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 是 | 产品ID，如 BTC-USDT |
| tdMode | String | 是 | 交易模式 保证金模式： isolated：逐仓 ；cross：全仓 非保证金模式： cash：非保证金spot_isolated：现货逐仓(仅适用于现货带单) ，现货带单时，tdMode 的值需要指定为spot_isolated |
| ccy | String | 否 | 保证金币种，仅适用于现货和合约模式下的全仓杠杆订单 |
| clOrdId | String | 否 | 客户自定义订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 |
| tag | String | 否 | 订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-16位之间。 |
| side | String | 是 | 订单方向 buy：买， sell：卖 |
| posSide | String | 可选 | 持仓方向 在开平仓模式下必填，且仅可选择 long 或 short。 仅适用交割、永续。 |
| ordType | String | 是 | 订单类型 market：市价单limit：限价单 post_only：只做maker单 fok：全部成交或立即取消 ioc：立即成交并取消剩余 optimal_limit_ioc：市价委托立即成交并取消剩余（仅适用交割、永续）mmp：做市商保护(仅适用于组合保证金账户模式下的期权订单)mmp_and_post_only：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单) |
| sz | String | 是 | 委托数量 |
| px | String | 可选 | 委托价格，仅适用于limit、post_only、fok、ioc、mmp、mmp_and_post_only类型的订单期权下单时，px/pxUsd/pxVol 只能填一个 |
| pxUsd | String | 可选 | 以USD价格进行期权下单 仅适用于期权 期权下单时 px/pxUsd/pxVol 必填一个，且只能填一个 |
| pxVol | String | 可选 | 以隐含波动率进行期权下单，例如 1 代表 100% 仅适用于期权 期权下单时 px/pxUsd/pxVol 必填一个，且只能填一个 |
| reduceOnly | Boolean | 否 | 是否只减仓，true 或 false，默认false仅适用于 币币杠杆，以及买卖模式下的交割/永续仅适用于 现货和合约模式和跨币种保证金模式 |
| tgtCcy | String | 否 | 市价单委托数量sz的单位，仅适用于币币市价订单base_ccy: 交易货币 ；quote_ccy：计价货币买单默认 quote_ccy， 卖单默认base_ccy |
| banAmend | Boolean | 否 | 是否禁止币币市价改单，true 或 false，默认false 为true时，余额不足时，系统不会改单，下单会失败，仅适用于币币市价单 |
| stpId | String | 否 | 用户自定义1<=x<=999999999的整数 |
| stpMode | String | 否 | 自成交保护模式 默认为 cancel maker cancel_maker,cancel_taker, cancel_bothCancel both不支持FOK |
| quickMgnType | String | 否 | manual：手动，auto_borrow：自动借币，auto_repay：自动还币 默认是 manual：手动 |
| attachAlgoOrds | Array of object | 否 | 下单附带止盈止损信息 |
| > attachAlgoClOrdId | String | 否 | 下单附带止盈止损时，客户自定义的策略订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 订单完全成交，下止盈止损委托单时，该值会传给 algoClOrdId |
| > tpTriggerPx | String | 可选 | 止盈触发价 对于条件止盈单，如果填写此参数，必须填写 止盈委托价 |
| > tpOrdPx | String | 可选 | 止盈委托价 对于条件止盈单，如果填写此参数，必须填写 止盈触发价 对于限价止盈单，需填写此参数，不需要填写止盈触发价 委托价格为-1时，执行市价止盈 |
| > tpOrdKind | String | 否 | 止盈订单类型condition: 条件单limit: 限价单默认为 condition |
| > slTriggerPx | String | 可选 | 止损触发价，如果填写此参数，必须填写 止损委托价 |
| > slOrdPx | String | 可选 | 止损委托价，如果填写此参数，必须填写 止损触发价 委托价格为-1时，执行市价止损 |
| > tpTriggerPxType | String | 否 | 止盈触发价类型last：最新价格index：指数价格mark：标记价格默认为 last |
| > slTriggerPxType | String | 否 | 止损触发价类型last：最新价格index：指数价格mark：标记价格默认为 last |
| > sz | String | 可选 | 数量。仅适用于“多笔止盈”的止盈订单，且对于“多笔止盈”的止盈订单必填 |
| > amendPxOnTriggerType | String | 否 | 是否启用开仓价止损，仅适用于分批止盈的止损订单，第一笔止盈触发时，止损触发价格是否移动到开仓均价止损0：不开启，默认值 1：开启，且止损触发价不能为空 |
返回结果
{
"code":"0",
"msg":"",
"data":[
{
"clOrdId":"oktswap6",
"ordId":"12345689",
"tag":"",
"ts":"1695190491421",
"sCode":"0",
"sMsg":""
},
{
"clOrdId":"oktswap7",
"ordId":"12344",
"tag":"",
"ts":"1695190491421",
"sCode":"0",
"sMsg":""
}
],
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| code | String | 结果代码，0表示成功 |
| msg | String | 错误信息，代码为0时，该字段为空 |
| data | String | 包含结果的对象数组 |
| > ordId | String | 订单ID |
| > clOrdId | String | 客户自定义订单ID |
| > tag | String | 订单标签 |
| > ts | String | 系统完成订单请求处理的时间戳，Unix时间戳的毫秒数格式，如 1597026383085 |
| > sCode | String | 事件执行结果的code，0代表成功 |
| > sMsg | String | 事件执行失败或成功时的msg |
| inTime | String | REST网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 返回的时间是请求验证后的时间。 |
| outTime | String | REST网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
POST / 撤单
撤销之前下的未完成订单。
限速：60次/2s
限速规则（期权以外）：UserID + Instrument ID
限速规则（只限期权）：UserID + Instrument Family
HTTP请求
POST /api/v5/trade/cancel-order
请求示例
POST /api/v5/trade/cancel-order
body
{
"ordId":"590908157585625111",
"instId":"BTC-USDT"
}
import okx.Trade as Trade
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘: 0, 模拟盘: 1
tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)
# 撤单
result = tradeAPI.cancel_order(instId="BTC-USDT", ordId = "590908157585625111")
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 是 | 产品ID，如 BTC-USDT |
| ordId | String | 可选 | 订单ID， ordId和clOrdId必须传一个，若传两个，以ordId为主 |
| clOrdId | String | 可选 | 用户自定义ID |
返回结果
{
"code":"0",
"msg":"",
"data":[
{
"clOrdId":"oktswap6",
"ordId":"12345689",
"ts":"1695190491421",
"sCode":"0",
"sMsg":""
}
],
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| code | String | 结果代码，0表示成功 |
| msg | String | 错误信息，代码为0时，该字段为空 |
| data | String | 包含结果的对象数组 |
| > ordId | String | 订单ID |
| > clOrdId | String | 客户自定义订单ID |
| > ts | String | 系统完成订单请求处理的时间戳，Unix时间戳的毫秒数格式，如 1597026383085 |
| > sCode | String | 事件执行结果的code，0代表成功 |
| > sMsg | String | 事件执行失败时的msg |
| inTime | String | REST网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 返回的时间是请求验证后的时间。 |
| outTime | String | REST网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
POST / 批量撤单
撤销未完成的订单，每次最多可以撤销20个订单。请求参数应该按数组格式传递。
限速：300个/2s
限速规则（期权以外）：UserID + Instrument ID
限速规则（只限期权）：UserID + Instrument Family
HTTP请求
POST /api/v5/trade/cancel-batch-orders
请求示例
POST /api/v5/trade/cancel-batch-orders
body
[
{
"instId":"BTC-USDT",
"ordId":"590908157585625111"
},
{
"instId":"BTC-USDT",
"ordId":"590908544950571222"
}
]
import okx.Trade as Trade
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘: 0, 模拟盘: 1
tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)
# 按ordId撤单
cancel_orders_with_orderId = [
{"instId": "BTC-USDT", "ordId": "590908157585625111"},
{"instId": "BTC-USDT", "ordId": "590908544950571222"}
]
result = tradeAPI.cancel_multiple_orders(cancel_orders_with_orderId)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 是 | 产品ID，如 BTC-USD-190927 |
| ordId | String | 可选 | 订单ID， ordId和clOrdId必须传一个，若传两个，以ordId为主 |
| clOrdId | String | 可选 | 用户自定义ID |
返回结果
{
"code":"0",
"msg":"",
"data":[
{
"clOrdId":"oktswap6",
"ordId":"12345689",
"ts":"1695190491421",
"sCode":"0",
"sMsg":""
},
{
"clOrdId":"oktswap7",
"ordId":"12344",
"ts":"1695190491421",
"sCode":"0",
"sMsg":""
}
],
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| code | String | 结果代码，0表示成功 |
| msg | String | 错误信息，代码为0时，该字段为空 |
| data | String | 包含结果的对象数组 |
| > ordId | String | 订单ID |
| > clOrdId | String | 客户自定义订单ID |
| > ts | String | 系统完成订单请求处理的时间戳，Unix时间戳的毫秒数格式，如 1597026383085 |
| > sCode | String | 事件执行结果的code，0代表成功 |
| > sMsg | String | 事件执行失败时的msg |
| inTime | String | REST网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 返回的时间是请求验证后的时间。 |
| outTime | String | REST网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
POST / 修改订单
修改当前未成交的挂单
限速：60次/2s
跟单交易带单产品的限速：4个/2s
限速规则：UserID + Instrument ID
该接口限速同时受到 子账户限速 及 基于成交比率的子账户限速 限速规则的影响。
HTTP请求
POST /api/v5/trade/amend-order
请求示例
POST /api/v5/trade/amend-order
body
{
"ordId":"590909145319051111",
"newSz":"2",
"instId":"BTC-USDT"
}
import okx.Trade as Trade
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘: 0, 模拟盘: 1
tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)
# 修改订单
result = tradeAPI.amend_order(
instId="BTC-USDT",
ordId="590909145319051111",
newSz="2"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 是 | 产品ID |
| cxlOnFail | Boolean | 否 | 当订单修改失败时，该订单是否需要自动撤销。默认为falsefalse：不自动撤单true：自动撤单 |
| ordId | String | 可选 | 订单IDordId和clOrdId必须传一个，若传两个，以ordId为主 |
| clOrdId | String | 可选 | 用户自定义订单ID |
| reqId | String | 否 | 用户自定义修改事件ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 |
| newSz | String | 可选 | 修改的新数量，必须大于0，对于部分成交订单，该数量应包含已成交数量。 |
| newPx | String | 可选 | 修改后的新价格 修改的新价格期权改单时，newPx/newPxUsd/newPxVol 只能填一个，且必须与下单参数保持一致，如下单用px，改单时需使用newPx |
| newPxUsd | String | 可选 | 以USD价格进行期权改单 仅适用于期权，期权改单时，newPx/newPxUsd/newPxVol 只能填一个 |
| newPxVol | String | 可选 | 以隐含波动率进行期权改单，例如 1 代表 100% 仅适用于期权，期权改单时，newPx/newPxUsd/newPxVol 只能填一个 |
| attachAlgoOrds | Array of object | 否 | 修改附带止盈止损信息 |
| > attachAlgoId | String | 可选 | 附带止盈止损的订单ID，由系统生成，改单时，可用来标识该笔附带止盈止损订单。下止盈止损委托单时，该值不会传给 algoId |
| > attachAlgoClOrdId | String | 可选 | 下单附带止盈止损时，客户自定义的策略订单ID |
| > newTpTriggerPx | String | 可选 | 止盈触发价 如果止盈触发价或者委托价为0，那代表删除止盈。 |
| > newTpOrdPx | String | 可选 | 止盈委托价 委托价格为-1时，执行市价止盈。 |
| > newTpOrdKind | String | 否 | 止盈订单类型condition: 条件单limit: 限价单 |
| > newSlTriggerPx | String | 可选 | 止损触发价 如果止损触发价或者委托价为0，那代表删除止损。 |
| > newSlOrdPx | String | 可选 | 止损委托价 委托价格为-1时，执行市价止损。 |
| > newTpTriggerPxType | String | 可选 | 止盈触发价类型last：最新价格index：指数价格mark：标记价格只适用于 交割/永续如果要新增止盈，该参数必填 |
| > newSlTriggerPxType | String | 可选 | 止损触发价类型last：最新价格index：指数价格mark：标记价格只适用于 交割/永续如果要新增止损，该参数必填 |
| > sz | String | 可选 | 新的张数。仅适用于“多笔止盈”的止盈订单且必填 |
| > amendPxOnTriggerType | String | 否 | 是否启用开仓价止损，仅适用于分批止盈的止损订单0：不开启，默认值1：开启 |
返回结果
{
"code":"0",
"msg":"",
"data":[
{
"clOrdId":"",
"ordId":"12344",
"ts":"1695190491421",
"reqId":"b12344",
"sCode":"0",
"sMsg":""
}
],
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| code | String | 结果代码，0表示成功 |
| msg | String | 错误信息，代码为0时，该字段为空 |
| data | String | 包含结果的对象数组 |
| > ordId | String | 订单ID |
| > clOrdId | String | 用户自定义ID |
| > ts | String | 系统完成订单请求处理的时间戳，Unix时间戳的毫秒数格式，如 1597026383085 |
| > reqId | String | 用户自定义修改事件ID |
| > sCode | String | 事件执行结果的code，0代表成功 |
| > sMsg | String | 事件执行失败时的msg |
| inTime | String | REST网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 返回的时间是请求验证后的时间。 |
| outTime | String | REST网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
POST / 批量修改订单
修改未完成的订单，一次最多可批量修改20个订单。请求参数应该按数组格式传递。
限速：300个/2s
跟单交易带单产品的限速：4个/2s
限速规则：UserID + Instrument ID
该接口限速同时受到 子账户限速 及 基于成交比率的子账户限速 限速规则的影响。
HTTP请求
POST /api/v5/trade/amend-batch-orders
请求示例
POST /api/v5/trade/amend-batch-orders
body
[
{
"ordId":"590909308792049444",
"newSz":"2",
"instId":"BTC-USDT"
},
{
"ordId":"590909308792049555",
"newSz":"2",
"instId":"BTC-USDT"
}
]
import okx.Trade as Trade
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘: 0, 模拟盘: 1
tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)
# 按ordId修改未完成的订单
amend_orders_with_orderId = [
{"instId": "BTC-USDT", "ordId": "590909308792049444","newSz":"2"},
{"instId": "BTC-USDT", "ordId": "590909308792049555","newSz":"2"}
]
result = tradeAPI.amend_multiple_orders(amend_orders_with_orderId)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 是 | 产品ID |
| cxlOnFail | Boolean | 否 | 当订单修改失败时，该订单是否需要自动撤销。默认为falsefalse：不自动撤单true：自动撤单 |
| ordId | String | 可选 | 订单ID， ordId和clOrdId必须传一个，若传两个，以ordId为主 |
| clOrdId | String | 可选 | 用户自定义order ID |
| reqId | String | 否 | 用户自定义修改事件ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 |
| newSz | String | 可选 | 修改的新数量，必须大于0，对于部分成交订单，该数量应包含已成交数量。 |
| newPx | String | 可选 | 修改后的新价格 修改的新价格期权改单时，newPx/newPxUsd/newPxVol 只能填一个，且必须与下单参数保持一致，如下单用px，改单时需使用newPx |
| newPxUsd | String | 可选 | 以USD价格进行期权改单 仅适用于期权，期权改单时，newPx/newPxUsd/newPxVol 只能填一个 |
| newPxVol | String | 可选 | 以隐含波动率进行期权改单，例如 1 代表 100% 仅适用于期权，期权改单时，newPx/newPxUsd/newPxVol 只能填一个 |
| attachAlgoOrds | Array of object | 否 | 下单附带止盈止损信息 |
| > attachAlgoId | String | 可选 | 附带止盈止损的订单ID，由系统生成，改单时，可用来标识该笔附带止盈止损订单。下止盈止损委托单时，该值不会传给 algoId |
| > attachAlgoClOrdId | String | 可选 | 下单附带止盈止损时，客户自定义的策略订单ID |
| > newTpTriggerPx | String | 可选 | 止盈触发价 如果止盈触发价或者委托价为0，那代表删除止盈。 |
| > newTpOrdPx | String | 可选 | 止盈委托价 委托价格为-1时，执行市价止盈。 |
| > newTpOrdKind | String | 否 | 止盈订单类型condition: 条件单limit: 限价单 |
| > newSlTriggerPx | String | 可选 | 止损触发价 如果止损触发价或者委托价为0，那代表删除止损。 |
| > newSlOrdPx | String | 可选 | 止损委托价 委托价格为-1时，执行市价止损。 |
| > newTpTriggerPxType | String | 可选 | 止盈触发价类型last：最新价格index：指数价格mark：标记价格只适用于 交割/永续如果要新增止盈，该参数必填 |
| > newSlTriggerPxType | String | 可选 | 止损触发价类型last：最新价格index：指数价格mark：标记价格只适用于 交割/永续如果要新增止损，该参数必填 |
| > sz | String | 可选 | 新的张数。仅适用于“多笔止盈”的止盈订单且必填 |
| > amendPxOnTriggerType | String | 否 | 是否启用开仓价止损，仅适用于分批止盈的止损订单0：不开启，默认值 1：开启 |
返回结果
{
"code":"0",
"msg":"",
"data":[
{
"clOrdId":"oktswap6",
"ordId":"12345689",
"ts":"1695190491421",
"reqId":"b12344",
"sCode":"0",
"sMsg":""
},
{
"clOrdId":"oktswap7",
"ordId":"12344",
"ts":"1695190491421",
"reqId":"b12344",
"sCode":"0",
"sMsg":""
}
],
"inTime": "1695190491421339",
"outTime": "1695190491423240"
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| code | String | 结果代码，0表示成功 |
| msg | String | 错误信息，代码为0时，该字段为空 |
| data | String | 包含结果的对象数组 |
| > ordId | String | 订单ID |
| > clOrdId | String | 用户自定义ID |
| > ts | String | 系统完成订单请求处理的时间戳，Unix时间戳的毫秒数格式，如 1597026383085 |
| > reqId | String | 用户自定义修改事件ID |
| > sCode | String | 事件执行结果的code，0代表成功 |
| > sMsg | String | 事件执行失败时的msg |
| inTime | String | REST网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 返回的时间是请求验证后的时间。 |
| outTime | String | REST网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 |
POST / 市价仓位全平
市价平掉指定交易产品的持仓
限速：20次/2s
限速规则（期权以外）：UserID + Instrument ID
限速规则（只限期权）：UserID + Instrument Family
HTTP请求
POST /api/v5/trade/close-position
请求示例
POST /api/v5/trade/close-position
body
{
"instId":"BTC-USDT-SWAP",
"mgnMode":"cross"
}
import okx.Trade as Trade
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘: 0, 模拟盘: 1
tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)
# 市价全平
result = tradeAPI.close_positions(
instId="BTC-USDT-SWAP",
mgnMode="cross"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 是 | 产品ID |
| posSide | String | 可选 | 持仓方向 买卖模式下：可不填写此参数，默认值net，如果填写，仅可以填写net 开平仓模式下： 必须填写此参数，且仅可以填写 long：平多 ，short：平空 |
| mgnMode | String | 是 | 保证金模式cross：全仓 ； isolated：逐仓 |
| ccy | String | 可选 | 保证金币种，现货和合约模式下的全仓币币杠杆平仓必填 |
| autoCxl | Boolean | 否 | 当市价全平时，平仓单是否需要自动撤销,默认为false.false：不自动撤单 true：自动撤单 |
| clOrdId | String | 否 | 客户自定义ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 |
| tag | String | 否 | 订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。 |
返回结果
{
"code": "0",
"data": [
{
"clOrdId": "",
"instId": "BTC-USDT-SWAP",
"posSide": "long",
"tag": ""
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instId | String | 产品ID |
| posSide | String | 持仓方向 |
| clOrdId | String | 客户自定义ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 |
| tag | String | 订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。 |
GET / 获取订单信息
查订单信息
限速：60次/2s
限速规则（期权以外）：UserID + Instrument ID
限速规则（只限期权）：UserID + Instrument Family
HTTP请求
GET /api/v5/trade/order
请求示例
GET /api/v5/trade/order?ordId=1753197687182819328&instId=BTC-USDT
import okx.Trade as Trade
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘: 0, 模拟盘: 1
tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)
# 通过 ordId 查询订单
result = tradeAPI.get_order(
instId="BTC-USDT",
ordId="680800019749904384"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instId | String | 是 | 产品ID，如 BTC-USDT只适用于交易中的产品 |
| ordId | String | 可选 | 订单ID，ordId和clOrdId必须传一个，若传两个，以ordId为主 |
| clOrdId | String | 可选 | 用户自定义ID 如果 clOrdId关联了多个订单，只会返回最近的那笔订单 |
返回结果
{
"code": "0",
"data": [
{
"accFillSz": "0.00192834",
"algoClOrdId": "",
"algoId": "",
"attachAlgoClOrdId": "",
"attachAlgoOrds": [],
"avgPx": "51858",
"cTime": "1708587373361",
"cancelSource": "",
"cancelSourceReason": "",
"category": "normal",
"ccy": "",
"clOrdId": "",
"fee": "-0.00000192834",
"feeCcy": "BTC",
"fillPx": "51858",
"fillSz": "0.00192834",
"fillTime": "1708587373361",
"instId": "BTC-USDT",
"instType": "SPOT",
"isTpLimit": "false",
"lever": "",
"linkedAlgoOrd": {
"algoId": ""
},
"ordId": "680800019749904384",
"ordType": "market",
"pnl": "0",
"posSide": "net",
"px": "",
"pxType": "",
"pxUsd": "",
"pxVol": "",
"quickMgnType": "",
"rebate": "0",
"rebateCcy": "USDT",
"reduceOnly": "false",
"side": "buy",
"slOrdPx": "",
"slTriggerPx": "",
"slTriggerPxType": "",
"source": "",
"state": "filled",
"stpId": "",
"stpMode": "",
"sz": "100",
"tag": "",
"tdMode": "cash",
"tgtCcy": "quote_ccy",
"tpOrdPx": "",
"tpTriggerPx": "",
"tpTriggerPxType": "",
"tradeId": "744876980",
"uTime": "1708587373362"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instType | String | 产品类型SPOT：币币MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权 |
| instId | String | 产品ID |
| tgtCcy | String | 币币市价单委托数量sz的单位base_ccy: 交易货币 ；quote_ccy：计价货币仅适用于 币币市价订单默认买单为 quote_ccy，卖单为base_ccy |
| ccy | String | 保证金币种，仅适用于现货和合约模式下的全仓币币杠杆订单 |
| ordId | String | 订单ID |
| clOrdId | String | 客户自定义订单ID |
| tag | String | 订单标签 |
| px | String | 委托价格，对于期权，以币(如BTC, ETH)为单位 |
| pxUsd | String | 期权价格，以USD为单位 仅适用于期权，其他业务线返回空字符串"" |
| pxVol | String | 期权订单的隐含波动率 仅适用于期权，其他业务线返回空字符串"" |
| pxType | String | 期权的价格类型 px：代表按价格下单，单位为币 (请求参数 px 的数值单位是BTC或ETH) pxVol：代表按pxVol下单 pxUsd：代表按照pxUsd下单，单位为USD (请求参数px 的数值单位是USD) |
| sz | String | 委托数量 |
| pnl | String | 收益，适用于有成交的平仓订单，其他情况均为0 |
| ordType | String | 订单类型 market：市价单limit：限价单 post_only：只做maker单 fok：全部成交或立即取消 ioc：立即成交并取消剩余 optimal_limit_ioc：市价委托立即成交并取消剩余（仅适用交割、永续）mmp：做市商保护(仅适用于组合保证金账户模式下的期权订单)mmp_and_post_only：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单) op_fok：期权简选（全部成交或立即取消） |
| side | String | 订单方向 |
| posSide | String | 持仓方向 |
| tdMode | String | 交易模式 |
| accFillSz | String | 累计成交数量 对于 币币和杠杆，单位为交易货币，如 BTC-USDT, 单位为 BTC；对于市价单，无论tgtCcy是base_ccy，还是quote_ccy，单位均为交易货币；对于交割、永续以及期权，单位为张。 |
| fillPx | String | 最新成交价格，如果成交数量为0，该字段为"" |
| tradeId | String | 最新成交ID |
| fillSz | String | 最新成交数量 对于 币币和杠杆，单位为交易货币，如 BTC-USDT, 单位为 BTC；对于市价单，无论tgtCcy是base_ccy，还是quote_ccy，单位均为交易货币；对于交割、永续以及期权，单位为张。 |
| fillTime | String | 最新成交时间 |
| avgPx | String | 成交均价，如果成交数量为0，该字段也为"" |
| state | String | 订单状态 canceled：撤单成功live：等待成交 partially_filled：部分成交filled：完全成交mmp_canceled：做市商保护机制导致的自动撤单 |
| lever | String | 杠杆倍数，0.01到125之间的数值，仅适用于 币币杠杆/交割/永续 |
| attachAlgoClOrdId | String | 下单附带止盈止损时，客户自定义的策略订单ID |
| tpTriggerPx | String | 止盈触发价 |
| tpTriggerPxType | String | 止盈触发价类型last：最新价格index：指数价格mark：标记价格 |
| tpOrdPx | String | 止盈委托价 |
| slTriggerPx | String | 止损触发价 |
| slTriggerPxType | String | 止损触发价类型last：最新价格index：指数价格mark：标记价格 |
| slOrdPx | String | 止损委托价 |
| attachAlgoOrds | Array of object | 下单附带止盈止损信息 |
| > attachAlgoId | String | 附带止盈止损的订单ID，改单时，可用来标识该笔附带止盈止损订单。下止盈止损委托单时，该值不会传给 algoId |
| > attachAlgoClOrdId | String | 下单附带止盈止损时，客户自定义的策略订单ID |
| > tpOrdKind | String | 止盈订单类型condition: 条件单limit: 限价单 |
| > tpTriggerPx | String | 止盈触发价 |
| > tpTriggerPxType | String | 止盈触发价类型last：最新价格index：指数价格mark：标记价格 |
| > tpOrdPx | String | 止盈委托价 |
| > slTriggerPx | String | 止损触发价 |
| > slTriggerPxType | String | 止损触发价类型last：最新价格index：指数价格mark：标记价格 |
| > slOrdPx | String | 止损委托价 |
| > sz | String | 张数。仅适用于“多笔止盈”的止盈订单 |
| > amendPxOnTriggerType | String | 是否启用开仓价止损，仅适用于分批止盈的止损订单0：不开启，默认值 1：开启 |
| > failCode | String | 委托失败的错误码，默认为"", 委托失败时有值，如 51020 |
| > failReason | String | 委托失败的原因，默认为"" 委托失败时有值 |
| linkedAlgoOrd | Object | 止损订单信息，仅适用于包含限价止盈单的双向止盈止损订单，触发后生成的普通订单 |
| > algoId | Object | 策略订单唯一标识 |
| stpId | String | 如果自成交保护不适用则返回"" |
| 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，策略订单触发时有值，否则为"" |
| isTpLimit | String | 是否为限价止盈，true 或 false. |
| uTime | String | 订单状态更新时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| cTime | String | 订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085 |
GET / 获取未成交订单列表
获取当前账户下所有未成交订单信息
限速：60次/2s
限速规则：UserID
HTTP请求
GET /api/v5/trade/orders-pending
请求示例
GET /api/v5/trade/orders-pending?ordType=post_only,fok,ioc&instType=SPOT
import okx.Trade as Trade
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘: 0, 模拟盘: 1
tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)
# 查询所有未成交订单
result = tradeAPI.get_order_list(
instType="SPOT",
ordType="post_only,fok,ioc"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 否 | 产品类型SPOT：币币MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权 |
| uly | String | 否 | 标的指数 |
| instFamily | String | 否 | 交易品种 适用于 交割/永续/期权 |
| instId | String | 否 | 产品ID，如 BTC-USDT |
| ordType | String | 否 | 订单类型market：市价单limit：限价单post_only：只做maker单fok：全部成交或立即取消ioc：立即成交并取消剩余optimal_limit_ioc：市价委托立即成交并取消剩余（仅适用交割、永续）mmp：做市商保护(仅适用于组合保证金账户模式下的期权订单)mmp_and_post_only：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单) op_fok：期权简选（全部成交或立即取消） |
| state | String | 否 | 订单状态live：等待成交partially_filled：部分成交 |
| after | String | 否 | 请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的ordId |
| before | String | 否 | 请求此ID之后（更新的数据）的分页内容，传的值为对应接口的ordId |
| limit | String | 否 | 返回结果的数量，最大为100，默认100条 |
返回结果
{
"code": "0",
"data": [
{
"accFillSz": "0",
"algoClOrdId": "",
"algoId": "",
"attachAlgoClOrdId": "",
"attachAlgoOrds": [],
"avgPx": "",
"cTime": "1724733617998",
"cancelSource": "",
"cancelSourceReason": "",
"category": "normal",
"ccy": "",
"clOrdId": "",
"fee": "0",
"feeCcy": "BTC",
"fillPx": "",
"fillSz": "0",
"fillTime": "",
"instId": "BTC-USDT",
"instType": "SPOT",
"isTpLimit": "false",
"lever": "",
"linkedAlgoOrd": {
"algoId": ""
},
"ordId": "1752588852617379840",
"ordType": "post_only",
"pnl": "0",
"posSide": "net",
"px": "13013.5",
"pxType": "",
"pxUsd": "",
"pxVol": "",
"quickMgnType": "",
"rebate": "0",
"rebateCcy": "USDT",
"reduceOnly": "false",
"side": "buy",
"slOrdPx": "",
"slTriggerPx": "",
"slTriggerPxType": "",
"source": "",
"state": "live",
"stpId": "",
"stpMode": "cancel_maker",
"sz": "0.001",
"tag": "",
"tdMode": "cash",
"tgtCcy": "",
"tpOrdPx": "",
"tpTriggerPx": "",
"tpTriggerPxType": "",
"tradeId": "",
"uTime": "1724733617998"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instType | String | 产品类型 |
| instId | String | 产品ID |
| tgtCcy | String | 币币市价单委托数量sz的单位base_ccy: 交易货币 ；quote_ccy：计价货币仅适用于 币币市价订单默认买单为 quote_ccy，卖单为base_ccy |
| ccy | String | 保证金币种，仅适用于现货和合约模式下的全仓币币杠杆订单 |
| ordId | String | 订单ID |
| clOrdId | String | 客户自定义订单ID |
| tag | String | 订单标签 |
| px | String | 委托价格，对于期权，以币(如BTC, ETH)为单位 |
| pxUsd | String | 期权价格，以USD为单位 仅适用于期权，其他业务线返回空字符串"" |
| pxVol | String | 期权订单的隐含波动率 仅适用于期权，其他业务线返回空字符串"" |
| pxType | String | 期权的价格类型 px：代表按价格下单，单位为币 (请求参数 px 的数值单位是BTC或ETH) pxVol：代表按pxVol下单 pxUsd：代表按照pxUsd下单，单位为USD (请求参数px 的数值单位是USD) |
| sz | String | 委托数量 |
| pnl | String | 收益，适用于有成交的平仓订单，其他情况均为0 |
| ordType | String | 订单类型market：市价单limit：限价单 post_only：只做maker单 fok：全部成交或立即取消 ioc：立即成交并取消剩余 optimal_limit_ioc：市价委托立即成交并取消剩余（仅适用交割、永续）mmp：做市商保护(仅适用于组合保证金账户模式下的期权订单)mmp_and_post_only：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单) op_fok：期权简选（全部成交或立即取消） |
| side | String | 订单方向 |
| posSide | String | 持仓方向 |
| tdMode | String | 交易模式 |
| accFillSz | String | 累计成交数量 |
| fillPx | String | 最新成交价格。如果还没成交，系统返回""。 |
| tradeId | String | 最新成交ID |
| fillSz | String | 最新成交数量 |
| fillTime | String | 最新成交时间 |
| avgPx | String | 成交均价。如果还没成交，系统返回0。 |
| state | String | 订单状态live：等待成交 partially_filled：部分成交 |
| lever | String | 杠杆倍数，0.01到125之间的数值，仅适用于 币币杠杆/交割/永续 |
| attachAlgoClOrdId | String | 下单附带止盈止损时，客户自定义的策略订单ID |
| tpTriggerPx | String | 止盈触发价 |
| tpTriggerPxType | String | 止盈触发价类型last：最新价格index：指数价格mark：标记价格 |
| slTriggerPx | String | 止损触发价 |
| slTriggerPxType | String | 止损触发价类型last：最新价格index：指数价格mark：标记价格 |
| slOrdPx | String | 止损委托价 |
| tpOrdPx | String | 止盈委托价 |
| attachAlgoOrds | Array of object | 下单附带止盈止损信息 |
| > attachAlgoId | String | 附带止盈止损的订单ID，改单时，可用来标识该笔附带止盈止损订单。下止盈止损委托单时，该值不会传给 algoId |
| > attachAlgoClOrdId | String | 下单附带止盈止损时，客户自定义的策略订单ID |
| > tpOrdKind | String | 止盈订单类型condition: 条件单limit: 限价单 |
| > tpTriggerPx | String | 止盈触发价 |
| > tpTriggerPxType | String | 止盈触发价类型last：最新价格index：指数价格mark：标记价格 |
| > tpOrdPx | String | 止盈委托价 |
| > slTriggerPx | String | 止损触发价 |
| > slTriggerPxType | String | 止损触发价类型last：最新价格index：指数价格mark：标记价格 |
| > slOrdPx | String | 止损委托价 |
| > sz | String | 张数。仅适用于“多笔止盈”的止盈订单 |
| > failCode | String | 委托失败的错误码，默认为"", 委托失败时有值，如 51020 |
| > failReason | String | 委托失败的原因，默认为"" 委托失败时有值 |
| > amendPxOnTriggerType | String | 是否启用开仓价止损，仅适用于分批止盈的止损订单0：不开启，默认值 1：开启 |
| linkedAlgoOrd | Object | 止损订单信息，仅适用于包含限价止盈单的双向止盈止损订单，触发后生成的普通订单 |
| > algoId | Object | 策略订单唯一标识 |
| stpId | String | 如果自成交保护不适用则返回"" |
| 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，策略订单触发时有值，否则为"" |
| isTpLimit | String | 是否为限价止盈，true 或 false. |
| uTime | String | 订单状态更新时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| cTime | String | 订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| cancelSource | String | 订单取消来源的原因枚举值代码 |
| cancelSourceReason | String | 订单取消来源的对应具体原因 |
GET / 获取历史订单记录（近七天）
获取最近7天挂单，且完成的订单数据，包括7天以前挂单，但近7天才成交的订单数据。按照订单创建时间倒序排序。
已经撤销的未成交单 只保留2小时
限速：40次/2s
限速规则：UserID
HTTP请求
GET /api/v5/trade/orders-history
请求示例
GET /api/v5/trade/orders-history?ordType=post_only,fok,ioc&instType=SPOT
import okx.Trade as Trade
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘: 0, 模拟盘: 1
tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)
# 查询币币历史订单（7天内）
# 已经撤销的未成交单 只保留2小时
result = tradeAPI.get_orders_history(
instType="SPOT",
ordType="post_only,fok,ioc"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 是 | 产品类型SPOT：币币MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权 |
| uly | String | 否 | 标的指数 |
| instFamily | String | 否 | 交易品种 适用于 交割/永续/期权 |
| instId | String | 否 | 产品ID，如BTC-USD-190927 |
| ordType | String | 否 | 订单类型 market：市价单limit：限价单 post_only：只做maker单 fok：全部成交或立即取消 ioc：立即成交并取消剩余optimal_limit_ioc：市价委托立即成交并取消剩余（仅适用交割、永续）mmp：做市商保护(仅适用于组合保证金账户模式下的期权订单)mmp_and_post_only：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单) op_fok：期权简选（全部成交或立即取消） |
| state | String | 否 | 订单状态canceled：撤单成功 filled：完全成交mmp_canceled：做市商保护机制导致的自动撤单 |
| category | String | 否 | 订单种类 twap：TWAP自动换币 adl：ADL自动减仓full_liquidation：强制平仓partial_liquidation：强制减仓 delivery：交割ddh：对冲减仓类型订单 |
| after | String | 否 | 请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的ordId |
| before | String | 否 | 请求此ID之后（更新的数据）的分页内容，传的值为对应接口的ordId |
| begin | String | 否 | 筛选的开始时间戳 cTime，Unix 时间戳为毫秒数格式，如 1597026383085 |
| end | String | 否 | 筛选的结束时间戳 cTime，Unix 时间戳为毫秒数格式，如 1597027383085 |
| limit | String | 否 | 返回结果的数量，最大为100，默认100条 |
返回结果
{
"code": "0",
"data": [
{
"accFillSz": "0.00192834",
"algoClOrdId": "",
"algoId": "",
"attachAlgoClOrdId": "",
"attachAlgoOrds": [],
"avgPx": "51858",
"cTime": "1708587373361",
"uTime": "1708679675245",
"cancelSource": "",
"cancelSourceReason": "",
"category": "normal",
"ccy": "",
"clOrdId": "",
"fee": "-0.00000192834",
"feeCcy": "BTC",
"fillPx": "51858",
"fillSz": "0.00192834",
"fillTime": "1708587373361",
"instId": "BTC-USDT",
"instType": "SPOT",
"isTpLimit": "false",
"lever": "",
"ordId": "680800019749904384",
"ordType": "market",
"pnl": "0",
"posSide": "",
"px": "",
"pxType": "",
"pxUsd": "",
"pxVol": "",
"quickMgnType": "",
"rebate": "0",
"rebateCcy": "USDT",
"reduceOnly": "false",
"side": "buy",
"slOrdPx": "",
"slTriggerPx": "",
"slTriggerPxType": "",
"source": "",
"state": "filled",
"stpId": "",
"stpMode": "",
"sz": "100",
"tag": "",
"tdMode": "cash",
"tgtCcy": "quote_ccy",
"tpOrdPx": "",
"tpTriggerPx": "",
"tpTriggerPxType": "",
"tradeId": "744876980",
"uTime": "1708587373362",
"linkedAlgoOrd": {
"algoId": ""
}
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instType | String | 产品类型 |
| instId | String | 产品ID |
| tgtCcy | String | 币币市价单委托数量sz的单位base_ccy: 交易货币 ；quote_ccy：计价货币仅适用于 币币市价订单默认买单为 quote_ccy，卖单为base_ccy |
| ccy | String | 保证金币种，仅适用于现货和合约模式下的全仓币币杠杆订单 |
| ordId | String | 订单ID |
| clOrdId | String | 客户自定义订单ID |
| tag | String | 订单标签 |
| px | String | 委托价格，对于期权，以币(如BTC, ETH)为单位 |
| pxUsd | String | 期权价格，以USD为单位 仅适用于期权，其他业务线返回空字符串"" |
| pxVol | String | 期权订单的隐含波动率 仅适用于期权，其他业务线返回空字符串"" |
| pxType | String | 期权的价格类型 px：代表按价格下单，单位为币 (请求参数 px 的数值单位是BTC或ETH) pxVol：代表按pxVol下单 pxUsd：代表按照pxUsd下单，单位为USD (请求参数px 的数值单位是USD) |
| sz | String | 委托数量 |
| ordType | String | 订单类型market：市价单limit：限价单 post_only：只做maker单fok：全部成交或立即取消ioc：立即成交并取消剩余optimal_limit_ioc：市价委托立即成交并取消剩余（仅适用交割、永续）mmp：做市商保护(仅适用于组合保证金账户模式下的期权订单)mmp_and_post_only：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单) op_fok：期权简选（全部成交或立即取消） |
| side | String | 订单方向 |
| posSide | String | 持仓方向 |
| tdMode | String | 交易模式 |
| accFillSz | String | 累计成交数量 |
| fillPx | String | 最新成交价格，如果成交数量为0，该字段为"" |
| tradeId | String | 最新成交ID |
| fillSz | String | 最新成交数量 |
| fillTime | String | 最新成交时间 |
| avgPx | String | 成交均价，如果成交数量为0，该字段也为"" |
| state | String | 订单状态canceled：撤单成功 filled：完全成交mmp_canceled：做市商保护机制导致的自动撤单 |
| lever | String | 杠杆倍数，0.01到125之间的数值，仅适用于 币币杠杆/交割/永续 |
| attachAlgoClOrdId | String | 下单附带止盈止损时，客户自定义的策略订单ID |
| tpTriggerPx | String | 止盈触发价 |
| tpTriggerPxType | String | 止盈触发价类型last：最新价格index：指数价格mark：标记价格 |
| tpOrdPx | String | 止盈委托价 |
| slTriggerPx | String | 止损触发价 |
| slTriggerPxType | String | 止损触发价类型last：最新价格index：指数价格mark：标记价格 |
| slOrdPx | String | 止损委托价 |
| attachAlgoOrds | Array of object | 下单附带止盈止损信息 |
| > attachAlgoId | String | 附带止盈止损的订单ID，改单时，可用来标识该笔附带止盈止损订单。下止盈止损委托单时，该值不会传给 algoId |
| > attachAlgoClOrdId | String | 下单附带止盈止损时，客户自定义的策略订单ID |
| > tpOrdKind | String | 止盈订单类型condition: 条件单limit: 限价单 |
| > tpTriggerPx | String | 止盈触发价 |
| > tpTriggerPxType | String | 止盈触发价类型last：最新价格index：指数价格mark：标记价格 |
| > tpOrdPx | String | 止盈委托价 |
| > slTriggerPx | String | 止损触发价 |
| > slTriggerPxType | String | 止损触发价类型last：最新价格index：指数价格mark：标记价格 |
| > slOrdPx | String | 止损委托价 |
| > sz | String | 张数。仅适用于“多笔止盈”的止盈订单 |
| > amendPxOnTriggerType | String | 是否启用开仓价止损，仅适用于分批止盈的止损订单0：不开启，默认值 1：开启 |
| > failCode | String | 委托失败的错误码，默认为"", 委托失败时有值，如 51020 |
| > failReason | String | 委托失败的原因，默认为"" 委托失败时有值 |
| linkedAlgoOrd | Object | 止损订单信息，仅适用于包含限价止盈单的双向止盈止损订单，触发后生成的普通订单 |
| > algoId | Object | 策略订单唯一标识 |
| stpId | String | 如果自成交保护不适用则返回"" |
| 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，策略订单触发时有值，否则为"" |
| isTpLimit | String | 是否为限价止盈，true 或 false. |
| uTime | String | 订单状态更新时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| cTime | String | 订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085 |
GET / 获取历史订单记录（近三个月）
获取最近3个月挂单，且完成的订单数据，包括3个月以前挂单，但近3个月才成交的订单数据。按照订单创建时间倒序排序。
限速：20次/2s
限速规则：UserID
HTTP请求
GET /api/v5/trade/orders-history-archive
请求示例
GET /api/v5/trade/orders-history-archive?ordType=post_only,fok,ioc&instType=SPOT
import okx.Trade as Trade
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘: 0, 模拟盘: 1
tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)
# 查询币币历史订单（3月内）
result = tradeAPI.get_orders_history_archive(
instType="SPOT",
ordType="post_only,fok,ioc"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 是 | 产品类型SPOT：币币MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权 |
| uly | String | 否 | 标的指数 |
| instFamily | String | 否 | 交易品种 适用于 交割/永续/期权 |
| instId | String | 否 | 产品ID，如 BTC-USDT |
| ordType | String | 否 | 订单类型market：市价单limit：限价单 post_only：只做maker单 fok：全部成交或立即取消ioc：立即成交并取消剩余optimal_limit_ioc：市价委托立即成交并取消剩余（仅适用交割、永续）mmp：做市商保护(仅适用于组合保证金账户模式下的期权订单)mmp_and_post_only：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单) op_fok：期权简选（全部成交或立即取消） |
| state | String | 否 | 订单状态canceled：撤单成功 filled：完全成交mmp_canceled：做市商保护机制导致的自动撤单 |
| category | String | 否 | 订单种类twap：TWAP自动换币 adl：ADL自动减仓full_liquidation：强制平仓partial_liquidation：强制减仓delivery：交割ddh：对冲减仓类型订单 |
| after | String | 否 | 请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的ordId |
| before | String | 否 | 请求此ID之后（更新的数据）的分页内容，传的值为对应接口的ordId |
| begin | String | 否 | 筛选的开始时间戳 cTime，Unix 时间戳为毫秒数格式，如 1597026383085 |
| end | String | 否 | 筛选的结束时间戳 cTime，Unix 时间戳为毫秒数格式，如 1597027383085 |
| limit | String | 否 | 返回结果的数量，最大为100，默认100条 |
返回结果
{
"code": "0",
"data": [
{
"accFillSz": "0.00192834",
"algoClOrdId": "",
"algoId": "",
"attachAlgoClOrdId": "",
"attachAlgoOrds": [],
"avgPx": "51858",
"cTime": "1708587373361",
"cancelSource": "",
"cancelSourceReason": "",
"category": "normal",
"ccy": "",
"clOrdId": "",
"fee": "-0.00000192834",
"feeCcy": "BTC",
"fillPx": "51858",
"fillSz": "0.00192834",
"fillTime": "1708587373361",
"instId": "BTC-USDT",
"instType": "SPOT",
"isTpLimit": "false",
"lever": "",
"ordId": "680800019749904384",
"ordType": "market",
"pnl": "0",
"posSide": "",
"px": "",
"pxType": "",
"pxUsd": "",
"pxVol": "",
"quickMgnType": "",
"rebate": "0",
"rebateCcy": "USDT",
"reduceOnly": "false",
"side": "buy",
"slOrdPx": "",
"slTriggerPx": "",
"slTriggerPxType": "",
"source": "",
"state": "filled",
"stpId": "",
"stpMode": "",
"sz": "100",
"tag": "",
"tdMode": "cash",
"tgtCcy": "quote_ccy",
"tpOrdPx": "",
"tpTriggerPx": "",
"tpTriggerPxType": "",
"tradeId": "744876980",
"uTime": "1708587373362",
"linkedAlgoOrd": {
"algoId": ""
}
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instType | String | 产品类型 |
| instId | String | 产品ID |
| tgtCcy | String | 币币市价单委托数量sz的单位base_ccy: 交易货币 ；quote_ccy：计价货币仅适用于 币币市价订单默认买单为 quote_ccy，卖单为base_ccy |
| ccy | String | 保证金币种，仅适用于现货和合约模式下的全仓币币杠杆订单 |
| ordId | String | 订单ID |
| clOrdId | String | 客户自定义订单ID |
| tag | String | 订单标签 |
| px | String | 委托价格，对于期权，以币(如BTC, ETH)为单位 |
| pxUsd | String | 期权价格，以USD为单位 仅适用于期权，其他业务线返回空字符串"" |
| pxVol | String | 期权订单的隐含波动率 仅适用于期权，其他业务线返回空字符串"" |
| pxType | String | 期权的价格类型 px：代表按价格下单，单位为币 (请求参数 px 的数值单位是BTC或ETH) pxVol：代表按pxVol下单 pxUsd：代表按照pxUsd下单，单位为USD (请求参数px 的数值单位是USD) |
| sz | String | 委托数量 |
| ordType | String | 订单类型 market：市价单limit：限价单 post_only：只做maker单 fok：全部成交或立即取消 ioc：立即成交并取消剩余 optimal_limit_ioc：市价委托立即成交并取消剩余（仅适用交割、永续）mmp：做市商保护(仅适用于组合保证金账户模式下的期权订单)mmp_and_post_only：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单) op_fok：期权简选（全部成交或立即取消） |
| side | String | 订单方向 |
| posSide | String | 持仓方向 |
| tdMode | String | 交易模式 |
| accFillSz | String | 累计成交数量 |
| fillPx | String | 最新成交价格，如果成交数量为0，该字段为"" |
| tradeId | String | 最新成交ID |
| fillSz | String | 最新成交数量 |
| fillTime | String | 最新成交时间 |
| avgPx | String | 成交均价，如果成交数量为0，该字段也为"" |
| state | String | 订单状态 canceled：撤单成功 filled：完全成交mmp_canceled：做市商保护机制导致的自动撤单 |
| lever | String | 杠杆倍数，0.01到125之间的数值，仅适用于 币币杠杆/交割/永续 |
| attachAlgoClOrdId | String | 下单附带止盈止损时，客户自定义的策略订单ID |
| tpTriggerPx | String | 止盈触发价 |
| tpTriggerPxType | String | 止盈触发价类型last：最新价格index：指数价格mark：标记价格 |
| tpOrdPx | String | 止盈委托价 |
| slTriggerPx | String | 止损触发价 |
| slTriggerPxType | String | 止损触发价类型last：最新价格index：指数价格mark：标记价格 |
| slOrdPx | String | 止损委托价 |
| stpId | String | 如果自成交保护不适用则返回"" |
| attachAlgoOrds | Array of object | 下单附带止盈止损信息 |
| > attachAlgoId | String | 附带止盈止损的订单ID，改单时，可用来标识该笔附带止盈止损订单。下止盈止损委托单时，该值不会传给 algoId |
| > attachAlgoClOrdId | String | 下单附带止盈止损时，客户自定义的策略订单ID |
| > tpOrdKind | String | 止盈订单类型condition: 条件单limit: 限价单 |
| > tpTriggerPx | String | 止盈触发价 |
| > tpTriggerPxType | String | 止盈触发价类型last：最新价格index：指数价格mark：标记价格 |
| > tpOrdPx | String | 止盈委托价 |
| > slTriggerPx | String | 止损触发价 |
| > slTriggerPxType | String | 止损触发价类型last：最新价格index：指数价格mark：标记价格 |
| > slOrdPx | String | 止损委托价 |
| > sz | String | 张数。仅适用于“多笔止盈”的止盈订单 |
| > amendPxOnTriggerType | String | 是否启用开仓价止损，仅适用于分批止盈的止损订单0：不开启，默认值 1：开启 |
| > failCode | String | 委托失败的错误码，默认为"", 委托失败时有值，如 51020 |
| > failReason | String | 委托失败的原因，默认为"" 委托失败时有值 |
| linkedAlgoOrd | Object | 止损订单信息，仅适用于包含限价止盈单的双向止盈止损订单，触发后生成的普通订单 |
| > algoId | Object | 策略订单唯一标识 |
| stpMode | String | 自成交保护模式 |
| feeCcy | String | 交易手续费币种 |
| fee | String | 手续费与返佣 对于币币和杠杆，为订单交易累计的手续费，平台向用户收取的交易手续费，为负数。如： -0.01 对于交割、永续和期权，为订单交易累计的手续费和返佣 |
| rebateCcy | String | 返佣金币种 |
| rebate | String | 返佣金额，仅适用于币币和杠杆，平台向达到指定lv交易等级的用户支付的挂单奖励（返佣），如果没有返佣金，该字段为“”。手续费返佣为正数，如：0.01 |
| pnl | String | 收益，适用于有成交的平仓订单，其他情况均为0 |
| source | String | 订单来源6：计划委托策略触发后的生成的普通单7：止盈止损策略触发后的生成的普通单13：策略委托单触发后的生成的普通单25：移动止盈止损策略触发后的生成的普通单 |
| category | String | 订单种类normal：普通委托twap：TWAP自动换币 adl：ADL自动减仓full_liquidation：强制平仓partial_liquidation：强制减仓 delivery：交割ddh：对冲减仓类型订单 |
| reduceOnly | String | 是否只减仓，true 或 false |
| cancelSource | String | 订单取消来源的原因枚举值代码 |
| cancelSourceReason | String | 订单取消来源的对应具体原因 |
| algoClOrdId | String | 客户自定义策略订单ID。策略订单触发，且策略单有algoClOrdId是有值，否则为"", |
| algoId | String | 策略委托单ID，策略订单触发时有值，否则为"" |
| isTpLimit | String | 是否为限价止盈，true 或 false. |
| uTime | String | 订单状态更新时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| cTime | String | 订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085 |
GET / 获取成交明细（近三天）
获取近3天的订单成交明细信息
限速：60次/2s
限速规则：UserID
HTTP 请求
GET /api/v5/trade/fills
请求示例
GET /api/v5/trade/fills
import okx.Trade as Trade
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘: 0, 模拟盘: 1
tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)
# 获取成交明细
result = tradeAPI.get_fills()
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 否 | 产品类型SPOT：币币MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权 |
| uly | String | 否 | 标的指数 |
| instFamily | String | 否 | 交易品种 适用于 交割/永续/期权 |
| instId | String | 否 | 产品 ID，如BTC-USDT |
| ordId | String | 否 | 订单 ID |
| subType | String | 否 | 成交类型 1：买入2：卖出 3：开多 4：开空 5：平多 6：平空 100：强减平多 101：强减平空 102：强减买入 103：强减卖出 104：强平平多 105：强平平空 106：强平买入 107：强平卖出 110：强平换币转入 111：强平换币转出 118：系统换币转入 119：系统换币转出 125：自动减仓平多 126：自动减仓平空 127：自动减仓买入 128：自动减仓卖出 212：一键借币的自动借币 213：一键借币的自动还币 204：大宗交易买 205：大宗交易卖 206：大宗交易开多 207：大宗交易开空 208：大宗交易平多 209：大宗交易平空 270：价差交易买271：价差交易卖272：价差交易开多273：价差交易开空274：价差交易平多275：价差交易平空 |
| after | String | 否 | 请求此 ID 之前（更旧的数据）的分页内容，传的值为对应接口的billId |
| before | String | 否 | 请求此 ID 之后（更新的数据）的分页内容，传的值为对应接口的billId |
| begin | String | 否 | 筛选的开始时间戳 ts，Unix 时间戳为毫秒数格式，如 1597026383085 |
| end | String | 否 | 筛选的结束时间戳 ts，Unix 时间戳为毫秒数格式，如 1597027383085 |
| limit | String | 否 | 返回结果的数量，最大为100，默认100条 |
返回结果
{
"code": "0",
"data": [
{
"side": "buy",
"fillSz": "0.00192834",
"fillPx": "51858",
"fillPxVol": "",
"fillFwdPx": "",
"fee": "-0.00000192834",
"fillPnl": "0",
"ordId": "680800019749904384",
"feeRate": "-0.001",
"instType": "SPOT",
"fillPxUsd": "",
"instId": "BTC-USDT",
"clOrdId": "",
"posSide": "net",
"billId": "680800019754098688",
"subType": "1",
"fillMarkVol": "",
"tag": "",
"fillTime": "1708587373361",
"execType": "T",
"fillIdxPx": "",
"tradeId": "744876980",
"fillMarkPx": "",
"feeCcy": "BTC",
"ts": "1708587373362"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instType | String | 产品类型 |
| instId | String | 产品 ID |
| tradeId | String | 最新成交 ID |
| ordId | String | 订单 ID |
| clOrdId | String | 用户自定义订单ID |
| billId | String | 账单 ID |
| subType | String | 成交类型 |
| tag | String | 订单标签 |
| fillPx | String | 最新成交价格，同"账单流水查询"的 px |
| fillSz | String | 最新成交数量 |
| fillIdxPx | String | 交易执行时的指数价格 对于交叉现货币对，返回 baseCcy-USDT 的指数价格。 例如LTC-ETH，该字段返回LTC-USDT的指数价格。 |
| fillPnl | String | 最新成交收益，适用于有成交的平仓订单。其他情况均为0。 |
| fillPxVol | String | 成交时的隐含波动率，仅适用于期权，其他业务线返回空字符串"" |
| fillPxUsd | String | 成交时的期权价格，以USD为单位，仅适用于期权，其他业务线返回空字符串"" |
| fillMarkVol | String | 成交时的标记波动率，仅适用于期权，其他业务线返回空字符串"" |
| fillFwdPx | String | 成交时的远期价格，仅适用于期权，其他业务线返回空字符串"" |
| fillMarkPx | String | 成交时的标记价格，仅适用于 交割/永续/期权 |
| side | String | 订单方向 buy：买 sell：卖 |
| posSide | String | 持仓方向 long：多 short：空 买卖模式返回 net |
| execType | String | 流动性方向 T：taker M：maker不适用于系统订单比如强平和ADL |
| feeCcy | String | 交易手续费币种或者返佣金币种 |
| fee | String | 手续费金额或者返佣金额，手续费扣除为‘负数’，如-0.01；手续费返佣为‘正数’，如 0.01 |
| ts | String | 成交明细产生时间，Unix时间戳的毫秒数格式，如1597026383085 |
| fillTime | String | 成交时间，与订单频道的fillTime相同 |
| feeRate | String | 手续费费率。 该字段仅对 币币和杠杆返回 |
GET / 获取成交明细（近三个月）
获取近3个月订单成交明细信息
限速：10 次/2s
限速规则：UserID
HTTP 请求
GET /api/v5/trade/fills-history
请求示例
GET /api/v5/trade/fills-history?instType=SPOT
import okx.Trade as Trade
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘: 0, 模拟盘: 1
tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)
# 查询 币币 成交明细（3月内）
result = tradeAPI.get_fills_history(
instType="SPOT"
)
print(result)
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instType | String | 是 | 产品类型SPOT：币币MARGIN：币币杠杆SWAP：永续合约FUTURES：交割合约OPTION：期权 |
| uly | String | 否 | 标的指数 |
| instFamily | String | 否 | 交易品种 适用于 交割/永续/期权 |
| instId | String | 否 | 产品 ID，如BTC-USD-190927 |
| ordId | String | 否 | 订单 ID |
| subType | String | 否 | 成交类型 1：买入2：卖出 3：开多 4：开空 5：平多 6：平空 100：强减平多 101：强减平空 102：强减买入 103：强减卖出 104：强平平多 105：强平平空 106：强平买入 107：强平卖出 110：强平换币转入 111：强平换币转出 118：系统换币转入 119：系统换币转出 125：自动减仓平多 126：自动减仓平空 127：自动减仓买入 128：自动减仓卖出 212：一键借币的自动借币 213：一键借币的自动还币 204：大宗交易买 205：大宗交易卖 206：大宗交易开多 207：大宗交易开空 208：大宗交易平多 209：大宗交易平空 270：价差交易买271：价差交易卖272：价差交易开多273：价差交易开空274：价差交易平多275：价差交易平空 |
| after | String | 否 | 请求此 ID 之前（更旧的数据）的分页内容，传的值为对应接口的 billId |
| before | String | 否 | 请求此 ID 之后（更新的数据）的分页内容，传的值为对应接口的 billId |
| begin | String | 否 | 筛选的开始时间戳 ts，Unix 时间戳为毫秒数格式，如 1597026383085 |
| end | String | 否 | 筛选的结束时间戳 ts，Unix 时间戳为毫秒数格式，如 1597027383085 |
| limit | String | 否 | 返回结果的数量，最大为100，默认100条 |
返回结果
{
"code": "0",
"data": [
{
"side": "buy",
"fillSz": "0.00192834",
"fillPx": "51858",
"fillPxVol": "",
"fillFwdPx": "",
"fee": "-0.00000192834",
"fillPnl": "0",
"ordId": "680800019749904384",
"feeRate": "-0.001",
"instType": "SPOT",
"fillPxUsd": "",
"instId": "BTC-USDT",
"clOrdId": "",
"posSide": "net",
"billId": "680800019754098688",
"subType": "1",
"fillMarkVol": "",
"tag": "",
"fillTime": "1708587373361",
"execType": "T",
"fillIdxPx": "",
"tradeId": "744876980",
"fillMarkPx": "",
"feeCcy": "BTC",
"ts": "1708587373362"
}
],
"msg": ""
}
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instType | String | 产品类型 |
| instId | String | 产品 ID |
| tradeId | String | 最新成交 ID |
| ordId | String | 订单 ID |
| clOrdId | String | 用户自定义订单ID |
| billId | String | 账单 ID |
| subType | String | 成交类型 |
| tag | String | 订单标签 |
| fillPx | String | 最新成交价格，同"账单流水查询"的 px |
| fillSz | String | 最新成交数量 |
| fillIdxPx | String | 交易执行时的指数价格 对于交叉现货币对，返回 baseCcy-USDT 的指数价格。 例如LTC-ETH，该字段返回 LTC-USDT 的指数价格。 |
| fillPnl | String | 最新成交收益，适用于有成交的平仓订单。其他情况均为0。 |
| fillPxVol | String | 成交时的隐含波动率，仅适用于期权，其他业务线返回空字符串"" |
| fillPxUsd | String | 成交时的期权价格，以USD为单位，仅适用于期权，其他业务线返回空字符串"" |
| fillMarkVol | String | 成交时的标记波动率，仅适用于期权，其他业务线返回空字符串"" |
| fillFwdPx | String | 成交时的远期价格，仅适用于期权，其他业务线返回空字符串"" |
| fillMarkPx | String | 成交时的标记价格，仅适用于 交割/永续/期权 |
| side | String | 订单方向buy：买sell：卖 |
| posSide | String | 持仓方向long：多short：空买卖模式返回 net |
| execType | String | 流动性方向T：takerM：maker不适用于系统订单比如强平和ADL |
| feeCcy | String | 交易手续费币种或者返佣金币种 |
| fee | String | 手续费金额或者返佣金额 手续费扣除为‘负数’，如 -0.01 手续费返佣为‘正数’，如 0.01 |
| ts | String | 成交明细产生时间，Unix时间戳的毫秒数格式，如 1597026383085 |
| fillTime | String | 成交时间，与订单频道的fillTime相同 |
| feeRate | String | 手续费费率。 该字段仅对 币币和杠杆返回 |
GET / 获取一键兑换主流币币种列表
获取小币一键兑换主流币币种列表。仅可兑换余额在 $10 以下小币币种。
限速：1次/2s
限速规则：UserID
HTTP 请求
GET /api/v5/trade/easy-convert-currency-list
请求示例
GET /api/v5/trade/easy-convert-currency-list
import okx.Trade as Trade
# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1" # 实盘: 0, 模拟盘: 1
tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)
# 获取小币一键兑换主流币币种列表
result = tradeAPI.get_easy_convert_currency_list()
print(result)
请求参数
无
返回结果
{
"code":