撮合交易

交易

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

POST / 下单

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

限速：60次/2s

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

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

限速规则（只限期权）：User ID + 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 注意：isolated（现货杠杆逐仓）在跨币种保证金模式和组合保证金模式下不可用。 事件合约对应交易产品仅支持isolated逐仓下单
ccy	String	条件必填	保证金币种 通常可选；逐仓杠杆订单及合约模式下的全仓杠杆订单必填
clOrdId	String	否	客户自定义订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
tag	String	否	订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。
side	String	是	订单方向 buy：买， sell：卖
posSide	String	可选	持仓方向 在开平仓模式下必填，且仅可选择 long 或 short。 仅适用交割、永续。SPOT 或 MARGIN 订单请勿传此字段。交割/永续在开平仓模式下如未填写，返回错误码 51000。
ordType	String	是	订单类型 market：市价单，仅适用于币币/杠杆/交割/永续 limit：限价单 post_only：只做maker单 fok：全部成交或立即取消 ioc：立即成交并取消剩余 optimal_limit_ioc：以价格限制区间的最高买价（买单）或最低卖价（卖单）挂限价单，未成交部分立即取消（IOC）。仅适用交割、永续合约，订单不会以超出当前价格限制边界的价格成交 mmp：做市商保护(仅适用于组合保证金账户模式下的期权订单) mmp_and_post_only：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单) rpi：Retail Price Improvement 订单 elp：流动性增强计划订单（已弃用，请使用 rpi。2026年10月31日前仍可使用。）
sz	String	是	委托数量
px	String	可选	委托价格，仅适用于limit、post_only、fok、ioc、mmp、mmp_and_post_only类型的订单 期权下单时，px/pxUsd/pxVol 只能填一个
outcome	String	可选	用户交易的市场结果方向。 yes no 仅适用于 EVENTS，且为必填
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时：余额不足时，整笔订单将被拒绝。为false（默认）时：系统将缩减 sz 至可用余额所能支持的数量后执行。仅适用于币币市价单
pxAmendType	String	否	订单价格修正类型 0：当px超出价格限制时，不允许系统修改订单价格 1：当px超出价格限制时，允许系统将价格修改为限制范围内的最优值 默认值为0
tradeQuoteCcy	String	否	用于交易的计价币种。仅适用于币币。 默认值为 instId 的计价币种，比如：对于 BTC-USD，默认取 USD。
slippagePct	String	否	币币、币币杠杆市价单（tgtCcy 为到手币种：买单为 base_ccy，卖单为 quote_ccy）的最大可接受滑点。 取值范围：0 至 0.05（即 0% 至 5%，含边界），以百分比形式表示时最多保留 2 位小数，例如 0.01（1%）和 0.0123（1.23%）合法；0.01234（1.234%）将被拒绝。 不填或为空时，默认为 0.00%。 不支持改单修改滑点，如需调整请撤单重新提交。 仅适用于币币和币币杠杆的市价单。
stpMode	String	否	自成交保护模式 cancel_maker,cancel_taker, cancel_both Cancel both不支持FOK 默认使用账户层面的acctStpMode进行下单，该字段的默认值为cancel_maker，用户可通过母账户登录网页修改该配置；用户亦可以通过下单接口的stpMode参数指定订单的STP模式。
rpiTakerAccess	Boolean	否	默认值为 false。 设为 true 时，订单可使用 RPI 流动性，适用于 limit、market、fok、ioc 订单。 当 rpiTakerAccess 为 true 时，减速带机制在下单和改单时均适用于所有 ordType，包括 post_only。 改单时不会从原始订单继承，必须每次显式指定（省略则该次改单视为 false）。 isElpTakerAccess 在 2026年10月31日前作为别名继续被接受。
rpiPxRound	Boolean	否	默认值为 false。仅对 RPI 做市商订单（ordType: rpi）生效。设为 true 时，违反 RPI 做市商间距规则的价格将自动向外取整至最近的合规价位，而非被拒绝。对非 RPI 订单及 OPTION/EVENTS 无效。
attachAlgoOrds	Array of objects	否	附带止盈止损或移动止盈止损订单信息
> attachAlgoClOrdId	String	否	下单附带止盈止损或移动止盈止损时，客户自定义的策略订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 订单完全成交，下附带策略委托单时，该值会传给algoClOrdId
> tpTriggerPx	String	可选	止盈触发价 对于条件止盈单，如果填写此参数，必须填写 止盈委托价
> tpTriggerRatio	String	可选	止盈触发比例，0.3 代表 30% 仅适用于交割/永续合约 tpTriggerPx 和 tpTriggerRatio 只能传入其中一个 如果主单为买入订单，必须大于 0，如果主单为卖出订单，必须处于 -1 和 0 之间。
> tpOrdPx	String	可选	止盈委托价 对于条件止盈单，如果填写此参数，必须填写 止盈触发价 对于限价止盈单，需填写此参数，不需要填写止盈触发价 委托价格为-1时，执行市价止盈
> tpOrdKind	String	否	止盈订单类型 condition: 条件单 limit: 限价单 默认为condition
> slTriggerPx	String	可选	止损触发价，如果填写此参数，必须填写 止损委托价
> slTriggerRatio	String	可选	止损触发比例，0.3 代表 30% 仅适用于交割/永续合约 slTriggerPx 和 slTriggerRatio 只能传入其中一个 如果主单为买入订单，必须处于 0 和 1 之间，如果主单为卖出订单，必须大于 0。
> slOrdPx	String	可选	止损委托价，如果填写此参数，必须填写 止损触发价 委托价格为-1时，执行市价止损
> tpTriggerPxType	String	否	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格 默认为last
> slTriggerPxType	String	否	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格 默认为last
> sz	String	可选	数量。仅适用于“多笔止盈”的止盈订单，且对于“多笔止盈”的止盈订单必填
> amendPxOnTriggerType	String	否	是否启用开仓价止损，仅适用于分批止盈的止损订单，第一笔止盈触发时，止损触发价格是否移动到开仓均价止损 0：不开启，默认值 1：开启，且止损触发价不能为空
> callbackRatio	String	可选	回调幅度的比例，如 0.05 代表 5%。 callbackRatio 和 callbackSpread 必须传入其中一个，且只能传入一个。 仅适用于 ordType = move_order_stop
> callbackSpread	String	可选	回调幅度的价距。 callbackRatio 和 callbackSpread 必须传入其中一个，且只能传入一个。 仅适用于 ordType = move_order_stop
> activePx	String	否	激活价格。 激活价格是移动止盈止损的激活条件，当市场最新成交价达到或超过激活价格，委托被激活。激活后系统开始计算止盈止损的实际触发价格。如果不填写激活价格，即下单后就被激活。 仅适用于 ordType = move_order_stop

返回结果

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

返回参数

参数名	类型	描述
code	String	结果代码，0表示成功
msg	String	错误信息，代码为0时，该字段为空
data	Array of objects	包含结果的对象数组
> ordId	String	订单ID
> clOrdId	String	客户自定义订单ID
> tag	String	订单标签
> ts	String	订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085。与订单频道中的 cTime 相同。
> sCode	String	事件执行结果的code，0代表成功
> sMsg	String	事件执行失败或成功时的msg
> subCode	String	sCode 的子码。 当 sCode 为 0（请求成功）时，返回 ""。 当 sCode 不为 0（事件执行失败）且存在子码时，返回对应的子码；若无子码，则返回 ""。
inTime	String	REST网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 返回的时间是请求验证后的时间。
outTime	String	REST网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123

tdMode 交易模式，下单时需要指定 现货模式：

• 币币和期权买方：cash 合约模式：
• 逐仓杠杆（仅限于现货杠杆逐仓）：isolated
• 全仓杠杆：cross
• 币币：cash
• 全仓交割/永续/期权：cross 跨币种保证金模式：
• 全仓币币：cross
• 全仓交割/永续/期权：cross 组合保证金模式：
• 全仓币币：cross
• 全仓交割/永续/期权：cross

clOrdId clOrdId 是用户在 User ID 维度自定义的订单唯一标识符。如果在请求参数中传入了，那它一定会在返回参数内，并且可以用于查询订单，撤销订单，修改订单等接口。 clOrdId 不能与当前所有挂单（live 或 partially_filled 状态）的 clOrdId 重复。订单达到终态（filled、canceled、mmp_canceled）后，相同的 clOrdId 可重新用于新订单。系统不强制历史唯一性——当多笔订单共享同一 clOrdId 时，GET /api/v5/trade/order 仅返回最新一笔。"普通委托单"指通过本接口下的标准订单；clOrdId 不会传递至附带的止盈止损策略订单。

posSide 持仓方向，买卖模式下此参数非必填，如果填写仅可以选择net；在开平仓模式下必填，且仅可选择 long 或 short。 开平仓模式下，side和posSide需要进行组合 开多：买入开多（side 填写 buy； posSide 填写 long ） 开空：卖出开空（side 填写 sell； posSide 填写 short ） 平多：卖出平多（side 填写 sell；posSide 填写 long ） 平空：买入平空（side 填写 buy； posSide 填写 short ） 组合保证金模式：交割和永续仅支持买卖模式 SPOT 或 MARGIN 订单请勿传此字段。交割/永续在买卖模式下可不传或传 net。

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

sz 交易数量，表示要购买或者出售的数量。 当币币/币币杠杆以限价买入和卖出时，指交易货币数量。 当币币杠杆以市价买入时，指计价货币的数量。 当币币杠杆以市价卖出时，指交易货币的数量。 对于币币市价单，单位由 tgtCcy 决定 当交割、永续、期权买入和卖出时，指合约张数。合约面值 = sz × ctVal × markPx（正向合约）或 sz × ctVal（反向合约，USD 计价）。ctVal 和 ctType 可通过 GET /api/v5/public/instruments 获取。

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

tgtCcy 市价单委托数量sz的单位：仅适用于币币市价下单交易。 快速参考（以 BTC-USDT 为例）：

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

px 期权下单时，委托价格需为 tickSz 的整数倍。 当不为整数倍时，取值规则以tickSz取 0.0005 为例： 当委托价格对0.0005的余数大于0.00025或者委托价格小于0.0005时，向上取； 当委托价格对0.0005的余数小于等于0.00025，且委托价格大于0.0005时，向下取。

对于下单附带止盈止损： 附带的止盈止损订单仅在母单成交后才会激活。若母单在任何成交前被撤销，附带的止盈止损也将一并丢弃。如需独立于母单的止盈止损，请使用 POST /api/v5/trade/order-algo。

1. 只有当该订单成交时，才会生成止盈止损策略订单；若母单在成交前被撤销，则不会生成止盈止损策略订单。
2. tgtCcy 为 base_ccy 时的市价买单和 tgtCcy 为 quote_ccy 时的市价卖单，均不支持附带止盈止损
3. tpOrdKind 为 limit，且只有一笔单边止盈时，attachAlgoClOrdId 可以作为 clOrdId 在获取订单信息接口查询。
4. 对于“分批止盈”，包含限价止盈和触发止盈：

• 分批止盈的每笔止盈止损订单仅支持单向止盈止损，slTriggerPx&slOrdPx 与 tpTriggerPx&tpOrdPx 只能填写一组，否则 报错 51076
• 同一笔订单上附带分批止盈的止盈触发价类型 (tpTriggerPxType) 必须保持一致，否则报错 51080
• 同一笔订单上附带分批止盈的止盈触发价 (tpTriggerPx) 不能相等，否则报错 51081
• 在附带分批止盈时，止盈订单的数量不能为空，否则报错 51089
• 同一笔订单上分批止盈的止盈数量之和，需要等于订单的委托数量，否则报错 51083
• 同一笔订单上分批止盈的止盈委托不能超过 10 笔，否则报错 51079
• 币币/杠杆不支持开启'开仓价止损'，否则报错 51077
• 同一笔订单上附带分批止盈的止损委托单不能超过 1 笔，否则报错 51084
• 附带止盈止损开启'开仓价止损'时 (amendPxOnTriggerType 设置为 1)，该笔订单上的止盈委托单必须大于等于 2 笔，否则报错 51085
• 同一笔订单上附带分批止盈的止盈类型必须保持一致，否则报错 51091
• 同一笔订单上附带分批止盈的止盈委托价不能相等，否则报错 51092
• 同一笔订单上附带分批止盈，其中限价止盈的止盈委托价 (tpOrdPx) 不能为 -1 (市价)，否则报错 51093
• 币币、杠杆和期权交易不支持限价止盈，否则报错 51094

强制自成交保护 交易系统会以母账户维度实施强制自成交保护，同一母账户下所有账户，包括母账户本身和所有子账户，都无法进行自成交。默认使用账户层面的acctStpMode进行下单，该字段的默认值为cancel_maker，用户可通过母账户登录网页修改该配置；用户亦可以通过下单接口的stpMode参数指定订单的STP模式。 强制自成交保护不会导致延迟。 有三种STP模式。STP模式始终基于taker订单中的配置。 1.Cancel Maker：这是默认的STP模式，系统撤Maker订单以防止自成交。然后，taker订单会基于深度继续和下一个订单成交。 2.Cancel Taker：撤Taker订单以防止自成交。如果用户的Maker订单不是深度里第一个订单，Taker订单会被部分成交，然后撤单。FOK订单会确保完全成交和自成交保护。 3.Cancel Both：撤Taker和Maker订单以防止自成交。如果用户的Maker订单不是深度里第一个订单，Taker订单会被部分成交，然后Taker订单的剩余数量和第一个自我Maker订单被取消。此模式不支持FOK订单。将 stpMode=cancel_both 与 ordType=fok 组合使用将返回错误码 50016。

tradeQuoteCcy 对于特定国家和地区的用户，下单成功需要填写该参数，否则会取 instId 的计价币种为默认值，报错 51000。 传值必须取 tradeQuoteCcyList 的枚举值，tradeQuoteCcyList 来自获取交易产品基础信息(GET /api/v5/account/instruments) 接口。

POST / 批量下单

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

限速：300个/2s

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

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

限速规则（只限期权）：User ID + 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 注意：isolated 在跨币种保证金模式和组合保证金模式下不可用。 事件合约对应交易产品仅支持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单(仅适用于组合保证金账户模式下的期权订单) rpi：Retail Price Improvement 订单 elp：流动性增强计划订单（已弃用，请使用 rpi。2026年10月31日前仍可使用。）
sz	String	是	委托数量
px	String	可选	委托价格，仅适用于limit、post_only、fok、ioc、mmp、mmp_and_post_only类型的订单 期权下单时，px/pxUsd/pxVol 只能填一个
speedBump	String	可选	减速带 1：事件合约速度限制（延迟可能因市场情况调整，不提前通知）。对 EVENTS 产品的非只挂单操作为必填。
outcome	String	可选	用户交易的市场结果方向。 yes no 仅适用于 EVENTS，且为必填
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时，余额不足时，系统不会改单，下单会失败，仅适用于币币市价单
pxAmendType	String	否	订单价格修正类型 0：当px超出价格限制时，不允许系统修改订单价格 1：当px超出价格限制时，允许系统将价格修改为限制范围内的最优值 默认值为0
stpMode	String	否	自成交保护模式 cancel_maker,cancel_taker, cancel_both Cancel both不支持FOK 默认使用账户层面的acctStpMode进行下单，该字段的默认值为cancel_maker，用户可通过母账户登录网页修改该配置；用户亦可以通过下单接口的stpMode参数指定订单的STP模式。
tradeQuoteCcy	String	否	用于交易的计价币种。仅适用于币币。 默认值为 instId 的计价币种，比如：对于 BTC-USD，默认取 USD。
slippagePct	String	否	币币、币币杠杆市价单（tgtCcy 为到手币种：买单为 base_ccy，卖单为 quote_ccy）的最大可接受滑点。 取值范围：0 至 0.05（即 0% 至 5%，含边界），以百分比形式表示时最多保留 2 位小数，例如 0.01（1%）和 0.0123（1.23%）合法；0.01234（1.234%）将被拒绝。 不填或为空时，默认为 0.00%。 不支持改单修改滑点，如需调整请撤单重新提交。 仅适用于币币和币币杠杆的市价单。
rpiTakerAccess	Boolean	否	默认值为 false。 设为 true 时，订单可使用 RPI 流动性，适用于 limit、market、fok、ioc 订单。 当 rpiTakerAccess 为 true 时，减速带机制在下单和改单时均适用于所有 ordType，包括 post_only。 改单时不会从原始订单继承，必须每次显式指定（省略则该次改单视为 false）。 isElpTakerAccess 在 2026年10月31日前作为别名继续被接受。
rpiPxRound	Boolean	否	默认值为 false。仅对 RPI 做市商订单（ordType: rpi）生效。设为 true 时，违反 RPI 做市商间距规则的价格将自动向外取整至最近的合规价位，而非被拒绝。对非 RPI 订单及 OPTION/EVENTS 无效。
attachAlgoOrds	Array of objects	否	附带止盈止损或移动止盈止损订单信息
> attachAlgoClOrdId	String	否	下单附带止盈止损或移动止盈止损时，客户自定义的策略订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 订单完全成交，下附带策略委托单时，该值会传给algoClOrdId
> tpTriggerPx	String	可选	止盈触发价 对于条件止盈单，如果填写此参数，必须填写 止盈委托价
> tpTriggerRatio	String	可选	止盈触发比例，0.3 代表 30% 仅适用于交割/永续合约 tpTriggerPx 和 tpTriggerRatio 只能传入其中一个 如果主单为买入订单，必须大于 0，如果主单为卖出订单，必须处于 -1 和 0 之间。
> tpOrdPx	String	可选	止盈委托价 对于条件止盈单，如果填写此参数，必须填写 止盈触发价 对于限价止盈单，需填写此参数，不需要填写止盈触发价 委托价格为-1时，执行市价止盈
> tpOrdKind	String	否	止盈订单类型 condition: 条件单 limit: 限价单 默认为condition
> slTriggerPx	String	可选	止损触发价，如果填写此参数，必须填写 止损委托价
> slTriggerRatio	String	可选	止损触发比例，0.3 代表 30% 仅适用于交割/永续合约 slTriggerPx 和 slTriggerRatio 只能传入其中一个 如果主单为买入订单，必须处于 0 和 1 之间，如果主单为卖出订单，必须大于 0。0 代表删除止损。
> slOrdPx	String	可选	止损委托价，如果填写此参数，必须填写 止损触发价 委托价格为-1时，执行市价止损
> tpTriggerPxType	String	否	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格 默认为last
> slTriggerPxType	String	否	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格 默认为last
> sz	String	可选	数量。仅适用于"多笔止盈"的止盈订单，且对于"多笔止盈"的止盈订单必填
> amendPxOnTriggerType	String	否	是否启用开仓价止损，仅适用于分批止盈的止损订单，第一笔止盈触发时，止损触发价格是否移动到开仓均价止损 0：不开启，默认值 1：开启，且止损触发价不能为空
> callbackRatio	String	可选	回调幅度的比例，如 0.05 代表 5%。 callbackRatio 和 callbackSpread 必须传入其中一个，且只能传入一个。 仅适用于 ordType = move_order_stop
> callbackSpread	String	可选	回调幅度的价距。 callbackRatio 和 callbackSpread 必须传入其中一个，且只能传入一个。 仅适用于 ordType = move_order_stop
> activePx	String	否	激活价格。 激活价格是移动止盈止损的激活条件，当市场最新成交价达到或超过激活价格，委托被激活。激活后系统开始计算止盈止损的实际触发价格。如果不填写激活价格，即下单后就被激活。 仅适用于 ordType = move_order_stop

返回结果

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

返回参数

参数名	类型	描述
code	String	结果代码，0表示成功
msg	String	错误信息，代码为0时，该字段为空
data	Array of objects	包含结果的对象数组
> ordId	String	订单ID
> clOrdId	String	客户自定义订单ID
> tag	String	订单标签
> ts	String	订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085。与订单频道中的 cTime 相同。
> sCode	String	事件执行结果的code，0代表成功
> sMsg	String	事件执行失败或成功时的msg
> subCode	String	sCode 的子码。 当 sCode 为 0（请求成功）时，返回 ""。 当 sCode 不为 0（请求失败）且存在子码时，返回对应的子码；若无子码，则返回 ""。
inTime	String	REST网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 返回的时间是请求验证后的时间。
outTime	String	REST网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123

在组合保证金账户模式下，或者全部成功，或者全部失败。

clOrdId clOrdId是用户自定义的唯一ID用来识别订单。如果在请求参数中传入了，那它一定会在返回参数内，并且可以用于查询订单，撤销订单，修改订单等接口。 clOrdId不能与当前所有挂单和当前请求中的clOrdId重复。

POST / 撤单

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

限速：60次/2s

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

限速规则（只限期权）：User ID + 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	Array of objects	包含结果的对象数组
> ordId	String	订单ID
> clOrdId	String	客户自定义订单ID
> ts	String	订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085。与订单频道中的 cTime 相同。
> sCode	String	事件执行结果的code，0代表成功
> sMsg	String	事件执行失败时的msg
inTime	String	REST网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 返回的时间是请求验证后的时间。
outTime	String	REST网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123

撤单返回sCode等于0不能严格认为该订单已经被撤销，只表示您的撤单请求被系统服务器所接受，撤单结果以订单频道推送的状态或者查询订单状态为准

POST / 批量撤单

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

限速：300个/2s

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

限速规则（只限期权）：User ID + 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	Array of objects	包含结果的对象数组
> ordId	String	订单ID
> clOrdId	String	客户自定义订单ID
> ts	String	订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085。与订单频道中的 cTime 相同。
> sCode	String	事件执行结果的code，0代表成功
> sMsg	String	事件执行失败时的msg
inTime	String	REST网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 返回的时间是请求验证后的时间。
outTime	String	REST网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123

POST / 修改订单

修改当前未成交的挂单

限速：60次/2s

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

限速规则：User ID + Instrument ID

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

HTTP请求

POST /api/v5/trade/amend-order

请求示例

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

import okx.Trade as Trade

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

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

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

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

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID
cxlOnFail	Boolean	否	订单修改失败时是否自动撤单 有效值：false 或 true，默认值为 false。 修改失败的场景包括：newSz 不是 lotSz 的整数倍、超出仓位或风险限额等。false（默认）：修改失败时原订单继续保持不变。true：修改失败时原订单将自动撤销。
ordId	String	可选	订单ID ordId和clOrdId必须传一个，若传两个，以ordId为主
clOrdId	String	可选	用户自定义订单ID
reqId	String	否	用户自定义修改事件ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
newSz	String	可选	修改后的总目标委托量，必须大于0。这是期望的总委托量，而非剩余未成交量。对于部分成交的订单：如果已成交3张合约，您希望总量为8张，则填写 newSz=8（而非5）。系统将尝试成交剩余的5张。newSz、newPx（或期权的 newPxUsd/newPxVol）至少需要填写一个。
newPx	String	可选	修改后的新价格 修改的新价格期权改单时，newPx/newPxUsd/newPxVol 只能填一个，且必须与下单参数保持一致，如下单用px，改单时需使用newPx newSz 或 newPx 至少需要填写一个。
speedBump	String	可选	减速带 1：事件合约速度限制（延迟可能因市场情况调整，不提前通知）。对 EVENTS 产品的非只挂单操作为必填。
newPxUsd	String	可选	以USD价格进行期权改单 仅适用于期权，期权改单时，newPx/newPxUsd/newPxVol 只能填一个
newPxVol	String	可选	以隐含波动率进行期权改单，如 1 代表 100% 仅适用于期权，期权改单时，newPx/newPxUsd/newPxVol 只能填一个
pxAmendType	String	否	订单价格修正类型 0：当newPx超出价格限制时，不允许系统修改订单价格 1：当newPx超出价格限制时，允许系统将价格修改为限制范围内的最优值 默认值为0
attachAlgoOrds	Array of objects	否	修改附带止盈止损或移动止盈止损订单信息
> attachAlgoId	String	可选	附带止盈止损或移动止盈止损的订单ID，由系统生成，改单时必填，用来标识该笔附带止盈止损订单。下附带策略委托单时，该值不会传给 algoId
> attachAlgoClOrdId	String	可选	下单附带止盈止损或移动止盈止损时，客户自定义的策略订单ID
> newTpTriggerPx	String	可选	止盈触发价 如果止盈触发价或者委托价为0，那代表删除止盈。
> newTpTriggerRatio	String	可选	止盈触发比例，0.3 代表 30% 仅适用于交割/永续合约 newTpTriggerPx 和 newTpTriggerRatio 只能传入其中一个 如果主单为买入订单，必须大于 0，如果主单为卖出订单，必须处于 -1 和 0 之间。0 代表删除止盈。
> newTpOrdPx	String	可选	止盈委托价 委托价格为-1时，执行市价止盈。
> newTpOrdKind	String	否	止盈订单类型 condition: 条件单 limit: 限价单
> newSlTriggerPx	String	可选	止损触发价 如果止损触发价或者委托价为0，那代表删除止损。
> newSlTriggerRatio	String	可选	止损触发比例，0.3 代表 30% 仅适用于交割/永续合约 newSlTriggerPx 和 newSlTriggerRatio 只能传入其中一个 如果主单为买入订单，必须处于 0 和 1 之间，如果主单为卖出订单，必须大于 0。0 代表删除止损。
> newSlOrdPx	String	可选	止损委托价 委托价格为-1时，执行市价止损。
> newTpTriggerPxType	String	可选	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格 只适用于交割/永续 如果要新增止盈，该参数必填
> newSlTriggerPxType	String	可选	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格 只适用于交割/永续 如果要新增止损，该参数必填
> sz	String	可选	新的张数。仅适用于“多笔止盈”的止盈订单且必填
> amendPxOnTriggerType	String	否	是否启用开仓价止损，仅适用于分批止盈的止损订单 0：不开启，默认值 1：开启
> newCallbackRatio	String	可选	新的回调幅度比例，如 0.05 代表 5%。 newCallbackRatio 和 newCallbackSpread 只能传入其中一个。 仅适用于 ordType = move_order_stop
> newCallbackSpread	String	可选	新的回调幅度价距。 newCallbackRatio 和 newCallbackSpread 只能传入其中一个。 仅适用于 ordType = move_order_stop
> newActivePx	String	否	新的激活价格。 仅适用于 ordType = move_order_stop
rpiTakerAccess	Boolean	否	默认值为 false。 设为 true 时，改单后的订单可使用 RPI 流动性，适用于 limit、market、fok、ioc 订单。 改单时不会从原始订单继承，必须每次显式指定（省略则该次改单视为 false）。
rpiPxRound	Boolean	否	默认值为 false。仅对 RPI 做市商订单（ordType: rpi）生效。设为 true 时，违反间距规则的价格将自动向外取整至最近的合规价位，而非被拒绝。对非 RPI 订单及 OPTION/EVENTS 无效。

newSz 修改的数量<=该笔订单已成交数量时，该订单的状态会修改为完全成交状态。

返回结果

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

返回参数

参数名	类型	描述
code	String	结果代码，0表示成功
msg	String	错误信息，代码为0时，该字段为空
data	Array of objects	包含结果的对象数组
> ordId	String	订单ID
> clOrdId	String	用户自定义ID
> ts	String	订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085。与订单频道中的 cTime 相同。
> reqId	String	用户自定义修改事件ID
> sCode	String	事件执行结果的code，0代表成功
> sMsg	String	事件执行失败时的msg
> subCode	String	sCode 的子码。 当 sCode 为 0（请求成功）时，返回 ""。 当 sCode 不为 0（请求失败）且存在子码时，返回对应的子码；若无子码，则返回 ""。
inTime	String	REST网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 返回的时间是请求验证后的时间。
outTime	String	REST网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123

修改订单返回sCode等于0不能严格认为该订单已经被修改，只表示您的修改订单请求被系统服务器所接受，改单结果以订单频道推送的状态或者查询订单状态为准

POST / 批量修改订单

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

限速：300个/2s

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

限速规则：User ID + Instrument ID

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

与其他限速按接口调用次数不同，该接口限速按订单的总个数限速。如果单次批量请求中只有一个元素，则算在单个修改订单限速中。

HTTP请求

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

请求示例

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

import okx.Trade as Trade

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

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

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

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

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

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID
cxlOnFail	Boolean	否	订单修改失败时是否自动撤单 有效值：false 或 true，默认值为 false。 修改失败的场景包括：newSz 不是 lotSz 的整数倍、超出仓位或风险限额等。false（默认）：修改失败时原订单继续保持不变。true：修改失败时原订单将自动撤销。
ordId	String	可选	订单ID， ordId和clOrdId必须传一个，若传两个，以ordId为主
clOrdId	String	可选	用户自定义order ID
reqId	String	否	用户自定义修改事件ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
newSz	String	可选	修改的新数量，必须大于0，对于部分成交订单，该数量应包含已成交数量。
newPx	String	可选	修改后的新价格 修改的新价格期权改单时，newPx/newPxUsd/newPxVol 只能填一个，且必须与下单参数保持一致，如下单用px，改单时需使用newPx
speedBump	String	可选	减速带 1：事件合约速度限制（延迟可能因市场情况调整，不提前通知）。对 EVENTS 产品的非只挂单操作为必填。
newPxUsd	String	可选	以USD价格进行期权改单 仅适用于期权，期权改单时，newPx/newPxUsd/newPxVol 只能填一个
newPxVol	String	可选	以隐含波动率进行期权改单，如 1 代表 100% 仅适用于期权，期权改单时，newPx/newPxUsd/newPxVol 只能填一个
pxAmendType	String	否	订单价格修正类型 0：当newPx超出价格限制时，不允许系统修改订单价格 1：当newPx超出价格限制时，允许系统将价格修改为限制范围内的最优值 默认值为0
attachAlgoOrds	Array of objects	否	附带止盈止损或移动止盈止损订单信息
> attachAlgoId	String	可选	附带止盈止损或移动止盈止损的订单ID，由系统生成，改单时必填，用来标识该笔附带止盈止损订单。下附带策略委托单时，该值不会传给 algoId
> attachAlgoClOrdId	String	可选	下单附带止盈止损或移动止盈止损时，客户自定义的策略订单ID
> newTpTriggerPx	String	可选	止盈触发价 如果止盈触发价或者委托价为0，那代表删除止盈。
> newTpTriggerRatio	String	可选	止盈触发比例，0.3 代表 30% 仅适用于交割/永续合约 newTpTriggerPx 和 newTpTriggerRatio 只能传入其中一个 如果主单为买入订单，必须大于 0，如果主单为卖出订单，必须处于 -1 和 0 之间。 0 means to delete the take-profit.
> newTpOrdPx	String	可选	止盈委托价 委托价格为-1时，执行市价止盈。
> newTpOrdKind	String	否	止盈订单类型 condition: 条件单 limit: 限价单
> newSlTriggerPx	String	可选	止损触发价 如果止损触发价或者委托价为0，那代表删除止损。
> newSlTriggerRatio	String	可选	止损触发比例，0.3 代表 30% 仅适用于交割/永续合约 newSlTriggerPx 和 newSlTriggerRatio 只能传入其中一个 如果主单为买入订单，必须处于 0 和 1 之间，如果主单为卖出订单，必须大于 0。0 means to delete the stop-loss.
> newSlOrdPx	String	可选	止损委托价 委托价格为-1时，执行市价止损。
> newTpTriggerPxType	String	可选	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格 只适用于交割/永续 如果要新增止盈，该参数必填
> newSlTriggerPxType	String	可选	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格 只适用于交割/永续 如果要新增止损，该参数必填
> sz	String	可选	新的张数。仅适用于“多笔止盈”的止盈订单且必填
> amendPxOnTriggerType	String	否	是否启用开仓价止损，仅适用于分批止盈的止损订单 0：不开启，默认值 1：开启
> newCallbackRatio	String	可选	新的回调幅度比例，如 0.05 代表 5%。 newCallbackRatio 和 newCallbackSpread 只能传入其中一个。 仅适用于 ordType = move_order_stop
> newCallbackSpread	String	可选	新的回调幅度价距。 newCallbackRatio 和 newCallbackSpread 只能传入其中一个。 仅适用于 ordType = move_order_stop
> newActivePx	String	否	新的激活价格。 仅适用于 ordType = move_order_stop
rpiTakerAccess	Boolean	否	默认值为 false。 设为 true 时，改单后的订单可使用 RPI 流动性，适用于 limit、market、fok、ioc 订单。 改单时不会从原始订单继承，必须每次显式指定（省略则该次改单视为 false）。
rpiPxRound	Boolean	否	默认值为 false。仅对 RPI 做市商订单（ordType: rpi）生效。设为 true 时，违反间距规则的价格将自动向外取整至最近的合规价位，而非被拒绝。对非 RPI 订单及 OPTION/EVENTS 无效。

newSz 修改的数量<=该笔订单已成交数量时，该订单的状态会修改为完全成交状态。

返回结果

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

返回参数

参数名	类型	描述
code	String	结果代码，0表示成功
msg	String	错误信息，代码为0时，该字段为空
data	Array of objects	包含结果的对象数组
> ordId	String	订单ID
> clOrdId	String	用户自定义ID
> ts	String	订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085。与订单频道中的 cTime 相同。
> reqId	String	用户自定义修改事件ID
> sCode	String	事件执行结果的code，0代表成功
> sMsg	String	事件执行失败时的msg
> subCode	String	sCode 的子码。 当 sCode 为 0（请求成功）时，返回 ""。 当 sCode 不为 0（请求失败）且存在子码时，返回对应的子码；若无子码，则返回 ""。
inTime	String	REST网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123 返回的时间是请求验证后的时间。
outTime	String	REST网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123

POST / 市价仓位全平

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

限速：20次/2s

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

限速规则（只限期权）：User ID + 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

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

限速规则（只限期权）：User ID + 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",
            "tradeQuoteCcy": "USDT",
            "uTime": "1708587373362"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instType	String	产品类型 SPOT：币币 MARGIN：币币杠杆 SWAP：永续合约 FUTURES：交割合约 OPTION：期权 EVENTS：事件合约
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：期权简选（全部成交或立即取消） rpi：Retail Price Improvement 订单 elp：流动性增强计划订单（已弃用，请使用 rpi。2026年10月31日前仍可使用。）
side	String	订单方向
posSide	String	持仓方向
tdMode	String	交易模式
accFillSz	String	自下单以来的累计成交数量。在WebSocket订单频道推送中，accFillSz 始终表示累计总量，而非本次推送的增量。 对于币币和杠杆，单位为交易货币，如 BTC-USDT, 单位为 BTC； 对于交割、永续以及期权，单位为张。
fillPx	String	最新成交价格，如果成交数量为0，该字段为""
tradeId	String	最新成交ID
fillSz	String	最近一次单笔成交数量（非累计）。累计成交总量请使用 accFillSz。 对于币币和杠杆，单位为交易货币，如 BTC-USDT, 单位为 BTC； 对于交割、永续以及期权，单位为张。
fillTime	String	最新成交时间
avgPx	String	成交均价，如果成交数量为0，该字段也为""
state	String	订单状态： live：已在订单簿中，尚无成交。 partially_filled：部分成交，仍在订单簿中。 filled：完全成交，终态。 canceled：撤单，终态。IOC 订单被撤销时可能存在部分成交，此时 accFillSz 不为零。 mmp_canceled：由做市商保护机制自动撤单，终态。 注意：GET /api/v5/trade/orders-pending 仅返回 live 和 partially_filled；GET /api/v5/trade/orders-history 返回 filled、canceled 和 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 objects	附带止盈止损或移动止盈止损订单信息
> attachAlgoId	String	附带止盈止损或移动止盈止损的订单ID，改单时，可用来标识该笔附带止盈止损订单。下附带策略委托单时，该值不会传给 algoId
> attachAlgoClOrdId	String	下单附带止盈止损或移动止盈止损时，客户自定义的策略订单ID
> tpOrdKind	String	止盈订单类型 condition: 条件单 limit: 限价单
> tpTriggerPx	String	止盈触发价
> tpTriggerRatio	String	止盈触发比例，0.3 代表 30% 仅适用于交割/永续合约
> tpTriggerPxType	String	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格
> tpOrdPx	String	止盈委托价
> slTriggerPx	String	止损触发价
> slTriggerRatio	String	止损触发比例，0.3 代表 30% 仅适用于交割/永续合约
> slTriggerPxType	String	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格
> slOrdPx	String	止损委托价
> sz	String	张数。仅适用于“多笔止盈”的止盈订单
> amendPxOnTriggerType	String	是否启用开仓价止损，仅适用于分批止盈的止损订单 0：不开启，默认值 1：开启
> callbackRatio	String	回调幅度的比例，如 0.05 代表 5%
> callbackSpread	String	回调幅度的价距
> activePx	String	激活价格
> failCode	String	委托失败的错误码，默认为"", 委托失败时有值，如 51020
> failReason	String	委托失败的原因，默认为"" 委托失败时有值
linkedAlgoOrd	Object	止损订单信息，仅适用于包含限价止盈单的双向止盈止损订单，触发后生成的普通订单
> algoId	String	策略订单唯一标识
stpId	String	自成交保护ID 如果自成交保护不适用则返回""（已弃用）
stpMode	String	自成交保护模式
feeCcy	String	手续费币种 对于币币和杠杆的挂单卖单，表示计价币种；其他情况下，表示收取手续费的币种。
fee	String	手续费金额。符号规则：负数表示向平台净支付手续费；正数表示从平台净获得返佣。该净额已包含手续费与返佣的轧差。 对于币币和杠杆（除挂单卖单外）：平台收取的累计手续费，始终为负数。 对于币币和杠杆的挂单卖单、交割、永续和期权：累计手续费和返佣（币币和杠杆挂单卖单始终以计价币种计算）。 如需分开核算，请结合 feeCcy+fee 与 rebateCcy+rebate 使用，两者货币种类可能不同。
rebateCcy	String	返佣币种 对于币币和杠杆的挂单卖单，表示交易币种；其他情况下，表示支付返佣的币种。
rebate	String	返佣金额，仅适用于币币和杠杆 对于挂单卖单：以交易币种为单位的累计手续费和返佣金额。 其他情况下，表示挂单返佣金额，始终为正数，如无返佣则返回""。
source	String	订单来源（列表不完整——如遇未知值请做容错处理，后续可能新增类型）： 6：计划委托策略触发后生成的普通单 7：止盈止损策略触发后生成的普通单 13：策略委托单触发后生成的普通单 25：移动止盈止损策略触发后生成的普通单 34：追逐限价委托生成的普通单 所有值均表示由母策略或算法订单触发生成的系统子单。
category	String	订单种类： normal：用户正常下单。 twap：系统生成的强制还款单（非TWAP算法策略）。 adl：ADL自动减仓，系统触发的仓位削减。 full_liquidation：因保证金不足触发的全仓强制平仓。 partial_liquidation：因保证金不足触发的部分强制平仓。 delivery：期货/期权到期结算执行。 ddh：期权做市商系统触发的Delta动态对冲单。 auto_conversion：系统触发的资产自动转换单。
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
tradeQuoteCcy	String	用于交易的计价币种。
outcome	String	用户交易的市场结果方向。 yes no 仅适用于 EVENTS

GET / 获取未成交订单列表

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

限速：60次/2s

限速规则：User ID

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：期权 EVENTS：事件合约
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：期权简选（全部成交或立即取消） rpi：Retail Price Improvement 订单 elp：流动性增强计划订单（已弃用，请使用 rpi。2026年10月31日前仍可使用。）
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": "",
            ”tradeQuoteCcy“: "USDT",
            "uTime": "1724733617998"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instType	String	产品类型 SPOT：币币 MARGIN：币币杠杆 SWAP：永续合约 FUTURES：交割合约 OPTION：期权 EVENTS：事件合约
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：期权简选（全部成交或立即取消） rpi：Retail Price Improvement 订单 elp：流动性增强计划订单（已弃用，请使用 rpi。2026年10月31日前仍可使用。）
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 objects	附带止盈止损或移动止盈止损订单信息
> attachAlgoId	String	附带止盈止损或移动止盈止损的订单ID，改单时，可用来标识该笔附带止盈止损订单。下附带策略委托单时，该值不会传给 algoId
> attachAlgoClOrdId	String	下单附带止盈止损或移动止盈止损时，客户自定义的策略订单ID
> tpOrdKind	String	止盈订单类型 condition: 条件单 limit: 限价单
> tpTriggerPx	String	止盈触发价
> tpTriggerRatio	String	止盈触发比例，0.3 代表 30% 仅适用于交割/永续合约
> tpTriggerPxType	String	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格
> tpOrdPx	String	止盈委托价
> slTriggerPx	String	止损触发价
> slTriggerRatio	String	止损触发比例，0.3 代表 30% 仅适用于交割/永续合约
> slTriggerPxType	String	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格
> slOrdPx	String	止损委托价
> sz	String	张数。仅适用于”多笔止盈”的止盈订单
> amendPxOnTriggerType	String	是否启用开仓价止损，仅适用于分批止盈的止损订单 0：不开启，默认值 1：开启
> callbackRatio	String	回调幅度的比例，如 0.05 代表 5%
> callbackSpread	String	回调幅度的价距
> activePx	String	激活价格
> failCode	String	委托失败的错误码，默认为””, 委托失败时有值，如 51020
> failReason	String	委托失败的原因，默认为”” 委托失败时有值
linkedAlgoOrd	Object	止损订单信息，仅适用于包含限价止盈单的双向止盈止损订单，触发后生成的普通订单
> algoId	String	策略订单唯一标识
stpId	String	自成交保护ID 如果自成交保护不适用则返回""（已弃用）
stpMode	String	自成交保护模式
feeCcy	String	手续费币种 对于币币和杠杆的挂单卖单，表示计价币种；其他情况下，表示收取手续费的币种。
fee	String	手续费金额 对于币币和杠杆（除挂单卖单外）：平台收取的累计手续费，始终为负数。 对于币币和杠杆的挂单卖单、交割、永续和期权：累计手续费和返佣（币币和杠杆挂单卖单始终以计价币种计算）。
rebateCcy	String	返佣币种 对于币币和杠杆的挂单卖单，表示交易币种；其他情况下，表示支付返佣的币种。
rebate	String	返佣金额，仅适用于币币和杠杆 对于挂单卖单：以交易币种为单位的累计手续费和返佣金额。 其他情况下，表示挂单返佣金额，始终为正数，如无返佣则返回""。
source	String	订单来源 6：计划委托策略触发后的生成的普通单 7：止盈止损策略触发后的生成的普通单 13：策略委托单触发后的生成的普通单 25：移动止盈止损策略触发后的生成的普通单 34: 追逐限价委托生成的普通单
category	String	订单种类 normal：普通委托 twap：TWAP自动换币 adl：ADL自动减仓 full_liquidation：强制平仓 partial_liquidation：强制减仓 delivery：交割 ddh：对冲减仓类型订单 auto_conversion：抵押借币自动还币订单
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	订单取消来源的对应具体原因
tradeQuoteCcy	String	用于交易的计价币种。
outcome	String	用户交易的市场结果方向。 yes no 仅适用于 EVENTS

GET / 获取历史订单记录（近七天）

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

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

限速：40次/2s

限速规则：User ID

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：期权 EVENTS：事件合约
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：期权简选（全部成交或立即取消） rpi：Retail Price Improvement 订单 elp：流动性增强计划订单（已弃用，请使用 rpi。2026年10月31日前仍可使用。）
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",
            ”tradeQuoteCcy“: "USDT",
            "uTime": "1708587373362",
            "linkedAlgoOrd": {
                "algoId": ""
            }
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instType	String	产品类型 SPOT：币币 MARGIN：币币杠杆 SWAP：永续合约 FUTURES：交割合约 OPTION：期权 EVENTS：事件合约
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：期权简选（全部成交或立即取消） rpi：Retail Price Improvement 订单 elp：流动性增强计划订单（已弃用，请使用 rpi。2026年10月31日前仍可使用。）
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 objects	附带止盈止损或移动止盈止损订单信息
> attachAlgoId	String	附带止盈止损或移动止盈止损的订单ID，改单时，可用来标识该笔附带止盈止损订单。下附带策略委托单时，该值不会传给 algoId
> attachAlgoClOrdId	String	下单附带止盈止损或移动止盈止损时，客户自定义的策略订单ID
> tpOrdKind	String	止盈订单类型 condition: 条件单 limit: 限价单
> tpTriggerPx	String	止盈触发价
> tpTriggerRatio	String	止盈触发比例，0.3 代表 30% 仅适用于交割/永续合约
> tpTriggerPxType	String	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格
> tpOrdPx	String	止盈委托价
> slTriggerPx	String	止损触发价
> slTriggerRatio	String	止损触发比例，0.3 代表 30% 仅适用于交割/永续合约
> slTriggerPxType	String	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格
> slOrdPx	String	止损委托价
> sz	String	张数。仅适用于“多笔止盈”的止盈订单
> amendPxOnTriggerType	String	是否启用开仓价止损，仅适用于分批止盈的止损订单 0：不开启，默认值 1：开启
> callbackRatio	String	回调幅度的比例，如 0.05 代表 5%
> callbackSpread	String	回调幅度的价距
> activePx	String	激活价格
> failCode	String	委托失败的错误码，默认为"", 委托失败时有值，如 51020
> failReason	String	委托失败的原因，默认为"" 委托失败时有值
linkedAlgoOrd	Object	止损订单信息，仅适用于包含限价止盈单的双向止盈止损订单，触发后生成的普通订单
> algoId	String	策略订单唯一标识
stpId	String	自成交保护ID 如果自成交保护不适用则返回""（已弃用）
stpMode	String	自成交保护模式
feeCcy	String	手续费币种 对于币币和杠杆的挂单卖单，表示计价币种；其他情况下，表示收取手续费的币种。
fee	String	手续费金额 对于币币和杠杆（除挂单卖单外）：平台收取的累计手续费，始终为负数。 对于币币和杠杆的挂单卖单、交割、永续和期权：累计手续费和返佣（币币和杠杆挂单卖单始终以计价币种计算）。
rebateCcy	String	返佣币种 对于币币和杠杆的挂单卖单，表示交易币种；其他情况下，表示支付返佣的币种。
rebate	String	返佣金额，仅适用于币币和杠杆 对于挂单卖单：以交易币种为单位的累计手续费和返佣金额。 其他情况下，表示挂单返佣金额，始终为正数，如无返佣则返回""。
source	String	订单来源 6：计划委托策略触发后的生成的普通单 7：止盈止损策略触发后的生成的普通单 13：策略委托单触发后的生成的普通单 25：移动止盈止损策略触发后的生成的普通单 34: 追逐限价委托生成的普通单
pnl	String	收益(不包括手续费) 适用于有成交的平仓订单，其他情况均为0
category	String	订单种类 normal：普通委托 twap：TWAP自动换币 adl：ADL自动减仓 full_liquidation：强制平仓 partial_liquidation：强制减仓 delivery：交割 ddh：对冲减仓类型订单 auto_conversion：抵押借币自动还币订单
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
quickMgnType	String	一键借币类型，仅适用于杠杆逐仓的一键借币模式 manual：手动，auto_borrow：自动借币，auto_repay：自动还币（已弃用）
tradeQuoteCcy	String	用于交易的计价币种。
outcome	String	用户交易的市场结果方向。 yes no 仅适用于 EVENTS

GET / 获取历史订单记录（近三个月）

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

限速：20次/2s

限速规则：User ID

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：期权 EVENTS：事件合约
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：期权简选（全部成交或立即取消） rpi：Retail Price Improvement 订单 elp：流动性增强计划订单（已弃用，请使用 rpi。2026年10月31日前仍可使用。）
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",
            ”tradeQuoteCcy“: "USDT",
            "uTime": "1708587373362",
            "linkedAlgoOrd": {
                "algoId": ""
            }
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instType	String	产品类型 SPOT：币币 MARGIN：币币杠杆 SWAP：永续合约 FUTURES：交割合约 OPTION：期权 EVENTS：事件合约
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：期权简选（全部成交或立即取消） rpi：Retail Price Improvement 订单 elp：流动性增强计划订单（已弃用，请使用 rpi。2026年10月31日前仍可使用。）
side	String	订单方向
posSide	String	持仓方向
tdMode	String	交易模式
accFillSz	String	累计成交数量
fillPx	String	最新成交价格，如果成交数量为0，该字段为""
tradeId	String	最新成交ID
fillSz	String	最新成交数量
fillTime	String	最新成交时间
avgPx	String	成交均价，如果成交数量为0，该字段也为""
state	String	订单状态 canceled：撤单成功 filled：完全成交 mmp_canceled：做市商保护机制导致的自动撤单
lever	String	杠杆倍数，0.01到125之间的数值，仅适用于 币币杠杆/交割/永续
attachAlgoClOrdId	String	下单附带止盈止损或移动止盈止损时，客户自定义的策略订单ID
tpTriggerPx	String	止盈触发价
tpTriggerPxType	String	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格
tpOrdPx	String	止盈委托价
slTriggerPx	String	止损触发价
slTriggerPxType	String	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格
slOrdPx	String	止损委托价
stpId	String	自成交保护ID 如果自成交保护不适用则返回""（已弃用）
attachAlgoOrds	Array of objects	附带止盈止损或移动止盈止损订单信息
> attachAlgoId	String	附带止盈止损或移动止盈止损的订单ID，改单时，可用来标识该笔附带止盈止损订单。下附带策略委托单时，该值不会传给 algoId
> attachAlgoClOrdId	String	下单附带止盈止损或移动止盈止损时，客户自定义的策略订单ID
> tpOrdKind	String	止盈订单类型 condition: 条件单 limit: 限价单
> tpTriggerPx	String	止盈触发价
> tpTriggerRatio	String	止盈触发比例，0.3 代表 30% 仅适用于交割/永续合约
> tpTriggerPxType	String	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格
> tpOrdPx	String	止盈委托价
> slTriggerPx	String	止损触发价
> slTriggerRatio	String	止损触发比例，0.3 代表 30% 仅适用于交割/永续合约
> slTriggerPxType	String	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格
> slOrdPx	String	止损委托价
> sz	String	张数。仅适用于“多笔止盈”的止盈订单
> amendPxOnTriggerType	String	是否启用开仓价止损，仅适用于分批止盈的止损订单 0：不开启，默认值 1：开启
> callbackRatio	String	回调幅度的比例，如 0.05 代表 5%
> callbackSpread	String	回调幅度的价距
> activePx	String	激活价格
> failCode	String	委托失败的错误码，默认为"", 委托失败时有值，如 51020
> failReason	String	委托失败的原因，默认为"" 委托失败时有值
linkedAlgoOrd	Object	止损订单信息，仅适用于包含限价止盈单的双向止盈止损订单，触发后生成的普通订单
> algoId	String	策略订单唯一标识
stpMode	String	自成交保护模式
feeCcy	String	手续费币种 对于币币和杠杆的挂单卖单，表示计价币种；其他情况下，表示收取手续费的币种。
fee	String	手续费金额 对于币币和杠杆（除挂单卖单外）：平台收取的累计手续费，始终为负数。 对于币币和杠杆的挂单卖单、交割、永续和期权：累计手续费和返佣（币币和杠杆挂单卖单始终以计价币种计算）。
rebateCcy	String	返佣币种 对于币币和杠杆的挂单卖单，表示交易币种；其他情况下，表示支付返佣的币种。
rebate	String	返佣金额，仅适用于币币和杠杆 对于挂单卖单：以交易币种为单位的累计手续费和返佣金额。 其他情况下，表示挂单返佣金额，始终为正数，如无返佣则返回""。
pnl	String	收益(不包括手续费) 适用于有成交的平仓订单，其他情况均为0
source	String	订单来源 6：计划委托策略触发后的生成的普通单 7：止盈止损策略触发后的生成的普通单 13：策略委托单触发后的生成的普通单 25：移动止盈止损策略触发后的生成的普通单 34: 追逐限价委托生成的普通单
category	String	订单种类 normal：普通委托 twap：TWAP自动换币 adl：ADL自动减仓 full_liquidation：强制平仓 partial_liquidation：强制减仓 delivery：交割 ddh：对冲减仓类型订单 auto_conversion：抵押借币自动还币订单
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
quickMgnType	String	一键借币类型，仅适用于杠杆逐仓的一键借币模式 manual：手动，auto_borrow：自动借币，auto_repay：自动还币（已弃用）
tradeQuoteCcy	String	用于交易的计价币种。
outcome	String	用户交易的市场结果方向。 yes no 仅适用于 EVENTS

该接口不包含已撤销的完全无成交类型订单数据，可通过获取历史订单记录（近七天)接口获取。

对于已完成的期权订单，如果是px订单，pxVol 和 pxUsd 会实时更新，如果是 pxUsd 订单，pxVol 会实时更新，如果是pxVol 订单，pxUsd 会实时更新。

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

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

限速：60次/2s

限速规则：User ID

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：期权 EVENTS：事件合约
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：系统换币转出 112：交割平多 113：交割平空 125：自动减仓平多 126：自动减仓平空 127：自动减仓买入 128：自动减仓卖出 212：一键借币的自动借币 213：一键借币的自动还币 204：大宗交易买 205：大宗交易卖 206：大宗交易开多 207：大宗交易开空 208：大宗交易平多 209：大宗交易平空 236：小额兑换买入 237：小额兑换卖出 270：价差交易买 271：价差交易卖 272：价差交易开多 273：价差交易开空 274：价差交易平多 275：价差交易平空 324：移仓买入 325：移仓卖出 326：移仓开多 327：移仓开空 328：移仓平多 329：移仓平空 376：质押借币超限买入 377： 质押借币超限卖出 410：买入yes 411：买入no 412：卖出yes 413：卖出no 414：yes结算 415：no结算
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",
            "tradeQuoteCcy": "USDT"
        }
    ],
    "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	本次成交的已实现盈亏，以结算货币（见 feeCcy）计价，仅适用于平仓交易。正数为盈利，负数为亏损。公式：正向合约 = (fillPx − avgPx) × fillSz × ctVal；反向合约 = (1/avgPx − 1/fillPx) × fillSz × ctVal。开仓交易返回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毫秒数格式（UTC）。注意：此字段与 fillTime（实际撮合成交时间）不同。若需按时间顺序排列成交记录，请使用 fillTime 而非 ts 进行排序。
fillTime	String	成交时间，与订单频道的fillTime相同
feeRate	String	手续费费率。 该字段仅对 币币和杠杆返回
tradeQuoteCcy	String	用于交易的计价币种。

tradeId 当订单种类（category）为 partial_liquidation：强制减仓、full_liquidation：强制平仓、adl：ADL自动减仓时，成交明细 tradeId 字段的值为负数，以便和其他撮合成交场景区分，订单信息 tradeId 字段的值为 0

ordId 订单ID, 对于大宗交易总是 "" 。

clOrdId 用户自定义订单ID, 对于大宗交易总是 "" 。

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

本接口可以查询最近 3 个月的成交明细数据。

限速：10 次/2s

限速规则：User ID

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：期权 EVENTS：事件合约
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：系统换币转出 112：交割平多 113：交割平空 125：自动减仓平多 126：自动减仓平空 127：自动减仓买入 128：自动减仓卖出 212：一键借币的自动借币 213：一键借币的自动还币 204：大宗交易买 205：大宗交易卖 206：大宗交易开多 207：大宗交易开空 208：大宗交易平多 209：大宗交易平空 236：小额兑换买入 237：小额兑换卖出 270：价差交易买 271：价差交易卖 272：价差交易开多 273：价差交易开空 274：价差交易平多 275：价差交易平空 324：移仓买入 325：移仓卖出 326：移仓开多 327：移仓开空 328：移仓平多 329：移仓平空 376：质押借币超限买入 377： 质押借币超限卖出 410：买入yes 411：买入no 412：卖出yes 413：卖出no 414：yes结算 415：no结算
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",
            "tradeQuoteCcy": "USDT"
        }
    ],
    "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	手续费费率。 该字段仅对 币币和杠杆返回
tradeQuoteCcy	String	用于交易的计价币种。

tradeId 当成交明细所归属的订单种类（category）为 partial_liquidation：强制减仓、full_liquidation：强制平仓、adl：ADL自动减仓时，tradeId字段的值为负数，以便和其他撮合成交场景区分

ordId 订单ID, 对于大宗交易总是 "" 。

clOrdId 用户自定义订单ID, 对于大宗交易总是 "" 。

获取近3天的成交明细时，建议使用获取成交明细（近三天）接口。

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

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

限速：1次/2s

限速规则：User ID

HTTP 请求

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

请求示例

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

import okx.Trade as Trade

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

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

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

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

请求参数

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

返回结果

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

返回参数

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

POST / 一键兑换主流币交易

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

限速：1次/2s

限速规则：User ID

HTTP 请求

POST /api/v5/trade/easy-convert

请求示例

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

import okx.Trade as Trade

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

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

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

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

请求参数

参数名	类型	是否必须	描述
fromCcy	Array of strings	是	小币支付币种 单次最多同时选择5个币种，如有多个币种则用逗号隔开
toCcy	String	是	兑换的主流币 只选择一个币种，且不能和小币支付币种重复
source	String	否	资金来源 1：交易账户 2：资金账户 默认为1

返回结果

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

返回参数

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

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

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

限速：1次/2s

限速规则：User ID

HTTP 请求

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

请求示例

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

import okx.Trade as Trade

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

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

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

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

请求参数

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

返回结果

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

返回参数

参数名	类型	描述
fromCcy	String	小币支付币种
fillFromSz	String	对应的小币支付数量
toCcy	String	兑换到的主流币
fillToSz	String	兑换到的主流币数量
acct	String	兑换到的主流币所在的账户 6：资金账户 18：交易账户
status	String	当前兑换进度/状态 running: 进行中 filled: 已完成 failed: 失败
uTime	String	交易时间戳，Unix时间戳为毫秒数格式，如 1597026383085

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

查询一键还债币种列表。负债币种包括全仓负债和逐仓负债。仅适用于跨币种保证金模式/组合保证金模式。

限速：1次/2s

限速规则：User ID

HTTP 请求

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

请求示例

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

import okx.Trade as Trade

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

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

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

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

请求参数

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

返回结果

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

返回参数

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

POST / 一键还债交易

交易一键偿还全仓债务。不支持逐仓负债的偿还。根据资金和交易账户的剩余可用余额为最大偿还数量。仅适用于跨币种保证金模式/组合保证金模式。

限速：1次/2s

限速规则：User ID

HTTP 请求

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

请求示例

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

import okx.Trade as Trade

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

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

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

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

请求参数

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

返回结果

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

返回参数

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

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

查询一键还债近7天的历史记录与进度状态。仅适用于跨币种保证金模式/组合保证金模式。

限速：1次/2s

限速规则：User ID

HTTP 请求

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

请求示例

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

import okx.Trade as Trade

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

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

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

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

请求参数

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

返回结果

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

返回参数

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

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

查询一键还债币种列表。仅适用于现货模式/跨币种保证金模式/组合保证金模式。

限速：1次/2s

限速规则：User ID

HTTP 请求

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

请求示例

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

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,debug=True) 
result = tradeAPI.get_oneclick_repay_list_v2()
print(result)

返回结果

{
    "code": "0",
    "data": [
        {
            "debtData": [
                {
                    "debtAmt": "100",
                    "debtCcy": "USDC"
                }
            ],
            "repayData": [
                {
                    "repayAmt": "1.000022977",
                    "repayCcy": "BTC"
                },
                {
                    "repayAmt": "4998.0002397",
                    "repayCcy": "USDT"
                },
                {
                    "repayAmt": "100",
                    "repayCcy": "OKB"
                },
                {
                    "repayAmt": "1",
                    "repayCcy": "ETH"
                },
                {
                    "repayAmt": "100",
                    "repayCcy": "USDC"
                }
            ]
        }
    ],
    "msg": ""
}

返回参数

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

POST / 一键还债交易(新)

交易一键偿还债务。仅适用于现货模式/跨币种保证金模式/组合保证金模式。

限速：1次/2s

限速规则：User ID

HTTP 请求

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

请求示例

POST /api/v5/trade/one-click-repay-v2
body
{
    "debtCcy": "USDC", 
    "repayCcyList": ["USDC","BTC"] 
}

import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # 实盘: 0, 模拟盘: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag,debug=True)
result = tradeAPI.oneclick_repay_v2("USDC",["USDC","BTC"])
print(result)

请求参数

参数名	类型	是否必须	描述
debtCcy	String	是	负债币种
repayCcyList	Array of strings	是	偿还币种列表，如 ["USDC","BTC"] 资产还币优先级和数组中的排序一致（排第一的优先级最高）。

返回结果

{
    "code": "0",
    "data": [
        {
            "debtCcy": "USDC",
            "repayCcyList": [
                "USDC",
                "BTC"
            ],
            "ts": "1742192217514"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
debtCcy	String	负债币种
repayCcyList	Array of strings	偿还币种列表，如 ["USDC","BTC"] 资产还币优先级和数组中的排序一致（排第一的优先级最高）。
ts	String	请求时间，Unix时间戳为毫秒数格式，如 1597026383085

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

查询一键还债近7天的历史记录与进度状态。仅适用于现货模式。

限速：1次/2s

限速规则：User ID

HTTP 请求

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

请求示例

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

import okx.Trade as Trade

# API 初始化
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # 实盘: 0, 模拟盘: 1

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

请求参数

参数名	类型	是否必须	描述
after	String	否	查询在指定请求时间ts之前(包含)的内容，值为时间戳，Unix时间戳为毫秒数格式，如 1597026383085
before	String	否	查询在指定请求时间ts之后(包含)的内容，值为时间戳，Unix时间戳为毫秒数格式，如 1597026383085
limit	String	否	返回的结果集数量，默认为100，最大为100

返回结果

{
    "code": "0",
    "data": [
        {
            "debtCcy": "USDC",
            "fillDebtSz": "9.079631989",
            "ordIdInfo": [
                {
                    "cTime": "1742194485439",
                    "fillPx": "1",
                    "fillSz": "9.088651",
                    "instId": "USDC-USDT",
                    "ordId": "2338478342062235648",
                    "ordType": "ioc",
                    "px": "1.0049",
                    "side": "buy",
                    "state": "filled",
                    "sz": "9.0886514537313433"
                },
                {
                    "cTime": "1742194482326",
                    "fillPx": "83271.9",
                    "fillSz": "0.00010969",
                    "instId": "BTC-USDT",
                    "ordId": "2338478237607288832",
                    "ordType": "ioc",
                    "px": "82856.7",
                    "side": "sell",
                    "state": "filled",
                    "sz": "0.000109696512171"
                }
            ],
            "repayCcyList": [
                "USDC",
                "BTC"
            ],
            "status": "filled",
            "ts": "1742194481852"
        },
        {
            "debtCcy": "USDC",
            "fillDebtSz": "100",
            "ordIdInfo": [],
            "repayCcyList": [
                "USDC",
                "BTC"
            ],
            "status": "filled",
            "ts": "1742192217511"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
debtCcy	String	负债币种
repayCcyList	Array of strings	偿还币种列表，如 ["USDC","BTC"]
fillDebtSz	String	对应的负债币种成交数量
status	String	当前还债进度/状态 running：进行中 filled：已完成 failed：失败
ordIdInfo	Array of objects	相关订单信息
> ordId	String	订单ID
> instId	String	产品ID，如 BTC-USDT
> ordType	String	订单类型 ioc：立即成交并取消剩余
> side	String	订单方向 buy sell
> px	String	委托价格
> sz	String	委托数量
> fillPx	String	最新成交价格 如果成交数量为0，该字段为""
> fillSz	String	最新成交数量
> state	String	订单状态 filled：完全成交 canceled：撤单成功
> cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085
ts	String	请求时间，Unix时间戳的毫秒数格式，如 1597026383085

POST / 撤销 MMP 订单

撤销同一交易品种下用户所有的 MMP 挂单

仅适用于组合保证金账户模式下的期权订单，且有 MMP 权限。

限速：5次/2s

限速规则：User ID

HTTP请求

POST /api/v5/trade/mass-cancel

请求示例

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

请求参数

参数名	类型	是否必须	描述
instType	String	是	交易产品类型 OPTION:期权
instFamily	String	是	交易品种
lockInterval	String	否	锁定时长(毫秒) 范围应为[0, 10 000] 默认为 0. 如果想要立即解锁，您可以设置为 "0" 下单时，如果在该锁定期间，会报错 54008，如果在 MMP 触发期间，会报错 51034

返回结果

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

返回参数

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

POST / 倒计时全部撤单

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

限速：1次/s

限速规则：User ID + tag

HTTP请求

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

请求示例

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

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

print(result)

请求参数

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

返回结果

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

返回参数

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

建议用户每一秒调用接口一次。当倒计时全部撤单被触发时，交易引擎将为用户逐一取消其挂单，该操作可能持续数秒。该功能起到保护用户的作用，不应作为交易策略使用。

为使用标签维度倒计时全部撤单，首先，用户需使用现有下单接口的tag请求参数，为订单设置标签。调用CAA接口时，若不传入tag请求参数，则默认设置账户维度CAA，CAA触发时，撤销该子账户下的所有撮合交易产品挂单；若传入tag请求参数，则默认设置订单标签维度CAA，CAA触发时，带有此tag的撮合交易产品挂单将被撤销，带有其他tag或没有tag的订单将不受影响。 同一子账户下，用户最多能同时运行20个标签维度的CAA。系统仅计数活跃的标签维度CAA，已被触发或被用户主动撤销的将不被计入。超过限制时，用户将收到错误码51071。

GET / 获取账户限速

获取账户限速相关信息

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

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

限速：1次/s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

None

返回结果

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

返回参数

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

POST / 订单预检查

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

限速：5次/2s

限速规则：User ID

HTTP请求

POST /api/v5/trade/order-precheck

请求示例

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

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 BTC-USDT
tdMode	String	是	交易模式 保证金模式：isolated：逐仓 ；cross：全仓 非保证金模式：cash：非保证金 spot_isolated：现货逐仓(仅适用于现货带单) ，现货带单时，tdMode 的值需要指定为spot_isolated
side	String	是	订单方向 buy：买， sell：卖
posSide	String	可选	持仓方向 在开平仓模式下必填，且仅可选择 long 或 short。 仅适用交割、永续。
ordType	String	是	订单类型 market：市价单 limit：限价单 post_only：只做maker单 fok：全部成交或立即取消 ioc：立即成交并取消剩余 optimal_limit_ioc：市价委托立即成交并取消剩余（仅适用交割、永续） rpi：Retail Price Improvement 订单 elp：流动性增强计划订单（已弃用，请使用 rpi。2026年10月31日前仍可使用。）
sz	String	是	委托数量
px	String	可选	委托价格，仅适用于limit、post_only、fok、ioc类型的订单
outcome	String	可选	用户交易的市场结果方向。 yes no 仅适用于 EVENTS，且为必填
reduceOnly	Boolean	否	是否只减仓，true 或 false，默认false 仅适用于币币杠杆，以及买卖模式下的交割/永续 仅适用于合约模式和跨币种保证金模式
tgtCcy	String	否	市价单委托数量sz的单位，仅适用于币币市价订单 base_ccy: 交易货币 ；quote_ccy：计价货币 买单默认quote_ccy， 卖单默认base_ccy
attachAlgoOrds	Array of objects	否	附带止盈止损或移动止盈止损订单信息
> 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	可选	数量。仅适用于”多笔止盈”的止盈订单，且对于”多笔止盈”的止盈订单必填
> callbackRatio	String	可选	回调幅度的比例，如 0.05 代表 5%。 callbackRatio 和 callbackSpread 必须传入其中一个，且只能传入一个。 仅适用于 ordType = move_order_stop
> callbackSpread	String	可选	回调幅度的价距。 callbackRatio 和 callbackSpread 必须传入其中一个，且只能传入一个。 仅适用于 ordType = move_order_stop
> activePx	String	否	激活价格。 激活价格是移动止盈止损的激活条件，当市场最新成交价达到或超过激活价格，委托被激活。激活后系统开始计算止盈止损的实际触发价格。如果不填写激活价格，即下单后就被激活。 仅适用于 ordType = move_order_stop

返回结果

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

返回参数

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

WS / 订单频道

获取订单信息，首次订阅不推送，只有当下单、订单变更时，推送数据

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

服务地址

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

请求示例：单个

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

import asyncio

from okx.websocket.WsPrivateAsync import WsPrivateAsync

def callbackFunc(message):
    print(message)

async def main():

    ws = WsPrivateAsync(
        apiKey = "YOUR_API_KEY",
        passphrase = "YOUR_PASSPHRASE",
        secretKey = "YOUR_SECRET_KEY",
        url = "wss://ws.okx.com:8443/ws/v5/private",
        useServerTime=False
    )
    await ws.start()
    args = [{
        "channel": "orders",
        "instType": "FUTURES",
        "instId": "BTC-USD-200329"
    }]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求示例

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

import asyncio

from okx.websocket.WsPrivateAsync import WsPrivateAsync

def callbackFunc(message):
    print(message)

async def main():

    ws = WsPrivateAsync(
        apiKey = "YOUR_API_KEY",
        passphrase = "YOUR_PASSPHRASE",
        secretKey = "YOUR_SECRET_KEY",
        url = "wss://ws.okx.com:8443/ws/v5/private",
        useServerTime=False
    )
    await ws.start()
    args = [{
        "channel": "orders",
        "instType": "FUTURES",
        "instFamily": "BTC-USD"
    }]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求参数

参数	类型	是否必须	描述
id	String	否	消息的唯一标识。 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 subscribe unsubscribe
args	Array of objects	是	请求订阅的频道列表
> channel	String	是	频道名 orders
> instType	String	是	产品类型 SPOT：币币 MARGIN：币币杠杆 SWAP：永续合约 FUTURES：交割合约 OPTION：期权 EVENTS：事件合约 ANY：全部
> instFamily	String	否	交易品种 适用于交割/永续/期权
> instId	String	否	产品ID

成功返回示例：单个

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

成功返回示例

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

失败返回示例

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

返回参数

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

推送示例

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

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> uid	String	用户标识
> instType	String	产品类型 SPOT：币币 MARGIN：币币杠杆 SWAP：永续合约 FUTURES：交割合约 OPTION：期权 EVENTS：事件合约
> instFamily	String	交易品种
> instId	String	产品ID
data	Array of objects	订阅的数据
> instType	String	产品类型 SPOT：币币 MARGIN：币币杠杆 SWAP：永续合约 FUTURES：交割合约 OPTION：期权 EVENTS：事件合约
> instId	String	产品ID
> ccy	String	保证金币种，适用于逐仓杠杆及合约模式下的全仓杠杆订单以及交割、永续和期权合约订单。
> ordId	String	订单ID
> clOrdId	String	由用户设置的订单ID来识别您的订单
> tag	String	订单标签
> px	String	委托价格，对于期权，以币(如BTC, ETH)为单位
> pxUsd	String	期权价格，以USD为单位 仅适用于期权，其他业务线返回空字符串""
> pxVol	String	期权订单的隐含波动率 仅适用于期权，其他业务线返回空字符串""
> pxType	String	期权的价格类型 px：代表按价格下单，单位为币 (请求参数 px 的数值单位是BTC或ETH) pxVol：代表按pxVol下单 pxUsd：代表按照pxUsd下单，单位为USD (请求参数px 的数值单位是USD)
> sz	String	委托数量
> notionalUsd	String	委托单预估美元价值
> fillNotionalUsd	String	委托单已成交的美元价值
> ordType	String	订单类型 market：市价单 limit：限价单 post_only：只做maker单 fok：全部成交或立即取消单 ioc：立即成交并取消剩余单 optimal_limit_ioc：市价委托立即成交并取消剩余（仅适用交割、永续） mmp：做市商保护(仅适用于组合保证金账户模式下的期权订单) mmp_and_post_only：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单) op_fok：期权简选（全部成交或立即取消） rpi：Retail Price Improvement 订单 elp：流动性增强计划订单（已弃用，请使用 rpi。2026年10月31日前仍可使用。）
> side	String	订单方向，buy sell
> posSide	String	持仓方向 long：开平仓模式开多 short：开平仓模式开空 net：买卖模式
> tdMode	String	交易模式 保证金模式 isolated：逐仓 cross：全仓 非保证金模式 cash：现金
> tgtCcy	String	市价单委托数量sz的单位 base_ccy: 交易货币 quote_ccy：计价货币
> fillPx	String	当前推送消息的成交价格
> tradeId	String	当前推送消息的成交ID
> fillSz	String	当前推送消息的成交数量 对于币币和杠杆，单位为交易货币，如 BTC-USDT, 单位为 BTC；对于市价单，无论tgtCcy是base_ccy，还是quote_ccy，单位均为交易货币； 对于交割、永续以及期权，单位为张。
> fillPnl	String	当前推送消息的成交收益，适用于有成交的平仓订单。其他情况均为0。
> fillTime	String	当前推送消息的成交时间
> fillFee	String	当前推送消息的成交手续费金额或者返佣金额： 手续费扣除 为 ‘负数’，如 -0.01 ； 手续费返佣 为 ‘正数’，如 0.01
> fillFeeCcy	String	当前推送消息的成交手续费币种或者返佣币种。 如果fillFee小于0，为手续费币种；如果fillFee大于等于0，为返佣币种
> fillPxVol	String	成交时的隐含波动率仅适用于期权，其他业务线返回空字符串""
> fillPxUsd	String	成交时的期权价格，以USD为单位仅适用于期权，其他业务线返回空字符串""
> fillMarkVol	String	成交时的标记波动率，仅适用于期权，其他业务线返回空字符串""
> fillFwdPx	String	成交时的远期价格，仅适用于期权，其他业务线返回空字符串""
> fillMarkPx	String	成交时的标记价格，仅适用于 交割/永续/期权
> fillIdxPx	String	交易执行时的指数价格 对于交叉现货币对，返回 baseCcy-USDT 的指数价格。 例如LTC-ETH，该字段返回LTC-USDT的指数价格。
> execType	String	当前推送消息成交的流动性方向 T：taker M：maker
> accFillSz	String	累计成交数量 对于币币和杠杆，单位为交易货币，如 BTC-USDT, 单位为 BTC；对于市价单，无论tgtCcy是base_ccy，还是quote_ccy，单位均为交易货币； 对于交割、永续以及期权，单位为张。
> avgPx	String	成交均价，如果成交数量为0，该字段也为0
> state	String	订单状态 canceled：撤单成功 live：等待成交 partially_filled：部分成交 filled：完全成交 mmp_canceled：做市商保护机制导致的自动撤单
> lever	String	杠杆倍数，0.01到125之间的数值，仅适用于 币币杠杆/交割/永续
> attachAlgoClOrdId	String	下单附带止盈止损或移动止盈止损时，客户自定义的策略订单ID
> tpTriggerPx	String	止盈触发价
> tpTriggerPxType	String	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格
> tpOrdPx	String	止盈委托价，止盈委托价格为-1时，执行市价止盈
> slTriggerPx	String	止损触发价
> slTriggerPxType	String	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格
> slOrdPx	String	止损委托价，止损委托价格为-1时，执行市价止损
> attachAlgoOrds	Array of objects	附带止盈止损或移动止盈止损订单信息
>> attachAlgoId	String	附带止盈止损或移动止盈止损的订单ID，改单时，可用来标识该笔附带止盈止损订单。下附带策略委托单时，该值不会传给 algoId
>> attachAlgoClOrdId	String	下单附带止盈止损或移动止盈止损时，客户自定义的策略订单ID
>> tpOrdKind	String	止盈订单类型 condition: 条件单 limit: 限价单
>> tpTriggerPx	String	止盈触发价
>> tpTriggerRatio	String	止盈触发比例，0.3 代表 30% 仅适用于交割/永续合约
>> tpTriggerPxType	String	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格
>> tpOrdPx	String	止盈委托价
>> slTriggerPx	String	止损触发价
>> slTriggerRatio	String	止损触发比例，0.3 代表 30% 仅适用于交割/永续合约
>> slTriggerPxType	String	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格
>> slOrdPx	String	止损委托价
>> sz	String	张数。仅适用于“多笔止盈”的止盈订单
>> amendPxOnTriggerType	String	是否启用开仓价止损，仅适用于分批止盈的止损订单 0：不开启，默认值 1：开启
>> callbackRatio	String	回调幅度的比例，如 0.05 代表 5%
>> callbackSpread	String	回调幅度的价距
>> activePx	String	激活价格
> linkedAlgoOrd	Object	止损订单信息，仅适用于包含限价止盈单的双向止盈止损订单，触发后生成的普通订单
>> algoId	Object	策略订单唯一标识
> stpId	String	自成交保护ID 如果自成交保护不适用则返回""（已弃用）
> stpMode	String	自成交保护模式
> feeCcy	String	手续费币种 对于币币和杠杆的挂单卖单，表示计价币种；其他情况下，表示收取手续费的币种
> fee	String	手续费金额 对于币币和杠杆（除挂单卖单外）：平台收取的累计手续费，始终为负数。 对于币币和杠杆的挂单卖单、交割、永续和期权：累计手续费和返佣（币币和杠杆挂单卖单始终以计价币种计算）
> rebateCcy	String	返佣币种 对于币币和杠杆的挂单卖单，表示交易币种；其他情况下，表示支付返佣的币种
> rebate	String	返佣金额，仅适用于币币和杠杆 对于挂单卖单：以交易币种为单位的累计手续费和返佣金额。 其他情况下，表示挂单返佣金额，始终为正数，如无返佣时返回""。
> pnl	String	收益(不包括手续费) 适用于有成交的平仓订单，其他情况均为0 对于合约全仓爆仓，将包含相应强平惩罚金
> source	String	订单来源 6：计划委托策略触发后的生成的普通单 7：止盈止损策略触发后的生成的普通单 13：策略委托单触发后的生成的普通单 25：移动止盈止损策略触发后的生成的普通单 34: 追逐限价委托生成的普通单
> cancelSource	String	订单取消的来源 有效值及对应的含义是： 0: 已撤单：系统撤单 1: 用户主动撤单 2: 已撤单：预减仓撤单，用户保证金不足导致挂单被撤回 3: 已撤单：风控撤单，用户保证金不足有爆仓风险，导致挂单被撤回 4: 已撤单：币种借币量达到平台硬顶，系统已撤回该订单 6: 已撤单：触发 ADL 撤单，用户维持保证金率较低且有爆仓风险，导致挂单被撤回 7: 已撤单：交割合约到期 9: 已撤单：扣除资金费用后可用余额不足，系统已撤回该订单 10: 已撤单：期权合约到期 13: 已撤单：FOK 委托订单未完全成交，导致挂单被完全撤回 14: 已撤单：IOC 委托订单未完全成交，仅部分成交，导致部分挂单被撤回 15: 已撤单：该订单委托价不在限价范围内 17: 已撤单：平仓单被撤单，由于仓位已被市价全平 20: 系统倒计时撤单 21: 已撤单：相关仓位被完全平仓，系统已撤销该止盈止损订单 22 已撤单：存在更优价格的同方向订单，系统自动撤销当前操作的只减仓订单 23 已撤单：存在更优价格的同方向订单，系统自动撤销已存在的只减仓订单 27: 成交滑点超过5%，触发成交差价保护导致系统撤单 31: 当前只挂单订单 (Post only) 将会吃掉挂单深度 32: 自成交保护 33: 当前 taker 订单匹配的订单数量超过最大限制 36: 关联止损被触发，撤销限价止盈 37: 关联止损被撤销，撤销限价止盈 38: 您已撤销做市商保护 (MMP) 类型订单 39: 因做市商保护 (MMP) 被触发，该类型订单已被撤销 42: 初始下单价格与最新的买一或卖一价已达到最大追逐距离，您的订单已被自动取消 43: 由于买单价格高于指数价格或卖单价格低于指数价格，导致系统撤单 44：由于该币种的可用余额不足，无法在触发自动换币后进行兑换，您的订单已撤销，撤销订单后恢复的余额将用于自动换币。当该币种的总抵押借贷量达到平台抵押借贷风控上限时，则会触发自动换币。 45：RPI订单价格校验失败 46：由于降低Delta而导致的撤单
> amendSource	String	订单修改的来源 1: 用户主动改单，改单成功 2: 用户主动改单，并且当前这笔订单被只减仓修改，改单成功 4: 订单数量被系统按只减仓修改，改单成功，包括：用户主动下单后当前这笔订单被只减仓修改，以及用户当前已存在的挂单（非当前操作的订单）被只减仓修改 5：期权 px, pxVol 或 pxUsd 的跟随变动导致的改单，比如 iv=60，USD，px 锚定iv=60 时，USD, px 产生变动时的改单 6：系统因 RPI 做市商间距规则调整了订单价格（由 rpiPxRound 触发）
> category	String	订单种类分类 normal：普通委托订单种类 twap：TWAP订单种类 adl：ADL订单种类 full_liquidation：爆仓订单种类 partial_liquidation：减仓订单种类 delivery：交割 ddh：对冲减仓类型订单 auto_conversion：抵押借币自动还币订单
> isTpLimit	String	是否为限价止盈，true 或 false.
> uTime	String	订单更新时间，Unix时间戳的毫秒数格式，如 1597026383085
> cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085
> reqId	String	修改订单时使用的request ID，如果没有修改，该字段为""
> amendResult	String	修改订单的结果 -1：失败 0：成功 1：自动撤单（修改请求返回成功但最终改单失败导致自动撤销） 2: 自动改单成功，仅适用于期权pxUsd和pxVol订单的自动改单 通过API修改订单时，如果cxlOnFail设置为true且修改返回结果为失败时，则返回 "" 通过API修改订单时，如果修改返回结果为成功但修改最终失败后，当cxlOnFail设置为false时返回 -1;当cxlOnFail设置为true时则返回1 通过Web/APP修改订单时，如果修改失败后，则返回-1
> reduceOnly	String	是否只减仓，true 或 false
> quickMgnType	String	一键借币类型，仅适用于杠杆逐仓的一键借币模式 manual：手动，auto_borrow：自动借币，auto_repay：自动还币（已弃用）
> algoClOrdId	String	客户自定义策略订单ID。策略订单触发，且策略单有algoClOrdId时有值，否则为"",
> algoId	String	策略委托单ID，策略订单触发时有值，否则为""
> lastPx	String	最新成交价
> code	String	错误码，默认为0
> msg	String	错误消息，默认为""
> tradeQuoteCcy	String	用于交易的计价币种。
> outcome	String	用户交易的市场结果方向。 yes no 仅适用于 EVENTS

对于市价委托，订单频道推送消息会出现状态为“完全成交”，但最新成交数量 (fillSz) 为 0 的情况。

极端情况下，会出现同一条消息重复推送的情况（uTime 可能会不一样），建议做如下处理：

• 当tradeId有值时，代表成交，对于同一tradeId，请以第一条推送消息为准，忽略后续的推送消息；
• 当tradeId没有值且 state 为filled时，代表币币/杠杆市价单关闭，对于同一ordId的完全成交（state:filled）推送消息，请以第一条成交推送消息为准，忽略后续的推送消息；
• 当state为canceled或者mmp_canceled时，代表订单撤销，对于同一ordId的撤单推送消息，请以第一条推送消息为准，忽略后续的推送消息；
• 当reqId有值时，代表用户改单，改单时建议使用唯一的reqId，对于同一reqId的改单推送消息，请以第一条推送消息为准，忽略后续的推送消息。

REST 订单信息接口和订单频道在 fillPx、tradeId、fillSz、fillPnl、fillTime、fillFee、fillFeeCcy 和 execType 的定义上存在差异。

与交割合约不同，期权持仓到期之后，期权持仓在到期后会自动行权或作废，持仓本身随即消失，不会产生任何平仓订单，因此，该频道不会推送期权到期的平仓订单信息。

WS / 成交频道

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

该频道仅适用于交易等级VIP4及以上的用户，其他用户接入将收到错误码64003。其他用户请使用WS / 订单频道。

对于 EVENTS，无论实际订单是否为 YES 或 NO 方向，仅推送 YES 侧成交数据。

服务地址

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

请求示例：单个

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

import asyncio

from okx.websocket.WsPrivateAsync import WsPrivateAsync

def callbackFunc(message):
    print(message)

async def main():

    ws = WsPrivateAsync(
        apiKey = "YOUR_API_KEY",
        passphrase = "YOUR_PASSPHRASE",
        secretKey = "YOUR_SECRET_KEY",
        url = "wss://ws.okx.com:8443/ws/v5/private",
        useServerTime=False
    )
    await ws.start()
    args = [
        {
            "channel": "fills",
            "instId": "BTC-USDT-SWAP"
        }
    ]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求示例

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

import asyncio

from okx.websocket.WsPrivateAsync import WsPrivateAsync

def callbackFunc(message):
    print(message)

async def main():

    ws = WsPrivateAsync(
        apiKey = "YOUR_API_KEY",
        passphrase = "YOUR_PASSPHRASE",
        secretKey = "YOUR_SECRET_KEY",
        url = "wss://ws.okx.com:8443/ws/v5/private",
        useServerTime=False
    )
    await ws.start()
    args = [
        {
            "channel": "fills"
        }
    ]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求参数

参数名	类型	是否必须	描述
id	String	否	消息的唯一标识。 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 subscribe unsubscribe
args	Array of objects	是	订阅的频道
> channel	String	是	频道名 fills
> instId	String	否	产品ID

成功返回示例：单个

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

成功返回示例

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

返回参数

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

推送示例：单个

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

推送数据参数

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

• 该频道仅适用于交易等级VIP4及以上的用户，其他用户接入将收到错误码64003
• 该频道只推送部分订单频道的信息，与大宗交易、价差速递相关的成交，强平、自动减仓等非订单簿事件不会通过该频道推送。用户应同时关注订单频道，对订单做最终确认
• 该频道接收到成交推送时，账户余额、保证金、持仓等信息可能仍未发生变化
• taker订单将根据不同成交价格进行聚合，有聚合时，count字段表示聚合的订单匹配数量，tradeId代表聚合的多笔交易中最新一笔交易的ID；maker订单不会聚合
• 用户可以在下单时指定clOrdId，成交时会返回该字段。请注意，成交频道仅在用户输入的clOrdId符合带符号int64正整数格式（1-9223372036854775807, 2^63-1）时返回该字段；若用户未输入该字段，或clOrdId不符合格式要求，该字段将返回"0"。订单接口及频道将照常返回用户传入的clOrdId。所有请求及返回参数均为字符串类型。
• 未来，该频道将施加连接数量限制，子账户维度，订阅成交频道的最大连接数为20个。我们建议用户始终低于限制使用该频道，以免限制上线后对策略造成影响

WS / 下单

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

服务地址

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

限速：60次/2s

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

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

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

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

同下单 REST API 共享限速

请求示例

{
    "id": "1512",
    "op": "order",
    "args": [{
        "side": "buy",
        "instIdCode": 123456,
        "tdMode": "isolated",
        "ordType": "market",
        "sz": "100"
    }]
}

请求参数

参数名	类型	是否必须	描述
id	String	是	消息的唯一标识 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 order
args	Array of objects	是	请求参数
> instIdCode	Integer	是	产品唯一标识代码。
> tdMode	String	是	交易模式 保证金模式 isolated：逐仓 cross：全仓 非保证金模式 cash：现金 spot_isolated：现货逐仓(仅适用于现货带单) ，现货带单时，tdMode 的值需要指定为spot_isolated 事件合约对应交易产品仅支持isolated逐仓下单
> ccy	String	条件必填	保证金币种 通常可选；逐仓杠杆订单及合约模式下的全仓杠杆订单必填
> clOrdId	String	否	由用户设置的订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
> tag	String	否	订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-16位之间。
> side	String	是	订单方向，buy sell
> posSide	String	否	持仓方向 在买卖模式下，默认 net 在开平仓模式下必填，且仅可选择 long 或 short，仅适用于交割/永续
> ordType	String	是	订单类型 market：市价单，仅适用于币币/杠杆/交割/永续 limit：限价单 post_only：只做maker单 fok：全部成交或立即取消 ioc：立即成交并取消剩余 optimal_limit_ioc：市价委托立即成交并取消剩余（仅适用交割、永续） mmp：做市商保护(仅适用于组合保证金账户模式下的期权订单) mmp_and_post_only：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单) rpi：Retail Price Improvement 订单 elp：流动性增强计划订单（已弃用，请使用 rpi。2026年10月31日前仍可使用。）
> sz	String	是	委托数量
> px	String	可选	委托价格，仅适用于limit、post_only、fok、ioc、mmp、mmp_and_post_only类型的订单 期权下单时，px/pxUsd/pxVol 只能填一个
> speedBump	String	可选	减速带 1：事件合约速度限制（延迟可能因市场情况调整，不提前通知）。对 EVENTS 产品的非只挂单操作为必填。
> outcome	String	可选	用户交易的市场结果方向。 yes no 仅适用于 EVENTS，且为必填
> 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时，余额不足时，系统不会改单，下单会失败，仅适用于币币市价单
> pxAmendType	String	否	订单价格修正类型 0：当px超出价格限制时，不允许系统修改订单价格 1：当px超出价格限制时，允许系统将价格修改为限制范围内的最优值 默认值为0
> tradeQuoteCcy	String	否	用于交易的计价币种。仅适用于币币。 默认值为 instId 的计价币种，比如：对于 BTC-USD，默认取 USD。
> slippagePct	String	否	币币、币币杠杆市价单（tgtCcy 为到手币种：买单为 base_ccy，卖单为 quote_ccy）的最大可接受滑点。 取值范围：0 至 0.05（即 0% 至 5%，含边界），以百分比形式表示时最多保留 2 位小数，例如 0.01（1%）和 0.0123（1.23%）合法；0.01234（1.234%）将被拒绝。 不填或为空时，默认为 0.00%。 不支持改单修改滑点，如需调整请撤单重新提交。 仅适用于币币和币币杠杆的市价单。
> stpMode	String	否	自成交保护模式 cancel_maker,cancel_taker, cancel_both Cancel both不支持FOK 默认使用账户层面的acctStpMode进行下单，该字段的默认值为cancel_maker，用户可通过母账户登录网页修改该配置；用户亦可以通过下单接口的stpMode参数指定订单的STP模式。
> rpiTakerAccess	Boolean	否	默认值为 false。 设为 true 时，订单可使用 RPI 流动性，适用于 limit、market、fok、ioc 订单。 当 rpiTakerAccess 为 true 时，减速带机制在下单和改单时均适用于所有 ordType，包括 post_only。 改单时不会从原始订单继承，必须每次显式指定（省略则该次改单视为 false）。 isElpTakerAccess 在 2026年10月31日前作为别名继续被接受。
> rpiPxRound	Boolean	否	默认值为 false。仅对 RPI 做市商订单（ordType: rpi）生效。设为 true 时，违反 RPI 做市商间距规则的价格将自动向外取整至最近的合规价位，而非被拒绝。对非 RPI 订单及 OPTION/EVENTS 无效。
expTime	String	否	请求有效截止时间。Unix时间戳的毫秒数格式，如 1597026383085

成功返回示例

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

失败返回示例

{
    "id": "1512",
    "op": "order",
    "data": [{
        "clOrdId": "",
        "ordId": "",
        "tag": "",
        "ts":"1695190491421",
        "sCode": "51008",
        "sMsg": "Order failed. Insufficient USDT balance in account",
        "subCode": "1000"
    }],
    "code": "1",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

格式错误返回示例

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

返回参数

参数名	类型	描述
id	String	消息的唯一标识
op	String	操作 order
code	String	代码
msg	String	消息
data	Array of objects	请求成功后返回的数据
> ordId	String	订单ID
> clOrdId	String	由用户设置的订单ID
> tag	String	订单标签
> ts	String	订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085。与订单频道中的 cTime 相同。
> sCode	String	订单状态码，0 代表成功
> sMsg	String	订单状态消息
> subCode	String	sCode 的子码。 当 sCode 为 0（请求成功）时，返回 ""。 当 sCode 不为 0（请求失败）且存在子码时，返回对应的子码；若无子码，则返回 ""。
inTime	String	WebSocket 网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123
outTime	String	WebSocket 网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123

tdMode 交易模式，下单时需要指定 现货模式：

• 币币和期权买方：cash 合约模式：
• 逐仓杠杆：isolated
• 全仓杠杆：cross
• 币币：cash
• 全仓交割/永续/期权：cross
• 逐仓交割/永续/期权：isolated 跨币种保证金模式：
• 逐仓杠杆：isolated
• 全仓币币：cross
• 全仓交割/永续/期权：cross
• 逐仓交割/永续/期权：isolated 组合保证金模式：
• 逐仓杠杆：isolated
• 全仓币币：cross
• 全仓交割/永续/期权：cross
• 逐仓交割/永续/期权：isolated

clOrdId clOrdId 是用户在 User ID 维度自定义的订单唯一标识符。如果在请求参数中传入了，那它一定会在返回参数内，并且可以用于查询订单，撤销订单，修改订单等接口。 clOrdId不能与当前所有的挂单的clOrdId重复

posSide 持仓方向，买卖模式下此参数非必填，如果填写仅可以选择net；在开平仓模式下必填，且仅可选择 long 或 short。 开平仓模式下，side和posSide需要进行组合 开多：买入开多（side 填写 buy； posSide 填写 long ） 开空：卖出开空（side 填写 sell； posSide 填写 short ） 平多：卖出平多（side 填写 sell；posSide 填写 long ） 平空：买入平空（side 填写 buy； posSide 填写 short ） 组合保证金模式：交割和永续仅支持买卖模式

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

sz 交易数量，表示要购买或者出售的数量。 当币币/币币杠杆以限价买入和卖出时，指交易货币数量。 当币币杠杆以市价买入时，指计价货币的数量。 当币币杠杆以市价卖出时，指交易货币的数量。 对于币币市价单，单位由 tgtCcy 决定 当交割、永续、期权买入和卖出时，指合约张数。

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

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

px 期权下单时，委托价格需为 tickSz 的整数倍。 当不为整数倍时，取值规则以tickSz取 0.0005 为例： 当委托价格对0.0005的余数大于0.00025或者委托价格小于0.0005时，向上取； 当委托价格对0.0005的余数小于等于0.00025，且委托价格大于0.0005时，向下取。

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

WS / 批量下单

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

服务地址

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

限速：300个/2s

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

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

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

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

与其他限速按接口调用次数不同，该接口限速按订单的总个数限速。如果单次批量请求中只有一个元素，则算在单个下单限速中。

同批量下单 REST API 共享限速

请求示例

{
    "id": "1513",
    "op": "batch-orders",
    "args": [{
        "side": "buy",
        "instIdCode": 123456,
        "tdMode": "isolated",
        "ordType": "market",
        "sz": "100"
    }, {
        "side": "buy",
        "instIdCode": 654321,
        "tdMode": "isolated",
        "ordType": "limit",
        "sz": "1",
        "px": "20000"
    }]
}

请求参数

参数名	类型	是否必须	描述
id	String	是	消息的唯一标识 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	支持的业务操作，如 batch-orders
args	Array of objects	是	请求参数
> instIdCode	Integer	是	产品唯一标识代码。
> tdMode	String	否	交易模式 保证金模式 cross：全仓 isolated：逐仓 非保证金模式 cash：现金 spot_isolated：现货逐仓(仅适用于现货带单) ，现货带单时，tdMode 的值需要指定为spot_isolated 注意：isolated 在跨币种保证金模式和组合保证金模式下不可用。 事件合约对应交易产品仅支持isolated逐仓下单
> ccy	String	条件必填	保证金币种 通常可选；逐仓杠杆订单及合约模式下的全仓杠杆订单必填
> clOrdId	String	否	用户提供的订单ID 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
> tag	String	否	订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-16位之间。
> side	String	是	订单方向， buy sell
> posSide	String	否	持仓方向 在买卖模式下，默认 net 在开平仓模式下必填，且仅可选择 long 或 short，仅适用于交割/永续
> ordType	String	是	订单类型 market：市价单，仅适用于币币/杠杆/交割/永续 limit：限价单 post_only：只做maker单 fok：全部成交或立即取消单 ioc：立即成交并取消剩余单 optimal_limit_ioc：市价委托立即成交并取消剩余（仅适用交割、永续） mmp：做市商保护(仅适用于组合保证金账户模式下的期权订单) mmp_and_post_only：做市商保护且只做maker单(仅适用于组合保证金账户模式下的期权订单) rpi：Retail Price Improvement 订单 elp：流动性增强计划订单（已弃用，请使用 rpi。2026年10月31日前仍可使用。）
> sz	String	是	委托数量
> px	String	可选	委托价格，仅适用于limit、post_only、fok、ioc、mmp、mmp_and_post_only类型的订单 期权下单时，px/pxUsd/pxVol 只能填一个
> speedBump	String	可选	减速带 1：事件合约速度限制（延迟可能因市场情况调整，不提前通知）。对 EVENTS 产品的非只挂单操作为必填。
> outcome	String	可选	用户交易的市场结果方向。 yes no 仅适用于 EVENTS，且为必填
> 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时，余额不足时，系统不会改单，下单会失败，仅适用于币币市价单
> pxAmendType	String	否	订单价格修正类型 0：当px超出价格限制时，不允许系统修改订单价格 1：当px超出价格限制时，允许系统将价格修改为限制范围内的最优值 默认值为0
> tradeQuoteCcy	String	否	用于交易的计价币种。仅适用于币币。 默认值为 instId 的计价币种，比如：对于 BTC-USD，默认取 USD。
> slippagePct	String	否	币币、币币杠杆市价单（tgtCcy 为到手币种：买单为 base_ccy，卖单为 quote_ccy）的最大可接受滑点。 取值范围：0 至 0.05（即 0% 至 5%，含边界），以百分比形式表示时最多保留 2 位小数，例如 0.01（1%）和 0.0123（1.23%）合法；0.01234（1.234%）将被拒绝。 不填或为空时，默认为 0.00%。 不支持改单修改滑点，如需调整请撤单重新提交。 仅适用于币币和币币杠杆的市价单。
> stpMode	String	否	自成交保护模式 cancel_maker,cancel_taker, cancel_both Cancel both不支持FOK 默认使用账户层面的acctStpMode进行下单，该字段的默认值为cancel_maker，用户可通过母账户登录网页修改该配置；用户亦可以通过下单接口的stpMode参数指定订单的STP模式。
> rpiTakerAccess	Boolean	否	默认值为 false。 设为 true 时，订单可使用 RPI 流动性，适用于 limit、market、fok、ioc 订单。 当 rpiTakerAccess 为 true 时，减速带机制在下单和改单时均适用于所有 ordType，包括 post_only。 改单时不会从原始订单继承，必须每次显式指定（省略则该次改单视为 false）。 isElpTakerAccess 在 2026年10月31日前作为别名继续被接受。
> rpiPxRound	Boolean	否	默认值为 false。仅对 RPI 做市商订单（ordType: rpi）生效。设为 true 时，违反 RPI 做市商间距规则的价格将自动向外取整至最近的合规价位，而非被拒绝。对非 RPI 订单及 OPTION/EVENTS 无效。
expTime	String	否	请求有效截止时间。Unix时间戳的毫秒数格式，如 1597026383085

全部成功返回示例

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

部分成功返回示例

{
    "id": "1513",
    "op": "batch-orders",
    "data": [{
        "clOrdId": "",
        "ordId": "12345689",
        "tag": "",
        "ts":"1695190491421",
        "sCode": "0",
        "sMsg": "",
        "subCode": ""
    }, {
        "clOrdId": "",
        "ordId": "",
        "tag": "",
        "ts":"1695190491421",
        "sCode": "51008",
        "sMsg": "Order failed. Insufficient USDT balance in account",
        "subCode": "1000"
    }],
    "code": "2",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

全部失败返回示例

{
    "id": "1513",
    "op": "batch-orders",
    "data": [{
        "clOrdId": "oktswap6",
        "ordId": "",
        "tag": "",
        "ts":"1695190491421",
        "sCode": "51008",
        "sMsg": "Order failed. Insufficient USDT balance in account",
        "subCode": "1000"
    }, {
        "clOrdId": "oktswap7",
        "ordId": "",
        "tag": "",
        "ts":"1695190491421",
        "sCode": "51008",
        "sMsg": "Order failed. Insufficient USDT balance in account",
        "subCode": "1000"
    }],
    "code": "1",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

格式错误返回示例

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

返回参数

参数	类型	描述
id	String	消息的唯一标识
op	String	业务操作
code	String	代码
msg	String	消息
data	Array of objects	请求成功后返回的数据
> ordId	String	订单ID
> clOrdId	String	由用户设置的订单ID
> tag	String	订单标签
> ts	String	订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085。与订单频道中的 cTime 相同。
> sCode	String	订单状态码，0 代表成功
> sMsg	String	事件执行失败或成功时的msg
> subCode	String	sCode 的子码。 当 sCode 为 0（请求成功）时，返回 ""。 当 sCode 不为 0（请求失败）且存在子码时，返回对应的子码；若无子码，则返回 ""。
inTime	String	WebSocket 网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123
outTime	String	WebSocket 网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123

在组合保证金账户模式下，或者全部成功，或者全部失败。

clOrdId clOrdId是用户自定义的唯一ID用来识别订单。如果在请求参数中传入了，那它一定会在返回参数内，并且可以用于查询订单，撤销订单，修改订单等接口。 clOrdId不能与当前所有挂单和当前请求中的clOrdId重复。

WS / 撤单

撤销当前未完成订单

服务地址

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

限速：60次/2s

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

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

同撤单 REST API 共享限速

请求示例

{
    "id": "1514",
    "op": "cancel-order",
    "args": [{
        "instIdCode": 123456,
        "ordId": "2510789768709120"
    }]
}

请求参数

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

成功返回示例

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

失败返回示例

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

格式错误返回示例

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

返回参数

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

撤单返回sCode等于0不能严格认为该订单已经被撤销，只表示您的撤单请求被系统服务器所接受，撤单结果以订单频道推送的状态或者查询订单状态为准

WS / 批量撤单

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

服务地址

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

限速：300个/2s

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

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

与其他限速按接口调用次数不同，该接口限速按订单的总个数限速。如果单次批量请求中只有一个元素，则算在单个撤单限速中。

同批量撤单 REST API 共享限速

请求示例

{
    "id": "1515",
    "op": "batch-cancel-orders",
    "args": [{
        "instIdCode": 123456,
        "ordId": "2517748157541376"
    }, {
        "instIdCode": 654321,
        "ordId": "2517748155771904"
    }]
}

请求参数

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

全部成功返回示例

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

部分成功的返回示例

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

全部失败的返回示例

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

格式错误示例

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

返回参数

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

WS / 改单

修改当前未成交的订单

服务地址

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

限速：60次/2s

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

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

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

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

同改单 REST API 共享限速

请求示例

{
    "id": "1512",
    "op": "amend-order",
    "args": [{
        "instIdCode": 123456,
        "ordId": "2510789768709120",
        "newSz": "2"
    }]
}

请求参数

参数名	类型	是否必须	描述
id	String	是	消息的唯一标识 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	支持的业务操作，如 amend-order
args	Array of objects	是	请求参数
> instIdCode	Integer	是	产品唯一标识代码
> cxlOnFail	Boolean	否	当订单修改失败时，该订单是否需要自动撤销。默认为false false：不自动撤单 true：自动撤单
> ordId	String	可选	订单ID ordId和clOrdId必须传一个，若传两个，以 ordId 为主
> clOrdId	String	可选	用户提供的订单ID
> reqId	String	否	用户提供的reqId 如果提供，那在返回参数中返回reqId，方便找到相应的修改请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
> newSz	String	可选	请求修改的新数量，必须大于0。newSz和newPx不可同时为空。对于部分成交订单，该数量应包含已成交数量。
> newPx	String	可选	修改后的新价格 修改的新价格期权改单时，newPx/newPxUsd/newPxVol 只能填一个，且必须与下单参数保持一致，如下单用px，改单时需使用newPx
> speedBump	String	可选	减速带 1：事件合约速度限制（延迟可能因市场情况调整，不提前通知）。对 EVENTS 产品的非只挂单操作为必填。
> newPxUsd	String	可选	以USD价格进行期权改单 仅适用于期权，期权改单时，newPx/newPxUsd/newPxVol 只能填一个
> newPxVol	String	可选	以隐含波动率进行期权改单，例如 1 代表 100% 仅适用于期权，期权改单时，newPx/newPxUsd/newPxVol 只能填一个
> pxAmendType	String	否	订单价格修正类型 0：当newPx超出价格限制时，不允许系统修改订单价格 1：当newPx超出价格限制时，允许系统将价格修改为限制范围内的最优值 默认值为0
> rpiTakerAccess	Boolean	否	默认值为 false。 设为 true 时，改单后的订单可使用 RPI 流动性，适用于 limit、market、fok、ioc 订单。 改单时不会从原始订单继承，必须每次显式指定（省略则该次改单视为 false）。
> rpiPxRound	Boolean	否	默认值为 false。仅对 RPI 做市商订单（ordType: rpi）生效。设为 true 时，违反间距规则的价格将自动向外取整至最近的合规价位，而非被拒绝。对非 RPI 订单及 OPTION/EVENTS 无效。
expTime	String	否	请求有效截止时间。Unix时间戳的毫秒数格式，如 1597026383085

成功返回示例

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

失败返回示例

{
    "id": "1512",
    "op": "amend-order",
    "data": [{
        "clOrdId": "",
        "ordId": "2510789768709120",
        "ts": "1695190491421",
        "reqId": "b12344",
        "sCode": "51008",
        "sMsg": "Order failed. Insufficient USDT balance in account",
        "subCode": "1000"
    }],
    "code": "1",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

格式错误返回示例

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

}

返回参数

参数	类型	描述
id	String	消息的唯一标识
op	String	业务操作
code	String	代码
msg	String	消息
data	Array of objects	请求成功后返回的数据
> ordId	String	订单ID
> clOrdId	String	用户提供的订单ID
> ts	String	订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085。与订单频道中的 cTime 相同。
> reqId	String	用户提供的reqId 如果用户在请求中提供reqId，则返回相应reqId
> sCode	String	订单状态码，0 代表成功
> sMsg	String	订单状态消息
> subCode	String	sCode 的子码。 当 sCode 为 0（请求成功）时，返回 ""。 当 sCode 不为 0（请求失败）且存在子码时，返回对应的子码；若无子码，则返回 ""。
inTime	String	WebSocket 网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123
outTime	String	WebSocket 网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123

newSz : 当修改已经部分成交的订单时，新的委托数量必须大于等于已成交数量

修改订单返回sCode等于0不能严格认为该订单已经被修改，只表示您的修改订单请求被系统服务器所接受，改单结果以订单频道推送的状态或者查询订单状态为准

WS / 批量改单

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

服务地址

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

限速：300个/2s

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

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

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

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

与其他限速按接口调用次数不同，该接口限速按订单的总个数限速。如果单次批量请求中只有一个元素，则算在单个修改订单限速中。

同批量改单 REST API 共享限速

请求示例

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

请求参数

参数名	类型	是否必须	描述
id	String	是	消息的唯一标识 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	支持的业务操作，如 batch-amend-orders
args	Array of objects	是	请求参数
> instIdCode	Integer	是	产品唯一标识代码
> cxlOnFail	Boolean	否	当订单修改失败时，该订单是否需要自动撤销。默认为false false：不自动撤单 true：自动撤单
> ordId	String	可选	订单ID ordId 和 clOrdId 必须传一个，若传两个，以order id 为主
> clOrdId	String	可选	用户提供的订单ID
> reqId	String	否	用户提供的请求ID 如果提供，那在返回参数中返回reqId，方便找到相应的修改请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。
> newSz	String	可选	修改后的新数量，必须大于0。newSz和newPx不可同时为空。对于部分成交订单，该数量应包含已成交数量。
> newPx	String	可选	修改后的新价格 修改的新价格期权改单时，newPx/newPxUsd/newPxVol 只能填一个，且必须与下单参数保持一致，如下单用px，改单时需使用newPx
> speedBump	String	可选	减速带 1：事件合约速度限制（延迟可能因市场情况调整，不提前通知）。对 EVENTS 产品的非只挂单操作为必填。
> newPxUsd	String	可选	以USD价格进行期权改单 仅适用于期权，期权改单时，newPx/newPxUsd/newPxVol 只能填一个
> newPxVol	String	可选	以隐含波动率进行期权改单，例如 1 代表 100% 仅适用于期权，期权改单时，newPx/newPxUsd/newPxVol 只能填一个
> pxAmendType	String	否	订单价格修正类型 0：当newPx超出价格限制时，不允许系统修改订单价格 1：当newPx超出价格限制时，允许系统将价格修改为限制范围内的最优值 默认值为0
> rpiTakerAccess	Boolean	否	默认值为 false。 设为 true 时，改单后的订单可使用 RPI 流动性，适用于 limit、market、fok、ioc 订单。 改单时不会从原始订单继承，必须每次显式指定（省略则该次改单视为 false）。
> rpiPxRound	Boolean	否	默认值为 false。仅对 RPI 做市商订单（ordType: rpi）生效。设为 true 时，违反间距规则的价格将自动向外取整至最近的合规价位，而非被拒绝。对非 RPI 订单及 OPTION/EVENTS 无效。
expTime	String	否	请求有效截止时间。Unix时间戳的毫秒数格式，如 1597026383085

全部成功返回示例

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

全部失败返回示例

{
    "id": "1513",
    "op": "batch-amend-orders",
    "data": [{
        "clOrdId": "",
        "ordId": "12345689",
        "ts": "1695190491421",
        "reqId": "b12344",
        "sCode": "51008",
        "sMsg": "Order failed. Insufficient USDT balance in account",
        "subCode": "1000"
    }, {
        "clOrdId": "oktswap7",
        "ordId": "",
        "ts": "1695190491421",
        "reqId": "b12344",
        "sCode": "51008",
        "sMsg": "Order failed. Insufficient USDT balance in account",
        "subCode": "1000"
    }],
    "code": "1",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

部分成功返回示例

{
    "id": "1513",
    "op": "batch-amend-orders",
    "data": [{
        "clOrdId": "",
        "ordId": "12345689",
        "ts": "1695190491421",
        "reqId": "b12344",
        "sCode": "0",
        "sMsg": "",
        "subCode": ""

    }, {
        "clOrdId": "oktswap7",
        "ordId": "",
        "ts": "1695190491421",
        "reqId": "b12344",
        "sCode": "51008",
        "sMsg": "Order failed. Insufficient USDT balance in account",
        "subCode": "1000"
    }],
    "code": "2",
    "msg": "",
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

格式错误返回示例

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

返回参数

参数名	类型	描述
id	String	消息的唯一标识
op	String	业务操作
code	String	代码
msg	String	消息
data	Array of objects	请求成功后返回的数据
> ordId	String	订单ID
> clOrdId	String	由用户设置的订单ID
> ts	String	订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085。与订单频道中的 cTime 相同。
> reqId	String	用户提供的请求ID 如果用户在请求中提供reqId，则返回相应reqId
> sCode	String	订单状态码，0 代表成功
> sMsg	String	订单状态消息
> subCode	String	sCode 的子码。 当 sCode 为 0（请求成功）时，返回 ""。 当 sCode 不为 0（请求失败）且存在子码时，返回对应的子码；若无子码，则返回 ""。
inTime	String	WebSocket 网关接收请求时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123
outTime	String	WebSocket 网关发送响应时的时间戳，Unix时间戳的微秒数格式，如 1597026383085123

WS / 撤销 MMP 订单

撤销同一交易品种下用户所有的 MMP 挂单

仅适用于组合保证金账户模式下的期权订单，且有 MMP 权限。

服务地址

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

限速：5次/2s

限速规则：User ID

同撤销 MMP 订单 REST API 共享限速

请求示例

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

请求参数

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

成功返回示例

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

格式错误返回示例

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

返回参数

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

策略交易

POST / 策略委托下单

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

限速：20次/2s

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

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

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

HTTP请求

POST /api/v5/trade/order-algo

请求示例

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

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

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

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

# 冰山委托策略下单
POST /api/v5/trade/order-algo
body
{
    "instId": "BTC-USDT",
    "tdMode": "cash",
    "side": "buy",
    "ordType": "smart_iceberg",
    "sz": "1000",
    "szLimit": "50",
    "lmtOrderNumber": "5",
    "aggressiveness": "conservative",
    "pxLimit": "95000",
    "side": "buy",
    "posSide": "",
    "ordType": "smart_iceberg",
    "triggerParams": [
      {
          "triggerAction":"start",
          "triggerStrategy":"rsi",
          "timeframe":"30m",
          "thold":"10",
          "triggerCond":"cross",
          "timePeriod":"14"
}

import okx.Trade as Trade

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

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

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

# 单向止盈止损
result = tradeAPI.place_algo_order(
    instId="BTC-USDT",
    tdMode="cross",
    side="buy",
    ordType="conditional",
    sz="2",
    tpTriggerPx="15",
    tpOrdPx="18"
)
print(result)

请求参数

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

止盈止损

用户可预先设置触发价和委托价，等市场价到达触发价时，系统会按委托价自动下单。 单向止盈止损可设置单边的止盈或止损；双向止盈止损可设置双边，一边触发后另一边失效。 该委托不会预先占用仓位或保证金。

了解更多 止盈止损

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

止盈止损 当用户进行单向止盈止损委托（ordType=conditional）时，如果用户同时传了止盈止损四个参数，只进行止损的功能校验，忽略止盈的业务逻辑校验。

追逐限价委托

追逐限价委托会立即下 Post Only 订单（只做maker单）并跟随深度变动进行改单。 追逐限价委托和对应的 Post Only 订单不支持改单。

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

计划委托

当市场价格到达触发价格时，系统将按预先设置的委托价格和数量自动下单。 该委托不会预先占用仓位或保证金。 仅适用于币币、交割和永续。

了解更多 计划委托

参数名	类型	是否必须	描述
triggerPx	String	是	触发该策略订单的价格阈值，单位与该产品的 px 相同。具体使用哪种价格源取决于 triggerPxType（默认为最新成交价）。方向：做空止损单的触发价须低于 orderPx；做多止损单的触发价须高于 orderPx。方向违规将返回错误码 51046–51049。
orderPx	String	条件必填	触发后提交的委托价格，与 triggerPx（决定何时激活）相互独立。设为 -1 表示触发后以市价委托；设置具体价格表示触发后以限价委托。当 advanceOrdType 为 chase 时不适用（追逐委托无固定价格）。
advanceOrdType	String	否	计划委托的子订单类型。 fok：全部成交或立即取消 ioc：立即成交并取消剩余 chase：追逐限价委托。仅适用于 FUTURES 和 SWAP。 默认为空（按 orderPx 下发限价或市价单）。
advChaseParams	Array of objects	条件必填	追逐参数。当 advanceOrdType 为 chase 时必填。
> chaseType	String	条件必填	追逐距离单位。 distance（默认）：与买一价/卖一价的绝对价格距离，以结算货币计。 ratio：百分比。
> chaseVal	String	条件必填	追逐值。当 chaseType 为 distance 时，为与买一价/卖一价的距离（以结算货币计）；当 ratio 时，0.1 表示 10%。 默认值 0 表示直接跟随买一价/卖一价；大于 0 表示设置一个距离。
> maxChaseType	String	条件必填	最大追逐距离单位。distance 或 ratio。须与 maxChaseVal 成对出现。
> maxChaseVal	String	条件必填	最大追逐距离值。须为正数。须与 maxChaseType 成对出现。当偏离达到该值时，追逐委托自动撤单。
triggerPxType	String	否	触发价格类型： last：任意成交价达到或超过 triggerPx 时触发——响应最快，但在流动性较差市场中易受短暂插针影响。 index：基于多交易所合成指数触发——稳定，不受OKX自身插针影响。 mark：基于OKX标记价格触发——经过平滑处理，抗插针能力强；衍生品推荐使用。 现货产品仅支持 last。默认为 last。
attachAlgoOrds	Array of objects	否	附带止盈止损信息 适用于合约模式/跨币种保证金模式/组合保证金模式 当 advanceOrdType 为 chase 时不适用。
> attachAlgoClOrdId	String	否	下单附带止盈止损时，客户自定义的策略订单ID，字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 订单完全成交，下止盈止损委托单时，该值会传给algoClOrdId。
> tpTriggerPx	String	否	止盈触发价，如果填写此参数，必须填写止盈委托价
> tpTriggerRatio	String	否	止盈触发比例，0.3 代表 30% 仅适用于交割/永续合约 tpTriggerPx 和 tpTriggerRatio 只能传入其中一个 如果主单为买入订单，必须大于 0，如果主单为卖出订单，必须处于 -1 和 0 之间。
> tpTriggerPxType	String	否	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格 默认为last
> tpOrdPx	String	否	止盈委托价，如果填写此参数，必须填写止盈触发价 委托价格为-1时，执行市价止盈
> slTriggerPx	String	否	止损触发价，如果填写此参数，必须填写止损委托价
> slTriggerRatio	String	否	止损触发比例，0.3 代表 30% 仅适用于交割/永续合约 slTriggerPx 和 slTriggerRatio 只能传入其中一个 如果主单为买入订单，必须处于 0 和 1 之间，如果主单为卖出订单，必须大于 0。0 代表删除止损。
> slTriggerPxType	String	否	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格 默认为last
> slOrdPx	String	否	止损委托价，如果填写此参数，必须填写止损触发价 委托价格为-1时，执行市价止损
> callbackRatio	String	可选	回调幅度的比例，如 0.05 代表 5%。 callbackRatio 和 callbackSpread 必须传入其中一个，且只能传入一个。 仅适用于 ordType = move_order_stop
> callbackSpread	String	可选	回调幅度的价距。 callbackRatio 和 callbackSpread 必须传入其中一个，且只能传入一个。 仅适用于 ordType = move_order_stop
> activePx	String	否	激活价格。 激活价格是移动止盈止损的激活条件，当市场最新成交价达到或超过激活价格，委托被激活。激活后系统开始计算止盈止损的实际触发价格。如果不填写激活价格，即下单后就被激活。 仅适用于 ordType = move_order_stop

移动止盈止损

移动止盈止损是一种跟踪市场价格的止盈止损，它的触发价格会跟随市场波动而变化，触发成功后会下市价单。 实际触发价格的计算：卖出或开空时，实际触发价格 = 下单成功后最高价-回调幅度 (价距)，或下单成功后最高价 *(1-回调幅度 %) (比例)；买入或开多，实际触发价格 = 下单成功后最低价 + 回调幅度，或下单成功后最低价 *(1+ 回调幅度 %)。同时，您可以利用激活价格来设置委托被激活的价格。

了解更多 移动止盈止损

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

时间加权

时间加权是一种大额订单拆分后分时吃单的策略。 用户在进行大额交易时，为避免对市场造成过大冲击，需要将大单委托自动拆为多笔委托。

了解更多 时间加权委托

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

冰山委托

参数名	类型	是否必须	描述
szLimit	String	是	单笔最小数量限制，仅适用于 smart_iceberg
lmtOrderNumber	String	是	限价拆单数量，仅适用于 smart_iceberg
aggressiveness	String	是	激进度，仅适用于 smart_iceberg radical：更快成交 mid：较快成交，较优价格 conservative：盘口排队
pxLimit	String	否	价格上限，仅适用于 smart_iceberg
triggerParams	Array of objects	否	触发参数，列表为空时默认立即触发，仅适用于 smart_iceberg
> triggerAction	String	是	触发行为 start：启动冰山委托
> triggerStrategy	String	是	触发策略 instant：立即触发 price：价格触发 rsi：RSI指标触发 默认为 instant
> triggerPx	String	否	触发价格 仅在 triggerStrategy 为 price 时有效
> triggerCond	String	否	触发条件 cross_up：上穿 cross_down：下穿 above：上方 below：下方 cross：交叉 仅在 triggerStrategy 为 rsi 时有效
> timeframe	String	否	K线种类 3m、5m、15m、30m（m代表分钟） 1H、4H（H代表小时） 1D（D代表天） 仅在 triggerStrategy 为 rsi 时有效
> thold	String	否	阈值，取值 [1,100] 的整数 仅在 triggerStrategy 为 rsi 时有效
> timePeriod	String	否	RSI 计算周期，默认值为 14 仅在 triggerStrategy 为 rsi 时有效

返回结果

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

返回参数

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

POST / 撤销策略委托订单

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

限速：20个/2s

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

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

HTTP请求

POST /api/v5/trade/cancel-algos

请求示例

POST /api/v5/trade/cancel-algos
body
[
    {
        "algoId":"590919993110396111",
        "instId":"BTC-USDT"
    },
    {
        "algoId":"590920138287841222",
        "instId":"BTC-USDT"
    }
]

import okx.Trade as Trade

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

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

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

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

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

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID 如 BTC-USDT
algoId	String	可选	策略委托单ID algoId和algoClOrdId必须传一个，若传两个，以algoId为主
algoClOrdId	String	可选	客户自定义策略订单ID algoId和algoClOrdId必须传一个，若传两个，以algoId为主

返回结果

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

返回参数

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

POST / 修改策略委托订单

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

限速：20次/2s

限速规则：User ID + Instrument ID

HTTP请求

POST /api/v5/trade/amend-algos

请求示例

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

请求参数

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

止盈止损

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

计划委托

参数名	类型	是否必须	描述
newTriggerPx	String	是	修改后的触发价格
newOrdPx	String	是	修改后的委托价格 委托价格为-1时，执行市价委托
newTriggerPxType	String	否	修改后的计划委托触发价格类型 last：最新价格 index：指数价格 mark：标记价格 默认为last
attachAlgoOrds	Array of objects	否	修改附带止盈止损或移动止盈止损订单信息 适用于合约模式/跨币种保证金模式/组合保证金模式
> newTpTriggerPx	String	否	止盈触发价，如果填写此参数，必须填写止盈委托价
> newTpTriggerRatio	String	否	止盈触发比例，0.3 代表 30% 仅适用于交割/永续合约 newTpTriggerPx 和 newTpTriggerRatio 只能传入其中一个 如果主单为买入订单，必须大于 0，如果主单为卖出订单，必须处于 -1 和 0 之间。0 代表删除止盈。
> newTpTriggerPxType	String	否	修改后的止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格 默认为last
> newTpOrdPx	String	否	止盈委托价，如果填写此参数，必须填写止盈触发价 委托价格为-1时，执行市价止盈
> newSlTriggerPx	String	否	止损触发价，如果填写此参数，必须填写止损委托价
> newSlTriggerRatio	String	否	止损触发比例，0.3 代表 30% 仅适用于交割/永续合约 newSlTriggerPx 和 newSlTriggerRatio 只能传入其中一个 如果主单为买入订单，必须处于 0 和 1 之间，如果主单为卖出订单，必须大于 0。0 代表删除止损。
> newSlTriggerPxType	String	否	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格 默认为last
> newSlOrdPx	String	否	止损委托价，如果填写此参数，必须填写止损触发价 委托价格为-1时，执行市价止损
> newCallbackRatio	String	可选	新的回调幅度比例，如 0.05 代表 5%。 newCallbackRatio 和 newCallbackSpread 只能传入其中一个。 仅适用于 ordType = move_order_stop
> newCallbackSpread	String	可选	新的回调幅度价距。 newCallbackRatio 和 newCallbackSpread 只能传入其中一个。 仅适用于 ordType = move_order_stop
> newActivePx	String	否	新的激活价格。 仅适用于 ordType = move_order_stop
advChaseParams	Array of objects	条件必填	待修改的追逐参数。仅适用于 advanceOrdType 为 chase 的挂单中计划委托。
> newChaseVal	String	条件必填	新的追逐值。非负数，按订单已有（不可修改）的 chaseType 解释。不可越过原 chaseVal 的 0 ↔ 非 0 边界——直接跟随买一价/卖一价（0）与设置距离（大于 0）两种模式不可互换。
> newMaxChaseVal	String	条件必填	新的最大追逐距离值。须为正数，按已有（不可修改）的 maxChaseType 解释。仅在已启用最大追逐距离时适用。

返回结果

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

返回参数

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

GET / 获取策略委托单信息

限速：20次/2s

限速规则：User ID

HTTP请求

GET /api/v5/trade/order-algo

请求示例

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

请求参数

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

返回结果

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

返回参数

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

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

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

import okx.Trade as Trade

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

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

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

# 查询所有未触发的单向止盈止损策略订单
result = tradeAPI.order_algos_list(
    ordType="conditional"
)
print(result)

请求参数

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

返回结果

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

返回参数

参数名	类型	描述
instType	String	产品类型
instId	String	产品ID
ccy	String	保证金币种，适用于逐仓杠杆及合约模式下的全仓杠杆订单
ordId	String	最新一笔订单ID，即将废弃。
ordIdList	Array of strings	订单ID列表，当止盈止损存在市价拆单时，会有多个。 对于追逐委托（trigger+chase），该字段为空——生成的订单为策略委托，参见 subAlgoIdList。
subAlgoIdList	Array of strings	计划委托触发时生成的策略委托单 algoId。当 advanceOrdType 为 chase 时，在触发后存放生成的追逐委托 algoId，触发前为空。与 ordIdList 对应，后者记录生成的普通订单。
algoId	String	策略委托单ID
clOrdId	String	客户自定义订单ID
sz	String	委托数量
closeFraction	String	策略委托触发时，平仓的百分比。1 代表100%
ordType	String	订单类型
side	String	订单方向
posSide	String	持仓方向
tdMode	String	交易模式
tgtCcy	String	币币市价单委托数量sz的单位 base_ccy：交易货币 quote_ccy：计价货币 仅适用于币币市价订单 默认买单为quote_ccy，卖单为base_ccy
state	String	订单状态 live：待生效 pause：暂停生效
lever	String	杠杆倍数，0.01到125之间的数值 仅适用于 币币杠杆/交割/永续
tpTriggerPx	String	止盈触发价
tpTriggerPxType	String	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格
tpOrdPx	String	止盈委托价
slTriggerPx	String	止损触发价
slTriggerPxType	String	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格
slOrdPx	String	止损委托价
triggerPx	String	计划委托触发价格
triggerPxType	String	计划委托触发价类型 last：最新价格 index：指数价格 mark：标记价格
ordPx	String	计划委托单的委托价格
advanceOrdType	String	计划委托的子订单类型。 fok：全部成交或立即取消 ioc：立即成交并取消剩余 chase：追逐限价委托 默认为空。
advChaseParams	Array of objects	追逐参数。当 advanceOrdType 为 chase 时返回。
> chaseType	String	追逐距离单位。distance 或 ratio。
> chaseVal	String	追逐值。0 表示直接跟随买一价/卖一价；大于 0 表示距离。
> maxChaseType	String	最大追逐距离单位。distance 或 ratio。
> maxChaseVal	String	最大追逐距离值。
actualSz	String	实际委托量
actualPx	String	实际委托价
actualSide	String	实际触发方向 tp：止盈 sl：止损 仅适用于单向止盈止损委托和双向止盈止损委托
triggerTime	String	策略委托触发时间，Unix时间戳的毫秒数格式，如 1597026383085
pxVar	String	价格比例 仅适用于冰山委托和时间加权委托
pxSpread	String	价距 仅适用于冰山委托和时间加权委托
szLimit	String	单笔数量 仅适用于冰山委托和时间加权委托
tag	String	订单标签
pxLimit	String	挂单限制价，仅适用于时间加权委托 价格上限，仅适用于冰山委托
lmtOrderNumber	String	限价拆单数量 仅适用于 冰山委托
aggressiveness	String	激进度 radical：更快成交 mid：较快成交，较优价格 conservative：盘口排队 仅适用于 冰山委托
triggerParams	Array of objects	触发参数 仅适用于 冰山委托
> triggerAction	String	触发行为 start：启动冰山委托
> triggerStrategy	String	触发策略 instant：立即触发 price：价格触发 rsi：RSI指标触发
> triggerPx	String	触发价格 仅在 triggerStrategy 为 price 时有效
> triggerCond	String	触发条件 cross_up：上穿 cross_down：下穿 above：上方 below：下方 cross：交叉 仅在 triggerStrategy 为 rsi 时有效
> timeframe	String	K线种类 3m、5m、15m、30m（m代表分钟） 1H、4H（H代表小时） 1D（D代表天） 仅在 triggerStrategy 为 rsi 时有效
> thold	String	阈值，取值 [1,100] 的整数 仅在 triggerStrategy 为 rsi 时有效
> timePeriod	String	RSI 计算周期，默认值为 14 仅在 triggerStrategy 为 rsi 时有效
timeInterval	String	下单间隔 仅适用于时间加权委托
callbackRatio	String	回调幅度的比例 仅适用于移动止盈止损
callbackSpread	String	回调幅度的价距 仅适用于移动止盈止损
activePx	String	移动止盈止损激活价格 仅适用于移动止盈止损
moveTriggerPx	String	移动止盈止损触发价格 仅适用于移动止盈止损
reduceOnly	String	是否只减仓 true 或 false
quickMgnType	String	一键借币类型，仅适用于杠杆逐仓的一键借币模式 manual：手动，auto_borrow：自动借币，auto_repay：自动还币（已弃用）
last	String	下单时的最新成交价
failCode	String	代表策略触发失败的原因，委托失败时有值，如 51008，对于该接口一直为""。
algoClOrdId	String	客户自定义策略订单ID
amendPxOnTriggerType	String	是否启用开仓价止损，仅适用于分批止盈的止损订单 0：不开启，默认值 1：开启
attachAlgoOrds	Array of objects	附带止盈止损或移动止盈止损订单信息 适用于合约模式/跨币种保证金模式/组合保证金模式
> attachAlgoClOrdId	String	下单附带止盈止损或移动止盈止损时，客户自定义的策略订单ID，字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 订单完全成交，下附带策略委托单时，该值会传给algoClOrdId。
> tpTriggerPx	String	止盈触发价，如果填写此参数，必须填写止盈委托价
> tpTriggerRatio	String	止盈触发比例，0.3 代表 30% 仅适用于交割/永续合约
> tpTriggerPxType	String	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格
> tpOrdPx	String	止盈委托价，如果填写此参数，必须填写止盈触发价 委托价格为-1时，执行市价止盈
> slTriggerPx	String	止损触发价，如果填写此参数，必须填写止损委托价
> slTriggerRatio	String	止损触发比例，0.3 代表 30% 仅适用于交割/永续合约
> slTriggerPxType	String	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格
> slOrdPx	String	止损委托价，如果填写此参数，必须填写止损触发价 委托价格为-1时，执行市价止损
> callbackRatio	String	回调幅度的比例，如 0.05 代表 5%
> callbackSpread	String	回调幅度的价距
> activePx	String	激活价格
linkedOrd	Object	止盈订单信息，仅适用于止损单，且该止损订单来自包含限价止盈单的双向止盈止损订单
> ordId	String	订单 ID
cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085
uTime	String	订单更新时间，Unix时间戳的毫秒数格式，如 1597026383085
isTradeBorrowMode	String	是否自动借币 true：自动借币 false：不自动借币 仅适用于计划委托、移动止盈止损和 时间加权策略
chaseType	String	追逐类型。仅适用于追逐限价委托。
chaseVal	String	追逐值。仅适用于追逐限价委托。
maxChaseType	String	最大追逐值的类型。仅适用于追逐限价委托。
maxChaseVal	String	最大追逐值。仅适用于追逐限价委托。
tradeQuoteCcy	String	用于交易的计价币种。

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

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

import okx.Trade as Trade

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

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

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

# 查询 单向止盈止损 历史订单
result = tradeAPI.order_algos_history(
    state="effective",
    ordType="conditional"
)
print(result)

请求参数

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

返回结果

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

返回参数

参数名	类型	描述
instType	String	产品类型
instId	String	产品ID
ccy	String	保证金币种，适用于逐仓杠杆及合约模式下的全仓杠杆订单以及交割、永续和期权合约订单。
ordId	String	最新一笔订单ID，即将废弃。
ordIdList	Array of strings	订单ID列表，当止盈止损存在市价拆单时，会有多个。 对于追逐委托（trigger+chase），该字段为空——生成的订单为策略委托，参见 subAlgoIdList。
subAlgoIdList	Array of strings	计划委托触发时生成的策略委托单 algoId。当 advanceOrdType 为 chase 时，在触发后存放生成的追逐委托 algoId，触发前为空。与 ordIdList 对应，后者记录生成的普通订单。
algoId	String	策略委托单ID
clOrdId	String	客户自定义订单ID
sz	String	委托数量
closeFraction	String	策略委托触发时，平仓的百分比。1 代表100%
ordType	String	订单类型
side	String	订单方向
posSide	String	持仓方向
tdMode	String	交易模式
tgtCcy	String	币币市价单委托数量sz的单位 base_ccy: 交易货币 ；quote_ccy：计价货币 仅适用于币币市价订单 默认买单为quote_ccy，卖单为base_ccy
state	String	订单状态 effective：已生效 canceled：已撤销 order_failed：委托失败 partially_failed：部分委托失败
lever	String	杠杆倍数，0.01到125之间的数值 仅适用于 币币杠杆/交割/永续`
tpTriggerPx	String	止盈触发价
tpTriggerPxType	String	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格
tpOrdPx	String	止盈委托价
slTriggerPx	String	止损触发价
slTriggerPxType	String	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格
slOrdPx	String	止损委托价
triggerPx	String	计划委托触发价格
triggerPxType	String	计划委托委托价格类型 last：最新价格 index：指数价格 mark：标记价格
ordPx	String	计划委托委托价格
advanceOrdType	String	计划委托的子订单类型。 fok：全部成交或立即取消 ioc：立即成交并取消剩余 chase：追逐限价委托 默认为空。
advChaseParams	Array of objects	追逐参数。当 advanceOrdType 为 chase 时返回。
> chaseType	String	追逐距离单位。distance 或 ratio。
> chaseVal	String	追逐值。0 表示直接跟随买一价/卖一价；大于 0 表示距离。
> maxChaseType	String	最大追逐距离单位。distance 或 ratio。
> maxChaseVal	String	最大追逐距离值。
actualSz	String	实际委托量
actualPx	String	实际委托价
actualSide	String	实际触发方向 tp：止盈 sl：止损 仅适用于单向止盈止损委托和双向止盈止损委托
triggerTime	String	策略委托触发时间，Unix时间戳的毫秒数格式，如 1597026383085
pxVar	String	价格比例 仅适用于冰山委托和时间加权委托
pxSpread	String	价距 仅适用于冰山委托和时间加权委托
szLimit	String	单笔数量 仅适用于冰山委托和时间加权委托
pxLimit	String	挂单限制价 仅适用于冰山委托和时间加权委托
lmtOrderNumber	String	限价拆单数量 仅适用于冰山委托
aggressiveness	String	激进度 radical：更快成交 mid：较快成交，较优价格 conservative：盘口排队 仅适用于冰山委托
triggerParams	Array of objects	触发参数 仅适用于冰山委托
> triggerAction	String	触发行为 start：启动冰山委托
> triggerStrategy	String	触发策略 instant：立即触发 price：价格触发 rsi：RSI指标触发
> triggerPx	String	触发价格 仅在 triggerStrategy 为 price 时有效
> triggerCond	String	触发条件 cross_up：上穿 cross_down：下穿 above：上方 below：下方 cross：交叉 仅在 triggerStrategy 为 rsi 时有效
> timeframe	String	K线种类 3m、5m、15m、30m（m代表分钟） 1H、4H（H代表小时） 1D（D代表天） 仅在 triggerStrategy 为 rsi 时有效
> thold	String	阈值，取值 [1,100] 的整数 仅在 triggerStrategy 为 rsi 时有效
> timePeriod	String	RSI 计算周期，默认值为 14 仅在 triggerStrategy 为 rsi 时有效
tag	String	订单标签
timeInterval	String	下单间隔 仅适用于时间加权委托
callbackRatio	String	回调幅度的比例 仅适用于移动止盈止损
callbackSpread	String	回调幅度的价距 仅适用于移动止盈止损
activePx	String	移动止盈止损激活价格 仅适用于移动止盈止损
moveTriggerPx	String	移动止盈止损触发价格 仅适用于移动止盈止损
reduceOnly	String	是否只减仓 true或false
quickMgnType	String	一键借币类型，仅适用于杠杆逐仓的一键借币模式 manual：手动，auto_borrow：自动借币，auto_repay：自动还币（已弃用）
last	String	下单时的最新成交价
failCode	String	代表策略触发失败的原因，已撤销和已生效时为""，委托失败时有值，如 51008； 仅适用于单向止盈止损委托、双向止盈止损委托、移动止盈止损委托、计划委托。
algoClOrdId	String	客户自定义策略订单ID
amendPxOnTriggerType	String	是否启用开仓价止损，仅适用于分批止盈的止损订单 0：不开启，默认值 1：开启
attachAlgoOrds	Array of objects	附带止盈止损或移动止盈止损订单信息 适用于合约模式/跨币种保证金模式/组合保证金模式
> attachAlgoClOrdId	String	下单附带止盈止损或移动止盈止损时，客户自定义的策略订单ID，字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 订单完全成交，下附带策略委托单时，该值会传给algoClOrdId。
> tpTriggerPx	String	止盈触发价，如果填写此参数，必须填写止盈委托价
> tpTriggerRatio	String	止盈触发比例，0.3 代表 30% 仅适用于交割/永续合约
> tpTriggerPxType	String	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格
> tpOrdPx	String	止盈委托价，如果填写此参数，必须填写止盈触发价 委托价格为-1时，执行市价止盈
> slTriggerPx	String	止损触发价，如果填写此参数，必须填写止损委托价
> slTriggerRatio	String	止损触发比例，0.3 代表 30% 仅适用于交割/永续合约
> slTriggerPxType	String	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格
> slOrdPx	String	止损委托价，如果填写此参数，必须填写止损触发价 委托价格为-1时，执行市价止损
> callbackRatio	String	回调幅度的比例，如 0.05 代表 5%
> callbackSpread	String	回调幅度的价距
> activePx	String	激活价格
linkedOrd	Object	止盈订单信息，仅适用于止损单，且该止损订单来自包含限价止盈单的双向止盈止损订单
> ordId	String	订单 ID
cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085
uTime	String	订单更新时间，Unix时间戳的毫秒数格式，如 1597026383085
isTradeBorrowMode	String	是否自动借币 true：自动借币 false：不自动借币 仅适用于计划委托、移动止盈止损和 时间加权策略
chaseType	String	追逐类型。仅适用于追逐限价委托。
chaseVal	String	追逐值。仅适用于追逐限价委托。
maxChaseType	String	最大追逐值的类型。仅适用于追逐限价委托。
maxChaseVal	String	最大追逐值。仅适用于追逐限价委托。
tradeQuoteCcy	String	用于交易的计价币种。

WS / 策略委托订单频道

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

服务地址

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

请求示例：单个

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

import asyncio

from okx.websocket.WsPrivateAsync import WsPrivateAsync

def callbackFunc(message):
    print(message)

async def main():

    ws = WsPrivateAsync(
        apiKey = "YOUR_API_KEY",
        passphrase = "YOUR_PASSPHRASE",
        secretKey = "YOUR_SECRET_KEY",
        url = "wss://ws.okx.com:8443/ws/v5/business",
        useServerTime=False
    )
    await ws.start()
    args = [{
        "channel": "orders-algo",
        "instType": "FUTURES",
        "instFamily": "BTC-USD",
        "instId": "BTC-USD-200329"
    }]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求示例

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

import asyncio

from okx.websocket.WsPrivateAsync import WsPrivateAsync

def callbackFunc(message):
    print(message)

async def main():

    ws = WsPrivateAsync(
        apiKey = "YOUR_API_KEY",
        passphrase = "YOUR_PASSPHRASE",
        secretKey = "YOUR_SECRET_KEY",
        url = "wss://ws.okx.com:8443/ws/v5/business",
        useServerTime=False
    )
    await ws.start()
    args = [{
        "channel": "orders-algo",
        "instType": "FUTURES",
        "instFamily": "BTC-USD"
    }]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求参数

参数	类型	是否必须	描述
id	String	否	消息的唯一标识。 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 subscribe unsubscribe
args	Array of objects	是	请求订阅的频道列表
> channel	String	是	频道名 orders-algo
> instType	String	是	产品类型 SPOT：币币 MARGIN：币币杠杆 SWAP：永续合约 FUTURES：交割合约 ANY：全部
> instFamily	String	否	交易品种 适用于交割/永续/期权
> instId	String	否	产品ID

成功返回示例：单个

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

成功返回示例

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

失败返回示例

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

返回参数

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

推送示例：单个

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

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> uid	String	用户标识
> instType	String	产品类型
> instFamily	String	交易品种 适用于交割/永续/期权
> instId	String	产品ID
data	Array of objects	订阅的数据
> instType	String	产品类型
> instId	String	产品ID
> ccy	String	保证金币种，适用于逐仓杠杆及合约模式下的全仓杠杆订单以及交割、永续和期权合约订单。
> ordId	String	最新一笔订单ID，与策略委托订单关联的订单ID，即将废弃。
> ordIdList	Array of strings	订单ID列表，当止盈止损存在市价拆单时，会有多个。 对于追逐委托（trigger+chase），该字段为空——参见 subAlgoIdList。
> subAlgoIdList	Array of strings	计划委托触发时生成的策略委托单 algoId。当 advanceOrdType 为 chase 时，在触发后存放生成的追逐委托 algoId，触发前为空。与 ordIdList 对应，后者记录生成的普通订单。
> algoId	String	策略委托单ID
> clOrdId	String	客户自定义订单ID
> sz	String	委托数量，币币/币币杠杆 以币为单位；交割/永续/期权 以张为单位
> ordType	String	订单类型 conditional：单向止盈止损 oco：双向止盈止损 trigger：计划委托 chase：追逐限价委托
> side	String	订单方向，buy sell
> posSide	String	持仓方向 long：开平仓模式开多 short：开平仓模式开空 net：买卖模式
> tdMode	String	交易模式 保证金模式 cross：全仓 isolated：逐仓 非保证金模式 cash：现金
> tgtCcy	String	币币市价单委托数量sz的单位 base_ccy：交易货币 quote_ccy：计价货币 仅适用于币币市价订单 默认买单为quote_ccy，卖单为base_ccy
> lever	String	杠杆倍数，0.01到125之间的数值，仅适用于 币币杠杆/交割/永续
> state	String	订单状态 live：待生效 effective：已生效 canceled：已撤销 order_failed：委托失败 partially_failed：部分委托失败 partially_effective: 部分生效
> tpTriggerPx	String	止盈触发价
> tpTriggerPxType	String	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格
> tpOrdPx	String	止盈委托价，委托价格为-1时，执行市价止盈
> slTriggerPx	String	止损触发价
> slTriggerPxType	String	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格
> slOrdPx	String	止损委托价委托价格为-1时，执行市价止损
> triggerPx	String	计划委托单的触发价格
> triggerPxType	String	计划委托单的触发价类型 last：最新价格 index：指数价格 mark：标记价格
> ordPx	String	计划委托单的委托价格
> advanceOrdType	String	计划委托的子订单类型。 fok：全部成交或立即取消 ioc：立即成交并取消剩余 chase：追逐限价委托 默认为空。
> advChaseParams	Array of objects	追逐参数。当 advanceOrdType 为 chase 时返回。
>> chaseType	String	追逐距离单位。distance 或 ratio。
>> chaseVal	String	追逐值。0 表示直接跟随买一价/卖一价；大于 0 表示距离。
>> maxChaseType	String	最大追逐距离单位。distance 或 ratio。
>> maxChaseVal	String	最大追逐距离值。
> last	String	下单时的最新成交价
> actualSz	String	实际委托量
> actualPx	String	实际委价
> tag	String	订单标签
> notionalUsd	String	委托单预估美元价值
> actualSide	String	实际触发方向 sl：止损 tp：止盈 仅适用于单向止盈止损委托和双向止盈止损委托
> triggerTime	String	策略委托触发时间，Unix时间戳的毫秒数格式，如 1597026383085
> reduceOnly	String	是否只减仓，true 或 false
> failCode	String	代表策略触发失败的原因，已撤销和已生效时为""，委托失败时有值，如 51008； 仅适用于单向止盈止损委托、双向止盈止损委托、移动止盈止损委托、计划委托。
> algoClOrdId	String	客户自定义策略订单ID
> reqId	String	修改订单时使用的request ID，如果没有修改，该字段为""
> amendResult	String	修改订单的结果 -1：失败 0：成功
> amendPxOnTriggerType	String	是否启用开仓价止损，仅适用于分批止盈的止损订单 0：不开启，默认值 1：开启
> attachAlgoOrds	Array of objects	附带止盈止损或移动止盈止损订单信息 适用于合约模式/跨币种保证金模式/组合保证金模式
>> attachAlgoClOrdId	String	下单附带止盈止损或移动止盈止损时，客户自定义的策略订单ID，字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间。 订单完全成交，下附带策略委托单时，该值会传给algoClOrdId。
>> tpTriggerPx	String	止盈触发价，如果填写此参数，必须填写止盈委托价
>> tpTriggerRatio	String	止盈触发比例，0.3 代表 30% 仅适用于交割/永续合约
>> tpTriggerPxType	String	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格
>> tpOrdPx	String	止盈委托价，如果填写此参数，必须填写止盈触发价 委托价格为-1时，执行市价止盈
>> slTriggerPx	String	止损触发价，如果填写此参数，必须填写止损委托价
>> slTriggerRatio	String	止损触发比例，0.3 代表 30% 仅适用于交割/永续合约
>> slTriggerPxType	String	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格
>> slOrdPx	String	止损委托价，如果填写此参数，必须填写止损触发价 委托价格为-1时，执行市价止损
>> callbackRatio	String	回调幅度的比例，如 0.05 代表 5%
>> callbackSpread	String	回调幅度的价距
>> activePx	String	激活价格
> linkedOrd	Object	止盈订单信息，仅适用于止损单，且该止损订单来自包含限价止盈单的双向止盈止损订单
>> ordId	String	订单 ID
> cTime	String	订单创建时间，Unix时间戳的毫秒数格式，如 1597026383085
> uTime	String	订单更新时间，Unix时间戳的毫秒数格式，如 1597026383085
> isTradeBorrowMode	String	是否自动借币 true：自动借币 false：不自动借币 仅适用于计划委托、移动止盈止损和 时间加权策略
> chaseType	String	追逐类型。仅适用于追逐限价委托。
> chaseVal	String	追逐值。仅适用于追逐限价委托。
> maxChaseType	String	最大追逐值的类型。仅适用于追逐限价委托。
> maxChaseVal	String	最大追逐值。仅适用于追逐限价委托。
> tradeQuoteCcy	String	用于交易的计价币种。

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

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

服务地址

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

请求示例：单个

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

import asyncio

from okx.websocket.WsPrivateAsync import WsPrivateAsync

def callbackFunc(message):
    print(message)

async def main():

    ws = WsPrivateAsync(
        apiKey = "YOUR_API_KEY",
        passphrase = "YOUR_PASSPHRASE",
        secretKey = "YOUR_SECRET_KEY",
        url = "wss://ws.okx.com:8443/ws/v5/business",
        useServerTime=False
    )
    await ws.start()
    args = [
        {
          "channel": "algo-advance",
          "instType": "SPOT",
          "instId": "BTC-USDT"
        }
    ]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求示例

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

import asyncio

from okx.websocket.WsPrivateAsync import WsPrivateAsync

def callbackFunc(message):
    print(message)

async def main():

    ws = WsPrivateAsync(
        apiKey = "YOUR_API_KEY",
        passphrase = "YOUR_PASSPHRASE",
        secretKey = "YOUR_SECRET_KEY",
        url = "wss://ws.okx.com:8443/ws/v5/business",
        useServerTime=False
    )
    await ws.start()

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

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求参数

参数	类型	是否必须	描述
id	String	否	消息的唯一标识。 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 subscribe unsubscribe
args	Array of objects	是	请求订阅的频道列表
> channel	String	是	频道名 algo-advance
> instType	String	是	产品类型 SPOT：币币 MARGIN：币币杠杆 SWAP：永续合约 FUTURES：交割合约 ANY：全部
> instId	String	否	产品ID
> algoId	String	否	策略ID

成功返回示例：单个

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

成功返回示例

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

失败返回示例

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

返回参数

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

推送示例：单个

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

推送数据参数

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

网格交易

网格是一种在指定价格区间自动进行低买高卖的交易策略。用户设定参数后，系统分割小网格自动挂单，随着市场波动，策略低买高卖赚取波段收益。

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

POST / 网格策略委托下单

限速：20次/2s

限速规则：User ID + Instrument ID

HTTP请求

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

请求示例

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

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

请求参数

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

现货网格

参数名	类型	是否必须	描述
quoteSz	String	可选	计价币投入数量 quoteSz和baseSz至少指定一个
baseSz	String	可选	交易币投入数量 quoteSz和baseSz至少指定一个
tradeQuoteCcy	String	No	用于交易的计价币种。仅适用于现货网格。 默认值为 instId 的计价币种，例如 BTC-USD 的计价币种为 USD。

合约网格

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

返回结果

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

返回参数

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

POST / 修改网格策略基本参数

限速：20次/2s

限速规则：User ID

HTTP请求

POST /api/v5/tradingBot/grid/amend-algo-basic-param

请求示例

POST /api/v5/tradingBot/grid/amend-algo-basic-param
body
    {
        "algoId":"448965992920907776",
        "maxPx": "100",
        "minPx": "10",
        "gridNum": "5"
        "topupAmount": "123.45"
    }

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID
minPx	String	是	最小价格
maxPx	String	是	最大价格
gridNum	String	是	网格数
topupAmount	String	不是	仅限合约网格。可选填写用户自行提供的追加投资金额。若未填写，或明确填写为“0”，在编辑网格参数时，所需的追加投资金额将默认自动追加。

返回结果

{
    "code": "55186",
    "msg": "Due to market fluctuations, your investment amount is too large to apply these modifications.",
    "data": [
        {
            "algoId": "4283223775520665600",
            "maxTopupAmount": "12456.78",
            "requiredTopupAmount": "12.34"
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	策略订单ID
requiredTopupAmount	String	修改网格参数所需补充金额
maxTopupAmount	String	仅限合约网格。编辑网格参数时的最大追加投资金额。

报错码

报错码	HTTP Status 代码	报错文案
51000	400	{param} 参数错误。
51346	400	最高价格应高于最低价格。
55123	400	您的交易账户余额不足，无法使此修改生效。请您向交易账户转入资金后再试。
55124	200	由于行情波动，您的投入金额不足，修改后的参数无法生效。
55186	200	由于行情波动，您的投入金额过大，修改后的参数无法生效。

POST / 修改网格策略订单

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

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

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

请求参数

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

返回结果

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

返回参数

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

POST / 网格策略停止

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

POST / 合约网格平仓

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

POST / 撤销合约网格平仓单

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

POST / 网格策略立即触发

限速：20次/2s

限速规则：User ID + Instrument ID

HTTP请求

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

请求示例

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

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID
topUpAmt	String	否	增加的投资额，仅适用于现货网格

返回结果

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

返回参数

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

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

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

限速：20次/2s

限速规则：User ID

HTTP请求

GET /api/v5/tradingBot/grid/positions

请求示例

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

请求参数

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

返回结果

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

返回参数

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

POST / 现货网格提取利润

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

POST / 调整保证金计算

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

POST / 调整保证金

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

POST / 加仓

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID
amt	String	是	加仓数量
allowReinvestProfit	String	否	是否复投利润，仅适用于现货网格。 true 或者 false。默认为 true。

返回结果

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

返回参数

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

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

公共接口无须鉴权

限速：20次/2s

限速规则：IP

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

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

公共接口无须鉴权

限速：20次/2s

限速规则：IP

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

GET / RSI回测（公共）

公共接口无须鉴权

限速：20次/2s

限速规则：IP

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

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

公共接口无须鉴权

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

限速：5次/2s

限速规则：IP

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

POST / 网格跟单下单

限速：20次/2s

限速规则：User ID + Instrument ID

HTTP请求

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

请求示例

# 现货网格跟单
POST /api/v5/tradingBot/grid/copy-order-algo
body
{
    "instId": "BTC-USDT",
    "algoOrdType": "grid",
    "sourceAlgoId": "580007082221121536",
    "quoteSz": "1000"
}

# 合约网格跟单
POST /api/v5/tradingBot/grid/copy-order-algo
body
{
    "instId": "BTC-USDT-SWAP",
    "algoOrdType": "contract_grid",
    "sourceAlgoId": "580007082221121536",
    "lever": "3",
    "autoReserve": true,
    "sz": "5000"
}

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 BTC-USDT
algoOrdType	String	是	策略订单类型 grid：现货网格 contract_grid：合约网格
sourceAlgoId	String	是	被跟单的策略订单ID
quoteSz	String	否	计价币投入金额 仅适用于 grid
lever	String	否	杠杆倍数 仅适用于 contract_grid
autoReserve	Boolean	否	是否自动预留保证金，仅适用于 contract_grid true：自动计算实际保证金和额外保证金 false：手动指定 actualMarginSz 和 extraMarginSz
sz	String	否	合约网格总投入金额（USDT），当 autoReserve 为 true 时必填 仅适用于 contract_grid
actualMarginSz	String	否	实际保证金，当 autoReserve 为 false 时必填 仅适用于 contract_grid
extraMarginSz	String	否	额外保证金，当 autoReserve 为 false 时选填，默认为 0 仅适用于 contract_grid
algoClOrdId	String	否	客户自定义策略单ID
tag	String	否	订单标签

返回结果

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

返回参数

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

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

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

服务地址

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

请求示例

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

import asyncio

from okx.websocket.WsPrivateAsync import WsPrivateAsync

def callbackFunc(message):
    print(message)

async def main():

    ws = WsPrivateAsync(
        apiKey = "YOUR_API_KEY",
        passphrase = "YOUR_PASSPHRASE",
        secretKey = "YOUR_SECRET_KEY",
        url = "wss://ws.okx.com:8443/ws/v5/business",
        useServerTime=False
    )
    await ws.start()
    args = [{
        "channel": "grid-orders-spot",
        "instType": "SPOT"
    }]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求参数

参数	类型	是否必须	描述
id	String	否	消息的唯一标识。 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 subscribe unsubscribe
args	Array of objects	是	请求订阅的频道列表
> channel	String	是	频道名 grid-orders-spot
> instType	String	是	产品类型 SPOT：币币 ANY：全部
> instId	String	否	产品ID
> algoId	String	否	策略ID

成功返回示例

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

失败返回示例

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

返回参数

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

推送示例

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

推送数据参数

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

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

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

服务地址

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

请求示例

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

import asyncio

from okx.websocket.WsPrivateAsync import WsPrivateAsync

def callbackFunc(message):
    print(message)

async def main():

    ws = WsPrivateAsync(
        apiKey = "YOUR_API_KEY",
        passphrase = "YOUR_PASSPHRASE",
        secretKey = "YOUR_SECRET_KEY",
        url = "wss://ws.okx.com:8443/ws/v5/business",
        useServerTime=False
    )
    await ws.start()
    args = [{
        "channel": "grid-orders-contract",
        "instType": "SWAP"
    }]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求参数

参数	类型	是否必须	描述
id	String	否	消息的唯一标识。 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 subscribe unsubscribe
args	Array of objects	是	请求订阅的频道列表
> channel	String	是	频道名 grid-orders-contract
> instType	String	是	产品类型 SWAP：永续 FUTURE：交割 ANY：全部
> instId	String	否	产品ID
> algoId	String	否	策略ID

成功返回示例

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

失败返回示例

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

返回参数

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

推送示例

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

推送数据参数

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

WS / 合约网格持仓频道

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

请忽略空数据

服务地址

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

请求示例

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

import asyncio

from okx.websocket.WsPrivateAsync import WsPrivateAsync

def callbackFunc(message):
    print(message)

async def main():

    ws = WsPrivateAsync(
        apiKey = "YOUR_API_KEY",
        passphrase = "YOUR_PASSPHRASE",
        secretKey = "YOUR_SECRET_KEY",
        url = "wss://ws.okx.com:8443/ws/v5/business",
        useServerTime=False
    )
    await ws.start()
    args = [{
        "channel": "grid-positions",
        "algoId": "449327675342323712"
    }]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求参数

参数	类型	是否必须	描述
id	String	否	消息的唯一标识。 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 subscribe unsubscribe
args	Array of objects	是	请求订阅的频道列表
> channel	String	是	频道名 grid-positions
> algoId	String	是	策略ID

成功返回示例

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

失败返回示例

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

返回参数

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

推送示例

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

推送数据参数

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

WS / 网格策略子订单频道

支持网格策略子订单的事件推送

请忽略空数据

服务地址

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

请求示例

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

import asyncio

from okx.websocket.WsPrivateAsync import WsPrivateAsync

def callbackFunc(message):
    print(message)

async def main():

    ws = WsPrivateAsync(
        apiKey = "YOUR_API_KEY",
        passphrase = "YOUR_PASSPHRASE",
        secretKey = "YOUR_SECRET_KEY",
        url = "wss://ws.okx.com:8443/ws/v5/business",
        useServerTime=False
    )
    await ws.start()
    args = [{
        "channel": "grid-sub-orders",
        "algoId": "449327675342323712"
    }]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求参数

参数	类型	是否必须	描述
id	String	否	消息的唯一标识。 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 subscribe unsubscribe
args	Array of objects	是	请求订阅的频道列表
> channel	String	是	频道名 grid-sub-orders
> algoId	String	是	策略ID

成功返回示例

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

失败返回示例

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

返回参数

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

推送示例

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

推送数据参数

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

马丁交易

马丁策略是一种通过在市场下跌时自动分批加仓来摊低持仓均价的交易策略。用户设定首单金额、最大加仓次数、每次加仓的触发跌幅及止盈比例后，策略将在价格每次达到加仓条件时自动买入，待价格反弹至止盈目标时自动平仓获利。

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

POST / 马丁策略委托下单

限速：20次/2s

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

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

HTTP请求

POST /api/v5/tradingBot/dca/create

请求示例

# 马丁下单
POST /api/v5/tradingBot/dca/create
body
{
    "instId": "BTC-USDT",
    "algoOrdType": "contract_dca",
    "direction": "long",
    "lever": "2",
    "initOrdAmt"="50",
    "maxSafetyOrds"="0",
    "safetyOrdAmt"="10",
    "pxSteps"="0.01",
    "tpPct"="0.05",
    "triggerParams":[
      {
         "triggerAction":"start",
         "triggerStrategy":"rsi",
         "timeframe":"30m",
         "thold":"10",
         "triggerCond":"cross",
         "timePeriod":"14"
      }
}

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 BTC-USDT
algoOrdType	String	是	策略订单类型 contract_dca：合约马丁委托 spot_dca：现货马丁委托
initOrdAmt	String	是	初始订单金额
allowReinvest	String	否	是否复投利润，仅适用于合约马丁 true 或者 false，默认为 true
safetyOrdAmt	String	否	加仓单金额 当 maxSafetyOrds >= 1 时，safetyOrdAmt 必传
maxSafetyOrds	String	是	最大自动加仓次数
pxSteps	String	否	跌多少加仓 当 maxSafetyOrds >= 1 时，pxSteps 必传
pxStepsMult	String	否	加仓价差倍数 当 maxSafetyOrds >= 1 时，pxStepsMult 必传
volMult	String	否	加仓金额倍数 当 maxSafetyOrds >= 1 时，volMult 必传
tpPct	String	是	单周期止盈目标 0.05 表示 5%
slPct	String	否	止损目标 0.05 表示 5%
slMode	String	否	止损模式 limit：限价 market：市价
direction	String	否	合约马丁类型，仅适用于 contract_dca long：多仓，short：空仓
lever	String	是	杠杆倍数 仅适用于 contract_dca
triggerParams	Array of objects	是	信号触发参数
> triggerAction	String	是	触发行为 合约马丁触发行为：start：马丁启动 现货马丁触发行为：start：马丁启动
> triggerStrategy	String	是	触发策略 合约马丁类型：instant：立即触发，price：价格触发，rsi：RSI 指标触发，默认为 instant 现货马丁类型：instant：立即触发，rsi：RSI 指标触发，默认为 instant
> timeframe	String	否	K线种类 3m, 5m, 15m, 30m（m 代表分钟） 1H, 4H（H 代表小时） 1D（D 代表天） 该字段只在 triggerStrategy 为 rsi 时有效
> thold	String	否	阈值 取值 [1,100] 的整数 该字段只在 triggerStrategy 为 rsi 时有效
> triggerCond	String	否	触发条件 cross_up：上穿 cross_down：下穿 above：上方 below：下方 cross：交叉 该字段只在 triggerStrategy 为 rsi 时有效
> timePeriod	String	否	周期 14 该字段只在 triggerStrategy 为 rsi 时有效
> triggerPx	String	否	触发价格 该字段只在 triggerStrategy 为 price 时有效 仅适用于 contract_dca
profitSharingRatio	String	否	带单员分润比例，仅支持固定比例分润，仅适用于 contract_dca 0, 0.1, 0.2, 0.3
trackingMode	String	否	分润设置，仅适用于 contract_dca sync 同步，async 异步
tag	String	否	订单标签
algoClOrdId	String	否	客户端自定义策略单ID
tradeQuoteCcy	String	否	指定交易计价货币，仅适用spot_dca

返回结果

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

返回参数

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

POST / 现货DCA编辑参数

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

POST /api/v5/tradingBot/dca/amend-order-algo
body
{
    "algoId": "532177187189760000",
    "pxSteps": "0.02",
    "pxStepsMult": "2.0",
    "volMult": "2.0",
    "tpPct": "0.05",
    "slPct": "0.20",
    "initOrdAmt": "100",
    "safetyOrdAmt": "50",
    "maxSafetyOrds": "5",
    "reserveFunds": true,
    "triggerParams": [
        {
            "triggerAction": "start",
            "triggerStrategy": "instant"
        }
    ]
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略ID
pxSteps	String	是	价差比例（第一次加仓触发价格差）
pxStepsMult	String	是	价差放大倍数
volMult	String	是	金额放大倍数
tpPct	String	是	止盈目标，0.05 表示 5%
slPct	String	是	止损目标，0.05 表示 5%
initOrdAmt	String	是	初始订单金额（计价货币）
safetyOrdAmt	String	是	加仓单金额（计价货币）
maxSafetyOrds	String	是	最大加仓次数
reserveFunds	Boolean	是	是否预留全部资金 true：预留资金 false：不预留资金
triggerParams	Array of objects	是	信号触发参数
> triggerAction	String	否	触发行为 start：马丁启动
> triggerStrategy	String	否	触发策略 instant：立即触发 rsi：RSI 指标触发
> timeframe	String	否	K线种类 3m, 5m, 15m, 30m（m 代表分钟） 1H, 4H（H 代表小时） 1D（D 代表天） 该字段只在 triggerStrategy 为 rsi 时有效
> thold	String	否	阈值，取值 [1, 100] 的整数 该字段只在 triggerStrategy 为 rsi 时有效
> triggerCond	String	否	触发条件 cross_up：上穿 cross_down：下穿 above：上方 below：下方 cross：交叉 该字段只在 triggerStrategy 为 rsi 时有效
> timePeriod	String	否	周期，如 14 该字段只在 triggerStrategy 为 rsi 时有效

返回结果

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

返回参数

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

POST / 停止马丁策略委托订单

限速：20次/2s

限速规则：User ID

HTTP请求

POST /api/v5/tradingBot/dca/stop

请求示例

POST /api/v5/tradingBot/dca/stop
body
{
    "algoOrdType": "contract_dca",
    "algoId": "448965992920907776",
    "stopType": "1"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略ID
algoOrdType	String	是	策略订单类型 contract_dca：合约马丁委托 spot_dca：现货马丁委托
stopType	String	是	停止类型 合约马丁：1：市价全平，2：停止但不平仓 现货马丁：1：停止并卖出币，2：停止但不卖出币

返回结果

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

返回参数

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

GET / 获取进行中马丁策略委托单列表

限速：20次/2s

限速规则：User ID

HTTP请求

GET /api/v5/tradingBot/dca/ongoing-list

请求示例

GET /api/v5/tradingBot/dca/ongoing-list?algoOrdType=contract_dca&limit=20

请求参数

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

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "algoId": "565849588675117056",
            "algoOrdType": "contract_dca",
            "instId": "BTC-USDT-SWAP",
            "copyType": "0",
            "state": "running",
            "direction": "long",
            "lever": "3",
            "initOrdAmt": "100",
            "safetyOrdAmt": "200",
            "maxSafetyOrds": "5",
            "pxSteps": "0.02",
            "pxStepsMult": "1",
            "volMult": "1",
            "tpPxRange": "",
            "slPct": "",
            "slMode": "",
            "allowReinvest": true,
            "totalPnl": "12.5",
            "pnlRatio": "0.05",
            "totalFundingFee": "-0.5",
            "investmentAmt": "500",
            "investmentCcy": "USDT",
            "arbitragePnL": "2.1",
            "profitSharingRatio": "",
            "trackingMode": "",
            "triggerParams": [
                {
                    "triggerAction": "start",
                    "triggerStrategy": "instant"
                }
            ],
            "cTime": "1597026383085",
            "uTime": "1597026383085"
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	策略订单 ID
algoOrdType	String	策略订单类型 contract_dca：合约马丁委托 spot_dca：现货马丁委托
instId	String	产品 ID，如 BTC-USDT-SWAP
copyType	String	分润订单类型 0：普通订单 1：普通跟单 2：分润跟单 3：带单
state	String	订单状态 starting：启动中 running：运行中 stopping：终止中 pending_signal：等待触发 no_close_position：已停止未平仓
direction	String	合约马丁类型：long：多仓，short：空仓 现货马丁类型：long：做多
lever	String	杠杆倍数 仅适用于 contract_dca
initOrdAmt	String	初始订单金额
safetyOrdAmt	String	加仓单金额
maxSafetyOrds	String	最大自动加仓次数
pxSteps	String	跌多少加仓
pxStepsMult	String	加仓价差倍数
volMult	String	加仓金额倍数
tpPxRange	String	止盈价格限制 做多时止盈价格不得低于系统最小阈值；做空时不得高于最大阈值 仅适用于 contract_dca
slPct	String	止损目标，如 0.05 表示 5%
slMode	String	止损模式 limit：限价 market：市价
allowReinvest	Boolean	是否复投利润 true 或 false
totalPnl	String	总收益
pnlRatio	String	收益率
totalFundingFee	String	累计资金费用 仅适用于 contract_dca
investmentAmt	String	累计投入金额
investmentCcy	String	投入数量单位，仅支持 USDT/USDC
arbitragePnL	String	周期套利收益
transferInMargin	String	净转入金额，包括保证金和手动加仓金额 仅适用于 contract_dca
profitSharingRatio	String	分润比例，取值范围 [0, 0.3] 普通订单返回 "" 仅适用于 contract_dca
trackingMode	String	分润设置 sync：同步 async：异步 仅适用于 contract_dca
triggerParams	Array of objects	信号触发参数
> triggerAction	String	触发行为 start：马丁启动 stop：马丁停止
> triggerStrategy	String	触发策略 合约马丁类型：instant：立即触发，price：价格触发，rsi：RSI 指标触发，webhook：WS 信号触发 现货马丁类型：instant：立即触发，rsi：RSI 指标触发
> triggerPx	String	触发价格 仅在 triggerStrategy 为 price 时有效 仅适用于 contract_dca
> triggerCond	String	触发条件 cross_up：上穿 cross_down：下穿 above：上方 below：下方 cross：交叉 仅在 triggerStrategy 为 rsi 时有效
> timePeriod	String	周期，如 14 仅在 triggerStrategy 为 rsi 时有效
> thold	String	阈值，取值 [1, 100] 的整数 仅在 triggerStrategy 为 rsi 时有效
> timeframe	String	K 线种类 3m、5m、15m、30m（m 代表分钟） 1H、4H（H 代表小时） 1D（D 代表天） 仅在 triggerStrategy 为 rsi 时有效
cTime	String	订单创建时间，Unix 时间戳毫秒数，如 1597026383085
uTime	String	订单更新时间，Unix 时间戳毫秒数，如 1597026383085
ctVal	String	合约面值 仅适用于 contract_dca
tradeQuoteCcy	String	指定交易计价货币 仅适用于 spot_dca

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

限速：20次/2s

限速规则：User ID

HTTP请求

GET /api/v5/tradingBot/dca/history-list

请求示例

GET /api/v5/tradingBot/dca/history-list?algoOrdType=contract_dca

请求参数

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

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "algoId": "12345689",
            "algoOrdType": "contract_dca",
            "instId": "BTC-USDT-SWAP",
            "copyType": "0",
            "state": "stopped",
            "cancelType": "1",
            "direction": "long",
            "lever": "3",
            "initOrdAmt": "100",
            "safetyOrdAmt": "200",
            "maxSafetyOrds": "5",
            "pxSteps": "0.02",
            "pxStepsMult": "1",
            "volMult": "1",
            "slPct": "",
            "slMode": "",
            "allowReinvest": true,
            "totalPnl": "12.5",
            "pnlRatio": "0.05",
            "fundingFee": "-0.5",
            "investmentAmt": "500",
            "investmentCcy": "USDT",
            "arbitragePnL": "2.1",
            "transferInMargin": "500",
            "profitSharingRatio": "",
            "trackingMode": "",
            "triggerParams": [
                {
                    "triggerAction": "start",
                    "triggerStrategy": "instant"
                }
            ],
            "ctVal": "0.01",
            "cTime": "1597026383085",
            "uTime": "1597026383085"
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	策略订单 ID
algoOrdType	String	策略订单类型 contract_dca：合约马丁委托 spot_dca：现货马丁委托
instId	String	产品 ID，如 BTC-USDT-SWAP
copyType	String	分润订单类型 0：普通订单 1：普通跟单 2：分润跟单 3：带单
state	String	订单状态 starting：启动中 running：运行中 stopping：终止中 pending_signal：等待触发 no_close_position：已停止未平仓
cancelType	String	马丁策略停止原因 0：无 1：手动停止 2：止盈停止 3：止损停止 4：风控停止 5：交割停止
direction	String	合约马丁类型：long：多仓，short：空仓 现货马丁类型：long：做多
lever	String	杠杆倍数 仅适用于 contract_dca
initOrdAmt	String	初始订单金额
safetyOrdAmt	String	加仓单金额
maxSafetyOrds	String	最大自动加仓次数
pxSteps	String	跌多少加仓
pxStepsMult	String	加仓价差倍数
volMult	String	加仓金额倍数
slPct	String	止损目标，如 0.05 表示 5%
slMode	String	止损模式 limit：限价 market：市价
allowReinvest	Boolean	是否复投利润 true 或 false
totalPnl	String	总收益
pnlRatio	String	收益率
fundingFee	String	累计资金费用 仅适用于 contract_dca
investmentAmt	String	累计投入金额
investmentCcy	String	投入数量单位，仅支持 USDT/USDC
arbitragePnL	String	周期套利收益
transferInMargin	String	净转入金额，包括保证金和手动加仓金额 仅适用于 contract_dca
profitSharingRatio	String	分润比例，取值范围 [0, 0.3] 普通订单返回 "" 仅适用于 contract_dca
trackingMode	String	分润设置 sync：同步 async：异步 仅适用于 contract_dca
triggerParams	Array of objects	信号触发参数
> triggerAction	String	触发行为 start：马丁启动 stop：马丁停止
> triggerStrategy	String	触发策略 合约马丁类型：instant：立即触发，price：价格触发，rsi：RSI 指标触发，webhook：WS 信号触发 现货马丁类型：instant：立即触发，rsi：RSI 指标触发
> triggerPx	String	触发价格 仅在 triggerStrategy 为 price 时有效 仅适用于 contract_dca
> triggerCond	String	触发条件 cross_up：上穿 cross_down：下穿 above：上方 below：下方 cross：交叉 仅在 triggerStrategy 为 rsi 时有效
> timePeriod	String	周期，如 14 仅在 triggerStrategy 为 rsi 时有效
> thold	String	阈值，取值 [1, 100] 的整数 仅在 triggerStrategy 为 rsi 时有效
> timeframe	String	K 线种类 3m、5m、15m、30m（m 代表分钟） 1H、4H（H 代表小时） 1D（D 代表天） 仅在 triggerStrategy 为 rsi 时有效
ctVal	String	合约面值 仅适用于 contract_dca
cTime	String	订单创建时间，Unix 时间戳毫秒数，如 1597026383085
uTime	String	订单更新时间，Unix 时间戳毫秒数，如 1597026383085
tradeQuoteCcy	String	指定交易计价货币 仅适用于 spot_dca

GET / 获取马丁策略子订单列表

限速：20次/2s

限速规则：User ID

HTTP请求

GET /api/v5/tradingBot/dca/orders

请求示例

GET /api/v5/tradingBot/dca/orders?algoId=2833925189933756416&algoOrdType=contract_dca

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单 ID
algoOrdType	String	是	策略订单类型 contract_dca：合约马丁委托 spot_dca：现货马丁委托
cycleId	String	否	策略周期 ID
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的 ordId
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的 ordId
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "cycleId": "9876543",
            "ordId": "570627699870375936",
            "avgFillPx": "41500",
            "direction": "long",
            "side": "buy",
            "ordType": "init_order",
            "px": "41000",
            "sz": "10",
            "filledSz": "10",
            "state": "filled",
            "fee": "-0.2",
            "rebate": "0",
            "rebateCcy": "USDT",
            "lever": "3",
            "instId": "BTC-USDT-SWAP",
            "ctVal": "0.01",
            "fillTime": "1597026383085",
            "cTime": "1597026383085",
            "uTime": "1597026383085",
            "tradeQuoteCcy": ""
        }
    ]
}

返回参数

参数名	类型	描述
cycleId	String	策略周期 ID
ordId	String	子订单 ID
avgFillPx	String	子订单平均成交价格
direction	String	持仓方向 合约马丁类型：long：多仓，short：空仓 现货马丁类型：long：做多
side	String	子订单方向 buy：买 sell：卖
ordType	String	子订单类型 init_order：初始订单 safety_order：加仓订单 tp_order：止盈单 sl_order：止损单 manual_add_order：手动加仓单 close_position：平仓单 manual_close_position：手动平仓单
px	String	子订单委托价格
sz	String	子订单委托数量
filledSz	String	子订单成交数量
state	String	子订单状态 live：等待成交 partially_filled：部分成交 filled：完全成交 canceled：撤单成功 cancelling：撤单中
fee	String	子订单手续费数量
rebate	String	子订单返佣数量
rebateCcy	String	子订单返佣币种
lever	String	杠杆倍数 仅适用于 contract_dca
instId	String	产品 ID，如 BTC-USDT-SWAP
ctVal	String	合约面值 仅适用于 contract_dca
fillTime	String	子订单成交时间，Unix 时间戳毫秒数，如 1597026383085
cTime	String	子订单创建时间，Unix 时间戳毫秒数，如 1597026383085
uTime	String	子订单更新时间，Unix 时间戳毫秒数，如 1597026383085
tradeQuoteCcy	String	指定交易计价货币 仅适用于 spot_dca

POST / 手动加仓

限速：20次/2s

限速规则：User ID

HTTP请求

POST /api/v5/tradingBot/dca/orders/manual-buy

请求示例

POST /api/v5/tradingBot/dca/orders/manual-buy
body
{
    "algoId": "2833925189933756416",
    "algoOrdType": "contract_dca",
    "price": "41000",
    "amt": "100"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单 ID
algoOrdType	String	是	策略订单类型 contract_dca：合约马丁委托 spot_dca：现货马丁委托
price	String	是	加仓价格
amt	String	是	增加的投资额
ordType	String	否	订单类型 limit：限价单 market：市价单 仅适用于 spot_dca
tradeQuoteCcy	String	否	指定交易计价货币 仅适用于 spot_dca

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "algoId": "2833925189933756416",
            "algoClOrdId": "",
            "algoOrdType": "contract_dca",
            "tag": "",
            "diffAmount": "100",
            "sCode": "0",
            "sMsg": ""
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	策略订单 ID
algoClOrdId	String	客户端自定义策略单ID
algoOrdType	String	策略订单类型 contract_dca：合约马丁委托 spot_dca：现货马丁委托
tag	String	订单标签
diffAmount	String	手动加仓转入虚拟子账户的资金 仅适用于 contract_dca
sCode	String	事件执行结果的 code，0 代表成功
sMsg	String	事件执行失败时的 msg

POST / 修改复投设置

限速：20次/2s

限速规则：User ID

HTTP请求

POST /api/v5/tradingBot/dca/settings/reinvestment

请求示例

POST /api/v5/tradingBot/dca/settings/reinvestment
body
{
    "algoId": "2833925189933756416",
    "algoOrdType": "contract_dca",
    "allowReinvest": false
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单 ID
algoOrdType	String	是	策略订单类型 contract_dca：合约马丁委托
allowReinvest	Boolean	是	是否复投利润 true 或 false

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "algoId": "2833925189933756416",
            "algoOrdType": "contract_dca",
            "sCode": "0",
            "sMsg": ""
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	策略订单 ID
algoOrdType	String	策略订单类型 contract_dca：合约马丁委托
sCode	String	事件执行结果的 code，0 代表成功
sMsg	String	事件执行失败时的 msg

POST / 修改止盈参数

限速：20次/2s

限速规则：User ID

HTTP请求

POST /api/v5/tradingBot/dca/settings/take-profit

请求示例

POST /api/v5/tradingBot/dca/settings/take-profit
body
{
    "algoId": "2833925189933756416",
    "algoOrdType": "contract_dca",
    "tpPrice": "43500"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单 ID
algoOrdType	String	是	策略订单类型 contract_dca：合约马丁委托
tpPrice	String	是	止盈价格

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "algoId": "2833925189933756416",
            "algoOrdType": "contract_dca",
            "sCode": "0",
            "sMsg": ""
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	策略订单 ID
algoOrdType	String	策略订单类型 contract_dca：合约马丁委托
sCode	String	事件执行结果的 code，0 代表成功
sMsg	String	事件执行失败时的 msg

GET / 获取马丁策略委托持仓

限速：20次/2s

限速规则：User ID

HTTP请求

GET /api/v5/tradingBot/dca/position-details

请求示例

GET /api/v5/tradingBot/dca/position-details?algoId=2833925189933756416&algoOrdType=contract_dca

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单 ID
algoOrdType	String	是	策略订单类型 contract_dca：合约马丁委托 spot_dca：现货马丁委托

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "algoId": "2833925189933756416",
            "algoClOrdId": "",
            "algoOrdType": "contract_dca",
            "instId": "BTC-USDT-SWAP",
            "curCycleld": "3",
            "startTime": "1597026383085",
            "fillManualOrds": "0",
            "fillSafetyOrds": "2",
            "fundingFee": "-0.05",
            "initPx": "43200",
            "notionalUsd": "5000",
            "avgPx": "43000",
            "upl": "12.5",
            "liqPx": "38000",
            "sz": "2",
            "baseSz": "",
            "quoteSz": "",
            "slPx": "40000",
            "tpPx": "45000",
            "fee": "-0.2",
            "tradeQuoteCcy": ""
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	策略订单 ID
algoClOrdId	String	客户端自定义策略单ID
algoOrdType	String	策略订单类型 contract_dca：合约马丁委托 spot_dca：现货马丁委托
instId	String	产品ID，如 BTC-USDT
curCycleld	String	正在运行中的周期 ID
startTime	String	当轮周期开启时间，Unix 时间戳的毫秒数格式，如 1597026383085
fillManualOrds	String	周期手动加仓次数
fillSafetyOrds	String	周期已加仓次数
fundingFee	String	当轮周期累计资金费用 仅适用于 contract_dca
initPx	String	初始订单开仓均价或初始订单成交价
notionalUsd	String	仓位美金价值 仅适用于 contract_dca
avgPx	String	开仓均价
upl	String	未实现收益
liqPx	String	预估强平价 仅适用于 contract_dca
sz	String	合约数量 仅适用于 contract_dca
baseSz	String	当前周期持有的交易币数量 仅适用于 spot_dca
quoteSz	String	当前周期持有的计价币数量 仅适用于 spot_dca
slPx	String	止损价格
tpPx	String	止盈价格
fee	String	累计手续费金额，正数代表平台返佣，负数代表平台扣除
tradeQuoteCcy	String	指定交易计价货币 仅适用于 spot_dca

GET / 获取马丁周期列表

限速：20次/2s

限速规则：User ID

HTTP请求

GET /api/v5/tradingBot/dca/cycle-list

请求示例

GET /api/v5/tradingBot/dca/cycle-list?algoId=2833925189933756416&algoOrdType=contract_dca

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单 ID
algoOrdType	String	是	策略订单类型 contract_dca：合约马丁委托 spot_dca：现货马丁委托
instId	String	否	产品 ID
after	String	否	请求此ID之前（更旧的数据）的分页内容，传的值为对应接口的 cycleId
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的 cycleId
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "algoId": "2833925189933756416",
            "algoClOrdId": "",
            "cycleId": "9876543",
            "currentCycle": true,
            "realizedPnl": "12.5",
            "startTime": "1597026383085",
            "endTime": "",
            "fee": "-0.3",
            "avgPx": "41500",
            "tpPx": "43000"
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	策略订单 ID
algoClOrdId	String	客户端自定义策略单ID
cycleId	String	策略周期 ID
currentCycle	Boolean	是否是当轮周期 true 或 false
realizedPnl	String	已实现盈亏
startTime	String	周期开启时间，Unix 时间戳毫秒数，如 1597026383085
endTime	String	周期结束时间，Unix 时间戳毫秒数，如 1597026383085
fee	String	累计手续费金额，正数代表平台返佣，负数代表平台扣除
avgPx	String	开仓均价
tpPx	String	止盈价格

POST / 增加保证金

限速：20次/2s

限速规则：User ID

HTTP请求

POST /api/v5/tradingBot/dca/margin/add

请求示例

POST /api/v5/tradingBot/dca/margin/add
body
{
    "algoId": "2833925189933756416",
    "amt": "50"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单 ID
amt	String	是	增加的保证金金额

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "algoId": "2833925189933756416",
            "algoOrdType": "contract_dca",
            "sCode": "0",
            "sMsg": ""
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	策略订单 ID
algoOrdType	String	策略订单类型 contract_dca：合约马丁委托
sCode	String	事件执行结果的 code，0 代表成功
sMsg	String	事件执行失败时的 msg

POST / 减少保证金

限速：20次/2s

限速规则：User ID

HTTP请求

POST /api/v5/tradingBot/dca/margin/reduce

请求示例

POST /api/v5/tradingBot/dca/margin/reduce
body
{
    "algoId": "2833925189933756416",
    "amt": "50"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单 ID
amt	String	是	减少的保证金金额

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "algoId": "2833925189933756416",
            "algoOrdType": "contract_dca",
            "sCode": "0",
            "sMsg": ""
        }
    ]
}

返回参数

参数名	类型	描述
algoId	String	策略订单 ID
algoOrdType	String	策略订单类型 contract_dca：合约马丁委托
sCode	String	事件执行结果的 code，0 代表成功
sMsg	String	事件执行失败时的 msg

信号交易

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

POST / 创建信号

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

    ],
    "msg": ""
}

返回参数

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

GET / 查询所有信号

限速：20次/2s

限速规则：User ID

HTTP请求

GET /api/v5/tradingBot/signal/signals

请求示例

GET /api/v5/tradingBot/signal/signals

请求参数

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

返回结果

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

返回参数

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

POST / 创建信号策略

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

参数名	类型	是否必须	描述
signalChanId	String	是	信号ID
includeAll	Boolean	否	是否包含所有USDT 本位永续合约，默认false。 true: 包含 false : 不包含
instIds	String	否	该信号支持的产品ID列表， 多个instId 用逗号分隔。当 includeAll 为true 时， 忽略此参数
lever	String	是	杠杆倍数仅适用于合约信号
investAmt	String	是	投入金额
subOrdType	String	是	1：限价 2：市价 9：由tradingView信号指定
ratio	String	否	限价单的委托价格距离买一/卖一价的百分比。当委托类型为限价时，该字段有效。
entrySettingParam	String	否	进场参数设定
> allowMultipleEntry	String	否	是否允许多次进场，默认允许。 true：允许 false：不允许
> entryType	String	否	单次委托类型 1：单次委托量具体数值将从 TradingView 信号中传入 2：单次委托量为固定数量的保证金 3：单次委托量为固定的合约张数 4：单次委托量基于在收到触发信号时策略中可用保证金的百分比 5：单次委托量基于在创建策略时设置的初始投入保证金的百分比
> amt	String	否	单笔委托量 在单次委托类型是 固定保证金 / 合约张数 下该字段有效
> ratio	Array of objects	否	单笔委托数量百分比 在单次委托类型是 占用保证金比例 / 初始投资比例 下该字段有效
exitSettingParam	String	否	离场参数设定
> tpSlType	String	是	止盈止损类型，该参数用户确定设置止盈止损的触发价格计算的方式 pnl：基于平均持仓成本和预期收益率 price：基于相对于平均持仓成本的涨跌幅
> tpPct	String	否	止盈百分比
> slPct	String	否	止损百分比

返回结果

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

返回参数

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

POST / 停止信号策略

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

        }
    ],
    "msg": ""
}

返回参数

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

POST / 调整保证金

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

POST / 修改止盈止损

限速：20次/2s

限速规则：User ID

HTTP请求

POST /api/v5/tradingBot/signal/amendTPSL

请求示例

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

请求参数

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

返回结果

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

返回参数

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

POST / 设置币对

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

GET / 获取信号策略详情

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

GET / 获取活跃信号策略

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

GET / 获取历史信号策略

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

GET / 获取信号策略持仓

限速：20次/2s

限速规则：User ID

HTTP请求

GET /api/v5/tradingBot/signal/positions

请求示例

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

请求参数

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

返回结果

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

返回参数

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

GET /查看历史持仓信息

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

限速：10次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

POST / 市价仓位全平

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

POST / 下单

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

限速：20次/2s

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

ordType 订单类型，创建新订单时必须指定，您指定的订单类型将影响需要哪些订单参数和撮合系统如何执行您的订单，以下是有效的ordType： 普通委托： limit：限价单，要求指定sz 和 px market：自动以最高买/最低卖价格委托，遵循限价机制

sz 指合约张数。

reduceOnly 只减仓，下单时，此参数设置为 true 时，表示此笔订单具有减仓属性，只会减少持仓数量，不会增加新的持仓仓位 当前只减仓下单张数，加上价格时间优先于当前只减仓下单的只减仓挂单张数总和，不能超过持仓数量 仅适用于合约模式和跨币种保证金模式

POST / 撤单

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

撤单返回sCode等于0不能严格认为该订单已经被撤销，只表示您的撤单请求被系统服务器所接受，撤单结果以者查询订单状态为准

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

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

请求参数

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

返回结果

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

返回参数

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

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

定投

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

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

POST / 定投策略委托下单

限速：20次/2s

限速规则 ：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

POST / 修改定投策略订单

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

POST / 定投策略停止

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

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

限速：20次/2s

限速规则：User ID

HTTP请求

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

请求示例

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

请求参数

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

返回结果

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

返回参数

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

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

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

服务地址

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

请求示例

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

import asyncio

from okx.websocket.WsPrivateAsync import WsPrivateAsync

def callbackFunc(message):
    print(message)

async def main():

    ws = WsPrivateAsync(
        apiKey = "YOUR_API_KEY",
        passphrase = "YOUR_PASSPHRASE",
        secretKey = "YOUR_SECRET_KEY",
        url = "wss://ws.okx.com:8443/ws/v5/business",
        useServerTime=False
    )
    await ws.start()
    args = [{
        "channel": "algo-recurring-buy",
        "instType": "SPOT"
    }]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求参数

参数	类型	是否必须	描述
id	String	否	消息的唯一标识。 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 subscribe unsubscribe
args	Array of objects	是	请求订阅的频道列表
> channel	String	是	频道名 algo-recurring-buy
> instType	String	是	产品类型 SPOT：币币 ANY：全部
> algoId	String	否	策略ID

成功返回示例

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

失败返回示例

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

返回参数

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

推送示例

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

推送数据参数

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

POST / 编辑定投周期

限速：20次/2s

限速规则：User ID

HTTP请求

POST /api/v5/tradingBot/recurring/amend-recurring-time

请求示例

POST /api/v5/tradingBot/recurring/amend-recurring-time
body
{
    "algoId": "2837428373700509696",
    "recurringTimeType": "1",
    "period": "hourly",
    "recurringHour": "8",
    "recurringDay": "1",
    "recurringTime": "11",
    "timeZone": "8"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID
recurringTimeType	String	是	定投周期类型 1：自定义时间 2：立即触发
timeZone	String	是	时区（UTC），取值范围是 [-12,14] 的整数 如 8 表示UTC+8（东8区），北京时间
period	String	是	周期类型 monthly：月 weekly：周 daily：日 hourly：小时
recurringHour	String	可选	小时级别定投的间隔 1/4/8/12 如：1 代表每隔 1 个小时定投 当 period 为 hourly 时必填
recurringDay	String	可选	投资日 当周期类型为 monthly，则取值范围是 [1,28] 的整数 当周期类型为 weekly，则取值范围是 [1,7] 的整数 当周期类型为 daily/hourly，该参数可不填 仅在 recurringTimeType 为 1 时需要传
recurringTime	String	可选	投资时间，取值范围是 [0,23] 的整数 仅在 recurringTimeType 为 1 时需要传

返回结果

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

返回参数

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

POST / 编辑定投金额

限速：20次/2s

限速规则：User ID

HTTP请求

POST /api/v5/tradingBot/recurring/amend-recurring-amount

请求示例

POST /api/v5/tradingBot/recurring/amend-recurring-amount
body
{
    "algoId": "2837428373700509696",
    "amount": "20"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID
amount	String	是	编辑后的定投金额，仅支持创建策略时的投资币种

返回结果

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

返回参数

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

POST / 手动加仓

限速：20次/2s

限速规则：User ID

HTTP请求

POST /api/v5/tradingBot/recurring/add-investment

请求示例

POST /api/v5/tradingBot/recurring/add-investment
body
{
    "algoId": "2837428373700509696",
    "amount": "20"
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID
amount	String	是	加仓投入金额，仅支持创建策略时的投资币种

返回结果

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

返回参数

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

POST / 暂停定投策略

限速：20次/2s

限速规则：User ID

HTTP请求

POST /api/v5/tradingBot/recurring/pause

请求示例

POST /api/v5/tradingBot/recurring/pause
body
{
    "algoId": "2837428373700509696"
}

请求参数

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

返回结果

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

返回参数

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

POST / 重启定投策略

限速：20次/2s

限速规则：User ID

HTTP请求

POST /api/v5/tradingBot/recurring/restart

请求示例

POST /api/v5/tradingBot/recurring/restart
body
{
    "algoId": "2837428373700509696"
}

请求参数

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

返回结果

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

返回参数

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

POST / 编辑价格区间

限速：20次/2s

限速规则：User ID

HTTP请求

POST /api/v5/tradingBot/recurring/amend-price-range

请求示例

POST /api/v5/tradingBot/recurring/amend-price-range
body
{
    "algoId": "2837428373700509696",
    "recurringList": [
        {
            "ccy": "BTC",
            "minPx": "80000",
            "maxPx": "120000"
        }
    ]
}

请求参数

参数名	类型	是否必须	描述
algoId	String	是	策略订单ID
recurringList	Array	是	价格区间设置，币种必须在策略定投币种范围内
>ccy	String	是	定投币种
>minPx	String	是	价格区间最低价，"" 代表没有限制
>maxPx	String	是	价格区间最高价，"" 代表没有限制

返回结果

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

返回参数

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

跟单

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

1. 申请成为带单交易员

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

2. 带单合约

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

3. 开仓

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

4. 平仓

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

5. 止盈止损

• 可以通过带单仓位止盈止损接口或者策略委托下单接口设置止盈止损；
• 带单仓位止盈止损接口，一次仅为一个带单仓位设置。带单ID（subPosId）为必填参数，需要通过获取当前带单接口获取。
• 策略委托下单接口，为当前产品下指定的仓位（如：开平模式下，全仓模式下的多仓或空仓）设置，可能包含多个带单；

GET / 获取当前带单

获取当前未平仓的带单仓位。

按照开仓时间倒序排列。

限速：20次/2s

限速规则：User ID

HTTP请求

GET /api/v5/copytrading/current-subpositions

请求示例

GET /api/v5/copytrading/current-subpositions?instId=BTC-USDT-SWAP

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约 默认返回所有业务线的信息
instId	String	否	产品ID ，如BTC-USDT-SWAP
after	String	否	请求此id之前（更旧的数据）的分页内容，传的值为对应接口的subPosId
before	String	否	请求此id之后（更新的数据）的分页内容，传的值为对应接口的subPosId
limit	String	否	分页返回的结果集数量，最大为500，不填默认返回500条

返回结果

{
    "code": "0",
    "data": [
        {
            "algoId": "",
            "ccy": "USDT",
            "instId": "BTC-USDT-SWAP",
            "instType": "SWAP",
            "lever": "3",
            "margin": "12.6417",
            "markPx": "38205.8",
            "mgnMode": "isolated",
            "openAvgPx": "37925.1",
            "openOrdId": "",
            "openTime": "1701231120479",
            "posSide": "net",
            "slOrdPx": "",
            "slTriggerPx": "",
            "subPos": "1",
            "subPosId": "649945658862370816",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "uniqueCode": "25CD5A80241D6FE6",
            "upl": "0.2807",
            "uplRatio": "0.0222042921442527",
            "availSubPos": "1"
        },
        {
            "algoId": "",
            "ccy": "USDT",
            "instId": "BTC-USDT-SWAP",
            "instType": "SWAP",
            "lever": "3",
            "margin": "12.6263333333333333",
            "markPx": "38205.8",
            "mgnMode": "isolated",
            "openAvgPx": "37879",
            "openOrdId": "",
            "openTime": "1701225074786",
            "posSide": "net",
            "slOrdPx": "",
            "slTriggerPx": "",
            "subPos": "1",
            "subPosId": "649920301388038144",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "uniqueCode": "25CD5A80241D6FE6",
            "upl": "0.3268",
            "uplRatio": "0.0258824150584758",
            "availSubPos": "1"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品ID
subPosId	String	带单仓位ID
posSide	String	持仓方向 long：开平仓模式开多 short：开平仓模式开空 net：买卖模式（subPos为正代表开多，subPos为负代表开空）
mgnMode	String	保证金模式，isolated：逐仓 ；cross：全仓
lever	String	杠杆倍数
openOrdId	String	交易员开仓订单号，仅适用于带单仓位
openAvgPx	String	开仓均价
openTime	String	开仓时间
subPos	String	持仓张数
tpTriggerPx	String	止盈触发价
slTriggerPx	String	止损触发价
algoId	String	止盈止损委托单ID
instType	String	产品类型 SPOT：币币 SWAP：永续合约
tpOrdPx	String	止盈委托价，市价时为-1
slOrdPx	String	止损委托价，市价时为-1
margin	String	保证金
upl	String	未实现收益
uplRatio	String	未实现收益率
markPx	String	最新标记价格，仅适用于合约
uniqueCode	String	交易员唯一标识代码
ccy	String	保证金币种
availSubPos	String	可平张数/币数

GET / 获取历史带单

获取最近三个月的已经平仓的带单仓位，按照subPosId倒序排序。

限速：20次/2s

限速规则：User ID

HTTP请求

GET /api/v5/copytrading/subpositions-history

请求示例

GET /api/v5/copytrading/subpositions-history?instId=BTC-USDT-SWAP

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约 默认返回所有业务线的信息
instId	String	否	产品ID ，如BTC-USDT-SWAP
after	String	否	请求此id之前（更旧的数据）的分页内容，传的值为对应接口的subPosId
before	String	否	请求此id之后（更新的数据）的分页内容，传的值为对应接口的subPosId
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "closeAvgPx": "37617.5",
            "closeTime": "1701188587950",
            "instId": "BTC-USDT-SWAP",
            "instType": "SWAP",
            "lever": "3",
            "margin": "37.41",
            "markPx": "38203.4",
            "mgnMode": "isolated",
            "openAvgPx": "37410",
            "openOrdId": "",
            "openTime": "1701184638702",
            "pnl": "0.6225",
            "pnlRatio": "0.0166399358460306",
            "posSide": "net",
            "profitSharingAmt": "0.0407967",
            "subPos": "3",
            "closeSubPos": "2",
            "type": "1",
            "subPosId": "649750700213698561",
            "uniqueCode": "25CD5A80241D6FE6"
        },
        {
            "ccy": "USDT",
            "closeAvgPx": "37617.5",
            "closeTime": "1701188587950",
            "instId": "BTC-USDT-SWAP",
            "instType": "SWAP",
            "lever": "3",
            "margin": "24.94",
            "markPx": "38203.4",
            "mgnMode": "isolated",
            "openAvgPx": "37410",
            "openOrdId": "",
            "openTime": "1701184635381",
            "pnl": "0.415",
            "pnlRatio": "0.0166399358460306",
            "posSide": "net",
            "profitSharingAmt": "0.0271978",
            "subPos": "2",
            "closeSubPos": "2",
            "type": "2",
            "subPosId": "649750686292803585",
            "uniqueCode": "25CD5A80241D6FE6"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品ID
subPosId	String	带单仓位ID
posSide	String	持仓方向 long：开平仓模式开多 short：开平仓模式开空 net：买卖模式（subPos为正代表开多，subPos为负代表开空）
mgnMode	String	保证金模式，isolated：逐仓 ；cross：全仓
lever	String	杠杆倍数
openOrdId	String	交易员开仓订单号，仅适用于带单仓位
openAvgPx	String	开仓均价
openTime	String	开仓时间
subPos	String	持仓张数
closeTime	String	平仓时间(最近一次平仓的时间)
closeAvgPx	String	平仓均价
pnl	String	收益额
pnlRatio	String	收益率
instType	String	产品类型 SPOT：币币 SWAP：永续合约
margin	String	保证金
ccy	String	币种
markPx	String	最新标记价格，仅适用于合约
uniqueCode	String	交易员唯一标识代码
profitSharingAmt	String	跟单分润额，仅适用于跟单，已经废弃。
closeSubPos	String	已平仓量
type	String	平仓类型 1：部分平仓; 2：完全平仓;

POST / 带单或跟单仓位止盈止损

为当前未平仓的带单仓位设置止盈止损。

限速：20次/2s

限速规则：User ID

HTTP请求

POST /api/v5/copytrading/algo-order

请求示例

POST /api/v5/copytrading/algo-order
body
{
    "subPosId": "518541406042591232",
    "tpTriggerPx": "10000"
}

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约，默认值
subPosId	String	是	带单或者跟单仓位ID
tpTriggerPx	String	可选	止盈触发价，tpTriggerPx 和 slTriggerPx 至少需要填写一个 如果止盈触发价为0，那代表删除止盈。
slTriggerPx	String	可选	止损触发价， 如果止损触发价为0，那代表删除止损
tpOrdPx	String	否	止盈委托价 委托价格为-1时，执行市价止盈，默认为市价止盈 仅适用于现货交易员
slOrdPx	String	否	止损委托价 委托价格为-1时，执行市价止损，默认为市价止损 仅适用于现货交易员
tpTriggerPxType	String	否	止盈触发价类型 last：最新价格 index：指数价格 mark：标记价格 默认为last
slTriggerPxType	String	否	止损触发价类型 last：最新价格 index：指数价格 mark：标记价格 默认为last
tag	String	否	订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。
subPosType	String	否	数据的类型 lead: 带单，默认值 copy: 跟单

返回结果

{
    "code": "0",
    "data": [
        {
            "subPosId": "518560559046594560",
            "tag":""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
subPosId	String	带单或者跟单仓位ID
tag	String	订单标签

POST / 平仓带单

一次仅可平仓一个带单仓位。

subPosId 为必填参数，需要通过交易员获取当前带单接口获取。

限速：20次/2s

限速规则：User ID

HTTP请求

POST /api/v5/copytrading/close-subposition

请求示例

POST /api/v5/copytrading/close-subposition
body
{
    "subPosId": "518541406042591232"
}

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约，默认值
subPosId	String	是	带单仓位ID
tag	String	否	订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。
ordType	String	否	订单类型 market：市价单 limit：限价单 默认为市价单
px	String	否	委托价格，仅适用于limit类型的订单，且仅适用于现货交易员 委托价格为 0 代表撤销挂单 已经设置了限价单，仍为该条目设置价格时，视为改单。

返回结果

{
    "code": "0",
    "data": [
        {
            "subPosId": "518560559046594560",
            "tag":""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
subPosId	String	带单仓位ID
tag	String	订单标签

GET / 获取带单产品

获取平台支持带单的产品，以及获取带单员正在带单的产品

限速：5次/2s

限速规则：User ID

HTTP请求

GET /api/v5/copytrading/instruments

请求示例

GET /api/v5/copytrading/instruments

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约，默认值

返回结果

{
    "code": "0",
    "data": [
        {
            "enabled": true,
            "instId": "BTC-USDT-SWAP"
        },
        {
            "enabled": true,
            "instId": "ETH-USDT-SWAP"
        },
        {
            "enabled": false,
            "instId": "ADA-USDT-SWAP"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品ID
enabled	Boolean	是否设置了带单 true 或 false

POST / 交易员修改带单产品

交易员修改带单产品的设置。初始带单产品在申请带单交易员时进行设置。

非带单产品修改为带单产品时，该次请求中所有的非带单产品不能有持仓或者挂单。

限速：5次/2s

限速规则：User ID

HTTP请求

POST /api/v5/copytrading/set-instruments

请求示例

POST /api/v5/copytrading/set-instruments
body
{
    "instId": "BTC-USDT-SWAP,ETH-USDT-SWAP"
}

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约，默认值
instId	String	是	产品ID，如 BTC-USDT-SWAP，多个产品用半角逗号隔开

如果进行多个产品带单，instId传值需要包括所有将要带单的产品，因为当前请求设置成功后，之前的设置会被覆盖掉

返回结果

{
    "code": "0",
    "data": [
        {
            "enabled": true,
            "instId": "BTC-USDT-SWAP"
        },
        {
            "enabled": true,
            "instId": "ETH-USDT-SWAP"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品id， 如 BTC-USDT-SWAP
enabled	Boolean	true 或 false true 代表设置成功 false 代表设置失败

GET / 交易员历史分润明细

交易员获取最近三个月的分润明细。

限速：5次/2s

限速规则：User ID

HTTP请求

GET /api/v5/copytrading/profit-sharing-details

请求示例

GET /api/v5/copytrading/profit-sharing-details?limit=2

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约 默认返回所有业务线的信息
after	String	否	请求此id之前（更旧的数据）的分页内容，传的值为对应接口的profitSharingId
before	String	否	请求此id之后（更新的数据）的分页内容，传的值为对应接口的profitSharingId
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "nickName": "Potato",
            "profitSharingAmt": "0.00536",
            "profitSharingId": "148",
            "portLink": "",
            "ts": "1723392000000",
            "instType": "SWAP"
        },
        {
            "ccy": "USDT",
            "nickName": "Apple",
            "profitSharingAmt": "0.00336",
            "profitSharingId": "20",
            "portLink": "",
            "ts": "1723392000000",
            "instType": "SWAP"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	分润币种
profitSharingAmt	String	分润额，没有分润时，默认返回0
nickName	String	跟单人的昵称
profitSharingId	String	分润ID
instType	String	产品类型 SPOT：币币 SWAP：永续合约
portLink	String	跟单员头像的链接地址
ts	String	分润时间

GET / 交易员历史分润汇总

交易员获取自入驻平台以来，累计获得的总分润金额。

限速：5次/2s

限速规则：User ID

HTTP请求

GET /api/v5/copytrading/total-profit-sharing

请求示例

GET /api/v5/copytrading/total-profit-sharing

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约 默认返回所有业务线的信息

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "totalProfitSharingAmt": "0.6584928",
            "instType": "SWAP"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	分润币种
totalProfitSharingAmt	String	历史分润汇总
instType	String	产品类型 SPOT：币币 SWAP：永续合约

GET / 交易员待分润明细

交易员获取预计在下一个周期分到的分润金额明细。

当有跟单仓位平仓时，待分润明细会进行更新。

限速：5次/2s

限速规则：User ID

HTTP请求

GET /api/v5/copytrading/unrealized-profit-sharing-details

请求示例

GET /api/v5/copytrading/unrealized-profit-sharing-details

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SPOT：币币 SWAP：永续合约 默认返回所有业务线的信息

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "nickName": "Potato",
            "portLink": "",
            "ts": "1669901824779",
            "unrealizedProfitSharingAmt": "0.455472",
            "instType": "SWAP"
        },
        {
            "ccy": "USDT",
            "nickName": "Apple",
            "portLink": "",
            "ts": "1669460210113",
            "unrealizedProfitSharingAmt": "0.033608",
            "instType": "SWAP"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	分润币种，如：USDT
unrealizedProfitSharingAmt	String	待分润额
nickName	String	跟单人昵称
instType	String	产品类型 SPOT：币币 SWAP：永续合约
portLink	String	跟单员头像的链接地址
ts	String	数据更新时间

GET / 交易员待分润汇总

交易员获取待分润汇总。

限速：5次/2s

限速规则：User ID

HTTP请求

GET /api/v5/copytrading/total-unrealized-profit-sharing

请求示例

GET /api/v5/copytrading/total-unrealized-profit-sharing

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值

返回结果

{
    "code": "0",
    "data": [
        {
            "profitSharingTs": "1705852800000",
            "totalUnrealizedProfitSharingAmt": "0.114402985553185"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
profitSharingTs	String	当前周期待分润总额的结算时间，Unix时间戳的毫秒数格式，如 1597026383085
totalUnrealizedProfitSharingAmt	String	待分润总额

POST / 修改分润比例

修改分润比例

限速：5次/2s

限速规则：User ID

HTTP请求

POST /api/v5/copytrading/amend-profit-sharing-ratio

请求示例

POST /api/v5/copytrading/amend-profit-sharing-ratio
body
{
    "instType": "SWAP",
    "profitSharingRatio": "0.1"
}

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值
profitSharingRatio	String	是	分润比例。0.1 代表10%

返回结果

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

返回参数

参数名	类型	描述
result	Boolean	设置结果 true：设置成功

GET / 查看账户配置信息

获取跟单交易和带单交易相关的账户配置信息

限速：5次/2s

限速规则：User ID

HTTP请求

GET /api/v5/copytrading/config

请求示例

GET /api/v5/copytrading/config

请求参数

无

返回结果

{
    "code": "0",
    "data": [
        {
            "details": [
                {
                    "copyTraderNum": "1",
                    "instType": "SWAP",
                    "maxCopyTraderNum": "100",
                    "profitSharingRatio": "0",
                    "roleType": "1"
                },
                {
                    "copyTraderNum": "",
                    "instType": "SPOT",
                    "maxCopyTraderNum": "",
                    "profitSharingRatio": "",
                    "roleType": "0"
                }
            ],
            "nickName": "155***9957",
            "portLink": "",
            "uniqueCode": "5506D3681454A304"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
uniqueCode	String	交易员唯一标识代码
nickName	String	昵称
portLink	String	头像的链接地址
details	Array of objects	详情
> instType	String	产品类型 SPOT: 币币 SWAP: 永续合约
> roleType	String	用户角色 0：普通用户 1：带单者 2：跟单者
> profitSharingRatio	String	分润比例，仅适用于带单员，0.1 代表 10%，否则为""
> maxCopyTraderNum	String	最大跟单人数，仅适用于带单员
> copyTraderNum	String	当前跟单人数，仅适用于带单员

POST / 首次跟单设置

跟随某一交易员的首次设置，停止跟单后需先进行首次设置；

限速：5次/2s

限速规则：User ID

HTTP请求

POST /api/v5/copytrading/first-copy-settings

请求示例

POST /api/v5/copytrading/first-copy-settings
body
{
    "instType": "SWAP",
    "uniqueCode": "25CD5A80241D6FE6",
    "copyMgnMode": "cross",
    "copyInstIdType": "copy",
    "copyMode": "ratio_copy",
    "copyRatio": "1",
    "copyTotalAmt": "500",
    "subPosCloseType": "copy_close"
}

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。 数字加字母组合 长度为16或18位，如：213E8C92DC61EFAC（16位）或381749205163847291（18位）
copyMgnMode	String	是	跟单时的保证金模式 cross: 全仓； isolated: 逐仓； copy: 跟随带单员
copyInstIdType	String	是	跟单合约设置的类型 custom: 用户自定义，instId 必填； copy: 跟随交易员，自动同步交易员的合约变更
instId	String	可选	产品 ID 可传入多条，以逗号区分
copyMode	String	否	跟单模式 fixed_amount: 固定金额跟单，copyAmt必填； ratio_copy: 比例跟单，copyRatio必填 默认是fixed_amount
copyTotalAmt	String	是	跟单该交易员投入的最大跟单金额，单位为USDT。 超过该金额后将不再触发跟单行为
copyAmt	String	可选	单笔跟随金额，单位为USDT
copyRatio	String	可选	跟单比例
tpRatio	String	否	单笔止盈百分比，0.1 代表10%
slRatio	String	否	单笔止损百分比，0.1 代表10%
slTotalAmt	String	否	跟单止损总金额，单位为USDT 净损失达到该金额时，将自动解除跟单关系
subPosCloseType	String	是	剩余仓位处理方式 market_close: 立即市价全平 copy_close：跟随交易员平仓 manual_close: 手动处理 默认为 copy_close
tag	String	否	订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。

返回结果

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

返回参数

参数名	类型	描述
result	Boolean	设置结果 true：设置成功

POST / 修改跟单设置

跟随某一交易员，完成首次设置后，修改设置时，需要使用该接口

限速：5次/2s

限速规则：User ID

HTTP请求

POST /api/v5/copytrading/amend-copy-settings

请求示例

POST /api/v5/copytrading/amend-copy-settings
body
{
    "instType": "SWAP",
    "uniqueCode": "25CD5A80241D6FE6",
    "copyMgnMode": "cross",
    "copyInstIdType": "copy",
    "copyMode": "ratio_copy",
    "copyRatio": "1",
    "copyTotalAmt": "500",
    "subPosCloseType": "copy_close"
}

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。 数字加字母组合 长度为16或18位，如：213E8C92DC61EFAC（16位）或381749205163847291（18位）
copyMgnMode	String	是	跟单时的保证金模式 cross: 全仓； isolated: 逐仓； copy: 跟随带单员
copyInstIdType	String	是	跟单合约设置的类型 custom: 用户自定义，instId 必填； copy: 跟随交易员，自动同步交易员的合约变更
instId	String	可选	产品 ID 可传入多条，以逗号区分
copyMode	String	否	跟单模式 fixed_amount: 固定金额跟单，copyAmt必填； ratio_copy: 比例跟单，copyRatio必填 默认是fixed_amount
copyTotalAmt	String	是	跟单该交易员投入的最大跟单金额，单位为USDT。 超过该金额后将不再触发跟单行为
copyAmt	String	可选	单笔跟随金额，单位为USDT
copyRatio	String	可选	跟单比例
tpRatio	String	否	单笔止盈百分比，0.1 代表10%
slRatio	String	否	单笔止损百分比，0.1 代表10%
slTotalAmt	String	否	跟单止损总金额，单位为USDT 净损失达到该金额时，将自动解除跟单关系
subPosCloseType	String	是	剩余仓位处理方式 market_close: 立即市价全平 copy_close：跟随交易员平仓 manual_close: 手动处理 默认为 copy_close
tag	String	否	订单标签 字母（区分大小写）与数字的组合，可以是纯字母、纯数字，且长度在1-16位之间。

返回结果

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

返回参数

参数名	类型	描述
result	Boolean	设置结果 true：设置成功

POST / 停止跟单

该接口用来停止跟单

限速：5次/2s

限速规则：User ID

HTTP请求

POST /api/v5/copytrading/stop-copy-trading

请求示例

POST /api/v5/copytrading/stop-copy-trading
body
{
    "instType": "SWAP",
    "uniqueCode": "25CD5A80241D6FE6",
    "subPosCloseType": "manual_close"
}

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。 数字加字母组合 长度为16或18位，如：213E8C92DC61EFAC（16位）或381749205163847291（18位）
subPosCloseType	String	可选	剩余仓位处理方式，有相关的跟单条目时必填 market_close: 立即市价全平 copy_close：跟随交易员平仓 manual_close: 手动处理

返回结果

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

返回参数

参数名	类型	描述
result	Boolean	设置结果 true：设置成功

GET / 获取跟单设置

获取针对某个交易员的跟单设置

限速：5次/2s

限速规则：User ID

HTTP请求

GET /api/v5/copytrading/copy-settings

请求示例

GET /api/v5/copytrading/copy-settings?instType=SWAP&uniqueCode=25CD5A80241D6FE6

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。 数字加字母组合 长度为16或18位，如：213E8C92DC61EFAC（16位）或381749205163847291（18位）

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "copyAmt": "",
            "copyInstIdType": "copy",
            "copyMgnMode": "isolated",
            "copyMode": "ratio_copy",
            "copyRatio": "1",
            "copyState": "1",
            "copyTotalAmt": "500",
            "instIds": [
                {
                    "enabled": "1",
                    "instId": "ADA-USDT-SWAP"
                },
                {
                    "enabled": "1",
                    "instId": "YFII-USDT-SWAP"
                }
            ],
            "slRatio": "",
            "slTotalAmt": "",
            "subPosCloseType": "copy_close",
            "tpRatio": "",
            "tag": ""
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
copyMode	String	跟单模式 fixed_amount: 固定金额跟单 ratio_copy: 比例跟单
copyAmt	String	单笔跟随金额，单位为 USDT
copyRatio	String	跟单比例
copyTotalAmt	String	跟单该交易员投入的最大跟单金额，单位为USDT
tpRatio	String	单笔止盈百分比，0.1 代表10%
slRatio	String	单笔止损百分比，0.1 代表10%
copyInstIdType	String	跟单合约设置的类型 custom: 用户自定义 copy: 跟随交易员，自动同步交易员的合约变更
instIds	Array of objects	可跟单的合约列表，会返回交易员所有带单合约
> instId	String	产品 ID
> enabled	String	是否在跟单 0: 没有在跟单 1: 在跟单
slTotalAmt	String	跟单止损总金额，单位为 USDT
subPosCloseType	String	剩余仓位处理方式 market_close: 立即市价全平 copy_close：跟随交易员平仓 manual_close: 手动处理
copyMgnMode	String	跟单时的保证金模式 cross: 全仓； isolated: 逐仓； copy: 跟随带单员
ccy	String	保证金币种
copyState	String	当前跟单状态 0: 没在跟单 1：在跟单
tag	String	订单标签

GET / 获取我的交易员

获取当前跟随的交易员

限速：5次/2s

限速规则：User ID

HTTP请求

GET /api/v5/copytrading/current-lead-traders

请求示例

GET /api/v5/copytrading/current-lead-traders?instType=SWAP

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值

返回结果

{
    "code": "0",
    "data": [
        {
            "beginCopyTime": "1701224821936",
            "ccy": "USDT",
            "copyTotalAmt": "500",
            "copyTotalPnl": "0",
            "leadMode": "public",
            "margin": "1.89395",
            "nickName": "Trader9527",
            "portLink": "",
            "profitSharingRatio": "0.08",
            "todayPnl": "0",
            "uniqueCode": "25CD5A80241D6FE6",
            "upl": "0"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
portLink	String	头像
nickName	String	昵称
margin	String	跟单交易占用的保证金
copyTotalAmt	String	跟单员设置的跟单总金额
copyTotalPnl	String	跟单总收益 (USDT)
uniqueCode	String	带单员唯一标识代码
ccy	String	保证金币种
profitSharingRatio	String	分润比例，0.1 代表 10%
beginCopyTime	String	跟单开始时间，Unix时间戳的毫秒数格式，如 1597026383085
upl	String	未实现盈亏
todayPnl	String	今日已实现收益
leadMode	String	带单模式 public: 公开模式 private: 私域模式

GET / 获取跟单配置信息

公共接口，获取跟单设置时的参数配置信息

限速：5次/2s

限速规则：IP

HTTP请求

GET /api/v5/copytrading/public-config

请求示例

GET /api/v5/copytrading/public-config?instType=SWAP

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值

返回结果

{
    "code": "0",
    "data": [
        {
            "maxCopyAmt": "1000",
            "maxCopyRatio": "100",
            "maxCopyTotalAmt": "30000",
            "maxSlRatio": "0.75",
            "maxTpRatio": "1.5",
            "minCopyAmt": "20",
            "minCopyRatio": "0.01"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
maxCopyAmt	String	固定金额跟单时，单笔最大跟随金额
minCopyAmt	String	固定金额跟单时，单笔最小跟随金额
maxCopyTotalAmt	String	最大跟单金额（针对单个带单员），最小跟单金额同minCopyAmt
minCopyRatio	String	比例跟单的单笔最小比率
maxCopyRatio	String	比例跟单的单笔最大比率
maxTpRatio	String	单笔最大止盈比率，最小为 0
maxSlRatio	String	单笔最大止损比率，最小为 0

GET / 获取交易员排名

公共接口，获取交易员排名信息。

限速：5次/2s

限速规则：IP

HTTP请求

GET /api/v5/copytrading/public-lead-traders

请求示例

GET /api/v5/copytrading/public-lead-traders?instType=SWAP

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值
sortType	String	否	排名类型 overview: 综合排序，默认值 pnl: 按照交易员收益额排序 aum: 按照带单规模排序 win_ratio: 胜率 pnl_ratio: 收益率 current_copy_trader_pnl: 当前跟单人的收益额
state	String	否	交易员的状态 0: 所有交易员，默认值，包括有空缺和没有空缺 1: 有空缺的交易员
minLeadDays	String	否	最短带单时长 1: 7 天 2: 30 天 3: 90 天 4: 180天
minAssets	String	否	交易员资产范围的最小值，单位为 USDT
maxAssets	String	否	交易员资产范围的最大值，单位为 USDT
minAum	String	否	带单规模的最小值，单位为 USDT
maxAum	String	否	带单规模的最大值，单位为 USDT
dataVer	String	否	排名数据的版本，14 位数字，如：20231010182400，主要在分页时使用 每10分钟生成一版，仅保留最新的5个版本 默认使用最近的版本；不存在时不会报错，会使用最近的版本。
page	String	否	查询页数
limit	String	否	分页返回的结果集数量，最大为 20，不填默认返回 10 条

返回结果

{
    "code": "0",
    "data": [
        {
            "dataVer": "20231129213200",
            "ranks": [
                {
                    "accCopyTraderNum": "3536",
                    "aum": "1509265.3238761567721365",
                    "ccy": "USDT",
                    "copyState": "0",
                    "copyTraderNum": "999",
                    "leadDays": "156",
                    "maxCopyTraderNum": "1000",
                    "nickName": "Crypto to the moon",
                    "pnl": "48805.1105999999972258",
                    "pnlRatio": "1.6898",
                    "pnlRatios": [
                        {
                            "beginTs": "1701187200000",
                            "pnlRatio": "1.6744"
                        },
                        {
                            "beginTs": "1700755200000",
                            "pnlRatio": "1.649"
                        }
                    ],
                    "portLink": "https://static.okx.com/cdn/okex/users/headimages/20230624/f49a683aaf5949ea88b01bbc771fb9fc",
                    "traderInsts": [
                        "ICP-USDT-SWAP",
                        "MINA-USDT-SWAP"

                    ],
                    "uniqueCode": "540D011FDACCB47A",
                    "winRatio": "0.6957"
                }
            ],
            "totalPage": "1"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
dataVer	String	排名数据的版本
totalPage	String	总的页数
ranks	Array of objects	交易员排名信息
> aum	String	带单规模，单位为USDT
> copyState	String	当前跟单状态 0: 没在跟单 1：在跟单
> maxCopyTraderNum	String	最大跟单人数
> copyTraderNum	String	跟单人数
> accCopyTraderNum	String	累计跟单人数
> portLink	String	头像
> nickName	String	昵称
> ccy	String	保证金币种
> uniqueCode	String	交易员唯一标识码
> winRatio	String	胜率，0.1 代表 10%
> leadDays	String	带单天数
> traderInsts	Array of strings	交易员带单的合约列表
> pnl	String	近90日交易员收益，单位为 USDT
> pnlRatio	String	近90日交易员收益率，0.1 代表 10%
> pnlRatios	Array of objects	收益率数据
>> beginTs	String	当天收益率的开始时间
>> pnlRatio	String	当天收益率

GET / 获取交易员收益周表现

公共接口，获取交易员最近12周的收益表现，按时间倒序返回

限速：5次/2s

限速规则：IP

HTTP请求

GET /api/v5/copytrading/public-weekly-pnl

请求示例

GET /api/v5/copytrading/public-weekly-pnl?instType=SWAP&uniqueCode=D9ADEAB33AE9EABD

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。 数字加字母组合 长度为16或18位，如：213E8C92DC61EFAC（16位）或381749205163847291（18位）

返回结果

{
    "code": "0",
    "data": [
        {
            "beginTs": "1701014400000",
            "pnl": "-2.8428",
            "pnlRatio": "-0.0106"
        },
        {
            "beginTs": "1700409600000",
            "pnl": "81.8446",
            "pnlRatio": "0.3036"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
beginTs	String	当周收益率的开始时间
pnl	String	当周收益额
pnlRatio	String	当周收益率

GET / 获取交易员收益日表现

公共接口，获取交易员每日的收益表现，按时间倒序返回

限速：5次/2s

限速规则：IP

HTTP请求

GET /api/v5/copytrading/public-pnl

请求示例

GET /api/v5/copytrading/public-pnl?instType=SWAP&uniqueCode=D9ADEAB33AE9EABD&lastDays=1

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。 数字加字母组合 长度为16或18位，如：213E8C92DC61EFAC（16位）或381749205163847291（18位）
lastDays	String	是	最近天数 1: 近 7 天 2: 近 30 天 3: 近 90 天， 4: 近 365 天

返回结果

{
    "code": "0",
    "data": [
        {
            "beginTs": "1701100800000",
            "pnl": "97.3309",
            "pnlRatio": "0.3672"
        },
        {
            "beginTs": "1701014400000",
            "pnl": "96.7755",
            "pnlRatio": "0.3651"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
beginTs	String	当天开始时间
pnl	String	累计收益额
pnlRatio	String	累计收益率

GET / 获取交易员带单情况

公共接口，获取交易员带单情况。

限速：5次/2s

限速规则：IP

HTTP请求

GET /api/v5/copytrading/public-stats

请求示例

GET /api/v5/copytrading/public-stats?instType=SWAP&uniqueCode=D9ADEAB33AE9EABD&lastDays=1

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。 数字加字母组合 长度为16或18位，如：213E8C92DC61EFAC（16位）或381749205163847291（18位）
lastDays	String	是	最近天数 1: 近 7 天 2: 近 30 天 3: 近 90 天， 4: 近 365 天

返回结果

{
    "code": "0",
    "data": [
        {
            "avgSubPosNotional": "213.1038",
            "ccy": "USDT",
            "curCopyTraderPnl": "96.8071",
            "investAmt": "265.095252476476294",
            "lossDays": "1",
            "profitDays": "2",
            "winRatio": "0.6667"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
winRatio	String	胜率
profitDays	String	盈利天数
lossDays	String	亏损天数
curCopyTraderPnl	String	当前跟随者收益 (USDT)
avgSubPosNotional	String	平均仓位价值 (USDT)
investAmt	String	带单本金 (USDT)
ccy	String	保证金币种

GET / 获取交易员币种偏好

公共接口，获取交易员币种偏好，返回结果按 ratio 从大到小排序

限速：5次/2s

限速规则：IP

HTTP请求

GET /api/v5/copytrading/public-preference-currency

请求示例

GET /api/v5/copytrading/public-preference-currency?instType=SWAP&uniqueCode=CB4594A3BB5D3538

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。 数字加字母组合 长度为16或18位，如：213E8C92DC61EFAC（16位）或381749205163847291（18位）

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "ETH",
            "ratio": "0.8881"
        },
        {
            "ccy": "BTC",
            "ratio": "0.0666"
        },
        {
            "ccy": "YFII",
            "ratio": "0.0453"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
ccy	String	币种
ratio	String	占比，0.1 代表 10%

GET / 获取交易员当前带单

公共接口，获取交易员当前带单。

限速：5次/2s

限速规则：IP

HTTP请求

GET /api/v5/copytrading/public-current-subpositions

请求示例

GET /api/v5/copytrading/public-current-subpositions?instType=SWAP&uniqueCode=D9ADEAB33AE9EABD

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值
uniqueCode	String	是	交易员唯一标识码
after	String	否	请求此id之前（更旧的数据）的分页内容，传的值为对应接口的subPosId
before	String	否	请求此id之后（更新的数据）的分页内容，传的值为对应接口的subPosId
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "instId": "ETH-USDT-SWAP",
            "instType": "SWAP",
            "lever": "5",
            "margin": "16.23304",
            "markPx": "2027.31",
            "mgnMode": "isolated",
            "openAvgPx": "2029.13",
            "openTime": "1701144639417",
            "posSide": "short",
            "subPos": "4",
            "subPosId": "649582930998104064",
            "uniqueCode": "D9ADEAB33AE9EABD",
            "upl": "0.0728",
            "uplRatio": "0.0044846806266725"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品ID
subPosId	String	带单仓位ID
posSide	String	持仓方向 long：开平仓模式开多 short：开平仓模式开空 net：买卖模式（subPos为正代表开多，subPos为负代表开空）
mgnMode	String	保证金模式，isolated：逐仓 ；cross：全仓
lever	String	杠杆倍数
openAvgPx	String	开仓均价
openTime	String	开仓时间
subPos	String	持仓张数
instType	String	产品类型 SPOT：币币 SWAP：永续合约
margin	String	保证金
upl	String	未实现收益
uplRatio	String	未实现收益率
markPx	String	最新标记价格，仅适用于合约
uniqueCode	String	交易员唯一标识代码
ccy	String	币种

GET / 获取交易员历史带单

公共接口，获取交易员最近三个月的已经平仓的带单仓位，按照subPosId倒序排序。

限速：5次/2s

限速规则：IP

HTTP请求

GET /api/v5/copytrading/public-subpositions-history

请求示例

GET /api/v5/copytrading/public-subpositions-history?instType=SWAP&uniqueCode=9A8534AB09862774

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值
uniqueCode	String	是	交易员唯一标识码 数字加字母组合 长度为16或18位，如：213E8C92DC61EFAC（16位）或381749205163847291（18位）
after	String	否	请求此id之前（更旧的数据）的分页内容，传的值为对应接口的subPosId
before	String	否	请求此id之后（更新的数据）的分页内容，传的值为对应接口的subPosId
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "closeAvgPx": "28385.9",
            "closeTime": "1697709137162",
            "instId": "BTC-USDT-SWAP",
            "instType": "SWAP",
            "lever": "20",
            "margin": "4.245285",
            "mgnMode": "isolated",
            "openAvgPx": "28301.9",
            "openTime": "1697698048031",
            "pnl": "0.252",
            "pnlRatio": "0.05935997229868",
            "posSide": "long",
            "subPos": "3",
            "subPosId": "635126416883355648",
            "uniqueCode": "9A8534AB09862774"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品ID
subPosId	String	带单仓位ID
posSide	String	持仓方向 long：开平仓模式开多 short：开平仓模式开空 net：买卖模式（subPos为正代表开多，subPos为负代表开空）
mgnMode	String	保证金模式，isolated：逐仓 ；cross：全仓
lever	String	杠杆倍数
openAvgPx	String	开仓均价
openTime	String	开仓时间
subPos	String	持仓张数
closeTime	String	平仓时间(最近一次平仓的时间)
closeAvgPx	String	平仓均价
pnl	String	收益额
pnlRatio	String	收益率
instType	String	产品类型 SPOT：币币 SWAP：永续合约
margin	String	保证金
ccy	String	币种
uniqueCode	String	交易员唯一标识代码

GET / 获取跟单人信息

公共接口，获取交易员的跟单人信息，按收益从高到低返回

限速：5次/2s

限速规则：IP

HTTP请求

GET /api/v5/copytrading/public-copy-traders

请求示例

GET /api/v5/copytrading/public-copy-traders?instType=SWAP&uniqueCode=D9ADEAB33AE9EABD

请求参数

参数名	类型	是否必须	描述
instType	String	否	产品类型 SWAP：永续合约，默认值
uniqueCode	String	是	带单交易员唯一标识码。 数字加字母组合 长度为16或18位，如：213E8C92DC61EFAC（16位）或381749205163847291（18位）
limit	String	否	返回结果的数量，最大为100，默认100条

返回结果

{
    "code": "0",
    "data": [
        {
            "ccy": "USDT",
            "copyTotalPnl": "2060.12242",
            "copyTraderNumChg": "1",
            "copyTraderNumChgRatio": "0.5",
            "copyTraders": [
                {
                    "beginCopyTime": "1686125051000",
                    "nickName": "bre***@gmail.com",
                    "pnl": "1076.77388",
                    "portLink": ""
                },
                {
                    "beginCopyTime": "1698133811000",
                    "nickName": "MrYanDao505",
                    "pnl": "983.34854",
                    "portLink": "https://static.okx.com/cdn/okex/users/headimages/20231010/fd31f45e99fe41f7bb219c0b53ae0ada"
                }
            ]
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
copyTotalPnl	String	跟单员总收益
ccy	String	总收益币种名称
copyTraderNumChg	String	近 7 日变化的跟单人数
copyTraderNumChgRatio	String	近 7 日跟单人数变化的比率
copyTraders	Array of objects	跟单员信息
> beginCopyTime	String	跟单开始时间，Unix时间戳的毫秒数格式，如 1597026383085
> nickName	String	昵称
> portLink	String	跟单员头像的链接地址
> pnl	String	跟单收益

WS / 带单消息通知频道

带单失败时的消息通知

服务地址

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

请求示例

{
    "id": "1512",
    "op": "subscribe",
    "args": [{
        "channel": "copytrading-lead-notification",
        "instType": "SWAP"
    }]
}

import asyncio

from okx.websocket.WsPrivateAsync import WsPrivateAsync

def callbackFunc(message):
    print(message)

async def main():

    ws = WsPrivateAsync(
        apiKey = "YOUR_API_KEY",
        passphrase = "YOUR_PASSPHRASE",
        secretKey = "YOUR_SECRET_KEY",
        url = "wss://ws.okx.com:8443/ws/v5/business",
        useServerTime=False
    )
    await ws.start()
    args = [{
        "channel": "copytrading-lead-notification",
        "instType": "SWAP"
    }]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求参数

参数	类型	是否必须	描述
id	String	否	消息的唯一标识。 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 subscribe unsubscribe
args	Array of objects	是	请求订阅的频道列表
> channel	String	是	频道名 copytrading-lead-notification
> instType	String	是	产品类型 SWAP：永续合约
> instId	String	否	产品ID

成功返回示例

{
    "id": "1512",
    "event": "subscribe",
    "arg": {
        "channel": "copytrading-lead-notification",
        "instType": "SWAP"
    },
    "connId": "aa993428"
}

失败返回示例

{
    "id": "1512",
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"copytrading-lead-notification\", \"instType\" : \"FUTURES\"}]}",
    "connId":"a4d3ae55"
}

返回参数

参数	类型	是否必须	描述
id	String	否	消息的唯一标识
event	String	是	事件 subscribe unsubscribe error
arg	Object	否	订阅的频道
> channel	String	是	频道名
> instType	String	是	产品类型 SWAP：永续合约
> instId	String	否	产品ID
code	String	否	错误码
msg	String	否	错误消息
connId	String	是	WebSocket 连接ID

推送示例：

{
    "arg": {
        "channel": "copytrading-lead-notification",
        "instType": "SWAP",
        "uid": "525627088439549953"
    },
    "data": [
        {
            "infoType": "2",
            "instId": "",
            "instType": "SWAP",
            "maxLeadTraderNum": "3",
            "minLeadEq": "",
            "posSide": "",
            "side": "",
            "subPosId": "667695035433385984",
            "uniqueCode": "3AF72F63E3EAD701"
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> uid	String	用户标识
> instType	String	产品类型
data	Array of objects	订阅的数据
> instType	String	产品类型
> infoType	String	消息类型 1: 带单失败，触发最大仓位限制 2: 带单失败，触发带单次数限制 3: 带单失败，交易账户 USDT 低于最小权益
> subPosId	String	带单仓位 ID
> uniqueCode	String	交易员唯一标识码
> instId	String	产品 ID
> side	String	订单方向，buy sell
> posSide	String	持仓方向 long：开平仓模式开多 short：开平仓模式开空 net：买卖模式
> maxLeadTraderNum	String	当前交易员单日最大带单次数
> minLeadEq	String	带单最小 USDT 权益

行情数据

行情数据功能模块下的API接口不需要身份验证。

行情数据存在多个服务且每个服务有独立的缓存，每次会随机请求到某一个服务，所以会存在两次请求，第二次获取到的数据早于第一次的情况。

针对事件合约，行情数据模块只返回YES侧的数据，用户可自行推导出NO侧数据。

GET / 获取所有产品行情信息

获取产品行情信息。在提前挂单阶段，best ask的价格有机会低于best bid。

限速：20次/2s

限速规则：IP

HTTP请求

GET /api/v5/market/tickers

请求示例

GET /api/v5/market/tickers?instType=SWAP

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取所有产品行情信息
result = marketDataAPI.get_tickers(
    instType="SWAP"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instType	String	是	产品类型 SPOT：币币 SWAP：永续合约 FUTURES：交割合约 OPTION：期权 EVENTS：事件合约
instFamily	String	否	交易品种 适用于交割/永续/期权，如 BTC-USD

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
     {
        "instType":"SWAP",
        "instId":"LTC-USD-SWAP",
        "last":"9999.99",
        "lastSz":"1",
        "askPx":"9999.99",
        "askSz":"11",
        "bidPx":"8888.88",
        "bidSz":"5",
        "open24h":"9000",
        "high24h":"10000",
        "low24h":"8888.88",
        "volCcy24h":"2222",
        "vol24h":"2222",
        "sodUtc0":"0.1",
        "sodUtc8":"0.1",
        "ts":"1597026383085"
     },
     {
        "instType":"SWAP",
        "instId":"BTC-USD-SWAP",
        "last":"9999.99",
        "lastSz":"1",
        "askPx":"9999.99",
        "askSz":"11",
        "bidPx":"8888.88",
        "bidSz":"5",
        "open24h":"9000",
        "high24h":"10000",
        "low24h":"8888.88",
        "volCcy24h":"2222",
        "vol24h":"2222",
        "sodUtc0":"0.1",
        "sodUtc8":"0.1",
        "ts":"1597026383085"
    }
  ]
}

返回参数

参数名	类型	描述
instType	String	产品类型
instId	String	产品ID
last	String	最新成交价
lastSz	String	最新成交的数量，0 代表没有成交量
askPx	String	卖一价
askSz	String	卖一价的挂单数数量
bidPx	String	买一价
bidSz	String	买一价的挂单数量
open24h	String	24小时开盘价
high24h	String	24小时最高价
low24h	String	24小时最低价
volCcy24h	String	24小时成交量，以币为单位 如果是衍生品合约，数值为交易货币的数量。比如，对于 BTC-USD-SWAP 和 BTC-USDT-SWAP，单位均为 BTC 如果是币币/币币杠杆，数值为计价货币的数量。
vol24h	String	24小时成交量，以张为单位 如果是衍生品合约，数值为合约的张数。 如果是币币/币币杠杆，数值为交易货币的数量。
sodUtc0	String	UTC 0 时开盘价
sodUtc8	String	UTC+8 时开盘价
ts	String	ticker数据产生时间，Unix时间戳的毫秒数格式，如 1597026383085

GET / 获取单个产品行情信息

获取产品行情信息。在提前挂单阶段，best ask的价格有机会低于best bid。

限速：20次/2s

限速规则：IP

HTTP请求

GET /api/v5/market/ticker

请求示例

GET /api/v5/market/ticker?instId=BTC-USD-SWAP

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取单个产品行情信息
result = marketDataAPI.get_ticker(
    instId="BTC-USD-SWAP"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 BTC-USD-SWAP

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "instType": "SWAP",
            "instId": "BTC-USD-SWAP",
            "last": "56956.1",
            "lastSz": "3",
            "askPx": "56959.1",
            "askSz": "10582",
            "bidPx": "56959",
            "bidSz": "4552",
            "open24h": "55926",
            "high24h": "57641.1",
            "low24h": "54570.1",
            "volCcy24h": "81137.755",
            "vol24h": "46258703",
            "ts": "1620289117764",
            "sodUtc0": "55926",
            "sodUtc8": "55926"
        }
    ]
}

返回参数

参数名	类型	描述
instType	String	产品类型
instId	String	产品ID
last	String	最新成交价
lastSz	String	最新成交的数量，0 代表没有成交量
askPx	String	卖一价
askSz	String	卖一价对应的数量
bidPx	String	买一价
bidSz	String	买一价对应的数量
open24h	String	24小时开盘价
high24h	String	24小时最高价
low24h	String	24小时最低价
volCcy24h	String	24小时成交量，以币为单位 如果是衍生品合约，数值为交易货币的数量。 如果是币币/币币杠杆，数值为计价货币的数量。
vol24h	String	24小时成交量，以张为单位 如果是衍生品合约，数值为合约的张数。 如果是币币/币币杠杆，数值为交易货币的数量。
sodUtc0	String	UTC+0 时开盘价
sodUtc8	String	UTC+8 时开盘价
ts	String	ticker数据产生时间，Unix时间戳的毫秒数格式，如 1597026383085

GET / 获取产品深度

获取产品深度列表，数据每 50 毫秒更新一次。在提前挂单阶段，best ask的价格有机会低于best bid。

该接口收到请求后不会立刻返回，而是会待服务端缓存数据更新后立即返回最新数据。

限速：40次/2s

限速规则：IP

HTTP请求

GET /api/v5/market/books

请求示例

GET /api/v5/market/books?instId=BTC-USDT

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取产品深度
result = marketDataAPI.get_orderbook(
    instId="BTC-USDT"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 BTC-USDT
sz	String	否	深度档位数量，最大值可传400，即买卖深度共800条 不填写此参数，默认返回1档深度数据

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "asks": [
                [
                    "41006.8",
                    "0.60038921",
                    "0",
                    "1"
                ]
            ],
            "bids": [
                [
                    "41006.3",
                    "0.30178218",
                    "0",
                    "2"
                ]
            ],
            "ts": "1629966436396",
            "seqId": 3235851742
        }
    ]
}

返回参数

参数名	类型	描述
asks	Array of Arrays	卖方深度
bids	Array of Arrays	买方深度
ts	String	深度产生的时间
seqId	Integer	当前消息的序列号

合约的asks和bids值数组举例说明： ["411.8","10", "0","4"] 411.8为深度价格，10为此价格的合约张数，0该字段已弃用(始终为0)，4为此价格的订单数量 现货/币币杠杆的asks和bids值数组举例说明： ["411.8","10", "0","4"] 411.8为深度价格，10为此价格的交易币的数量，0该字段已弃用(始终为0)，4为此价格的订单数量 asks和bids值数组举例说明： ["411.8", "10", "0", "4"]

• 411.8为深度价格
• 10为此价格的数量 （合约交易为张数，现货/币币杠杆为交易币的数量）
• 0该字段已弃用(始终为0)
• 4为此价格的订单数量

集合竞价期间，深度数据大约每秒更新一次

GET / 获取 RPI 产品深度

获取产品的合并深度列表，在每个价格档位上将有机深度与当前可成交的 RPI（Retail Price Improvement，散户价格优化）深度合并返回。不可成交的 RPI 订单由平台侧过滤，不会返回。

数据每 200 毫秒更新一次。该接口收到请求后不会立刻返回，而是会待服务端缓存数据更新后立即返回最新数据。

限速：20次/2s

限速规则：IP

HTTP请求

GET /api/v5/market/books-rpi

请求示例

GET /api/v5/market/books-rpi?instId=BTC-USDT-SWAP&sz=3

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 BTC-USDT-SWAP
sz	String	否	深度档位数量，最大值可传400，即买卖深度共800条 不填写此参数，默认返回1档深度数据

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "asks": [
                [
                    "67855.2",
                    "0.5",
                    "0.5",
                    "1"
                ],
                [
                    "67856.0",
                    "1.3",
                    "1.0",
                    "4"
                ],
                [
                    "67860.5",
                    "0.3",
                    "0",
                    "1"
                ]
            ],
            "bids": [
                [
                    "67854.8",
                    "1.7",
                    "1.2",
                    "3"
                ],
                [
                    "67853.0",
                    "0.8",
                    "0.8",
                    "1"
                ]
            ],
            "ts": "1785310731002",
            "seqId": 332042172451
        }
    ]
}

返回参数

参数名	类型	描述
asks	Array of Arrays	卖方深度，每个元素为 [price, totalQty, nonRpiQty, count]
bids	Array of Arrays	买方深度，每个元素为 [price, totalQty, nonRpiQty, count]
ts	String	深度产生的时间，Unix 时间戳，单位为毫秒
seqId	Integer	当前消息的序列号，与 books-rpi WebSocket 频道保持一致

asks和bids值数组举例说明： ["67856.0", "1.3", "1.0", "4"]

• 67856.0 为深度价格
• 1.3 为 totalQty ，即该价格的总数量，包含有机深度与当前可成交的 RPI 深度（合约交易为张数，现货/币币杠杆为交易币的数量）
• 1.0 为 nonRpiQty ，即该价格中有机（非 RPI）部分的数量
• 4 为该价格的订单数量，包含有机订单与当前可成交的 RPI 订单 该价格档位上可成交的 RPI 数量为 totalQty - nonRpiQty 。具备 RPI 权限的 taker 可成交至 totalQty ；不具备 RPI 权限的 taker 仅可成交至 nonRpiQty ，即使二者读取同一份数据。下单时将 rpiTakerAccess 设为 true 即可使用 RPI 流动性。 请注意，仅本接口的第三位为 nonRpiQty 。在 books、books-full、books-lite 接口中，同一位置为已弃用字段，始终为 "0"。 当某档位的 totalQty 与 nonRpiQty 相等时，表示该价格上当前没有可成交的 RPI 深度。对于没有 RPI 做市商报价的产品，以及依照撮合规则当前被隐藏的 RPI 挂单，出现该情况均属正常。

本接口不返回 checksum ，请使用 seqId 进行排序校验。 当 RPI 可成交状态不可用时，本接口以保守方式降级：排除 RPI 数量，每个档位返回的 totalQty 与 nonRpiQty 相等。

GET / 获取产品完整深度

获取产品深度列表。数据每秒更新一次。在提前挂单阶段，best ask的价格有机会低于best bid。

该接口收到请求后不会立刻返回，而是会待服务端缓存数据更新后立即返回最新数据。

限速：10次/2s

限速规则：IP

HTTP请求

GET /api/v5/market/books-full

请求示例

GET /api/v5/market/books-full?instId=BTC-USDT&sz=20

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 BTC-USDT
sz	String	否	深度档位数量，最大值可传5000，即买卖深度共10000条 不填写此参数，默认返回1档深度数据

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "asks": [
                [
                    "41006.8",
                    "0.60038921",
                    "1"
                ]
            ],
            "bids": [
                [
                    "41006.3",
                    "0.30178218",
                    "2"
                ]
            ],
            "ts": "1629966436396"
        }
    ]
}

返回参数

参数名	类型	描述
asks	Array of Arrays	卖方深度
bids	Array of Arrays	买方深度
ts	String	深度产生的时间

合约的asks和bids值数组举例说明： ["411.8", "10", "4"] 411.8为深度价格，10为此价格的合约张数，4为此价格的订单数量 现货/币币杠杆的asks和bids值数组举例说明： ["411.8", "10", "4"] 411.8为深度价格，10为此价格的交易币的数量，4为此价格的订单数量 asks和bids值数组举例说明： ["411.8", "10", "4"]

• 411.8为深度价格
• 10为此价格的数量 （合约交易为张数，现货/币币杠杆为交易币的数量）
• 4为此价格的订单数量

集合竞价期间，深度数据大约每秒更新一次

GET / 获取交易产品K线数据

获取K线数据。K线数据按请求的粒度分组返回，K线数据每个粒度最多可获取最近1,440条。

限速：40次/2s

限速规则：IP

HTTP请求

GET /api/v5/market/candles

请求示例

GET /api/v5/market/candles?instId=BTC-USDT

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取交易产品K线数据
result = marketDataAPI.get_candlesticks(
    instId="BTC-USDT"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 BTC-USDT
bar	String	否	时间粒度，默认值1m 如 [1m/3m/5m/15m/30m/1H/2H/4H] UTC+8开盘价k线：[6H/12H/1D/2D/3D/1W/1M/3M] UTC+0开盘价k线：[/6Hutc/12Hutc/1Dutc/2Dutc/3Dutc/1Wutc/1Mutc/3Mutc]
after	String	否	请求此时间戳之前（更旧的数据）的分页内容，传的值为对应接口的ts
before	String	否	请求此时间戳之后（更新的数据）的分页内容，传的值为对应接口的ts, 单独使用时，会返回最新的数据。
limit	String	否	分页返回的结果集数量，最大为300，不填默认返回100条
adjust	String	否	复权类型，仅适用于股票永续合约。 forward：前复权。 不填时默认返回不复权数据。

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
     [
        "1597026383085",
        "3.721",
        "3.743",
        "3.677",
        "3.708",
        "8422410",
        "22698348.04828491",
        "12698348.04828491",
        "0"
    ],
    [
        "1597026383085",
        "3.731",
        "3.799",
        "3.494",
        "3.72",
        "24912403",
        "67632347.24399722",
        "37632347.24399722",
        "1"
    ]
    ]
}

返回参数

参数名	类型	描述
ts	String	开始时间，Unix时间戳的毫秒数格式，如 1597026383085
o	String	开盘价格
h	String	最高价格
l	String	最低价格
c	String	收盘价格
vol	String	交易量，以张为单位 如果是衍生品合约，数值为合约的张数。 如果是币币/币币杠杆，数值为交易货币的数量。
volCcy	String	交易量，以币为单位 如果是衍生品合约，数值为交易货币的数量。 如果是币币/币币杠杆，数值为计价货币的数量。
volCcyQuote	String	交易量，以计价货币为单位 如 BTC-USDT和BTC-USDT-SWAP，单位均是USDT。 BTC-USD-SWAP单位是USD。
confirm	String	K线状态 0：K线未完结 1：K线已完结

返回的第一条K线数据可能不是完整周期k线，返回值数组顺序分别为是：[ts,o,h,l,c,vol,volCcy,volCcyQuote,confirm] 对于当前周期的K线数据，没有成交时，开高收低默认都取上一周期的收盘价格。

当传入 adjust=forward 时，历史K线的开高低收（OHLC）价格将乘以对应时期的复权因子。对于拆股，成交量（ vol 、 volCcy ）也会按相同比例调整。成交金额（ volCcyQuote ）不做调整。该参数仅对股票永续合约有效。

GET / 获取交易产品历史K线数据

获取最近几年的历史k线数据(1s k线支持查询最近3个月的数据)

限速：20次/2s

限速规则：IP

HTTP请求

GET /api/v5/market/history-candles

请求示例

GET /api/v5/market/history-candles?instId=BTC-USDT

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取交易产品历史K线数据
result = marketDataAPI.get_history_candlesticks(
    instId="BTC-USDT"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 BTC-USDT
after	String	否	请求此时间戳之前（更旧的数据）的分页内容，传的值为对应接口的ts
before	String	否	请求此时间戳之后（更新的数据）的分页内容，传的值为对应接口的ts, 单独使用时，会返回最新的数据。
bar	String	否	时间粒度，默认值1m 如 [1s/1m/3m/5m/15m/30m/1H/2H/4H] UTC+8开盘价k线：[6H/12H/1D/2D/3D/1W/1M/3M] UTC+0开盘价k线：[6Hutc/12Hutc/1Dutc/2Dutc/3Dutc/1Wutc/1Mutc/3Mutc]
limit	String	否	分页返回的结果集数量，最大为300，不填默认返回100条
adjust	String	否	复权类型，仅适用于股票永续合约。 forward：前复权。 不填时默认返回不复权数据。

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
     [
        "1597026383085",
        "3.721",
        "3.743",
        "3.677",
        "3.708",
        "8422410",
        "22698348.04828491",
        "12698348.04828491",
        "1"
    ],
    [
        "1597026383085",
        "3.731",
        "3.799",
        "3.494",
        "3.72",
        "24912403",
        "67632347.24399722",
        "37632347.24399722",
        "1"
    ]
    ]
}

返回参数

参数名	类型	描述
ts	String	开始时间，Unix时间戳的毫秒数格式，如 1597026383085
o	String	开盘价格
h	String	最高价格
l	String	最低价格
c	String	收盘价格
vol	String	交易量，以张为单位 如果是衍生品合约，数值为合约的张数。 如果是币币/币币杠杆，数值为交易货币的数量。
volCcy	String	交易量，以币为单位 如果是衍生品合约，数值为交易货币的数量。 如果是币币/币币杠杆，数值为计价货币的数量。
volCcyQuote	String	交易量，以计价货币为单位 如 BTC-USDT和BTC-USDT-SWAP，单位均是USDT BTC-USD-SWAP单位是USD
confirm	String	K线状态 0：K线未完结 1：K线已完结

返回值数组顺序分别为是：[ts,o,h,l,c,vol,volCcy,volCcyQuote,confirm]

期权不支持 1s K线， 其他业务线 (币币, 杠杆, 交割和永续)支持

当传入 adjust=forward 时，历史K线的开高低收（OHLC）价格将乘以对应时期的复权因子。对于拆股，成交量（ vol 、 volCcy ）也会按相同比例调整。成交金额（ volCcyQuote ）不做调整。该参数仅对股票永续合约有效。

GET / 获取交易产品公共成交数据

查询市场上的成交信息数据

限速：100次/2s

限速规则：IP

HTTP请求

GET /api/v5/market/trades

请求示例

GET /api/v5/market/trades?instId=BTC-USDT

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取交易产品公共成交数据
result = marketDataAPI.get_trades(
    instId="BTC-USDT"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 BTC-USDT
limit	String	否	分页返回的结果集数量，最大为500，不填默认返回100条

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "instId": "BTC-USDT",
            "side": "sell",
            "sz": "0.00001",
            "source": "0",
            "px": "29963.2",
            "tradeId": "242720720",
            "ts": "1654161646974"
        },
        {
            "instId": "BTC-USDT",
            "side": "sell",
            "sz": "0.00001",
            "source": "0",
            "px": "29964.1",
            "tradeId": "242720719",
            "ts": "1654161641568"
        }
    ]
}

返回参数

参数名	类型	描述
instId	String	产品ID
tradeId	String	成交ID
px	String	成交价格
sz	String	成交数量 对于币币交易，成交数量的单位为交易货币 对于交割、永续以及期权，单位为张。
side	String	吃单方向 buy：买 sell：卖
source	String	订单来源 0：普通订单 1：RPI 订单
ts	String	成交时间，Unix时间戳的毫秒数格式， 如1597026383085

最多获取最近500条历史公共成交数据

GET / 获取交易产品公共历史成交数据

查询市场上的成交信息数据，可以分页获取最近3个月的数据。

限速：20次/2s

限速规则：IP

HTTP请求

GET /api/v5/market/history-trades

请求示例

GET /api/v5/market/history-trades?instId=BTC-USDT

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取交易产品公共历史成交数据
result = marketDataAPI.get_history_trades(
    instId="BTC-USDT"
)
print(result)

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 BTC-USDT
type	String	否	分页类型 1：tradeId 分页 2：时间戳分页 默认为1：tradeId 分页
after	String	否	请求此 ID 或 ts 之前的分页内容，传的值为对应接口的 tradeId 或 ts
before	String	否	请求此ID之后（更新的数据）的分页内容，传的值为对应接口的 tradeId。 不支持时间戳分页。单独使用时，会返回最新的数据。
limit	String	否	分页返回的结果集数量，最大为100，不填默认返回100条

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "instId": "BTC-USDT",
            "side": "sell",
            "sz": "0.00001",
            "source": "0",
            "px": "29963.2",
            "tradeId": "242720720",
            "ts": "1654161646974"
        },
        {
            "instId": "BTC-USDT",
            "side": "sell",
            "sz": "0.00001",
            "source": "0",
            "px": "29964.1",
            "tradeId": "242720719",
            "ts": "1654161641568"
        }
    ]
}

返回参数

参数名	类型	描述
instId	String	产品ID
tradeId	String	成交ID
px	String	成交价格
sz	String	成交数量 对于币币交易，成交数量的单位为交易货币 对于交割、永续以及期权，单位为张。
side	String	吃单方向 buy：买 sell：卖
source	String	订单来源 0：普通订单 1：流动性增强计划订单
ts	String	成交时间，Unix时间戳的毫秒数格式， 如1597026383085

GET / 获取期权品种公共成交数据

查询期权同一个交易品种下的成交信息数据，最多返回100条。

限速：20次/2s

限速规则：IP

HTTP请求

GET /api/v5/market/option/instrument-family-trades

请求示例

GET /api/v5/market/option/instrument-family-trades?instFamily=BTC-USD

请求参数

参数名	类型	是否必须	描述
instFamily	String	是	交易品种，如 BTC-USD，适用于期权

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "vol24h": "103381",
            "tradeInfo": [
                {
                    "instId": "BTC-USD-221111-17750-C",
                    "side": "sell",
                    "sz": "1",
                    "px": "0.0075",
                    "tradeId": "20",
                    "ts": "1668090715058"
                },
                {
                    "instId": "BTC-USD-221111-17750-C",
                    "side": "sell",
                    "sz": "91",
                    "px": "0.01",
                    "tradeId": "19",
                    "ts": "1668090421062"
                }
            ],
            "optType": "C"
        },
        {
            "vol24h": "144499",
            "tradeInfo": [
                {
                    "instId": "BTC-USD-230127-10000-P",
                    "side": "sell",
                    "sz": "82",
                    "px": "0.019",
                    "tradeId": "23",
                    "ts": "1668090967057"
                },
                {
                    "instId": "BTC-USD-221111-16250-P",
                    "side": "sell",
                    "sz": "102",
                    "px": "0.0045",
                    "tradeId": "24",
                    "ts": "1668090885050"
                }
            ],
            "optType": "P"
        }
    ]
}

返回参数

参数名	类型	描述
vol24h	String	24小时成交量，以张为单位
optType	String	期权类型，C：看涨期权 P：看跌期权
tradeInfo	Array of objects	成交数据列表
> instId	String	产品ID
> tradeId	String	成交ID
> px	String	成交价格
> sz	String	成交数量，单位为张。
> side	String	成交方向 buy：买 sell：卖
> ts	String	成交时间，Unix时间戳的毫秒数格式， 如1597026383085

GET / 获取期权公共成交数据

最多返回最近的100条成交数据

限速：20次/2s

限速规则：IP

HTTP请求

GET /api/v5/public/option-trades

请求示例

GET /api/v5/public/option-trades?instFamily=BTC-USD

请求参数

参数名	类型	是否必须	描述
instId	String	可选	产品ID，如 BTC-USD-221230-4000-C，instId 和 instFamily 必须传一个，若传两个，以 instId 为主
instFamily	String	可选	交易品种，如 BTC-USD
optType	String	否	期权类型，C：看涨期权 P：看跌期权

返回结果

{
    "code": "0",
    "data": [
        {
            "fillVol": "0.24415013671875",
            "fwdPx": "16676.907614127158",
            "idxPx": "16667",
            "instFamily": "BTC-USD",
            "instId": "BTC-USD-221230-16600-P",
            "markPx": "0.006308943261227884",
            "optType": "P",
            "px": "0.005",
            "side": "sell",
            "sz": "30",
            "tradeId": "65",
            "ts": "1672225112048"
        }
    ],
    "msg": ""
}

返回参数

参数名	类型	描述
instId	String	产品ID
instFamily	String	交易品种
tradeId	String	成交ID
px	String	成交价格
sz	String	成交数量。单位为张。
side	String	成交方向 buy：买 sell：卖
optType	String	期权类型，C：看涨期权 P：看跌期权 ，仅适用于期权
fillVol	String	成交时的隐含波动率（对应成交价格）
fwdPx	String	成交时的远期价格
idxPx	String	成交时的指数价格
markPx	String	成交时的标记价格
ts	String	成交时间，Unix时间戳的毫秒数格式， 如1597026383085

GET / 获取平台24小时总成交量

24小时成交量滚动计算

限速：2次/2s

限速规则：IP

HTTP请求

GET /api/v5/market/platform-24-volume

请求示例

GET /api/v5/market/platform-24-volume

import okx.MarketData as MarketData

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

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# 获取平台24小时总成交量
result = marketDataAPI.get_volume()
print(result)

返回结果

{
    "code":"0",
    "msg":"",
    "data":[
     {
         "volCny": "230900886396766",
         "volUsd": "34462818865189",
         "ts": "1657856040389"
     }
  ]
}

返回参数

参数名	类型	描述
volUsd	String	订单簿交易近24小时总成交量，以美元为单位
volCny	String	订单簿交易近24小时总成交量，以人民币为单位
ts	String	接口返回数据时间

GET / 集合竞价信息

获取集合竞价相关信息

限速：20次/2s

限速规则：IP

HTTP请求

GET /api/v5/market/call-auction-details

请求示例

GET /api/v5/market/call-auction-details?instId=ONDO-USDC

请求参数

参数名	类型	是否必须	描述
instId	String	是	产品ID，如 BTC-USDT

返回结果

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "instId": "ONDO-USDC",
            "unmatchedSz": "9988764",
            "eqPx": "0.6",
            "matchedSz": "44978",
            "state": "continuous_trading",
            "auctionEndTime": "1726542000000",
            "ts": "1726542000007"
        }
    ]
}

返回参数

参数名	类型	描述
instId	String	产品ID
eqPx	String	均衡价格
matchedSz	String	买卖双边的匹配数量，单位为交易货币
unmatchedSz	String	未匹配数量
auctionEndTime	String	集合竞价结束时间，Unix时间戳的毫秒数格式，如 1597026383085
state	String	交易状态 call_auction：集合竞价 continuous_trading：连续交易
ts	String	数据产生时间，Unix时间戳的毫秒数格式，如 1597026383085

在集合竞价期间，用户可以获取均衡价格、匹配数量、未匹配数量和集合竞价结束时间的更新。数据大约每秒更新一次。当集合竞价结束时，该接口将返回实际开盘价、匹配数量和未匹配数量。 对于从未进入集合竞价的交易产品，该接口也会返回结果，但交易状态字段state始终为continuous_trading，其他字段为0或空。

WS / 行情频道

获取产品的最新成交价、买一价、卖一价和24小时交易量等信息。在提前挂单阶段，best ask的价格有机会低于best bid。

最快100ms推送一次，没有触发事件时不推送，触发推送的事件有：成交、买一卖一发生变动。

URL Path

/ws/v5/public

请求示例

{
    "id": "1512",
    "op": "subscribe",
    "args": [{
        "channel": "tickers",
        "instId": "BTC-USDT"
    }]
}

import asyncio

from okx.websocket.WsPublicAsync import WsPublicAsync

def callbackFunc(message):
    print(message)

async def main():
    ws = WsPublicAsync(url="wss://wspap.okx.com:8443/ws/v5/public")
    await ws.start()
    args = [{
        "channel": "tickers",
        "instId": "BTC-USDT"
    }]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求参数

参数	类型	是否必须	描述
id	String	否	消息的唯一标识。 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 subscribe unsubscribe
args	Array of objects	是	请求订阅的频道列表
> channel	String	是	频道名 tickers
> instId	String	是	产品ID

成功返回示例

{
    "id": "1512",
    "event": "subscribe",
    "arg": {
        "channel": "tickers",
        "instId": "BTC-USDT"
    },
    "connId": "a4d3ae55"
}

失败返回示例

{
    "id": "1512",
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"tickers\", \"instId\" : \"LTC-USD-200327\"}]}",
    "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
    "arg": {
        "channel": "tickers",
        "instId": "BTC-USDT"
    },
    "data": [{
        "instType": "SPOT",
        "instId": "BTC-USDT",
        "last": "9999.99",
        "lastSz": "0.1",
        "askPx": "9999.99",
        "askSz": "11",
        "bidPx": "8888.88",
        "bidSz": "5",
        "open24h": "9000",
        "high24h": "10000",
        "low24h": "8888.88",
        "volCcy24h": "2222",
        "vol24h": "2222",
        "sodUtc0": "2222",
        "sodUtc8": "2222",
        "ts": "1597026383085"
    }]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
data	Array of objects	订阅的数据
> instType	String	产品类型
> instId	String	产品ID
> last	String	最新成交价
> lastSz	String	最新成交的数量，0 代表没有成交量
> askPx	String	卖一价
> askSz	String	卖一价对应的量
> bidPx	String	买一价
> bidSz	String	买一价对应的数量
> open24h	String	24小时开盘价
> high24h	String	24小时最高价
> low24h	String	24小时最低价
> volCcy24h	String	24小时成交量，以币为单位 如果是衍生品合约，数值为交易货币的数量。 如果是币币/币币杠杆，数值为计价货币的数量。
> vol24h	String	24小时成交量，以张为单位 如果是衍生品合约，数值为合约的张数。 如果是币币/币币杠杆，数值为交易货币的数量。
> sodUtc0	String	UTC+0 时开盘价
> sodUtc8	String	UTC+8 时开盘价
> ts	String	数据产生时间，Unix时间戳的毫秒数格式，如 1597026383085

WS / K线频道

获取K线数据，推送频率最快是间隔1秒推送一次数据。

URL Path

/ws/v5/business

请求示例

{
  "id": "1512",
    "op": "subscribe",
    "args": [{
        "channel": "candle1D",
        "instId": "BTC-USDT"
    }]
}

import asyncio

from okx.websocket.WsPublicAsync import WsPublicAsync

def callbackFunc(message):
    print(message)

async def main():
    ws = WsPublicAsync(url="wss://wspap.okx.com:8443/ws/v5/business")
    await ws.start()
    args = [
        {
          "channel": "candle1D",
          "instId": "BTC-USDT"
        }
    ]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求参数

参数	类型	是否必须	描述
id	String	否	消息的唯一标识。 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 subscribe unsubscribe
args	Array of objects	是	请求订阅的频道列表
> channel	String	是	频道名 candle3M candle1M candle1W candle1D candle2D candle3D candle5D candle12H candle6H candle4H candle2H candle1H candle30m candle15m candle5m candle3m candle1m candle1s candle3Mutc candle1Mutc candle1Wutc candle1Dutc candle2Dutc candle3Dutc candle5Dutc candle12Hutc candle6Hutc
> instId	String	是	产品ID

成功返回示例

{
  "id": "1512",
    "event": "subscribe",
    "arg": {
        "channel": "candle1D",
        "instId": "BTC-USDT"
    },
  "connId": "a4d3ae55"
}

失败返回示例

{
  "id": "1512",
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"candle1D\", \"instId\" : \"BTC-USD-191227\"}]}",
  "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
  "arg": {
    "channel": "candle1D",
    "instId": "BTC-USDT"
  },
  "data": [
    [
      "1629993600000",
      "42500",
      "48199.9",
      "41006.1",
      "41006.1",
      "3587.41204591",
      "166741046.22583129",
      "166741046.22583129",
      "0"
    ]
  ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
data	Array of Arrays	订阅的数据
> ts	String	开始时间，Unix时间戳的毫秒数格式，如 1597026383085
> o	String	开盘价格
> h	String	最高价格
> l	String	最低价格
> c	String	收盘价格
> vol	String	交易量，以张为单位 如果是衍生品合约，数值为合约的张数。 如果是币币/币币杠杆，数值为交易货币的数量。
> volCcy	String	交易量，以币为单位 如果是衍生品合约，数值为交易货币的数量。 如果是币币/币币杠杆，数值为计价货币的数量。
> volCcyQuote	String	交易量，以计价货币为单位 如 BTC-USDT和BTC-USDT-SWAP单位均是USDT。 BTC-USD-SWAP单位是USD。
> confirm	String	K线状态 0：K线未完结 1：K线已完结

WS / 交易频道

获取最近的成交数据，有成交数据就推送，每次推送可能聚合多条成交数据。

根据每个taker订单的不同成交价格，不同成交来源推送消息，并使用count字段表示聚合的订单匹配数量。

URL Path

/ws/v5/public

请求示例

{
  "id": "1512",
    "op": "subscribe",
    "args": [{
        "channel": "trades",
        "instId": "BTC-USDT"
    }]
}

import asyncio
from okx.websocket.WsPublicAsync import WsPublicAsync

def callbackFunc(message):
    print(message)

async def main():
    ws = WsPublicAsync(url="wss://wspap.okx.com:8443/ws/v5/public")
    await ws.start()
    args = [
        {
          "channel": "trades",
          "instId": "BTC-USDT"
        }
    ]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求参数

参数	类型	是否必须	描述
id	String	否	消息的唯一标识。 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 subscribe unsubscribe
args	Array of objects	是	请求订阅的频道列表
> channel	String	是	频道名 trades
> instId	String	是	产品ID

成功返回示例

{
  "id": "1512",
    "event": "subscribe",
    "arg": {
        "channel": "trades",
        "instId": "BTC-USDT"
    },
  "connId": "a4d3ae55"
}

失败返回示例

{
  "id": "1512",
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"trades\", \"instId\" : \"BTC-USD-191227\"}]}",
  "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
  "arg": {
    "channel": "trades",
    "instId": "BTC-USDT"
  },
  "data": [
    {
      "instId": "BTC-USDT",
      "tradeId": "130639474",
      "px": "42219.9",
      "sz": "0.12060306",
      "side": "buy",
      "ts": "1630048897897",
      "count": "3",
      "source": "0",
      "seqId": 1234
    }
  ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
data	Array of objects	订阅的数据
> instId	String	产品ID，如 BTC-USDT
> tradeId	String	聚合的多笔交易中最新一笔交易的成交ID
> px	String	成交价格
> sz	String	成交数量 对于币币交易，成交数量的单位为交易货币 对于交割、永续以及期权，单位为张。
> side	String	吃单方向 buy sell
> ts	String	成交时间，Unix时间戳的毫秒数格式，如 1597026383085
> count	String	聚合的订单匹配数量
> source	String	订单来源 0：普通订单 1：流动性增强计划订单
> seqId	Integer	推送的序列号

聚合功能说明：

1. 系统将根据每个taker订单的不同成交价格，不同成交来源推送消息，并使用count字段表示聚合的订单匹配数量。
2. tradeId是聚合的多笔交易中最新一笔交易的 ID。
3. 当count = 1时，表示taker订单部分或完全成交时仅匹配了一个maker订单。
4. 当count > 1时，表示taker订单以相同价格匹配了多个maker订单。例如，如果tradeId = 123，且count = 3，表示该消息聚合了tradeId = 123, 122, 121的成交。maker侧有多笔价格相同的订单被成交。
5. 用户可以使用此数据与“全部交易”频道的数据进行对比。
6. 深度及聚合交易数据仍按顺序发布。

同时发生的不同交易推送数据的seqId可能相同。

WS / 全部交易频道

获取最近的成交数据，有成交数据就推送，每次推送仅包含一条成交数据。

URL Path

/ws/v5/business

请求示例

{
  "id": "1512",
    "op": "subscribe",
    "args": [{
        "channel": "trades-all",
        "instId": "BTC-USDT"
    }]
}

import asyncio

from okx.websocket.WsPublicAsync import WsPublicAsync

def callbackFunc(message):
    print(message)

async def main():
    ws = WsPublicAsync(url="wss://wspap.okx.com:8443/ws/v5/business")
    await ws.start()
    args = [
        {
          "channel": "trades-all",
          "instId": "BTC-USDT"
        }
    ]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求参数

参数	类型	是否必须	描述
id	String	否	消息的唯一标识。 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 subscribe unsubscribe
args	Array of objects	是	请求订阅的频道列表
> channel	String	是	频道名 trades-all
> instId	String	是	产品ID

成功返回示例

{
  "id": "1512",
    "event": "subscribe",
    "arg": {
        "channel": "trades-all",
        "instId": "BTC-USDT"
    },
  "connId": "a4d3ae55"
}

失败返回示例

{
  "id": "1512",
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"trades-all\", \"instId\" : \"BTC-USD-191227\"}]}",
  "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
  "arg": {
    "channel": "trades-all",
    "instId": "BTC-USDT"
  },
  "data": [
    {
      "instId": "BTC-USDT",
      "tradeId": "130639474",
      "px": "42219.9",
      "sz": "0.12060306",
      "side": "buy",
      "source": "0",
      "ts": "1630048897897"
    }
  ]
}

推送数据参数

参数名	类型	描述
arg	Array of objects	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
data	Array of objects	订阅的数据
> instId	String	产品ID，如 BTC-USDT
> tradeId	String	成交ID
> px	String	成交价格
> sz	String	成交数量 对于币币交易，成交数量的单位为交易货币 对于交割、永续以及期权，单位为张。
> side	String	成交方向 buy sell
> source	String	订单来源 0：普通订单 1：流动性增强计划订单
> ts	String	成交时间，Unix时间戳的毫秒数格式，如 1597026383085

WS / 深度频道

获取深度数据。在提前挂单阶段，best ask的价格有机会低于best bid。books是400档频道，books5是5档频道， bbo-tbt是先1档后实时推送的频道，books-l2-tbt是先400档后实时推送的频道，books50-l2-tbt是先50档后实时推的频道；

• books 首次推400档快照数据，以后增量推送，每100毫秒推送一次变化的数据
• books-elp（已弃用，请使用 books-rpi）仅推送ELP订单，首次推400档快照数据，以后增量推送，每100毫秒推送一次变化的数据
• books-rpi：合并有机和 RPI 深度。初始全量推送 400 档，之后每 100ms 推送增量。无 checksum，排序依赖 seqId/prevSeqId。每个 asks/bids 元素为 [price, totalQty, nonRpiQty, count]。取代 books-elp。
• books5 首次推5档快照数据，以后定量推送，每100毫秒当5档快照数据有变化推送一次5档数据
• bbo-tbt 首次推1档快照数据，以后定量推送，每10毫秒当1档快照数据有变化推送一次1档数据
• books-l2-tbt 首次推400档快照数据，以后增量推送，每10毫秒推送一次变化的数据
• books50-l2-tbt 首次推50档快照数据，以后增量推送，每10毫秒推送一次变化的数据
• 单个连接、交易产品维度，深度频道的推送顺序固定为：bbo-tbt -> books-l2-tbt -> books50-l2-tbt -> books -> books-elp -> books-rpi -> books5。
• 在相同连接下，用户将无法为相同交易产品同时订阅 books-l2-tbt 以及 books50-l2-tbt/books频道
  • 更多细节，请参阅更新日志 2024-07-17

books-l2-tbt400档深度频道，只允许交易手续费等级VIP4及以上的API用户订阅，其他用户接入将收到错误码64003。 books50-l2-tbt50档深度频道，只允许交易手续费等级VIP4及以上的API用户订阅，其他用户接入将收到错误码64003。

身份认证参考登录功能

服务地址

/ws/v5/public

请求示例

{
    "id": "1512",
    "op": "subscribe",
    "args": [{
        "channel": "books",
        "instId": "BTC-USDT"
    }]
}

import asyncio

from okx.websocket.WsPublicAsync import WsPublicAsync

def callbackFunc(message):
    print(message)

async def main():
    ws = WsPublicAsync(url="wss://wspap.okx.com:8443/ws/v5/public")
    await ws.start()
    args = [
      {
        "channel": "books",
        "instId": "BTC-USDT"
      }
    ]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求参数

参数	类型	是否必须	描述
id	String	否	消息的唯一标识。 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 subscribe unsubscribe
args	Array of objects	是	请求订阅的频道列表
> channel	String	是	频道名 books books5 bbo-tbt books-l2-tbt books50-l2-tbt
> instId	String	是	产品ID

返回示例

{
    "id": "1512",
    "event": "subscribe",
    "arg": {
        "channel": "books",
        "instId": "BTC-USDT"
    },
    "connId": "a4d3ae55"
}

失败示例

{
    "id": "1512",
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"books\", \"instId\" : \"BTC-USD-191227\"}]}",
    "connId": "a4d3ae55"
}

返回参数

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

推送示例 ：全量

{
    "arg": {
        "channel": "books",
        "instId": "BTC-USDT"
    },
    "action": "snapshot",
    "data": [{
        "asks": [
            ["8476.98", "415", "0", "13"],
            ["8477", "7", "0", "2"],
            ["8477.34", "85", "0", "1"],
            ["8477.56", "1", "0", "1"],
            ["8505.84", "8", "0", "1"],
            ["8506.37", "85", "0", "1"],
            ["8506.49", "2", "0", "1"],
            ["8506.96", "100", "0", "2"]
        ],
        "bids": [
            ["8476.97", "256", "0", "12"],
            ["8475.55", "101", "0", "1"],
            ["8475.54", "100", "0", "1"],
            ["8475.3", "1", "0", "1"],
            ["8447.32", "6", "0", "1"],
            ["8447.02", "246", "0", "1"],
            ["8446.83", "24", "0", "1"],
            ["8446", "95", "0", "3"]
        ],
        "ts": "1597026383085",
        "checksum": 0,
        "prevSeqId": -1,
        "seqId": 123456
    }]
}

推送示例：增量

{
    "arg": {
        "channel": "books",
        "instId": "BTC-USDT"
    },
    "action": "update",
    "data": [{
        "asks": [
            ["8476.98", "415", "0", "13"],
            ["8477", "7", "0", "2"],
            ["8477.34", "85", "0", "1"],
            ["8477.56", "1", "0", "1"],
            ["8505.84", "8", "0", "1"],
            ["8506.37", "85", "0", "1"],
            ["8506.49", "2", "0", "1"],
            ["8506.96", "100", "0", "2"]
        ],
        "bids": [
            ["8476.97", "256", "0", "12"],
            ["8475.55", "101", "0", "1"],
            ["8475.54", "100", "0", "1"],
            ["8475.3", "1", "0", "1"],
            ["8447.32", "6", "0", "1"],
            ["8447.02", "246", "0", "1"],
            ["8446.83", "24", "0", "1"],
            ["8446", "95", "0", "3"]
        ],
        "ts": "1597026383085",
        "checksum": 0,
        "prevSeqId": 123456,
        "seqId": 123457
    }]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
action	String	推送数据动作，增量推送数据还是全量推送数据 snapshot：全量 update：增量
data	Array of objects	订阅的数据
> asks	Array of Arrays	卖方深度
> bids	Array of Arrays	买方深度
> ts	String	数据更新时间戳，Unix时间戳的毫秒数格式，如 1597026383085 例外： 对于bbo-tbt 频道，ts 为撮合引擎触发时的时间戳
> checksum	Integer	检验和（已弃用）。该字段仍会在 books、books-l2-tbt、books50-l2-tbt 推送中保留，但其值固定为 0，不应再用于数据完整性校验。请改用 seqId/prevSeqId 校验数据的连续性和准确性。
> prevSeqId	Integer	上一个推送的序列号。仅适用 books，books-l2-tbt，books50-l2-tbt
> seqId	Integer	推送的序列号 （下方注解）

asks和bids值数组举例说明： ["411.8", "10", "0", "4"]

• 411.8为深度价格
• 10为此价格的数量 （合约交易为张数，现货/币币杠杆为交易币的数量
• 0该字段已弃用(始终为0)
• 4为此价格的订单数量

如果需要订阅多个50或400档频道，建议通过多个链接进行订阅，每个链接低于30条频道。

集合竞价期间，深度数据大约每秒更新一次

books/books5/bbo-tbt/books-l2-tbt/books50-l2-tbt不包含ELP订单 books-elp仅返回 ELP 订单，包含有效部分及无效部分（无效部分指 ELP 买单价格高于非 ELP 订单最佳买单价；或 ELP 卖单价格低于非 ELP 订单最佳卖单价）。用户需根据非 ELP 订单的最佳买/卖价区分有效部分和无效部分。

序列号

seqId是交易所行情的一个序号。如果用户通过多个websocket连接同一频道，收到的序列号会是相同的。每个instId对应一套。用户可以使用在增量推送频道的prevSeqId和seqId来构建消息序列。这将允许用户检测数据包丢失和消息的排序。正常场景下seqId的值大于prevSeqId。新消息中的prevSeqId与上一条消息的seqId匹配。最小序列号值为0，除了快照消息的prevSeqId为-1。

异常情况：

1. 如果一段时间内（约 60 秒）没有深度更新，对于定量推送频道，OKX 会推送最近的一条更新，对于增量推送频道，OKX将发一条消息'asks': [], 'bids': []以通知用户连接是正常的。推送的seqId跟上一条信息的一样，prevSeqId等于seqId。
2. 序列号可能由于维护而重置，在这种情况下，用户将收到一条seqId小于prevSeqId的增量消息。随后的消息将遵循常规的排序规则。

示例

1. 快照推送：prevSeqId = -1，seqId = 10
2. 增量推送1（正常更新）：prevSeqId = 10，seqId = 15
3. 增量推送2（无更新）：prevSeqId = 15，seqId = 15
4. 增量推送3（序列重置）：prevSeqId = 15，seqId = 3
5. 增量推送4（正常更新）：prevSeqId = 3，seqId = 5

bbo-tbt 频道推送示例

{
  "arg": {
    "channel": "bbo-tbt",
    "instId": "BCH-USDT-SWAP"
  },
  "data": [
    {
      "asks": [
        [
          "111.06","55154","0","2"
        ]
      ],
      "bids": [
        [
          "111.05","57745","0","2"
        ]
      ],
      "ts": "1670324386802",
      "seqId": 363996337
    }
  ]
}

books5 频道推送示例

{
  "arg": {
    "channel": "books5",
    "instId": "BCH-USDT-SWAP"
  },
  "data": [
    {
      "asks": [
        ["111.06","55154","0","2"],
        ["111.07","53276","0","2"],
        ["111.08","72435","0","2"],
        ["111.09","70312","0","2"],
        ["111.1","67272","0","2"]],
      "bids": [
        ["111.05","57745","0","2"],
        ["111.04","57109","0","2"],
        ["111.03","69563","0","2"],
        ["111.02","71248","0","2"],
        ["111.01","65090","0","2"]],
      "instId": "BCH-USDT-SWAP",
      "ts": "1670324386802",
      "seqId": 363996337
    }
  ]
}

WS / 期权公共成交频道

获取最近的期权成交数据，有成交数据就推送，每次推送仅包含一条成交数据。

URL Path

/ws/v5/public

请求示例

{
    "id": "1512",
    "op": "subscribe",
    "args": [{
        "channel": "option-trades",
        "instType": "OPTION",
        "instFamily": "BTC-USD"
    }]
}

import asyncio

from okx.websocket.WsPublicAsync import WsPublicAsync

def callbackFunc(message):
    print(message)

async def main():
    ws = WsPublicAsync(url="wss://wspap.okx.com:8443/ws/v5/public")
    await ws.start()
    args = [{
        "channel": "option-trades",
        "instType": "OPTION",
        "instFamily": "BTC-USD"
    }]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求参数

参数	类型	是否必须	描述
id	String	否	消息的唯一标识。 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 subscribe unsubscribe
args	Array of objects	是	请求订阅的频道列表
> channel	String	是	频道名 option-trades
> instType	String	是	产品类型，OPTION：期权
> instId	String	可选	产品ID，如 BTC-USD-221230-4000-C，instId 和 instFamily 必须传一个，若传两个，以 instId 为主
> instFamily	String	可选	交易品种，如 BTC-USD

成功返回示例

{
    "id": "1512",
    "event": "subscribe",
    "arg": {
        "channel": "option-trades",
        "instType": "OPTION",
        "instFamily": "BTC-USD"
    },
    "connId": "a4d3ae55"
}

失败返回示例

{
    "id": "1512",
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"option-trades\"}]}",
    "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
    "arg": {
        "channel": "option-trades",
        "instType": "OPTION",
        "instFamily": "BTC-USD"
    },
    "data": [
        {
            "fillVol": "0.5066007836914062",
            "fwdPx": "16469.69928595038",
            "idxPx": "16537.2",
            "instFamily": "BTC-USD",
            "instId": "BTC-USD-230224-18000-C",
            "markPx": "0.04690107010619562",
            "optType": "C",
            "px": "0.045",
            "side": "sell",
            "sz": "2",
            "tradeId": "38",
            "ts": "1672286551080"
        }
    ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
data	Array of objects	订阅的数据
> instId	String	产品ID
> instFamily	String	交易品种
> tradeId	String	成交ID
> px	String	成交价格
> sz	String	成交数量，单位为张。
> side	String	成交方向 buy：买 sell：卖
> optType	String	期权类型，C：看涨期权 P：看跌期权 ，仅适用于期权
> fillVol	String	成交时的隐含波动率（对应成交价格）
> fwdPx	String	成交时的远期价格
> idxPx	String	成交时的指数价格
> markPx	String	成交时的标记价格
> ts	String	成交时间，Unix时间戳的毫秒数格式， 如1597026383085

该频道订阅成功后的首条数据可能为最近一笔成交的缓存数据，请忽略。

WS / 集合竞价信息频道

获取集合竞价相关信息

URL Path

/ws/v5/public

请求示例

{
    "id": "1512",
    "op": "subscribe",
    "args": [{
        "channel": "call-auction-details",
        "instId": "ONDO-USDC"
    }]
}

import asyncio

from okx.websocket.WsPublicAsync import WsPublicAsync

def callbackFunc(message):
    print(message)

async def main():
    ws = WsPublicAsync(url="wss://wspap.okx.com:8443/ws/v5/public")
    await ws.start()
    args = [{
        "channel": "call-auction-details",
        "instId": "ONDO-USDC"
    }]

    await ws.subscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

    await ws.unsubscribe(args, callback=callbackFunc)
    await asyncio.sleep(10)

asyncio.run(main())

请求参数

参数	类型	是否必须	描述
id	String	否	消息的唯一标识。 用户提供，返回参数中会返回以便于找到相应的请求。 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度必须要在1-32位之间。
op	String	是	操作 subscribe unsubscribe
args	Array of objects	是	请求订阅的频道列表
> channel	String	是	频道名 call-auction-details
> instId	String	是	产品ID

成功返回示例

{
  "id": "1512",
  "event": "subscribe",
  "arg": {
      "channel": "call-auction-details",
      "instId": "ONDO-USDC"
    },
  "connId": "a4d3ae55"
}

失败返回示例

{
  "id": "1512",
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"call-auction-details\", \"instId\" : \"BTC-USD-191227\"}]}",
  "connId": "a4d3ae55"
}

返回参数

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

推送示例

{
  "arg": {
    "channel": "call-auction-details",
    "instId": "ONDO-USDC"
  },
  "data": [
        {
            "instId": "ONDO-USDC",
            "unmatchedSz": "9988764",
            "eqPx": "0.6",
            "matchedSz": "44978",
            "state": "continuous_trading",
            "auctionEndTime": "1726542000000",
            "ts": "1726542000007"
        }
  ]
}

推送数据参数

参数名	类型	描述
arg	Object	订阅成功的频道
> channel	String	频道名
> instId	String	产品ID
data	Array of objects	订阅的数据
> instId	String	产品ID
> eqPx	String	均衡价格
> matchedSz	String	买卖双边的匹配数量，单位为交易货币
> unmatchedSz	String	未匹配数量
> auctionEndTime	String	集合竞价结束时间，Unix时间戳的毫秒数格式，如 1597026383085
> state	String	交易状态 call_auction：集合竞价 continuous_trading：连续交易
> ts	String	数据产生时间，Unix时间戳的毫秒数格式，如 1597026383085

在集合竞价期间，用户可以获取均衡价格、匹配数量、未匹配数量和集合竞价结束时间的更新。数据大约每秒更新一次。当集合竞价结束时，该频道将推送最后一条消息，返回实际开盘价、匹配数量和未匹配数量，交易状态state为continuous_trading。

SBE 行情数据

概述

以下 WebSocket 频道返回的数据支持简单二进制编码（SBE）：

• WS / 交易频道：trades
• WS / 深度频道：bbo-tbt 和 books-l2-tbt

XML Schema

SBE XML schema 已经发布：

下载 XML Schema

基本信息

• bbo-tbt 频道无用户等级限制，但需登录后方可订阅；trades 与 books-l2-tbt 频道在实盘环境仅对交易费等级 VIP4 及以上 用户开放，其他用户接入将收到错误码64003。在模拟盘环境仅对交易费等级 VIP1 及以上 用户开放。
• SBE 频道将使用新的 WebSocket URL。

实盘交易：wss://ws.okx.com:8443/ws/v5/public-sbe

模拟盘交易：wss://wspap.okx.com:8443/ws/v5/public-sbe

• 同一个连接上会同时存在 JSON 和 SBE 格式的数据，可以通过 WebSocket 帧类型区分。opcode 1 表示 JSON，opcode 2 表示 SBE。
• 价格和数量将会使用尾数和指数来表示。例如，尾数为 123456，指数为 -4，表示 12.3456（实际值 = 尾数 * 10 ^ 指数）。
• 获取交易产品基础信息 接口会新增整数类型的 instIdCode 字段，SBE 协议将会使用该字段代表交易产品，用户需要将 instIdCode 映射为 instId. 请注意 instIdCode 在交易产品重新上币时会发生改变，然而，instIdCode 在 instId 重命名时保持不变。
• tsUs 和 outTime 来自不同的服务，因此它们的相对顺序无法保证。
• tsUs 是微秒格式时间戳，但是仅精确到毫秒。毫秒时间加上 000 得到微秒格式时间。比如：毫秒时间 1726233600001 对应的微秒格式时间 (tsUs) 为 1726233600001000。

接入信息

• 需在 WebSocket 连接请求头中添加 API key 和 签名进行登录：
  • 连接请求必须包含以下内容：
    • OK-ACCESS-KEY：API 密钥，字符串格式。
    • OK-ACCESS-SIGN：Base64 编码的签名。
    • OK-ACCESS-TIMESTAMP：Unix Epoch 时间（秒），例如：1751335333。
    • OK-ACCESS-PASSPHRASE：创建 API 密钥时指定的 Passphrase。
  • OK-ACCESS-SIGN 头的生成方式如下：
    • 准备签名前字符串：timestamp + method + requestPath
    • 准备 SecretKey。
    • 使用 HMAC SHA256 算法对签名前字符串进行签名。
    • 将签名编码为 Base64 格式。例如：sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(timestamp + 'GET' + '/users/self/verify', SecretKey))
    • timestamp 示例：const timestamp = '' + Date.now() / 1,000，例如 1704876947。
    • method：始终为 'GET'。
    • requestPath：始终为 '/users/self/verify'。
  • HTTP 响应状态码 101 表示登录成功。
  • HTTP 响应状态代码 401 表示登录失败，响应体中会包含报错消息，报错消息采用 JSON 格式。

登录报错示例：
{
    "msg": "Invalid apiKey",
    "code": "60005"
    "connId":"24a2aea3"
}

• 订阅请求必须以 JSON 格式发送，响应也将采用 JSON 格式，可通过 opcode 1识别是否为 JSON 格式的消息。
  • 协议类似于现有的 JSON 格式订阅请求/响应。
  • 区别在于应该使用 instIdCode 而非 instId。

订阅请求示例
{
    "op": "subscribe",
    "args": [
        {
            "channel": "trades",
            "instIdCode": 211874
        }
    ]
}

订阅响应示例
{
    "event": "subscribe",
    "arg": {
        "channel": "trades",
        "instIdCode": 211874
    },
    "connId": "accb8e21"
}

• 通知事件支持 JSON 格式：

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

• 服务端在收到 pong 帧 20 秒后会发送一次操作码为 9 的 ping 帧。
  • 如果 WebSocket 服务器在 60 秒内未收到 pong 帧，连接将自动断开。
  • 收到 ping 帧后，需尽快以 opcode 10 的 pong 帧响应，并复制 ping 帧的 payload（payload为随机数字文本，如 11446744073709551615）。
  • 允许发送未经请求的 pong 帧，但无法阻止断开连接。建议这些 pong 帧的 payload 为空。
• 对于 trades、bbo-tbt 和 books-l2-tbt 频道，数据将以 SBE 二进制格式返回，可以通过 opcode 2 识别，通过 template ID 区分频道。与现有的 JSON 格式连接相比，主要区别包括：
  • 对于 trades 频道，返回 seqId。
  • 对于 bbo-tbt 频道，提供实时数据，但在系统超载时可能会发生数据丢失，不同连接的数据可能会不一样。
  • 对于 books-l2-tbt：
    • 当价格和数量的小数位发生变化时，会推送指数更新消息（template ID: 1002），包含上一个推送的序列号和当前推送的序列号，可以通过 template ID 进行识别。为了保持序列号一致性，必须处理指数更新消息。
    • 将不再返回 checksum。
    • 订阅后不再推送初始快照数据。但是，欧易 将提供 REST API 接口：获取产品 SBE 深度，返回 SBE 二进制格式的 400 档快照数据。该接口约每 500 毫秒更新一次，收到请求后不会立刻返回，而是会待服务端缓存数据更新后立即返回最新数据。
• 频道与事件的关系不是一一对应的。books-l2-tbt 包含两种类型的事件。映射关系如下所示。

频道	XML Template ID 和 message name
bbo-tbt	1000: BboTbtChannelEvent
books-l2-tbt	1001: BooksL2TbtChannelEvent 1002: BooksL2TbtExponentUpdateEvent
books-l2-tbt-elp （未启用）	1003: BooksL2TbtElpChannelEvent 1004: BooksL2TbtElpExponentUpdateEvent
trades	1005: TradesChannelEvent

• 如何正确管理本地订单簿
  1. 打开 SBE WebSocket 连接并订阅 books-l2-tbt 频道。
  2. 缓存从频道中接收的事件。记录您接收到的第一个事件的 prevSeqId。 注意：对于 template ID 1002 是指数更新事件，仅包含指数更新信息，不包含买入和卖出数据。对于模板ID 1001，会包含买入和卖出数据。
  3. 从 /books-sbe 获取深度快照，例如 https://openapi.okx.com/api/v5/market/books-sbe?instIdCode=12345&source=0
  4. 如果快照的 seqId 小于步骤 2 中的 prevSeqId，请返回步骤 3。
  5. 在缓存的事件中，丢弃事件 seqId <= 快照 seqId 的任何事件。
  6. 对于缓存中的第一个事件，满足该条件： seqId： 事件prevSeqId <= 快照 seqId < 事件 seqId。
  7. 将您的本地订单簿设置为本地快照。它的序列号就是快照 seqId。
  8. 对所有缓存的事件，使用下面的流程处理，同样适用于所有后续接收的事件。
  • 如果 template ID 为 1002（BooksL2TbtExponentUpdateEvent），则仅更新指数，不包含买入和卖出数据。如果 template ID 为 1001（BooksL2TbtChannelEvent），则按照以下流程处理。
  • 对于 bids 和 asks 中的每组价格数据，在订单簿中更新数量：
    • 如果价格数据在订单簿中不存在，则插入新数量。
    • 如果数量为零，则从订单簿中删除价格数据。
  • 将订单簿序列号设置为最新的序列号(seqId)。

注意：不是所有快照 seqId 都会出现在 books-l2-tbt 频道中。

• 序列号

seqId是交易所行情的一个序号。如果用户通过多个websocket连接同一频道，收到的序列号会是相同的。每个instIdCode对应一套。用户可以使用在增量推送频道的prevSeqId和seqId来构建消息序列。这将允许用户检测数据包丢失和消息的排序。正常场景下seqId的值大于prevSeqId。新消息中的prevSeqId与上一条消息的seqId匹配。最小序列号值为0，除了快照消息的prevSeqId为-1。

异常情况：

1. 如果一段时间内（约 60 秒）没有深度更新，对于定量推送频道，OKX 会推送最近的一条更新，对于增量推送频道，OKX将发一条 numInGroup: 0 的消息以通知用户连接是正常的。推送的seqId跟上一条信息的一样，prevSeqId等于seqId。

2. 序列号可能由于维护而重置，在这种情况下，用户将收到一条seqId小于prevSeqId的增量消息。随后的消息将遵循常规的排序规则。

示例

1. 增量推送1（正常更新）：prevSeqId = 10，seqId = 15
2. 增量推送2（无更新）：prevSeqId = 15，seqId = 15
3. 增量推送3（序列重置）：prevSeqId = 15，seqId = 3
4. 增量推送4（正常更新）：prevSeqId = 3，seqId = 5

SBE 订单簿

这是一个公共接口，返回初始 400 档快照的 SBE 二进制数据。该接口约每 500 毫秒更新一次，收到请求后不会立刻返回，而是会待服务端缓存数据更新后立即返回最新数据。

注意：如果请求失败，错误消息的格式将会是 JSON。

对于 HTTP 请求头，不需要设置为 application/sbe；但是，如果请求成功，响应头为 Content-Type: application/sbe，如果请求失败，则为 Content-Type: application/json。

限速：10 次/10 秒

限速规则：IP + instIdCode

HTTP 请求

GET /api/v5/market/books-sbe

请求示例

GET /api/v5/market/books-sbe?instIdCode=12345&source=0

请求参数

参数名	类型	是否必须	描述
instIdCode	Integer	是	产品 ID 唯一标识码。
source	Integer	是	订单簿的来源。 0: 普通

返回示例

错误消息示例

返回头：
Content-Type: application/json

返回 body：
{
    "code": "51000",
    "msg": "Parameter instIdCode error",
    "data": []
}

返回参数

请参考 XML schema 中 ID 为 1006 的 SnapshotDepthResponseEvent。

新增错误码

错误码	HTTP 状态码	错误提示
60034	401	该频道仅支持手续费等级为 {0} 及以上的用户订阅使用

升级

• 通常情况下，升级是兼容的（例如新增一个字段）。这种情况下，XML schema ID 不会变化，但 schema version 会增加。
• 如果涉及不兼容的变更，则会至少提前 1–2 个月发布新的 XML schema（使用新的 schema ID）。在过渡期结束前，你需要做好同时使用新旧 XML schema 处理数据的准备（基于他们的 schema ID 和 version）。