Gate API v4 v4.27.0

下方有示例代码，请求和返回示例。 点击上方的语言 tab 来切换各语言的代码示例。

欢迎使用 Gate.io API

APIv4 接口提供了现货、杠杆、合约交易相关的操作，包括公共接口查询市场行情，以及需要认证的私有接口， 实现基于 API 的自动交易。

访问链接

REST API BaseURL:

• 实盘交易: https://api.gateio.ws/api/v4
• 合约模拟交易: https://fx-api-testnet.gateio.ws/api/v4
• 合约实盘交易备选入口（只适用合约 API）：https://fx-api.gateio.ws/api/v4

SDK

可用 SDK:

• Python (opens new window)
• Java (opens new window)
• PHP (opens new window)
• Go (opens new window)
• C# (opens new window)
• NodeJS (opens new window)
• Javascript (opens new window)

部分 SDK 除了各接口的示例文档以外，还额外提供了调用 SDK 的示例应用程序。 示例应用程序提供了一个相对更加丰富的 SDK 使用示例，可以完整构建运行， 具体使用方式参考各 SDK 的示例程序说明

• Python (opens new window)
• Java (opens new window)
• C# (opens new window)
• Go (opens new window)

关于APIv4 Key升级

2020 年 4 月

APIv4 最开始合约的 Key 与现货的是分开管理的。不过从现在开始我们对 APIv4 的 Key 进行了升级改造。 用户现在可以创建多个 Key，而且可以为每个 Key 配置不同的操作权限。比如你可以创建一个 Key 同时拥有现货的读写和合约的读写权限，这样的话只需要一个 Key 就可以同时操作现货和合约交易。

用户原有的 Key 会无缝迁移到新的管理方案，原先的 Key 在新的管理模式下，对应一个 Key 只配置了现货的权限，另一个 Key 只配置了合约的权限，用户可以使用新的管理模式对迁移后的 Key 重新配置权限。

与 APIv2 的区别

APIv4 是一套全新的 HTTP REST API ，独立于 APIv2 。APIv4 提供了完整的交易功能，增强了 API 的认证鉴权。另外 APIv4 基于 OpenAPI 标准 (opens new window) 书写，SDK 和文档通过同一套 API 标准生成，确保文档和程序的完整一致。

APIv4 与 APIv2 在使用上有如下区别：

1. 两者的 API Key 是独立的。 APIv2 在个人账户的 APIKeys 入口申请。而 APIv4 在个人账户的 APIv4Keys 页面申请。
2. APIv2 在交易操作上只支持现货交易，APIv4 支持现货、杠杆和合约的完整交易操作

如何选择：

1. 如果需要杠杆或合约交易，选择 APIv4
2. 如果只需要现货交易或者钱包操作，则根据个人当前状况自行选择

市商申请

为进一步提高平台盘口深度和交易流动性，我们将通过公开透明的方式招募机构做市商，根据为平台流动性做出的贡献情况，为专业机构做市商提供专业的做市商手续费率方案。

1. 提供 Gateio UID
2. 提供他所交易量截图或VIP等级等
3. 简述做市方法及规模

提供以上内容提交至 mm@gate.io ，我们将在3个工作日内受理。

TIP

VIP11及以上需在个人中心开启GT抵扣，才可享有专业市商费率。

技术支持

使用过程中如有问题或者建议，您可以选择以下任意方式联系我们：

• 提交工单反馈
• 在线工单反馈
• 将您的联系方式与问题发送至 mm@gate.io ，我们将为您分配技术专员为您服务

如您遇到API错误，建议您整理以下内容，方便我们为您快速分析问题：

1. 问题描述
2. Gateio UID
3. 请求的地址与参数
4. 错误代码
5. 返回结果

DANGER

即使是提交问题，也切勿将API key信息提交给客服及他人，否则会有严重的资产风险。如果已经不小心泄漏，请将已有API删除并重新生成。

Changelog

v4.27.0

2022-07-29

• GET /delivery/{settle}/tickers 接口，新增 basis_rate、basis_value 两个字段
• 新增 X-Client-Request-Id 请求 ID header，可以用来追踪请求
• 新增合约批量下单接口，POST /futures/{settle}/batch_orders
• 新增合约交易下单FOK订单类型

v4.26.0

2022-07-15

• 现货自动单支持统一帐户
• 新增 GET /wallet/saved_address 接口，获取提币白名单地址
• POST /wallet/transfers 接口，支援操作单号返回
• 新增 GET /wallet/sub_account_cross_margin_balances 接口，查询子账号全仓杠杆账户余额信息
• GET /margin/currency_pairs 接口、新增 status 字段

v4.25.1

2022-07-06

• 新增 GET /spot/time 获取服务器当前时间接口
• 获取交易对 ticker 信息 GET /spot/tickers，新增 change_utc0, change_utc8 字段
• 新增 GET /options/my_settlements 查询期权个人结算记录接口

v4.25.0

2022-06-24

• 支持统一帐户 API
• 全仓账户增加多个返回字段，详细请查看接口描述
• 全仓币种增加返回字段 status，判断全仓币种是否禁用 0-禁用 1-启用
• 现货交易增加接口POST /spot/cross_liquidate_orders，处理全仓币种禁用时平仓买入下单
• 获取合约账号接口新增 bonus 理财金字段和 history 累计统计数据字段
• 合约个人成交记录新增 text 订单的自定义信息,fee 成交手续费,point_fee成交点卡手续费等字段
• 订正撤销单个自动单名称
• POST /wallet/sub_account_transfers 支持划转到全仓杠杆账户

v4.24.0

2022-05-20

• 新增 /flash_swap 闪兑 API ，支持直接通过 API 方式进行闪兑操作，接口组关联现货权限
• 钱包新增 GET /wallet/sub_account_margin_balances , GET /wallet/sub_account_futures_balances 接口，方便主账号查询子账号的逐仓杠杆账户和永续合约账户的余额信息
• 永续合约新增 API GET /futures/{settle}/index_constituents/{index} 查询指数来源信息
• 修复合约自动订单 FuturesPriceTriggeredOrder 缺少 order_type 等字段的定义

v4.23.4

2022-04-25

• 永续合约新增订单修改接口 PUT /futures/{settle}/orders/{order_id}
• 现货 K 线查询支持 30d 粒度

v4.23.3

2022-04-01

1. 现货 K 线增加基础货币成交量返回
2. 现货币种信息返回增加该币所在链的信息
3. 钱包接口 GET /wallet/currency_chains 增加币种的充提状态返回
4. 永续合约双仓模式下增加缺失的全仓杠杆 cross_leverage_limit 参数
5. 永续、交割合约查询 K 线新增多个时间粒度的支持

v4.23.2

2022-01-21

1. 提现充值历史增加 fee 字段返回
2. 现货 Currency 币种模型增加固定费率

v4.23.1

2021-12-23

1. 现货下单 time_in_force 增加新类型 FOK
2. 新增错误代码 FOK_NOT_FILL

v4.23.0

2021-12-09

1. 新增期权 API
2. 新增详细的限速规则说明
3. 新增 GET /wallet/currency_chains 查询币种支持的链
4. 提现充值历史增加新的 status 可选值

v4.22.4

2021-11-01

1. SpotPriceTriggeredOrder 字段 ctime 和 ftime 更正为 int64

v4.22.3

2021-10-27

1. GET /spot/trades 支持指定 from 和 to 按时间范围筛选的查询

v4.22.2

2021-09-29

1. 提现充值记录新增 status 字段的可选值
2. 合约下单新增 auto_size 只写字段用于双向持仓模式的平仓操作

v4.22.1

2021-09-07

1. 新增钱包接口 GET /wallet/total_balance 获取用户总资产
2. 逐仓杠杆账户返回增加locked 和 risk 字段
3. 逐仓和全仓杠杆借入支持输入自定义 text

v4.22.0

2021-08-13

1. 交割合约支持 BTC 结算
2. 现货 API GET /spot/orders 和 GET /spot/my_trades 支持按时间范围筛选
3. 逐仓和全仓支持查询用户最大借入额度

v4.21.6

2021-08-12

1. 修复 GET /wallet/deposit_address 地址链字段错误名称

v4.21.5

2021-06-30

• 针对已结束的单子， GET /spot/orders, GET /spot/orders/{order_id} 以及 GET /spot/my_trades 接口可以不用指定 currency_pair 参数
• GET /wallet/withdraw_status 返回增加多链的固定提现手续费返回
• 新增 GET /margin/transferable and GET /margin/cross/transferable API 查询逐仓和全仓账户允许的最大转出额度
• 合约平仓历史 API 新增 from 和 to 的时间范围查询参数

v4.21.4

2021-06-23

• 新增全仓杠杆账户变动历史查询 GET /margin/cross/account_book
• 逐仓账户历史 GET /margin/account_book 返回增加毫秒时间戳

v4.21.3

2021-06-17

• 现货、合约深度增加时间戳返回

v4.21.2

2021-06-07

• 合约 API 新增对全仓杠杆调整的支持
• 新增 /margin/cross 全仓杠杆 API
• 新增现货下单对全仓杠杆账户的支持
• 逐仓杠杆账户查询返回新增账户未还利息
• 现货订单信息新增 create_time_ms 和 update_time_ms 毫秒时间返回
• 新增取消提现接口 DELETE /withdrawals/{withdrawal_id}

v4.20.1

2021-04-14

• 更新文档部分链接

v4.20.0

2021-03-25

• 增加现货自动订单接口组 /spot/price_orders

v4.19.6

2021-03-22

• 现货交易对查询增加开盘时间返回

v4.19.5

2021-03-18

• 指定订单 ID 的现货、永续合约操作支持使用用户自定义 ID（只在订单创建后的 30 分钟内有效）。

v4.19.4

2021-03-10

• /wallet/sub_account_transfers 接口支持转账到子账户的合约账户

v4.19.3

2021-03-04

• 新增杠杆借贷自动还款设置和查询接口 /margin/auto_repay
• /wallet/deposit_address 接口新增 multichain_address 字段，返回某些币种的多充值地址
• 优化部分文档内容

v4.19.2

2021-03-01

• 新增 /wallet/fee 接口用于查询交易费率，原有 /spot/fee 接口废弃
• 提现操作增加 chain 字段
• 合约深度查询 /futures/{settle}/order_book 增加 with_id 字段的说明，返回内容增加深度 ID 的说明
• 合约个人平仓历史查询 /futures/{settle}/position_close 增加 offset 参数，用于翻页获取历史平仓记录
• 增加合约价值的计算方法说明，具体参考 Contract 模型的描述
• 修复合约统计数据字段类型错误

v4.18.4

2021-01-22

• 现货 Trade 模型新增 create_time_ms 字段
• ETF 交易对 Ticker 增加净值等相关信息返回

v4.18.1

2021-01-07

• 现货下单新增冰山委托支持
• 修复 /futures/{settle}/contract_stats 返回数据的错误字段类型

v4.18.0

2020-12-21

• 现货新增 /spot/currencies 和 /spot/currencies/{currency} 查询币种信息
• 合约 ContractStat 返回新增 top_lsr_account 和 top_lsr_size 等多个字段

v4.17.1

2020-12-16

• /spot/order_book 接口 limit 字段最大值增加到 100

v4.17.0

2020-12-15

• 新增子账号余额查询接口 /wallet/sub_account_balances

v4.16.1

2020-12-10

• 修复 Position 模型定义里的错误字段名称 dual_mode 。正确应该是 mode

v4.16.0

2020-12-09

现货

• POST /spot/batch_orders 每个交易对可以创建的 order 数量提高到 10 个
• 现货 GET /spot/trades 新增 reverse 参数支持时间逆序查询历史记录

合约

• 永续合约新增双仓支持 API ，/futures/{settle}/dual_mode 接口设置是否开启双仓。 双仓相关的仓位操作参照 /futures/{settle}/dual_comp/positions 接口组
• 永续合约账户返回新增 in_dual_mode ，仓位返回新增 dual_mode
• 永续合约新增 /futures/{settle}/liq_orders 支持查询市场强平记录

v4.15.5

2020-11-04

• 新增 API /futures/{settle}/contract_stats 获取合约统计信息
• 新增 API /margin/{currency_pair} 获取单个杠杆交易对详情

v4.15.4

2020-09-01

• GET /spot/fee 接口返回新增 point_type 字段
• 新增 API GET /wallet/withdraw_status
• 新增了 C# SDK 入口

v4.15.2

2020-08-12

• 新增 GET /spot/fee 获取个人现货交易费率

v4.15.1

2020-08-04

• 新增获取现货市场所有当前委托 GET /spot/open_orders
• 新增杠杆账户余额变更历史 GET /margin/account_book

v4.14.1

2020-07-08

• 订单里的 text 字段最大允许长度提高到了 28 个字节（不包括前缀）

v4.14.0

2020-07-06

• 交割合约引擎 API /delivery 上线

v4.13.1

2020-06-28

• 新增 GET /wallet/sub_account_transfers 接口查询主子账号划转历史

v4.13.0

2020-05-20

• 增加了对提现操作的支持，详情关注 POST /withdrawals 接口和“认证”一节
• 账户划转 POST /wallet/transfers 支持现货到合约了。
• 钱包接口新增了提现充值历史记录查询
• 合约订单和个人成交列表支持传入 offset 参数
• 合约 Contract 模型添加新字段 in_delisting

v4.12.0

2020-04-08

• 升级 APIv4 的 Key ，不再按功能独立 Key，每个 Key 都可以独立配置多个功能的权限， 详细说明参考 “关于 APIv4 Key 升级” 一节
• 新增接口 POST /wallet/sub_account_transfers 支持主子账号余额划转
• GET /spot/candlesticks 增加请求参数 from 和 to ，方便获取历史数据

v4.11.2

2020-03-29

• Order 模型增加字段 filled_total 替换命名容易引起误解的 fill_price
• 添加新的错误码标识 POC_FILL_IMMEDIATELY

v4.11.1

2020-03-23

• 个人成交记录 GET /spot/my_trades 返回增加 role 交易角色信息
• 修复查询币币理财账户 GET /margin/funding_accounts 缺少未使用过理财的币种的问题

v4.11.0

2020-03-20

• 现货下单支持 GT 抵扣费率折扣
• 现货下单 Time in force 支持传入 poc

v4.10.1

2020-02-24

• 现货交易对新增字段 trade_status

v4.10.0

2020-02-17

• 杠杆下单支持传入 auto_borrow 字段（只写），在余额不足时由系统自动借入不足部分
• 增加指定订单 ID 的批量撤单接口 POST /spot/cancel_batch_orders
• 补充“错误处理”和“与 APIv2 的区别”文档

v4.9.1

2020-01-07

• Order 和 BatchOrder 新增订单最近修改时间、成交费率的返回
• GET /spot/my_trades 增加成交费率返回

v4.9.0

2019-12-17

• GET /futures/{settle}/trades 不再支持 last_id 参数，改用 from 和 to 来获取历史成交

v4.8.2

2019-12-02

• 新增 /spot/batch_orders 支持现货和杠杆的批量下单操作
• 杠杆还款产生的手续费率支持用户等级折扣
• Loan 模型里增加了 fee_rate 字段标识杠杆借出单的手续费率，orig_id 标识续借单的原始借出单 ID

v4.8.1

2019-11-27

• 修复 GET /futures/{settle}/positions 文档和代码示例缺少 settle 字段的说明和使用

v4.8.0

2019-11-07

• 合约 API 支持以 USDT 结算
• 原有的以 /futures 为前缀的所有接口前缀统一调整为 /futures/{settle} ，以支持基于多种结算货币的合约操作。
• /futures/{settle}/accounts 返回的账户信息里 currency 增加 USDT 的返回
• /futures/{setttle}/tickers 返回的交易量信息新增 volume_24h_base, volume_24h_quote 和 volume_24h_settle 字段，取代原有 volume_24h_btc 和 volume_24h_usd 的使用。 后两个字段为了兼容依然保留，但是新的操作不推荐继续使用。

将 /futures 替换成 /futures/usdt 就可以使用 USDT 结算的合约操作, 例如 GET /futures/usdt/accounts 能够获取 USDT 的合约账户，而 GET /futures/btc/accounts 则是用来获取 BTC 的合约账户。

为了保持兼容, 原有的 GET /futures/xxx 的 API 都会默认为 BTC GET /futures/btc/xxx 。如 GET /futures/accounts 会被服务默认按 GET /futures/btc/accounts 请求来处理

v4.7.3

2019-07-18

• 现货、合约下单增加 text ，支持用户自定义信息

v4.6.3

2019-06-11

• 合约账户和仓位信息里增加点卡相关信息

v4.7.2

2019-05-29

• 理财借出 Loan 的 rate 字段调整为非必选

v4.7.1

2019-04-17

• 新增 wallet v4 API ，目前仅支持现货与杠杆账户转账操作
• GET /margin/loans 接口支持按 rate 排序，支持可选 currency_pair 输入
• 修复各种文档问题

v4.6.2

2019-04-24

• 修复合约价格单文档覆盖了普通合约单接口 GET /futures/orders/{order_id} 和 DELETE /futures/orders/{order_id} 的文档

v4.6.1

2019-04-02

• 合约 Ticker 返回新增字段 high_24h 、 low_24h 和 funding_rate_indicative

v4.6.0

2019-03-21

只影响 SDK

• 修改合约相关的下单函数名，防止在 Go SDK 中与现货下单冲突
• 修复验签时没有对请求参数做 decode 的问题

v4.5.2

2019-03-14

• /spot/order_book 的参数 currency_pair 应为必选
• 优化代码示例

v4.5.1

2019-03-11

• 修复缺少 URL 参数的说明

v4.5.0

为了避免引起版本混乱，APIv4 此后的版本统一以 4 作为大版本号开头（包括文档和 SDK）

2019-03-05

• 新增现货 v4 API，在原有 API 基础之上提供更多功能
• 新增杠杆 v4 API，提供杠杆借贷功能；杠杆交易API 复用现货 v4 交易API
• 提供合约止盈止损自动单 API 支持，详情见 /futures/price_orders 一组接口
• 实盘交易统一 APIv4 统一 Base URL 到 https://api.gateio.ws/api/v4

v1.3.0

2019-02-13

重要更新

• base URLs 域名更新为 fx-api.gateio.ws 和 fx-api-testnet.gateio.ws 原有 *.gateio.io 已废弃

v1.2.1

2019-02-13

• 合约 Ticker 接口返回增加 volumn_24h_usd 和 volume_24h_btc

v1.2.0

2019-01-17

• 新增 GET /futures/contracts/{contract} 查询单个合约
• 新增 GET /futures/positions/{contract} 查询单个合约的仓位
• 新增 GET /futures/account_book 查询用户合约账户历史
• Contract 模型新增 config_change_time 字段
• 修复各种文档问题

v1.1.0

2019-01-08

• Contract, Position, FuturesOrder 模型增加更多参数
• 新增 API GET /futures/position_close 获取平仓记录
• API GET /futures/my_trades 增加可选参数 order_id 支持
• DELETE /futures/orders 和 DELETE /futures/orders/{order_id} 返回状态码从 204 改为 200, 并在请求成功后返回撤销的订单列表
• DELETE /futures/orders/{order_id} 对无效订单不忽略错误，改为返回 404
• POST /futures/orders 支持 POC 和冰山委托

v1.0.0

2018-12-30

• 初次发布

General

匹配机制

匹配优先级

Gate.io 订单匹配遵循 价格优先 > 时间优先 的原则

假设订单簿情况如下：

订单	下单时间	Ask/卖价
A	10:00	100
B	10:00	102
C	10:01	100

如果 10:02分 的现价买单 102，最终成交顺序为： A、C、B

订单生命周期

发送到匹配引擎的有效订单会立即被接受，并跟已有挂单进行匹配，然后将匹配结果返回给客户端。

匹配结果若是完全执行，则订单结束。若结果是不执行或部分执行，TimeInForce 为 IOC 的订单会立即结束； 其他情况的订单，则被挂在相应价格订单队尾，等待被匹配或者被撤销。

数据中心

Gate.io 数据中心位于AWS日本东京 (ap-northeast-1) 地区。

接口概览

接口分类	分类链接	概述
host + /api/v4/spot/*	现货交易	包含币种状态、行情信息、下单、成交记录等功能
host + /api/v4/margin/*	杠杆交易	杠杆账户管理、借贷、还款等
host + /api/v4/futures/*	永续合约交易	永续合约账户管理、行情信息、下单、成交记录等功能
host + /api/v4/delivery/*	交割合约交易	交割合约账户管理、行情信息、下单、成交记录等功能
host + /api/v4/options/*	期权交易	期权账户管理、行情信息、下单、成交记录等功能
host + /api/v4/wallet/*	钱包管理	充提记录、查询余额、资金划转等
host + /api/v4/withdrawals/*	提现	数字货币提现

API

HTTP 通用格式

• 所有读操作都是 GET 方法，只接受请求参数，不读取任何请求体。
• DELETE 方法移除指定资源（如委托），但因为 DELETE 方法也不读取任何请求体， 并不是所有移除操作都是用 DELETE 方法。复杂的移除操作通过 POST 方法配合请求体来实现。
• 更新操作使用 POST, PUT 或 PATCH 方法，不同的请求有不同的参数传递方式， 但是他们要么是通过请求体，要么是请求参数，不会二者混用。
• 所有操作成功时都会返回 HTTP 状态码 2xx 。401 说明认证有问题。其他 4xx 状态码说明请求无效。 如果是 5xx 错误，则是服务端处理请求时遇上了未知的严重错误，碰到的话请第一时间反馈。

时间

所有时间字段，如果没有额外说明，格式都是秒级的 Unix 时间戳，但是返回的格式可能不同 int64, number 或者 string ），示例值如：

• 1596531048
• "1596531048"
• 1596531048.285
• "1596531048.285"

最佳方式是按有小数点的 number 去解析 (string 需要实现转换）。 如果不需要高精度， 再强转成整数（或长整形）。上面的 SDK 会对不同格式的时间字段按照相应格式做好反序列化处理。

分页

分页的实现有如下两种方式：

• page, limit 方式
• limit, offset 方式

这两种方式里，limit 字段都是用来限制单次请求里列表返回的最大数量。没有特殊说明的情况下， 它的默认值是 100 ，最大允许 1000 。

page 方式类似于网页的翻页，从 1 开始计数。遍历完整列表的方法是使用同一个 limit，每次请求将 page 加 1，直到返回的列表长度小于 limit

offset 方式类似于数据库检索，遍历完整列表的方式是每次累加 limit 到 offset 上， 直到返回的列表长度小于 limit

举例说明，如果订单总数是 201 个。使用 page-limit 方式，请求参数可以按照如下发送：

1. page=1&limit=100
2. page=2&limit=100
3. page=3&limit=100

如果使用 limit-offset 方法，则是：

1. limit=100&offset=0
2. limit=100&offset=100
3. limit=100&offset=200

有一些请求可能会返回额外的分页元数据信息。这些元数据信息都存储在返回头部。以 GET /futures/{settle}/orders 为例，这个请求会在返回头部追加如下分页元数据信息：

• X-Pagination-Limit: 请求指定的 limit 参数
• X-Pagination-Offset: 请求指定的 offset 参数
• X-Pagination-Total: 满足条件的所有条目总数

限频规则

市场	入口	限速	依据	包含
现货	公共接口	900r/s	IP	深度、K线、交易对信息等
	私有接口	900r/s	API Key	成交历史、费率查询等
	下单	10r/s	用户 ID 和交易对	（批量）下单、杠杆下单等
	撤单	5000r/s	用户 ID	（批量）撤单
永续合约	公共接口	300r/s	IP	深度、K线、交易对信息、资金费率等
	下单	100r/s	用户 ID	下单
	私有接口	400r/s	用户 ID	仓位、费率等
	撤单			（批量）撤单
钱包	所有接口	200r/s	API Key	提现充值历史、转账等
提现	提现	1r/3s	用户 ID	提现

限速是每个子账号或主账号单独计算的

WebSocket:

• 发送消息频率：无限制
• 每个 IP 最大连接数: ≤ 300

注意:

触发限速上限后，如果

• 频率没有超过突发上限，请求会被延迟处理
• 超过突发上限，请求会被拒绝

返回格式

所有的接口返回都是 JSON 格式，需要用户自行转换提取数据。 所有操作成功时都会返回 HTTP 状态码 2xx 。401 说明认证有问题。其他 4xx 状态码说明请求无效。 如果是 5xx 错误，则是服务端处理请求时遇上了未知的严重错误，碰到的话请第一时间反馈。

返回状态

状态码	说明
200/201	请求执行成功
202	请求已被服务端接受，但是仍在处理中
204	请求成功，服务端没有提供返回体
400	无效请求
401	认证失败
404	未找到
429	请求过于频繁
5xx	服务器错误

数据类型

类型	说明
string	字符串类型，以双引号表示，涉及金额和价格也会使用字符串标识
integer	32位整数，主要涉及到状态码、大小、次数等
integer(int64)	64位整数，主要涉及到ID和高精度时间戳
number	浮点数，部分时间或统计数据会以浮点形式返回
object	对象，包含一个子对象{}
array	数组，包含多组内容
boolean	true 为真，false 为假

统一帐户

我们从 4.25.0 版本之后开始引入对统一账户的支持 。统一账户是Gate.io新⼀代的交易系统，主要功能在于打破经典账户 (Classic Account) 内各个账户之间的资金隔离，实现多产品业务线之间的多币种保证金共享，用户无需各类交易之间进行资金划转，不同交易产品之间仓位盈亏可以互相抵消，有效提升用户的资金利用率。统一帐户更详细介绍可以查看 帮助中心 。

用户在使用统一账户 API 功能之前需要先在官网 API 管理页面创建统一账号的 API Key ， 目前统一账户只支持现货全仓杠杆和永续合约交易。

如果创建 API Key 的权限选项无法选择，首先确保现货全仓账户已经开通并且有初始资金。

资金划转

经典帐户与统一帐户是两个不同的帐户，如果想实现多产品业务线之间的多币种保证金共享则必须使用统一帐户。

统一账户的资金来源于经典账户，由于涉及到经典账户的资金变动，资金的转入转出操作都只能使用经典账户的 API Key 来执行。

统一账户基于原有经典账户的全仓杠杆账户升级，因此经典账户只需要将自己的现货资金划转到现货全仓杠杆账户，即可为统一账户充值。 同理资金的转出操作也必须由经典账户从全仓杠杆账户划转到自己的现货账户。

统一账户的 API Key 只能在自己的多个账户之间划转， 由于保证金共享，统一账户也无需将全仓账户的资金划转到合约账户 （我们也限制了向合约账户的转入功能）。 但是如果合约账户有资金需要提取，必须由统一账户划转到自己的现货全仓杠杆账户，才可以交给经典账户执行资金转出动作。

现货交易

统一账户的现货交易与经典账户几乎完全一致，除了在订单操作中需要指定 account 的地方必须要指定 cross_margin ， 比如想挂 BTC_USDT 交易对的买单，下单请求会类似于

POST /spot/orders

{
  "currency_pair": "BTC_USDT",
  "account": "cross_margin",
  "side": "buy",
  ...
}

其他订单相关限制请直接参考各接口说明。

TIP

需要特别说明的是，统一账户升级自经典账户的现货全仓杠杆账户，经典账户的 API Key 原先就支持操作现货全仓杠杆账户， 为了不影响经典账户已有的操作，我们依然保留了经典账户的这个功能。所以不管是经典账户还是统一账户的 API Key 都可以操作同一个现货全仓杠杆账户（注意合约账户是分开的）

永续合约交易

统一账户永续合约的 API 操作与经典账户完全相同，不过当前只支持 USD 结算

TIP

需要留意一下在合约交易的部份，并没有像现货交易在使用经典帐户 API Key 的时候有做对全仓杠杆帐户的兼容性处理，所以当使用经典帐户 API Key 进行合约交易的时候，资产是保留在 经典帐户-合约 下面，而使用统一帐户 API Key 进行合约交易的时候，资产是保留在 统一帐户-合约 下面，这两个是不同的合约帐号。另外在 经典帐户-现货 下的资金, 是无法与 经典帐户-合约 共享保证金的。

请求ID

允许在请求里设置一个 X-Client-Request-Id 的 header,API在响应时也会携带这个header。 可以使用这个字段来定位API响应的是对应的哪个请求，方便用户来设置请求 id 做跟踪。

异常处理

APIv4 对于所有的异常请求，会设置状态码为非 2xx ，同时返回一个 JSON 格式的返回体来描述具体的错误信息。

返回体的格式通常如下所示：

{
  "label": "INVALID_PARAM_VALUE",
  "message": "Invalid parameter `text` with value: abc"
}

• label 用于标识某种错误的类型，格式 string ，它的值是一个固定的列表（见下方）。程序处理可以使用 label 字段的内容来设定和捕获异常
• message (或 detail) 表示详细的错误信息，方便 API 对接时，理解具体是因为什么样的参数设置导致请求出现了异常。 该字段内容不建议用于异常的捕获或识别。

以 Python requests (opens new window) 为例，异常的处理流程可以参考如下所示：

以下示例的异常捕获流程只涉及到业务相关的异常，网络连接超时等其他非业务相关的异常还需要自行处理。

import requests

r = requests.get("https://api.gateio.ws/api/v4/futures/btc/contracts/BTC_USD")
try:
    r.raise_for_status()
except requests.HTTPError:
    # 捕获非 2xx 错误，尝试解析 body 里返回的错误消息，并根据不同 label 做不同的异常处理
    if r.json()['label'] == 'xxx':
        print(r.json())

以 Python SDK (opens new window) 为示例：

import json
from gate_api import FuturesApi
from gate_api.rest import ApiException

api = FuturesApi()
try:
    api.get_futures_contract(settle='btc', contract="BTC_USD")
except ApiException as e:  # ApiException 封装了异常的各种信息，详情可参看类定义
    detail = json.loads(e.value.body)
    if detail['label'] == 'xxx':
        print(detail)

异常 label 列表

• 请求参数或格式问题

label	含义
INVALID_PARAM_VALUE	参数输入值无效
INVALID_PROTOCOL	参数输入值无效
INVALID_ARGUMENT	参数无效
INVALID_REQUEST_BODY	无效请求体
MISSING_REQUIRED_PARAM	缺少必选参数
BAD_REQUEST	无效请求
INVALID_CONTENT_TYPE	无效的 Content-Type 头部格式
NOT_ACCEPTABLE	Accept 头部无法满足
METHOD_NOT_ALLOWED	请求方法不接受
NOT_FOUND	资源 URL 不存在

• 认证相关

label	含义
INVALID_CREDENTIALS	认证接口缺少用户认证信息
INVALID_KEY	无效的 API Key
IP_FORBIDDEN	请求 IP 不在白名单
READ_ONLY	请求账户只读，不可执行写操作
INVALID_SIGNATURE	无效签名
MISSING_REQUIRED_HEADER	缺少必要的认证头部
REQUEST_EXPIRED	客户端时间与服务端时间相差过大
ACCOUNT_LOCKED	账户被锁定
FORBIDDEN	账户无权执行该操作
API_WITHDRAW_DISABLED	API提现操作临时禁用
INVALID_WITHDRAW_ID	无效的提现ID
INVALID_WITHDRAW_CANCEL_STATUS	当前提现状态无法取消

• 钱包相关

label	含义
SUB_ACCOUNT_NOT_FOUND	子账户不存在
SUB_ACCOUNT_LOCKED	子账号被冻结
MARGIN_BALANCE_EXCEPTION	杠杆账户异常
MARGIN_TRANSFER_FAILED	杠杆资金划转失败
TOO_MUCH_FUTURES_AVAILABLE	合约账户总资产达到上限
FUTURES_BALANCE_NOT_ENOUGH	合约账户余额不足
ACCOUNT_EXCEPTION	账户异常
SUB_ACCOUNT_TRANSFER_FAILED	子账户资金划转失败
ADDRESS_NOT_USED	指定的钱包地址未在网页执行过划转
TOO_FAST	提现频率过快
WITHDRAWAL_OVER_LIMIT	超出提现额度

• 现货和杠杆相关

label	含义
INVALID_PRECISION	无效的精度
INVALID_CURRENCY	无效的币种信息
INVALID_CURRENCY_PAIR	无效的交易对
POC_FILL_IMMEDIATELY	被动委托会立即成交
ORDER_NOT_FOUND	订单不存在
ORDER_CLOSED	订单已结束
ORDER_CANCELLED	订单已撤销
QUANTITY_NOT_ENOUGH	数量不足
BALANCE_NOT_ENOUGH	余额不足
MARGIN_NOT_SUPPORTED	该交易对不支持杠杆交易
MARGIN_BALANCE_NOT_ENOUGH	杠杆账户余额不足
AMOUNT_TOO_LITTLE	数额小于最低值
AMOUNT_TOO_MUCH	数额过大
REPEATED_CREATION	重复创建
LOAN_NOT_FOUND	借贷订单不存在
LOAN_RECORD_NOT_FOUND	借贷记录不存在
NO_MATCHED_LOAN	没有借贷记录能满足借入需求
NOT_MERGEABLE	借贷单不可合并
NO_CHANGE	修改的参数与当前状态无区别
REPAY_TOO_MUCH	还款数额超出借款数额
TOO_MANY_CURRENCY_PAIRS	批量下单指定了过多交易对
TOO_MANY_ORDERS	批量下单的单个交易对下单数过多
MIXED_ACCOUNT_TYPE	批量下单中使用了多个账户类型
AUTO_BORROW_TOO_MUCH	自动借入超出最多可借
TRADE_RESTRICTED	高负债率导致交易操作被限制
FOK_NOT_FILL	FOK 订单无法全部成交
INITIAL_MARGIN_TOO_LOW	用户总初始保证金率太低
NO_MERGEABLE_ORDERS	找不到能够合并的借贷订单

• 合约相关

label	含义
USER_NOT_FOUND	用户无合约账户
CONTRACT_NO_COUNTER	没有匹配的对手单
CONTRACT_NOT_FOUND	合约未找到
NOT_FOUND	请求路径不存在
RISK_LIMIT_EXCEEDED	委托超出风险限额
INSUFFICIENT_AVAILABLE	余额不足
LIQUIDATE_IMMEDIATELY	操作可能导致爆仓
LEVERAGE_TOO_HIGH	杠杆倍数设置过高
LEVERAGE_TOO_LOW	杠杆倍数设置过低
ORDER_NOT_FOUND	委托不存在
ORDER_NOT_OWNED	委托不存在
ORDER_FINISHED	委托已结束
TOO_MANY_ORDERS	过多未完成的委托
POSITION_CROSS_MARGIN	全仓不支持更新保证金
POSITION_IN_LIQUIDATION	仓位在强制平仓中
POSITION_IN_CLOSE	仓位正在平仓中
POSITION_EMPTY	仓位为空
REMOVE_TOO_MUCH	保证金超过可调范围
RISK_LIMIT_NOT_MULTIPLE	风险限额未按照步长调整
RISK_LIMIT_TOO_HIGH	超出最大风险限额
RISK_LIMIT_TOO_lOW	风险限额设置过低
PRICE_TOO_DEVIATED	下单价与标记价格相差过大
SIZE_TOO_LARGE	下单数量超过上限
SIZE_TOO_SMALL	下单数量不足下限
PRICE_OVER_LIQUIDATION	增加仓位时价格不能超过平仓价
PRICE_OVER_BANKRUPT	减少仓位时价格不能超过破产价
ORDER_POC_IMMEDIATE	被动委托会立即成交
INCREASE_POSITION	只减仓委托会增加仓位
CONTRACT_IN_DELISTING	当前合约市场处于下线过渡期，只允许创建只减仓委托或者平仓委托
POSITION_NOT_FOUND	仓位不存在
POSITION_DUAL_MODE	双向持仓模式不允许此操作
ORDER_PENDING	有委托存在则不允许此操作
POSITION_HOLDING	有持仓则不允许此操作
REDUCE_EXCEEDED	双向持仓模式下，减仓单超过仓位大小
NO_CHANGE	没有改变发生
AMEND_WITH_STOP	有止盈止损单时不能修改委托
ORDER_FOK	FOK 订单无法全部成交

• 服务异常

label	含义
INTERNAL	内部错误
SERVER_ERROR	内部错误
TOO_BUSY	服务当前忙

认证

生成 API key

在调用私有API接口前，需要生成账户的API key来验证身份。 您可以在网页端登录成功后，在【账户管理】-> 【APIv4 Keys】中生成， 或点击 这里 生成 API keys

每个账户最多可以创建 5 个 API key，每个 Key 的权限配置都是相互独立的。 建议给每个 Key 设置能够标明用途的备注名

Key 访问密钥
Secret Key 签名认证加密所使用的密钥

除此之外，还可以配置 IP 白名单，只允许服务端接收来自 IP 白名单里的客户端请求。每个 Key 最多可配置 20 个 IP 地址，IP 地址按照 IPv4 配置， 不支持 IP 地址段。若不设置 IP 白名单，服务端不会验证客户端 IP 来源。

TIP

注：如果发现 Key 的名字是 spot 或者 futures ，该 Key 很有可能是迁移之后系统的默认命名， 详情参考 “关于 APIv4 Key 升级” 一节。

创建的 Key 还可以更新和删除，不过需要注意的是 Key 的更新和删除，最多需要 5 分钟才能生效。

另外模拟合约与实盘合约属于两套不同的环境，实盘合约的 API Key 不可用于模拟合约。 如果需要使用模拟合约做 API 接口联调测试，需要在个人账户 APIv4Keys 页面的模拟合约入口单独申请。 模拟合约与实盘合约的接口请求方式完全相同，区别只是在 API 的 Base URL 和使用的 API Key

APIv4 权限

创建 Key 的时候，可以为该 Key 配置是否开启现货杠杆、合约、钱包或者提现的权限， 开启的权限可以配置读写或者只读。

产品	权限
现货/杠杆	只读查询订单 读写查询订单&下单
永续合约	只读查询订单 读写查询订单&下单
交割合约	只读查询订单 读写查询订单&下单
钱包	只读查询充提划转记录 读写 查询账户记录&资金划转
提现	只读查询提现记录 读写 查询提现记录&提现

所有请求方法为 GET 的都是读操作，其他的则是写请求。每个权限组可以设置为禁用、只读或读写。

值得注意的一点是，尽管提现操作组只有一个 API （即 POST /withdrawals ），考虑到一般使用情况， 还是将其从钱包操作里独立成一个权限组，而包括了提现记录的账户转出流水记录查询（即 GET /wallet/withdrawals ）还是保留在钱包 API 权限组了。

APIv4 验签请求接口发送要求

1. 在官网个人中心申请 APIv4 Key ，并确保该 Key 拥有对应操作的读写权限。
2. 在发送请求头部传入 KEY ，即 APIv4 密钥对的 Key
3. 在发送请求头部传入 Timestamp ，即请求发送的时间，格式是秒级精度的 Unix 时间戳。 同时该时间不能与当前时间差距超过 60 秒。
4. 在发送请求头部传入 SIGN ，即将请求生成签名字符串并用 APIv4 Secret 加密后生成的签名。 签名字符串生成方法参看下节，加密算法为 HexEncode(HMAC_SHA512(secret, signature_string)) ， 即通过 HMAC-SHA512 加密算法，将 APIv4 Secret 作为加密密钥，签名字符串作为加密消息， 生成加密结果的 16 进制输出。
5. 确保发送请求的客户端 IP 地址在所使用的密钥的 IP 地址白名单里。

APIv4 签名字符串生成方式

APIv4 中签名字符串按照如下方式拼接生成：

Request Method + "\n" + Request URL + "\n" + Query String + "\n" + HexEncode(SHA512(Request Payload)) + "\n" + Timestamp

Request Method

请求方法，全大写, 如 POST, GET

Request URL

请求 URL，不包括服务地址和端口，如 /api/v4/futures/orders

Query String

没有使用 URL 编码的请求参数，请求参数在参与计算签名时的顺序一定要保证和实际请求里的顺序一致。 如 status=finished&limit=50 。

如果没有请求参数，使用空字符串 ("")

HexEncode(SHA512(Request Payload))

将请求体字符串使用 SHA512 哈希之后的结果。如果没有请求体，使用空字符串的哈希结果，即 cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e

Timestamp

设置在请求头部 Timestamp 里的值

示例

注：示例中所有的换行都是为了方便显示人为添加的，实际只有示例中的一个 \n 保留

假设使用的 Key 为 key ，Secret 为 secret

1. 查询所有合约订单

	GET /api/v4/futures/orders?contract=BTC_USD&status=finished&limit=50 HTTP/1.1

签名字符串:

	GET\n
	/api/v4/futures/orders\n
	contract=BTC_USD&status=finished&limit=50\n
	cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e\n
	1541993715

说明

• /api/v4/futures/orders: 请求 URL
• contract=BTC_USD&status=finished&limit=50: 请求参数，与实际请求的顺序完全一致
• 请求体为空，使用空字符串的哈希输出
• 1541993715: Unix 时间戳

签名结果

55f84ea195d6fe57ce62464daaa7c3c02fa9d1dde954e4c898289c9a2407a3d6fb3faf24deff16790d726b66ac9f74526668b13bd01029199cc4fcc522418b8a

2. 创建合约委托

	POST /api/v4/futures/orders HTTP/1.1

	{"contract":"BTC_USD","type":"limit","size":100,"price":6800,"time_in_force":"gtc"}

签名字符串:

	POST\n
	/api/v4/futures/orders\n
	\n
	ad3c169203dc3026558f01b4df307641fa1fa361f086b2306658886d5708767b1854797c68d9e62fef2f991645aa82673622ebf417e091d0bd22bafe5d956cca\n
	1541993715

说明

• 请求参数为空，使用空字符串
• 使用 JSON 序列化之后的字符串的哈希输出

签名结果

eae42da914a590ddf727473aff25fc87d50b64783941061f47a3fdb92742541fc4c2c14017581b4199a1418d54471c269c03a38d788d802e2c306c37636389f0

# coding: utf-8

# Python 示例验签代码

"""
本示例仅作为演示签名计算方式使用，推荐使用各语言的 SDK ，因为已经集成了验签规则
"""

# coding: utf-8
import time
import hashlib
import hmac
import requests
import json

def gen_sign(method, url, query_string=None, payload_string=None):
    key = ''        # api_key
    secret = ''     # api_secret

    t = time.time()
    m = hashlib.sha512()
    m.update((payload_string or "").encode('utf-8'))
    hashed_payload = m.hexdigest()
    s = '%s\n%s\n%s\n%s\n%s' % (method, url, query_string or "", hashed_payload, t)
    sign = hmac.new(secret.encode('utf-8'), s.encode('utf-8'), hashlib.sha512).hexdigest()
    return {'KEY': key, 'Timestamp': str(t), 'SIGN': sign}

if __name__ == "__main__":
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    common_headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

    url = '/futures/orders'
    body = {"contract": "BTC_USD", "size": 100, "price": "30", "tif": "gtc"}
    request_content = json.dumps(body)
    sign_headers = gen_sign('POST', prefix + url, "", request_content)
    sign_headers.update(common_headers)
    print('signature headers: %s' % sign_headers)
    res = requests.post(host + prefix + url, headers=sign_headers, data=request_content)
    print(res.status_code)
    print(res.content)

常见问题

• POST /wallet/transfers 的操作记录怎么查询？

  通过 POST /wallet/transfers 执行的转账操作，按不同的账户类型，查询入口分在不同的服务地址，包括：

  • GET /margin/account_book 查询杠杆账户的转入转入历史
  • GET /futures/{settle}/account_book?type=dnw 查询永续合约账户的转入转出历史
  • GET /delivery/{settle}/account_book?type=dnw 查询交割合约账户的转入转出历史

• 杠杆下单怎么操作？

  杠杆下单复用了现货下单接口，只需要在 POST /spot/orders 或 POST /spot/batch_orders 时将请求体里的 account 参数设置为 margin 即可

• 合约操作返回 USER_NOT_FOUND

  原因是因为合约账户没有开户，只需要执行一笔账户划转操作即可。注意不同结算币种有不同的合约账户

• 合约提示 CONTRACT_NOT_FOUND

  不同结算币种的合约也是不同的，请确认指定的合约名称是否在对应结算币种支持的合约列表中。即

  GET /futures/{settle}/contracts 和 GET /delivery/{settle}/contracts

• 主子账号的区别

  • 子账号 API Key 不能操作主子账户互转API， 即 POST /wallet/sub_account_transfers
  • 子账号 API Key 不能使用API进行提现，即 POST /withdrawals
  • 如果创建子账号时没有开启对应业务的权限，即时子账号 API key 开启了权限，请求也一样会被拒绝

• 上面没有我的问题

  联系客服咨询具体问题。如果有使用到某一个语言的 SDK ，也可以在相应 SDK 的 github 项目中提交 issue

  提交问题的时候，建议至少包含以下信息，可以更快速定位问题：

  • 用户 ID
  • 原始的请求 URL、请求参数和请求体内容
    • 使用的 API Key 是实盘还是模拟的，具体的 Key 是什么（不需要提供 Secret）
    • 编程语言，最好提供一段发送请求的代码片段
    • 是否使用了 SDK ，如果使用了 SDK ，具体是调用哪个方法

Withdrawal

提现接口

提现

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/withdrawals'
query_param = ''
body='{"currency":"USDT","address":"1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs","amount":"222.61","memo":"","chain":"TRX"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/withdrawals"
query_param=""
body_param='{"currency":"USDT","address":"1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs","amount":"222.61","memo":"","chain":"TRX"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /withdrawals

提现

请求体示例

{
  "currency": "USDT",
  "address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
  "amount": "222.61",
  "memo": "",
  "chain": "TRX"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» amount	body	string	是	币的数量
» currency	body	string	是	币种名称
» address	body	string	否	提现地址。提现操作必填
» memo	body	string	否	转账memo等备注信息
» chain	body	string	否	提现的链名称
» fee	body	string	否	手续费

返回示例

202 返回

{
  "id": "210496",
  "timestamp": "1542000000",
  "currency": "USDT",
  "address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
  "txid": "128988928203223323290",
  "amount": "222.61",
  "memo": "",
  "status": "DONE",
  "chain": "TRX"
}

返回

状态码	含义	描述	格式
202	Accepted (opens new window)	提现请求已受理，处理结果查看该提现记录状态	Inline

返回格式

状态码 202

名称	类型	描述
» id	string	交易记录 ID
» txid	string	区块转账哈希记录
» timestamp	string	操作时间
» amount	string	币的数量
» currency	string	币种名称
» address	string	提现地址。提现操作必填
» memo	string	转账memo等备注信息
» status	string	交易状态 - DONE: 完成 - CANCEL: 已取消 - REQUEST: 请求中 - MANUAL: 待人工审核 - BCODE: 充值码操作 - EXTPEND: 已经发送等待确认 - FAIL: 链上失败等待确认 - INVALID: 无效订单 - VERIFY: 验证中 - PROCES: 处理中 - PEND: 处理中 - DMOVE: 待人工审核 - SPLITPEND: cny提现大于5w,自动分单
» chain	string	提现的链名称
» fee	string	手续费

枚举值列表

属性	值
status	DONE
status	CANCEL
status	REQUEST
status	MANUAL
status	BCODE
status	EXTPEND
status	FAIL
status	INVALID
status	VERIFY
status	PROCES
status	PEND
status	DMOVE
status	SPLITPEND

WARNING

该请求需要 API key 和 secret 认证

取消指定 ID 的提现操作

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/withdrawals/210496'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/withdrawals/210496"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /withdrawals/{withdrawal_id}

取消指定 ID 的提现操作

参数

名称	位置	类型	必选	描述
withdrawal_id	URL	string	是

返回示例

202 返回

{
  "id": "210496",
  "timestamp": "1542000000",
  "currency": "USDT",
  "address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
  "txid": "128988928203223323290",
  "amount": "222.61",
  "memo": "",
  "status": "DONE",
  "chain": "TRX"
}

返回

状态码	含义	描述	格式
202	Accepted (opens new window)	取消请求已受理，处理结果查看该提现记录状态	Inline

返回格式

状态码 202

名称	类型	描述
» id	string	交易记录 ID
» txid	string	区块转账哈希记录
» timestamp	string	操作时间
» amount	string	币的数量
» currency	string	币种名称
» address	string	提现地址。提现操作必填
» memo	string	转账memo等备注信息
» status	string	交易状态 - DONE: 完成 - CANCEL: 已取消 - REQUEST: 请求中 - MANUAL: 待人工审核 - BCODE: 充值码操作 - EXTPEND: 已经发送等待确认 - FAIL: 链上失败等待确认 - INVALID: 无效订单 - VERIFY: 验证中 - PROCES: 处理中 - PEND: 处理中 - DMOVE: 待人工审核 - SPLITPEND: cny提现大于5w,自动分单
» chain	string	提现的链名称
» fee	string	手续费

枚举值列表

属性	值
status	DONE
status	CANCEL
status	REQUEST
status	MANUAL
status	BCODE
status	EXTPEND
status	FAIL
status	INVALID
status	VERIFY
status	PROCES
status	PEND
status	DMOVE
status	SPLITPEND

WARNING

该请求需要 API key 和 secret 认证

Wallet

钱包接口

查询币种支持的链

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/currency_chains'
query_param = 'currency=GT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/wallet/currency_chains?currency=GT \
  -H 'Accept: application/json'

GET /wallet/currency_chains

查询币种支持的链

参数

名称	位置	类型	必选	描述
currency	请求参数	string	是	币种名称

返回示例

200 返回

[
  {
    "chain": "ETH",
    "name_cn": "以太坊ERC20",
    "name_en": "ETH/ERC20",
    "is_disabled": 0,
    "is_deposit_disabled": 0,
    "is_withdraw_disabled": 0
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» chain	string	链名称
» name_cn	string	链的中文名称
» name_en	string	链的英文名称
» is_disabled	integer	是否禁用，0 表示未禁用
» is_deposit_disabled	integer	充值是否禁用，0 表示未禁用
» is_withdraw_disabled	integer	提现是否禁用，0 表示未禁用

该请求不需要认证

获取币种充值地址

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/deposit_address'
query_param = 'currency=USDT'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/deposit_address"
query_param="currency=USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /wallet/deposit_address

获取币种充值地址

参数

名称	位置	类型	必选	描述
currency	请求参数	string	是	币种名称

返回示例

200 返回

{
  "currency": "USDT",
  "address": "LPXtk1kWHioP62SzfqwKbYE3Z7Wt2ujYEc",
  "multichain_addresses": [
    {
      "chain": "TRX",
      "address": "LPXtk1kWHioP62SzfqwKbYE3Z7Wt2ujYEc",
      "payment_id": "",
      "payment_name": "",
      "obtain_failed": 0
    }
  ]
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	地址获取成功	Inline

返回格式

状态码 200

名称	类型	描述
» currency	string	币种信息
» address	string	充值地址
» multichain_addresses	array
»» MultiChainAddressItem	object
»»» chain	string	链的名称
»»» address	string	充值地址
»»» payment_id	string	部分币种充值时必须填写的备注
»»» payment_name	string	备注类型, Tag 或 Memo
»»» obtain_failed	integer	地址是否获取成功，0 表示成功，1 表示失败，可能需要重新获取

WARNING

该请求需要 API key 和 secret 认证

获取提现记录

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/withdrawals'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/withdrawals"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /wallet/withdrawals

获取提现记录

记录查询时间范围不允许超过 30 天

参数

名称	位置	类型	必选	描述
currency	请求参数	string	否	指定查询币种，不指定返回全部币种
from	请求参数	integer(int64)	否	查询记录的起始时间，不指定则默认从当前时间开始向前推 7 天
to	请求参数	integer(int64)	否	查询记录的结束时间，不指定则默认为当前时间
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始

返回示例

200 返回

[
  {
    "id": "210496",
    "timestamp": "1542000000",
    "currency": "USDT",
    "address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
    "txid": "128988928203223323290",
    "amount": "222.61",
    "memo": "",
    "status": "DONE",
    "chain": "TRX"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» id	string	交易记录 ID
» txid	string	区块转账哈希记录
» timestamp	string	操作时间
» amount	string	币的数量
» currency	string	币种名称
» address	string	提现地址。提现操作必填
» memo	string	转账memo等备注信息
» status	string	交易状态 - DONE: 完成 - CANCEL: 已取消 - REQUEST: 请求中 - MANUAL: 待人工审核 - BCODE: 充值码操作 - EXTPEND: 已经发送等待确认 - FAIL: 链上失败等待确认 - INVALID: 无效订单 - VERIFY: 验证中 - PROCES: 处理中 - PEND: 处理中 - DMOVE: 待人工审核 - SPLITPEND: cny提现大于5w,自动分单
» chain	string	提现的链名称
» fee	string	手续费

枚举值列表

属性	值
status	DONE
status	CANCEL
status	REQUEST
status	MANUAL
status	BCODE
status	EXTPEND
status	FAIL
status	INVALID
status	VERIFY
status	PROCES
status	PEND
status	DMOVE
status	SPLITPEND

WARNING

该请求需要 API key 和 secret 认证

获取充值记录

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/deposits'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/deposits"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /wallet/deposits

获取充值记录

记录查询时间范围不允许超过 30 天

参数

名称	位置	类型	必选	描述
currency	请求参数	string	否	指定查询币种，不指定返回全部币种
from	请求参数	integer(int64)	否	查询记录的起始时间，不指定则默认从当前时间开始向前推 7 天
to	请求参数	integer(int64)	否	查询记录的结束时间，不指定则默认为当前时间
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始

返回示例

200 返回

[
  {
    "id": "210496",
    "timestamp": "1542000000",
    "currency": "USDT",
    "address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
    "txid": "128988928203223323290",
    "amount": "222.61",
    "memo": "",
    "status": "DONE",
    "chain": "TRX"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» id	string	交易记录 ID
» txid	string	区块转账哈希记录
» timestamp	string	操作时间
» amount	string	币的数量
» currency	string	币种名称
» address	string	提现地址。提现操作必填
» memo	string	转账memo等备注信息
» status	string	交易状态 - DONE: 完成 - CANCEL: 已取消 - REQUEST: 请求中 - MANUAL: 待人工审核 - BCODE: 充值码操作 - EXTPEND: 已经发送等待确认 - FAIL: 链上失败等待确认 - INVALID: 无效订单 - VERIFY: 验证中 - PROCES: 处理中 - PEND: 处理中 - DMOVE: 待人工审核 - SPLITPEND: cny提现大于5w,自动分单
» chain	string	提现的链名称
» fee	string	手续费

枚举值列表

属性	值
status	DONE
status	CANCEL
status	REQUEST
status	MANUAL
status	BCODE
status	EXTPEND
status	FAIL
status	INVALID
status	VERIFY
status	PROCES
status	PEND
status	DMOVE
status	SPLITPEND

WARNING

该请求需要 API key 和 secret 认证

交易账户互转

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/transfers'
query_param = ''
body='{"currency":"BTC","from":"spot","to":"margin","amount":"1","currency_pair":"BTC_USDT"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/wallet/transfers"
query_param=""
body_param='{"currency":"BTC","from":"spot","to":"margin","amount":"1","currency_pair":"BTC_USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /wallet/transfers

交易账户互转

个人交易账户之间的余额互转，目前支持以下互转操作：

1. 现货账户 - 杠杆账户
2. 现货账户 - 永续合约账户
3. 现货账户 - 交割合约账户
4. 现货账户 - 全仓杠杆账户
5. 现货账户 - 期权账户

请求体示例

{
  "currency": "BTC",
  "from": "spot",
  "to": "margin",
  "amount": "1",
  "currency_pair": "BTC_USDT"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» currency	body	string	是	转账货币名称。关联合约账户时，currency 可以设置的值为POINT(即点卡) 和支持的结算货币(如 BTC, USDT)
» from	body	string	是	转出账户
» to	body	string	是	转入账户
» amount	body	string	是	转账额度
» currency_pair	body	string	否	杠杆交易对。转入或转出杠杆账户时必填
» settle	body	string	否	合约结算币种。 转入转出合约账户时必填

枚举值列表

参数	值
» from	spot
» from	margin
» from	futures
» from	delivery
» from	cross_margin
» from	options
» to	spot
» to	margin
» to	futures
» to	delivery
» to	cross_margin
» to	options

返回示例

200 返回

{
  "tx_id": 59636381286
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	转账操作成功	Inline

返回格式

状态码 200

TransactionID

名称	类型	描述
» tx_id	integer(int64)	操作单号

WARNING

该请求需要 API key 和 secret 认证

主子账号互转

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/sub_account_transfers'
query_param = ''
body='{"currency":"BTC","sub_account":"10002","direction":"to","amount":"1","sub_account_type":"spot"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/wallet/sub_account_transfers"
query_param=""
body_param='{"currency":"BTC","sub_account":"10002","direction":"to","amount":"1","sub_account_type":"spot"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /wallet/sub_account_transfers

主子账号互转

支持转入转出到子账号的现货或合约账户，注意不管操作子账号的哪个账户，主账号的账户只使用现货账户

请求体示例

{
  "currency": "BTC",
  "sub_account": "10002",
  "direction": "to",
  "amount": "1",
  "sub_account_type": "spot"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» currency	body	string	是	转账货币名称
» sub_account	body	string	是	子账号用户 ID
» direction	body	string	是	资金流向，to - 转入子账号, from - 转出子账号
» amount	body	string	是	转账额度
» sub_account_type	body	string	否	操作的子账号交易账户， spot - 现货账户， futures - 永续合约账户, cross_margin - 全仓杠杆账户

枚举值列表

参数	值
» direction	to
» direction	from
» sub_account_type	spot
» sub_account_type	futures
» sub_account_type	cross_margin

返回

状态码	含义	描述	格式
204	No Content (opens new window)	转账操作成功	无

WARNING

该请求需要 API key 和 secret 认证

主子账号划转记录

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/sub_account_transfers'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/sub_account_transfers"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /wallet/sub_account_transfers

主子账号划转记录

记录查询时间范围不允许超过 30 天

注：只能查询到 2020-04-10 之后的记录

参数

名称	位置	类型	必选	描述
sub_uid	请求参数	string	否	子账号用户 ID ，不指定则返回所有子账号的记录
from	请求参数	integer(int64)	否	查询记录的起始时间，不指定则默认从当前时间开始向前推 7 天
to	请求参数	integer(int64)	否	查询记录的结束时间，不指定则默认为当前时间
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始

返回示例

200 返回

[
  {
    "uid": "10001",
    "timest": "1592809000",
    "source": "web",
    "currency": "BTC",
    "sub_account": "10002",
    "direction": "to",
    "amount": "1",
    "sub_account_type": "spot"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表获取成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» currency	string	转账货币名称
» sub_account	string	子账号用户 ID
» direction	string	资金流向，to - 转入子账号, from - 转出子账号
» amount	string	转账额度
» uid	string	主账号用户 ID
» timest	string	转账时间戳
» source	string	转账操作来源
» sub_account_type	string	操作的子账号交易账户， spot - 现货账户， futures - 永续合约账户, cross_margin - 全仓杠杆账户

枚举值列表

属性	值
direction	to
direction	from
sub_account_type	spot
sub_account_type	futures
sub_account_type	cross_margin

WARNING

该请求需要 API key 和 secret 认证

查询提现状态

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/withdraw_status'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/withdraw_status"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /wallet/withdraw_status

查询提现状态

参数

名称	位置	类型	必选	描述
currency	请求参数	string	否	指定币种名称查询

返回示例

200 返回

[
  {
    "currency": "GT",
    "name": "GateToken",
    "name_cn": "GateToken",
    "deposit": "0",
    "withdraw_percent": "0%",
    "withdraw_fix": "0.01",
    "withdraw_day_limit": "20000",
    "withdraw_day_limit_remain": "20000",
    "withdraw_amount_mini": "0.11",
    "withdraw_eachtime_limit": "20000",
    "withdraw_fix_on_chains": {
      "BTC": "20",
      "ETH": "15",
      "TRX": "0",
      "EOS": "2.5"
    }
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表获取成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» currency	string	币种
» name	string	币种名称
» name_cn	string	币种中文名称
» deposit	string	充值手续费
» withdraw_percent	string	提现手续费率百分比
» withdraw_fix	string	固定提现手续费用
» withdraw_day_limit	string	日提现额度
» withdraw_amount_mini	string	最少提现额度
» withdraw_day_limit_remain	string	剩余日提现额度
» withdraw_eachtime_limit	string	单次最多提现额度
» withdraw_fix_on_chains	object	多链的固定提现手续费用
»» additionalProperties	string

WARNING

该请求需要 API key 和 secret 认证

查询子账号余额信息

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/sub_account_balances'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/sub_account_balances"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /wallet/sub_account_balances

查询子账号余额信息

参数

名称	位置	类型	必选	描述
sub_uid	请求参数	string	否	子账号用户 ID ，不指定则返回所有子账号的记录

返回示例

200 返回

[
  {
    "uid": "10003",
    "available": {
      "BTC": "0.1",
      "GT": "2000",
      "USDT": "10"
    }
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表获取成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» uid	string	用户 ID
» available	object	币种可用余额
»» additionalProperties	string

WARNING

该请求需要 API key 和 secret 认证

查询子账号逐仓杠杆账户余额信息

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/sub_account_margin_balances'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/sub_account_margin_balances"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /wallet/sub_account_margin_balances

查询子账号逐仓杠杆账户余额信息

参数

名称	位置	类型	必选	描述
sub_uid	请求参数	string	否	子账号用户 ID ，不指定则返回所有子账号的记录

返回示例

200 返回

[
  {
    "uid": "10000",
    "available": [
      {
        "locked": false,
        "currency_pair": "BTC_USDT",
        "risk": "9999.99",
        "base": {
          "available": "0.1",
          "borrowed": "0",
          "interest": "0",
          "currency": "BTC",
          "locked": "0"
        },
        "quote": {
          "available": "0",
          "borrowed": "0",
          "interest": "0",
          "currency": "USDT",
          "locked": "0"
        }
      }
    ]
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表获取成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» uid	string	用户 ID
» available	array	账户余额信息
»» None	object	某交易对的杠杆账户信息，base 对应交易货币的账户信息，quote 对应计价货币的账户信息
»»» currency_pair	string	交易对
»»» locked	boolean	账户是否被锁定
»»» risk	string	杠杆账户当前风险率
»»» base	object	货币账户信息
»»»» currency	string	货币名称
»»»» available	string	可用于杠杆交易的额度，available = 保证金 + borrowed
»»»» locked	string	冻结资金，如已经放在杠杆市场里挂单交易的数额
»»»» borrowed	string	借入资金
»»»» interest	string	未还利息
»»» quote	object	货币账户信息
»»»» currency	string	货币名称
»»»» available	string	可用于杠杆交易的额度，available = 保证金 + borrowed
»»»» locked	string	冻结资金，如已经放在杠杆市场里挂单交易的数额
»»»» borrowed	string	借入资金
»»»» interest	string	未还利息

WARNING

该请求需要 API key 和 secret 认证

查询子账号永续合约账户余额信息

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/sub_account_futures_balances'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/sub_account_futures_balances"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /wallet/sub_account_futures_balances

查询子账号永续合约账户余额信息

参数

名称	位置	类型	必选	描述
sub_uid	请求参数	string	否	子账号用户 ID ，不指定则返回所有子账号的记录
settle	请求参数	string	否	指定查询某个结算币种的余额

返回示例

200 返回

[
  {
    "uid": "10003",
    "available": {
      "BTC": "0.1",
      "GT": "2000",
      "USDT": "10"
    }
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表获取成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» uid	string	用户 ID
» available	object	各结算账户信息
»» additionalProperties	object
»»» total	string	账户总资产，total = position_margin + order_margin + available
»»» unrealised_pnl	string	未实现盈亏
»»» position_margin	string	头寸保证金
»»» order_margin	string	未完成订单的保证金
»»» available	string	可用的转出或交易的额度，统一账户下包含授信额度的可用额度
»»» point	string	点卡数额
»»» currency	string	结算币种
»»» in_dual_mode	boolean	是否为双向持仓模式
»»» enable_credit	boolean	是否开启统一账户模式
»»» position_initial_margin	string	头寸占用的起始保证金，适用于统一账户模式
»»» maintenance_margin	string	头寸占用的维持保证金，适用于统一账户模式
»»» bonus	string	体验金
»»» history	object	累计统计数据
»»»» dnw	string	累计转入转出
»»»» pnl	string	累计交易盈亏
»»»» fee	string	累计手续费
»»»» refr	string	累计获取的推荐人返佣
»»»» fund	string	累计资金费用
»»»» point_dnw	string	累计点卡转入转出
»»»» point_fee	string	累计点卡抵扣手续费
»»»» point_refr	string	累计获取的点卡推荐人返佣
»»»» bonus_dnw	string	累计体验金转入转出
»»»» bonus_offset	string	累计体验金抵扣

WARNING

该请求需要 API key 和 secret 认证

查询子账号全仓杠杆账户余额信息

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/sub_account_cross_margin_balances'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/sub_account_cross_margin_balances"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /wallet/sub_account_cross_margin_balances

查询子账号全仓杠杆账户余额信息

参数

名称	位置	类型	必选	描述
sub_uid	请求参数	string	否	子账号用户 ID ，不指定则返回所有子账号的记录

返回示例

200 返回

[
  {
    "uid": "100000",
    "available": {
      "user_id": 100003,
      "locked": false,
      "total": "20.000000",
      "borrowed": "0.000000",
      "interest": "0",
      "borrowed_net": "0",
      "net": "20",
      "leverage": "3",
      "risk": "9999.99",
      "total_initial_margin": "0.00",
      "total_margin_balance": "20.00",
      "total_maintenance_margin": "0.00",
      "total_initial_margin_rate": "9999.9900",
      "total_maintenance_margin_rate": "9999.9900",
      "total_available_margin": "20.00",
      "balances": {
        "USDT": {
          "available": "20.000000",
          "freeze": "0.000000",
          "borrowed": "0.000000",
          "interest": "0.000000"
        }
      }
    }
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表获取成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» uid	string	用户 ID
» available	object
»» user_id	integer(int64)	全仓帐户用户ID，如果 0 代表这个子帐号尚未开通全仓帐户
»» locked	boolean	账户是否被锁定
»» balances	object
»»» CrossMarginBalance	object
»»»» available	string	可用额度
»»»» freeze	string	被锁定的额度
»»»» borrowed	string	借入额度
»»»» interest	string	未还利息
»»» total	string	折算成 USDT 的账户总资产，即所有币种(不包括点卡)的 (available+freeze)*price*discount 之和
»»» borrowed	string	折算成 USDT 的账户总借入数量，即所有币种(不包括点卡)的 borrowed*price*discount 之和
»»» borrowed_net	string	折算成 USDT 的账户总借入数量 * 放大系数
»»» net	string	折算成 USDT 的净资产
»»» leverage	string	杠杆倍数
»»» interest	string	折算成 USDT 的账户未接利息的总和，即所有币种(不包括点卡)的 interest*price*discount 之和
»»» risk	string	风险率，风险率小于 110% 会被爆仓，计算方式 total / (borrowed+interest)
»»» total_initial_margin	string	总初始保证金
»»» total_margin_balance	string	总保证金余额
»»» total_maintenance_margin	string	总维持保证金
»»» total_initial_margin_rate	string	总初始保证金率
»»» total_maintenance_margin_rate	string	总维持保证金率
»»» total_available_margin	string	可用的保证金额度

WARNING

该请求需要 API key 和 secret 认证

查询提币地址白名单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/saved_address'
query_param = 'currency=USDT'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/saved_address"
query_param="currency=USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /wallet/saved_address

查询提币地址白名单

参数

名称	位置	类型	必选	描述
currency	请求参数	string	是	币种
chain	请求参数	string	否	链名称
limit	请求参数	string	否	列表返回的最大数量, 最多 100

详细描述

chain: 链名称

limit: 列表返回的最大数量, 最多 100

返回示例

200 返回

[
  {
    "currency": "usdt",
    "chain": "TRX",
    "address": "TWYirLzw2RARB2jfeFcfRPmeuU3rC7rakT",
    "name": "gate",
    "tag": "",
    "verified": "1"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表获取成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» currency	string	币种
» chain	string	链名称
» address	string	地址
» name	string	名称
» tag	string	标签
» verified	string	是否通过验证 0-未验证, 1-已验正

WARNING

该请求需要 API key 和 secret 认证

查询个人交易费率

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/fee'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/fee"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /wallet/fee

查询个人交易费率

参数

名称	位置	类型	必选	描述
currency_pair	请求参数	string	否	指定交易对获取更准确的费率设置。

详细描述

currency_pair: 指定交易对获取更准确的费率设置。

该字段可选，通常情况下所有交易对的费率设置是一样的。

返回示例

200 返回

{
  "user_id": 10001,
  "taker_fee": "0.002",
  "maker_fee": "0.002",
  "futures_taker_fee": "-0.00025",
  "futures_maker_fee": "0.00075",
  "gt_discount": false,
  "gt_taker_fee": "0",
  "gt_maker_fee": "0",
  "loan_fee": "0.18",
  "point_type": "1"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

名称	类型	描述
» user_id	integer(int64)	用户 ID
» taker_fee	string	taker 费率
» maker_fee	string	maker 费率
» gt_discount	boolean	是否开启 GT 抵扣折扣
» gt_taker_fee	string	GT 抵扣 taker 费率，未开启 GT 抵扣则为 0
» gt_maker_fee	string	GT 抵扣 maker 费率，未开启 GT 抵扣则为 0
» loan_fee	string	杠杆理财的费率
» point_type	string	点卡类型，0 - 初版点卡，1 - 202009 启用的新点卡
» futures_taker_fee	string	合约 taker 费率
» futures_maker_fee	string	合约 maker 费率

WARNING

该请求需要 API key 和 secret 认证

查询个人账户总额

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/total_balance'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/total_balance"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /wallet/total_balance

查询个人账户总额

该查询接口返回的是各账户里所有币按照传入币种折算之后的总估值，折算价以及相关各账户的余额信息最长会有1分钟的缓存， 不推荐在即时计算时使用该接口的数据。

即时计算可根据账户类型查询对应的余额接口，如：

• GET /spot/accounts 查询现货账户
• GET /margin/accounts 查询杠杆账户
• GET /futures/{settle}/accounts 查询合约账户

参数

名称	位置	类型	必选	描述
currency	请求参数	string	否	用于统计换算的目标货币类型，可接受BTC，CNY，USD，USDT四个值。USDT是默认值

详细描述

currency: 用于统计换算的目标货币类型，可接受BTC，CNY，USD，USDT四个值。USDT是默认值

返回示例

200 返回

{
  "details": {
    "cross_margin": {
      "amount": "0",
      "currency": "USDT"
    },
    "spot": {
      "currency": "USDT",
      "amount": "42264489969935775.5160259954878034182418"
    },
    "finance": {
      "amount": "662714381.70310327810191647181",
      "currency": "USDT"
    },
    "margin": {
      "amount": "1259175.664137668554329559",
      "currency": "USDT"
    },
    "quant": {
      "amount": "591702859674467879.6488202650892478553852",
      "currency": "USDT"
    },
    "futures": {
      "amount": "2384175.5606114082065",
      "currency": "USDT"
    },
    "delivery": {
      "currency": "USDT",
      "amount": "1519804.9756702"
    },
    "warrant": {
      "amount": "0",
      "currency": "USDT"
    },
    "cbbc": {
      "currency": "USDT",
      "amount": "0"
    }
  },
  "total": {
    "currency": "USDT",
    "amount": "633967350312281193.068368815439797304437"
  }
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	请求有效且成功返回	Inline

返回格式

状态码 200

用户总资产信息

名称	类型	描述
» total	object	换算成目标币种的账户总额
»» amount	string	账户总额数字
»» currency	string	币种
» details	object	各账户总额 - cross_margin: 全仓杠杆账户 - spot: 现货账户 - finance: 金融账户 - margin: 杠杆账户 - quant: 量化账户 - futures: 永续合约账户 - delivery: 交割合约账户 - warrant: warrant 账户 - cbbc: 牛熊证账户
»» additionalProperties	object	换算成目标币种的账户总额
»»» amount	string	账户总额数字
»»» currency	string	币种

枚举值列表

属性	值
currency	BTC
currency	CNY
currency	USD
currency	USDT
currency	BTC
currency	CNY
currency	USD
currency	USDT

WARNING

该请求需要 API key 和 secret 认证

Spot

现货交易

查询所有币种信息

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/spot/currencies \
  -H 'Accept: application/json'

GET /spot/currencies

查询所有币种信息

币种标识有两种类型：

1. 仅币种名称，如 BTC, USDT
2. <币>_<链>，如 HT_ETH

后者是一个币种对应多个链时会出现。不管是哪种类型，币种信息里都会包含 chain 字段来标识链信息。 使用币种信息时可以通过该单币种名称以及 <币>_ 开头的币种名称来获取某个币对应的所有链的信息。

返回示例

200 返回

[
  {
    "currency": "GT",
    "delisted": false,
    "withdraw_disabled": false,
    "withdraw_delayed": false,
    "deposit_disabled": false,
    "trade_disabled": false,
    "chain": "GT"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» currency	string	币种名称
» delisted	boolean	是否下架
» withdraw_disabled	boolean	是否暂停提现
» withdraw_delayed	boolean	提现是否存在延迟
» deposit_disabled	boolean	是否暂停充值
» trade_disabled	boolean	是否暂停交易
» fixed_rate	string	固定交易手续费率。仅限固定交易费率的币种，普通币种该字段无效
» chain	string	币对应的链

该请求不需要认证

查询单个币种信息

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/currencies/GT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/spot/currencies/GT \
  -H 'Accept: application/json'

GET /spot/currencies/{currency}

查询单个币种信息

参数

名称	位置	类型	必选	描述
currency	URL	string	是	币种名称

返回示例

200 返回

{
  "currency": "GT",
  "delisted": false,
  "withdraw_disabled": false,
  "withdraw_delayed": false,
  "deposit_disabled": false,
  "trade_disabled": false,
  "chain": "GT"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

名称	类型	描述
» currency	string	币种名称
» delisted	boolean	是否下架
» withdraw_disabled	boolean	是否暂停提现
» withdraw_delayed	boolean	提现是否存在延迟
» deposit_disabled	boolean	是否暂停充值
» trade_disabled	boolean	是否暂停交易
» fixed_rate	string	固定交易手续费率。仅限固定交易费率的币种，普通币种该字段无效
» chain	string	币对应的链

该请求不需要认证

查询支持的所有交易对

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/currency_pairs'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/spot/currency_pairs \
  -H 'Accept: application/json'

GET /spot/currency_pairs

查询支持的所有交易对

返回示例

200 返回

[
  {
    "id": "ETH_USDT",
    "base": "ETH",
    "quote": "USDT",
    "fee": "0.2",
    "min_base_amount": "0.001",
    "min_quote_amount": "1.0",
    "amount_precision": 3,
    "precision": 6,
    "trade_status": "tradable",
    "sell_start": 1516378650,
    "buy_start": 1516378650
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询到所有交易对	[CurrencyPair]

该请求不需要认证

查询单个交易对详情

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/currency_pairs/ETH_BTC'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/spot/currency_pairs/ETH_BTC \
  -H 'Accept: application/json'

GET /spot/currency_pairs/{currency_pair}

查询单个交易对详情

参数

名称	位置	类型	必选	描述
currency_pair	URL	string	是	交易对

返回示例

200 返回

{
  "id": "ETH_USDT",
  "base": "ETH",
  "quote": "USDT",
  "fee": "0.2",
  "min_base_amount": "0.001",
  "min_quote_amount": "1.0",
  "amount_precision": 3,
  "precision": 6,
  "trade_status": "tradable",
  "sell_start": 1516378650,
  "buy_start": 1516378650
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	成功查询	CurrencyPair

该请求不需要认证

获取交易对 ticker 信息

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/tickers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/spot/tickers \
  -H 'Accept: application/json'

GET /spot/tickers

获取交易对 ticker 信息

如果指定 currency_pair 则只查询该交易对，否则返回全部信息

参数

名称	位置	类型	必选	描述
currency_pair	请求参数	string	否	交易对
timezone	请求参数	string	否	时区

枚举值列表

参数	值
timezone	utc0
timezone	utc8
timezone	all

返回示例

200 返回

[
  {
    "currency_pair": "BTC3L_USDT",
    "last": "2.46140352",
    "lowest_ask": "2.477",
    "highest_bid": "2.4606821",
    "change_percentage": "-8.91",
    "change_utc0": "-8.91",
    "change_utc8": "-8.91",
    "base_volume": "656614.0845820589",
    "quote_volume": "1602221.66468375534639404191",
    "high_24h": "2.7431",
    "low_24h": "1.9863",
    "etf_net_value": "2.46316141",
    "etf_pre_net_value": "2.43201848",
    "etf_pre_timestamp": 1611244800,
    "etf_leverage": "2.2803019447281203"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	成功查询	[Inline]

返回格式

状态码 200

名称	类型	描述
» currency_pair	string	交易对
» last	string	最新成交价
» lowest_ask	string	最新卖方最低价
» highest_bid	string	最新买方最高价
» change_percentage	string	最近24h涨跌百分比，跌用负数标识，如 -7.45
» change_utc0	string	utc0时区，最近24h涨跌百分比，跌用负数标识，如 -7.45
» change_utc8	string	utc8时区，最近24h涨跌百分比，跌用负数标识，如 -7.45
» base_volume	string	最近24h交易货币成交量
» quote_volume	string	最近24h计价货币成交量
» high_24h	string	24小时最高价
» low_24h	string	24小时最低价
» etf_net_value	string	ETF 净值
» etf_pre_net_value	string|null	ETF 前一再平衡点净值
» etf_pre_timestamp	integer(int64)|null	ETF 前一再平衡时间
» etf_leverage	string|null	ETF 当前杠杆率

该请求不需要认证

获取市场深度信息

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/order_book'
query_param = 'currency_pair=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/spot/order_book?currency_pair=BTC_USDT \
  -H 'Accept: application/json'

GET /spot/order_book

获取市场深度信息

市场深度买单会按照价格从高到低排序，卖单反之

参数

名称	位置	类型	必选	描述
currency_pair	请求参数	string	是	交易对
interval	请求参数	string	否	合并深度指定的价格精度，0 为不合并，不指定则默认为 0
limit	请求参数	integer	否	深度档位数量
with_id	请求参数	boolean	否	返回深度更新 ID

返回示例

200 返回

{
  "id": 123456,
  "current": 1623898993123,
  "update": 1623898993121,
  "asks": [
    [
      "1.52",
      "1.151"
    ],
    [
      "1.53",
      "1.218"
    ]
  ],
  "bids": [
    [
      "1.17",
      "201.863"
    ],
    [
      "1.16",
      "725.464"
    ]
  ]
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	成功查询	Inline

返回格式

状态码 200

名称	类型	描述
» id	integer(int64)	深度更新ID。深度每发生一次变化，ID 就会更新一次。仅在 with_id 设置为 true 该值有效
» current	integer(int64)	接口数据返回 ms 时间戳
» update	integer(int64)	深度变化 ms 时间戳
» asks	array	卖方深度列表
»» None	array	价格，数量的二元组
» bids	array	买方深度列表
»» None	array	价格，数量的二元组

该请求不需要认证

查询市场成交记录

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/trades'
query_param = 'currency_pair=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/spot/trades?currency_pair=BTC_USDT \
  -H 'Accept: application/json'

GET /spot/trades

查询市场成交记录

支持指定 from 和 to 按时间范围查询或基于 last_id 的翻页查询。默认按时间范围查询。

基于 last_id 翻页的查询方式不再推荐继续使用。如果指定 last_id ，时间范围查询参数会被忽略。

参数

名称	位置	类型	必选	描述
currency_pair	请求参数	string	是	交易对
limit	请求参数	integer	否	列表返回的最大数量
last_id	请求参数	string	否	以上个列表的最后一条记录的 ID 作为下个列表的起点
reverse	请求参数	boolean	否	是否获取小于 last_id 的数据，默认返回大于 last_id 的记录。
from	请求参数	integer(int64)	否	查询记录的起始时间
to	请求参数	integer(int64)	否	查询记录的结束时间，不指定则默认为当前时间
page	请求参数	integer	否	列表页数

详细描述

reverse: 是否获取小于 last_id 的数据，默认返回大于 last_id 的记录。

设置该字段为 true 可以用来回溯市场成交记录，为 false 可以用来获取最新成交。

当 last_id 未设置时，该字段无效。

返回示例

200 返回

[
  {
    "id": "1232893232",
    "create_time": "1548000000",
    "create_time_ms": "1548000000123.456",
    "order_id": "4128442423",
    "side": "buy",
    "role": "maker",
    "amount": "0.15",
    "price": "0.03",
    "fee": "0.0005",
    "fee_currency": "ETH",
    "point_fee": "0",
    "gt_fee": "0"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» id	string	成交记录 ID
» create_time	string	成交时间
» create_time_ms	string	成交时间，毫秒精度
» currency_pair	string	交易货币对
» side	string	买单或者卖单
» role	string	交易角色，公共接口无此字段返回
» amount	string	交易数量
» price	string	交易价
» order_id	string	关联的订单 ID，公共接口无此字段返回
» fee	string	成交扣除的手续费，公共接口无此字段返回
» fee_currency	string	手续费计价单位，公共接口无此字段返回
» point_fee	string	手续费抵扣使用的点卡数量，公共接口无此字段返回
» gt_fee	string	手续费抵扣使用的 GT 数量，公共接口无此字段返回

枚举值列表

属性	值
side	buy
side	sell
role	taker
role	maker

该请求不需要认证

市场 K 线图

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/candlesticks'
query_param = 'currency_pair=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/spot/candlesticks?currency_pair=BTC_USDT \
  -H 'Accept: application/json'

GET /spot/candlesticks

市场 K 线图

K 线图数据单次请求最大返回 1000 个点，指定 from, to 和 interval 的时候注意点数不能过多

参数

名称	位置	类型	必选	描述
currency_pair	请求参数	string	是	交易对
limit	请求参数	integer	否	指定数据点的数量，适用于取最近 limit 数量的数据，该字段与 from, to 互斥，如果指定了
from	请求参数	integer(int64)	否	指定 K 线图的起始时间，注意时间格式为秒(s)精度的 Unix 时间戳，
to	请求参数	integer(int64)	否	指定 K 线图的结束时间，不指定则默认当前时间，注意时间格式为秒(s)精度的 Unix 时间戳
interval	请求参数	string	否	数据点的时间间隔， 注意 30d 代表的是自然月，不是按30天对齐

详细描述

limit: 指定数据点的数量，适用于取最近 limit 数量的数据，该字段与 from, to 互斥，如果指定了 from, to 中的任意字段，该字段会被拒绝

from: 指定 K 线图的起始时间，注意时间格式为秒(s)精度的 Unix 时间戳， 不指定则默认为 to - 100 * interval，即向前最多 100 个点的时间

to: 指定 K 线图的结束时间，不指定则默认当前时间，注意时间格式为秒(s)精度的 Unix 时间戳

枚举值列表

参数	值
interval	10s
interval	1m
interval	5m
interval	15m
interval	30m
interval	1h
interval	4h
interval	8h
interval	1d
interval	7d
interval	30d

返回示例

200 返回

[
  [
    "1539852480",
    "971519.677",
    "0.0021724",
    "0.0021922",
    "0.0021724",
    "0.0021737"
  ]
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	成功查询	[[string]]

返回格式

状态码 200

名称	类型	描述
» None	array	每个时间粒度的 K 线数据，从左到右依次为: - 秒(s)精度的 Unix 时间戳 - 计价货币交易额 - 收盘价 - 最高价 - 最低价 - 开盘价 - 基础货币交易量

该请求不需要认证

查询账户费率

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/fee'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/fee"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /spot/fee

查询账户费率

该接口已废弃，不再推荐使用，新的费率查询接口为 /wallet/fee

参数

名称	位置	类型	必选	描述
currency_pair	请求参数	string	否	指定交易对获取更准确的费率设置。

详细描述

currency_pair: 指定交易对获取更准确的费率设置。

该字段可选，通常情况下所有交易对的费率设置是一样的。

返回示例

200 返回

{
  "user_id": 10001,
  "taker_fee": "0.002",
  "maker_fee": "0.002",
  "futures_taker_fee": "-0.00025",
  "futures_maker_fee": "0.00075",
  "gt_discount": false,
  "gt_taker_fee": "0",
  "gt_maker_fee": "0",
  "loan_fee": "0.18",
  "point_type": "1"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

名称	类型	描述
» user_id	integer(int64)	用户 ID
» taker_fee	string	taker 费率
» maker_fee	string	maker 费率
» gt_discount	boolean	是否开启 GT 抵扣折扣
» gt_taker_fee	string	GT 抵扣 taker 费率，未开启 GT 抵扣则为 0
» gt_maker_fee	string	GT 抵扣 maker 费率，未开启 GT 抵扣则为 0
» loan_fee	string	杠杆理财的费率
» point_type	string	点卡类型，0 - 初版点卡，1 - 202009 启用的新点卡
» futures_taker_fee	string	合约 taker 费率
» futures_maker_fee	string	合约 maker 费率

WARNING

该请求需要 API key 和 secret 认证

获取现货交易账户列表

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/accounts'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /spot/accounts

获取现货交易账户列表

参数

名称	位置	类型	必选	描述
currency	请求参数	string	否	指定币种名称查询

返回示例

200 返回

[
  {
    "currency": "ETH",
    "available": "968.8",
    "locked": "0"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» currency	string	币种信息
» available	string	可用金额
» locked	string	冻结金额

WARNING

该请求需要 API key 和 secret 认证

批量下单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/batch_orders'
query_param = ''
body='[{"text":"t-123456","currency_pair":"ETH_BTC","type":"limit","account":"spot","side":"buy","iceberg":"0","amount":"1","price":"5.00032","time_in_force":"gtc","auto_borrow":false}]'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/batch_orders"
query_param=""
body_param='[{"text":"t-123456","currency_pair":"ETH_BTC","type":"limit","account":"spot","side":"buy","iceberg":"0","amount":"1","price":"5.00032","time_in_force":"gtc","auto_borrow":false}]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /spot/batch_orders

批量下单

批量下单要求：

1. 用户自定义订单信息 text 必须指定
2. 每次只能下最多 4 个交易对且每个交易对只可批量下 10 个单
3. 现货交易和杠杆交易不能同时存在，即同个请求里所有 account 必须一致

请求体示例

[
  {
    "text": "t-123456",
    "currency_pair": "ETH_BTC",
    "type": "limit",
    "account": "spot",
    "side": "buy",
    "iceberg": "0",
    "amount": "1",
    "price": "5.00032",
    "time_in_force": "gtc",
    "auto_borrow": false
  }
]

参数

名称	位置	类型	必选	描述
body	body	array[object]	是

返回示例

200 返回

[
  {
    "text": "t-123456",
    "succeeded": true,
    "label": "",
    "message": "",
    "id": "12332324",
    "create_time": "1548000000",
    "update_time": "1548000100",
    "create_time_ms": 1548000000123,
    "update_time_ms": 1548000100123,
    "currency_pair": "ETC_BTC",
    "status": "cancelled",
    "type": "limit",
    "account": "spot",
    "side": "buy",
    "amount": "1",
    "price": "5.00032",
    "time_in_force": "gtc",
    "iceberg": "0",
    "left": "0.5",
    "filled_total": "2.50016",
    "fee": "0.005",
    "fee_currency": "ETH",
    "point_fee": "0",
    "gt_fee": "0",
    "gt_discount": false,
    "rebated_fee": "0",
    "rebated_fee_currency": "BTC"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	请求执行完成	[Inline]

返回格式

状态码 200

名称	类型	描述
» None	object	批量订单信息
»» text	string	订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件： 1. 必须以 t- 开头 2. 不计算 t- ，长度不能超过 28 字节 3. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.)
»» succeeded	boolean	请求执行结果
»» label	string	错误标识，当订单成功时该字段为空串
»» message	string	错误详情，当订单成功时改字段为空串
»» id	string	订单 ID
»» create_time	string	订单创建时间
»» update_time	string	订单最新修改时间
»» create_time_ms	integer(int64)	订单创建时间，毫秒精度
»» update_time_ms	integer(int64)	订单最近修改时间，毫秒精度
»» status	string	订单状态。 - open: 等待处理 - closed: 全部成交 - cancelled: 订单撤销
»» currency_pair	string	交易货币对
»» type	string	订单类型，limit - 限价单
»» account	string	账户类型，spot - 现货账户，margin - 杠杆账户，cross_margin - 全仓杠杆账户
»» side	string	买单或者卖单
»» amount	string	交易数量
»» price	string	交易价
»» time_in_force	string	Time in force 策略。 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单 - poc: PendingOrCancelled，被动委托，只挂单不吃单 - fok: FillOrKill，全部成交或者全部取消
»» iceberg	string	冰山下单显示的数量，不指定或传 0 都默认为普通下单。如果需要全部冰山，设置为 -1
»» auto_repay	boolean	全仓杠杆下单是否开启自动还款，默认关闭。需要注意的是: 1. 此字段仅针对全仓杠杆有效。逐仓杠杆不支持订单级别的自动还款设置，只能通过 POST /margin/auto_repay 修改用户级别的设置 2. auto_borrow 与 auto_repay 不支持同时开启
»» left	string	交易货币未成交数量
»» fill_price	string	已成交的计价币种总额，该字段废弃，建议使用相同意义的 filled_total
»» filled_total	string	已成交总金额
»» fee	string	成交扣除的手续费
»» fee_currency	string	手续费计价单位
»» point_fee	string	手续费抵扣使用的点卡数量
»» gt_fee	string	手续费抵扣使用的 GT 数量
»» gt_discount	boolean	是否开启GT抵扣
»» rebated_fee	string	返还的手续费
»» rebated_fee_currency	string	返还手续费计价单位

枚举值列表

属性	值
status	open
status	closed
status	cancelled
type	limit
account	spot
account	margin
account	cross_margin
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok

WARNING

该请求需要 API key 和 secret 认证

查询所有挂单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/open_orders'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/open_orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /spot/open_orders

查询所有挂单

查询所有交易对的当前挂单列表。

注意分页参数控制的是每个交易对里的挂单数量，交易对个数没有分页控制，所有有挂单的交易对全部返回。

默认查询现货和逐仓杠杆账户的挂单信息。查询全仓杠杆账户时，必须指定 account 参数为 cross_margin

参数

名称	位置	类型	必选	描述
page	请求参数	integer	否	列表页数
limit	请求参数	integer	否	每个交易对每页最多返回的数量
account	请求参数	string	否	指定查询账户。不指定默认现货和逐仓杠杆账户。指定 cross_margin 则查询全仓杠杆账户。

详细描述

account: 指定查询账户。不指定默认现货和逐仓杠杆账户。指定 cross_margin 则查询全仓杠杆账户。
统一账户只能指定 cross_margin

返回示例

200 返回

[
  {
    "currency_pair": "ETH_BTC",
    "total": 1,
    "orders": [
      {
        "id": "12332324",
        "text": "t-123456",
        "create_time": "1548000000",
        "update_time": "1548000100",
        "currency_pair": "ETH_BTC",
        "status": "open",
        "type": "limit",
        "account": "spot",
        "side": "buy",
        "amount": "1",
        "price": "5.00032",
        "time_in_force": "gtc",
        "left": "0.5",
        "filled_total": "2.50016",
        "fee": "0.005",
        "fee_currency": "ETH",
        "point_fee": "0",
        "gt_fee": "0",
        "gt_discount": false,
        "rebated_fee": "0",
        "rebated_fee_currency": "BTC"
      }
    ]
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» currency_pair	string	交易对
» total	integer	该交易对当前挂单总数
» orders	array
»» None	object	现货单详情
»»» id	string	订单 ID
»»» text	string	订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件： 1. 必须以 t- 开头 2. 不计算 t- ，长度不能超过 28 字节 3. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.)
»»» create_time	string	订单创建时间
»»» update_time	string	订单最新修改时间
»»» create_time_ms	integer(int64)	订单创建时间，毫秒精度
»»» update_time_ms	integer(int64)	订单最近修改时间，毫秒精度
»»» status	string	订单状态。 - open: 等待处理 - closed: 全部成交 - cancelled: 订单撤销
»»» currency_pair	string	交易货币对
»»» type	string	订单类型，limit - 限价单
»»» account	string	账户类型，spot - 现货账户，margin - 杠杆账户，cross_margin - 全仓杠杆账户 统一账户只能设置 cross_margin
»»» side	string	买单或者卖单
»»» amount	string	交易数量
»»» price	string	交易价
»»» time_in_force	string	Time in force 策略。 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单 - poc: PendingOrCancelled，被动委托，只挂单不吃单 - fok: FillOrKill，全部成交或者全部取消
»»» iceberg	string	冰山下单显示的数量，不指定或传 0 都默认为普通下单。如果需要全部冰山，设置为 -1
»»» auto_repay	boolean	全仓杠杆下单是否开启自动还款，默认关闭。需要注意的是: 1. 此字段仅针对全仓杠杆有效。逐仓杠杆不支持订单级别的自动还款设置，只能通过 POST /margin/auto_repay 修改用户级别的设置 2. auto_borrow 与 auto_repay 不支持同时开启
»»» left	string	交易货币未成交数量
»»» fill_price	string	已成交的计价币种总额，该字段废弃，建议使用相同意义的 filled_total
»»» filled_total	string	已成交总金额
»»» fee	string	成交扣除的手续费
»»» fee_currency	string	手续费计价单位
»»» point_fee	string	手续费抵扣使用的点卡数量
»»» gt_fee	string	手续费抵扣使用的 GT 数量
»»» gt_discount	boolean	是否开启GT抵扣
»»» rebated_fee	string	返还的手续费
»»» rebated_fee_currency	string	返还手续费计价单位

枚举值列表

属性	值
status	open
status	closed
status	cancelled
type	limit
account	spot
account	margin
account	cross_margin
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok

WARNING

该请求需要 API key 和 secret 认证

禁用币种下平仓单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/cross_liquidate_orders'
query_param = ''
body='{"currency_pair":"GT_USDT","amount":"12","price":"10.15","text":"t-34535"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/cross_liquidate_orders"
query_param=""
body_param='{"currency_pair":"GT_USDT","amount":"12","price":"10.15","text":"t-34535"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /spot/cross_liquidate_orders

禁用币种下平仓单

目前只支持全仓账户对禁用币种进行买入下单 最大买入数量 = (未还本息 - 币种余额 - 挂单该币种数量) / 0.998

请求体示例

{
  "currency_pair": "GT_USDT",
  "amount": "12",
  "price": "10.15",
  "text": "t-34535"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» text	body	string	否	订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件：
» currency_pair	body	string	是	交易货币对
» amount	body	string	是	交易数量
» price	body	string	是	交易价

详细描述

» text: 订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件：

1. 必须以 t- 开头
2. 不计算 t- ，长度不能超过 28 字节
3. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.)

返回示例

201 返回

{
  "id": "12332324",
  "text": "t-123456",
  "create_time": "1548000000",
  "update_time": "1548000100",
  "create_time_ms": 1548000000123,
  "update_time_ms": 1548000100123,
  "currency_pair": "ETH_BTC",
  "status": "cancelled",
  "type": "limit",
  "account": "spot",
  "side": "buy",
  "iceberg": "0",
  "amount": "1",
  "price": "5.00032",
  "time_in_force": "gtc",
  "left": "0.5",
  "filled_total": "2.50016",
  "fee": "0.005",
  "fee_currency": "ETH",
  "point_fee": "0",
  "gt_fee": "0",
  "gt_discount": false,
  "rebated_fee": "0",
  "rebated_fee_currency": "BTC"
}

返回

状态码	含义	描述	格式
201	Created (opens new window)	交易成功执行	Order

WARNING

该请求需要 API key 和 secret 认证

下单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/orders'
query_param = ''
body='{"text":"t-123456","currency_pair":"ETH_BTC","type":"limit","account":"spot","side":"buy","iceberg":"0","amount":"1","price":"5.00032","time_in_force":"gtc","auto_borrow":false}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/orders"
query_param=""
body_param='{"text":"t-123456","currency_pair":"ETH_BTC","type":"limit","account":"spot","side":"buy","iceberg":"0","amount":"1","price":"5.00032","time_in_force":"gtc","auto_borrow":false}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /spot/orders

下单

支持现货、杠杆、全仓杠杆下单。通过 account 字段来使用不同的账户，默认为 spot ，即使用现货账户下单。

使用杠杆账户交易，即 account 设置为 margin 的时候，可以设置 auto_borrow 为 true， 在账户余额不足的情况，由系统自动执行 POST /margin/loans 借入不足部分。 杠杆下单成交之后的获取到的资产是否自动用于归还逐仓杠杆账户的借入单，取决于用户逐仓杠杆账户的自动还款设置， 该账户自动还款设置可以通过 /margin/auto_repay 来查询和设置。

使用全仓杠杆账户交易，即 account 设置为 cross_margin 的时候，同样可以启用 auto_borrow 来实现自动借入不足部分，但是与逐仓杠杆账户不同的是，全仓杠杆账户的委托是否自动还款取决于下单时的 auto_repay 设置，该设置只对当前委托生效，即只有该委托成交之后获取到的资产会用来还款全仓杠杆账户的借入单。 全仓杠杆账户下单目前不支持同时开启 auto_borrow 和 auto_repay。

自动还款会在订单结束时触发，即 status 为 cancelled 或者 closed 。

委托状态

挂单中的委托状态是 open ，在数量全部成交之前保持为 open 。如果被全部吃掉，则订单结束，状态变成 closed 。 假如全部成交之前，订单被撤销，不管是否有部分成交，状态都会变为 cancelled

冰山委托

iceberg 用来设置冰山委托显示的数量，如果需要完全隐藏，设置为 -1 。注意隐藏部分成交时按照 taker 的手续费率收取。

请求体示例

{
  "text": "t-123456",
  "currency_pair": "ETH_BTC",
  "type": "limit",
  "account": "spot",
  "side": "buy",
  "iceberg": "0",
  "amount": "1",
  "price": "5.00032",
  "time_in_force": "gtc",
  "auto_borrow": false
}

参数

名称	位置	类型	必选	描述
body	body	Order	是
» text	body	string	否	订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件：
» currency_pair	body	string	是	交易货币对
» type	body	string	否	订单类型，limit - 限价单
» account	body	string	否	账户类型，spot - 现货账户，margin - 杠杆账户，cross_margin - 全仓杠杆账户
» side	body	string	是	买单或者卖单
» amount	body	string	是	交易数量
» price	body	string	是	交易价
» time_in_force	body	string	否	Time in force 策略。
» iceberg	body	string	否	冰山下单显示的数量，不指定或传 0 都默认为普通下单。如果需要全部冰山，设置为 -1
» auto_borrow	body	boolean	否	杠杆(包括逐仓全仓)交易时，如果账户余额不足，是否由系统自动借入不足部分
» auto_repay	body	boolean	否	全仓杠杆下单是否开启自动还款，默认关闭。需要注意的是:

详细描述

» text: 订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件：

1. 必须以 t- 开头
2. 不计算 t- ，长度不能超过 28 字节
3. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.)

» account: 账户类型，spot - 现货账户，margin - 杠杆账户，cross_margin - 全仓杠杆账户
统一账户只能设置 cross_margin

» time_in_force: Time in force 策略。

• gtc: GoodTillCancelled
• ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单
• poc: PendingOrCancelled，被动委托，只挂单不吃单
• fok: FillOrKill，全部成交或者全部取消

» auto_repay: 全仓杠杆下单是否开启自动还款，默认关闭。需要注意的是:

1. 此字段仅针对全仓杠杆有效。逐仓杠杆不支持订单级别的自动还款设置，只能通过 POST /margin/auto_repay 修改用户级别的设置
2. auto_borrow 与 auto_repay 不支持同时开启

枚举值列表

参数	值
» type	limit
» account	spot
» account	margin
» account	cross_margin
» side	buy
» side	sell
» time_in_force	gtc
» time_in_force	ioc
» time_in_force	poc
» time_in_force	fok

返回示例

201 返回

{
  "id": "12332324",
  "text": "t-123456",
  "create_time": "1548000000",
  "update_time": "1548000100",
  "create_time_ms": 1548000000123,
  "update_time_ms": 1548000100123,
  "currency_pair": "ETH_BTC",
  "status": "cancelled",
  "type": "limit",
  "account": "spot",
  "side": "buy",
  "iceberg": "0",
  "amount": "1",
  "price": "5.00032",
  "time_in_force": "gtc",
  "left": "0.5",
  "filled_total": "2.50016",
  "fee": "0.005",
  "fee_currency": "ETH",
  "point_fee": "0",
  "gt_fee": "0",
  "gt_discount": false,
  "rebated_fee": "0",
  "rebated_fee_currency": "BTC"
}

返回

状态码	含义	描述	格式
201	Created (opens new window)	交易成功执行。具体执行结果根据下单时的 Time in force 策略来决定	Order

WARNING

该请求需要 API key 和 secret 认证

查询订单列表

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/orders'
query_param = 'currency_pair=BTC_USDT&status=open'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/orders"
query_param="currency_pair=BTC_USDT&status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /spot/orders

查询订单列表

注意查询结果默认是现货和逐仓杠杆账户的订单列表，如果查询全仓杠杆账户的订单列表时，必须要设置 account 为 cross_margin

status 设置为 open ，即查询挂单列表时，只支持 page 和 limit 的分页控制。 limit 最大只允许设置到 100 。 不支持 side 和按时间范围查询的 from, to 参数。

status 设置为 finished ，即查询历史委托的时候， 除分页查询以外，还支持 from 和 to 按时间范围的查询。 此外还支持设置 side 参数筛选单边历史。

时间范围筛选的参数均是按订单结束时间来处理。

参数

名称	位置	类型	必选	描述
currency_pair	请求参数	string	是	指定交易对查询。如果查询挂单的记录，该字段必选。如果查询已成交的记录，该字段可以不指定。
status	请求参数	string	是	基于状态查询订单列表
page	请求参数	integer	否	列表页数
limit	请求参数	integer	否	列表返回的最大数量，如果 status 设置为 open ，limit 最大允许 100
account	请求参数	string	否	指定查询账户。不指定默认现货和逐仓杠杆账户。指定 cross_margin 则查询全仓杠杆账户。
from	请求参数	integer(int64)	否	查询记录的起始时间
to	请求参数	integer(int64)	否	查询记录的结束时间，不指定则默认为当前时间
side	请求参数	string	否	指定全部买单或全部卖单，不指定则两者都包括

详细描述

status: 基于状态查询订单列表

open - 挂单中 finished - 已结束

account: 指定查询账户。不指定默认现货和逐仓杠杆账户。指定 cross_margin 则查询全仓杠杆账户。
统一账户只能指定 cross_margin

枚举值列表

参数	值
status	open
status	finished
side	buy
side	sell

返回示例

200 返回

[
  {
    "id": "12332324",
    "text": "t-123456",
    "create_time": "1548000000",
    "update_time": "1548000100",
    "create_time_ms": 1548000000123,
    "update_time_ms": 1548000100123,
    "currency_pair": "ETH_BTC",
    "status": "cancelled",
    "type": "limit",
    "account": "spot",
    "side": "buy",
    "iceberg": "0",
    "amount": "1",
    "price": "5.00032",
    "time_in_force": "gtc",
    "left": "0.5",
    "filled_total": "2.50016",
    "fee": "0.005",
    "fee_currency": "ETH",
    "point_fee": "0",
    "gt_fee": "0",
    "gt_discount": false,
    "rebated_fee": "0",
    "rebated_fee_currency": "BTC"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Order]

WARNING

该请求需要 API key 和 secret 认证

批量取消一个交易对里状态为 open 的订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/orders'
query_param = 'currency_pair=BTC_USDT'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/spot/orders"
query_param="currency_pair=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /spot/orders

批量取消一个交易对里状态为 open 的订单

不指定 account 参数时，包括现货、逐仓杠杆和全仓杠杆在内的所有挂单都会执行撤销操作。

可以单独指定某一种账户，撤销指定账户下的所有挂单

参数

名称	位置	类型	必选	描述
currency_pair	请求参数	string	是	交易对
side	请求参数	string	否	指定全部买单或全部卖单，不指定则两者都包括
account	请求参数	string	否	指定账户类型

详细描述

account: 指定账户类型

• 经典账户：不指定则全部包含
• 统一账户：只能指定cross_margin

枚举值列表

参数	值
side	buy
side	sell
account	spot
account	margin
account	cross_margin

返回示例

200 返回

[
  {
    "id": "12332324",
    "text": "t-123456",
    "create_time": "1548000000",
    "update_time": "1548000100",
    "create_time_ms": 1548000000123,
    "update_time_ms": 1548000100123,
    "currency_pair": "ETH_BTC",
    "status": "cancelled",
    "type": "limit",
    "account": "spot",
    "side": "buy",
    "iceberg": "0",
    "amount": "1",
    "price": "5.00032",
    "time_in_force": "gtc",
    "left": "0.5",
    "filled_total": "2.50016",
    "fee": "0.005",
    "fee_currency": "ETH",
    "point_fee": "0",
    "gt_fee": "0",
    "gt_discount": false,
    "rebated_fee": "0",
    "rebated_fee_currency": "BTC"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	批量撤销请求接收并处理，是否成功根据订单列表来决定	[Order]

WARNING

该请求需要 API key 和 secret 认证

批量撤销指定 ID 的订单列表

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/cancel_batch_orders'
query_param = ''
body='[{"currency_pair":"BTC_USDT","id":"123456"}]'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/cancel_batch_orders"
query_param=""
body_param='[{"currency_pair":"BTC_USDT","id":"123456"}]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /spot/cancel_batch_orders

批量撤销指定 ID 的订单列表

可以指定多个不同的交易对。一次请求最多只能撤销 20 条记录

请求体示例

[
  {
    "currency_pair": "BTC_USDT",
    "id": "123456"
  }
]

参数

名称	位置	类型	必选	描述
body	body	array[object]	是

返回示例

200 返回

[
  {
    "currency_pair": "BTC_USDT",
    "id": "123456",
    "succeeded": true,
    "label": null,
    "message": null
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	撤销任务执行完成	[Inline]

返回格式

状态码 200

名称	类型	描述
» CancelOrderResult	object	订单撤销结果
»» currency_pair	string	订单的交易对
»» id	string	订单 ID
»» succeeded	boolean	是否撤销成功
»» label	string	撤销失败时的错误标识，成功时为空
»» message	string	撤销失败时的错误描述，成功时为空
»» account	string	默认为空，当撤销的订单是全仓杠杆账户订单时，该字段为 cross_margin

WARNING

该请求需要 API key 和 secret 认证

查询单个订单详情

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/orders/12345'
query_param = 'currency_pair=BTC_USDT'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/orders/12345"
query_param="currency_pair=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /spot/orders/{order_id}

查询单个订单详情

默认查询现货、逐仓杠杆账户的订单，如果需要查询全仓杠杆账户订单，必须指定 account 为 cross_margin。 统一账户 account 只能指定为 cross_margin。

参数

名称	位置	类型	必选	描述
order_id	URL	string	是	成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID（即 text 字段）。
currency_pair	请求参数	string	是	交易对
account	请求参数	string	否	指定查询账户。不指定默认现货和逐仓杠杆账户。指定 cross_margin 则查询全仓杠杆账户。

详细描述

order_id: 成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID（即 text 字段）。 基于自定义 ID 的操作只在订单创建之后的 30 分钟之内有效，过期之后只能使用订单 ID

account: 指定查询账户。不指定默认现货和逐仓杠杆账户。指定 cross_margin 则查询全仓杠杆账户。
统一账户只能指定 cross_margin

返回示例

200 返回

{
  "id": "12332324",
  "text": "t-123456",
  "create_time": "1548000000",
  "update_time": "1548000100",
  "create_time_ms": 1548000000123,
  "update_time_ms": 1548000100123,
  "currency_pair": "ETH_BTC",
  "status": "cancelled",
  "type": "limit",
  "account": "spot",
  "side": "buy",
  "iceberg": "0",
  "amount": "1",
  "price": "5.00032",
  "time_in_force": "gtc",
  "left": "0.5",
  "filled_total": "2.50016",
  "fee": "0.005",
  "fee_currency": "ETH",
  "point_fee": "0",
  "gt_fee": "0",
  "gt_discount": false,
  "rebated_fee": "0",
  "rebated_fee_currency": "BTC"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	详情查询成功	Order

WARNING

该请求需要 API key 和 secret 认证

撤销单个订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/orders/12345'
query_param = 'currency_pair=BTC_USDT'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/spot/orders/12345"
query_param="currency_pair=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /spot/orders/{order_id}

撤销单个订单

默认撤销现货、逐仓杠杆账户的订单，如果需要撤销全仓杠杆账户订单，必须指定 account 为 cross_margin。 统一账户 account 只能指定为 cross_margin。

参数

名称	位置	类型	必选	描述
order_id	URL	string	是	成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID（即 text 字段）。
currency_pair	请求参数	string	是	交易对
account	请求参数	string	否	指定查询账户。不指定默认现货和逐仓杠杆账户。指定 cross_margin 则查询全仓杠杆账户。

详细描述

order_id: 成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID（即 text 字段）。 基于自定义 ID 的操作只在订单创建之后的 30 分钟之内有效，过期之后只能使用订单 ID

account: 指定查询账户。不指定默认现货和逐仓杠杆账户。指定 cross_margin 则查询全仓杠杆账户。
统一账户只能指定 cross_margin

返回示例

200 返回

{
  "id": "12332324",
  "text": "t-123456",
  "create_time": "1548000000",
  "update_time": "1548000100",
  "create_time_ms": 1548000000123,
  "update_time_ms": 1548000100123,
  "currency_pair": "ETH_BTC",
  "status": "cancelled",
  "type": "limit",
  "account": "spot",
  "side": "buy",
  "iceberg": "0",
  "amount": "1",
  "price": "5.00032",
  "time_in_force": "gtc",
  "left": "0.5",
  "filled_total": "2.50016",
  "fee": "0.005",
  "fee_currency": "ETH",
  "point_fee": "0",
  "gt_fee": "0",
  "gt_discount": false,
  "rebated_fee": "0",
  "rebated_fee_currency": "BTC"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	订单撤销成功	Order

WARNING

该请求需要 API key 和 secret 认证

查询个人成交记录

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/my_trades'
query_param = 'currency_pair=BTC_USDT'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/my_trades"
query_param="currency_pair=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /spot/my_trades

查询个人成交记录

默认查询现货、逐仓杠杆账户的成交记录，如果需要查询全仓杠杆账户的成交记录，必须指定 account 为 cross_margin 。

可以通过指定 from 或(和) to 来查询指定时间范围内的历史。

时间范围筛选的参数均是按订单结束时间来处理。

参数

名称	位置	类型	必选	描述
currency_pair	请求参数	string	是	指定交易对查询。如果查询挂单的记录，该字段必选。如果查询已成交的记录，该字段可以不指定。
limit	请求参数	integer	否	列表返回的最大数量
page	请求参数	integer	否	列表页数
order_id	请求参数	string	否	指定查询订单 ID 的成交记录。指定该参数时 currency_pair 要求必填
account	请求参数	string	否	指定查询账户。不指定默认现货和逐仓杠杆账户。指定 cross_margin 则查询全仓杠杆账户。
from	请求参数	integer(int64)	否	查询记录的起始时间
to	请求参数	integer(int64)	否	查询记录的结束时间，不指定则默认为当前时间

详细描述

account: 指定查询账户。不指定默认现货和逐仓杠杆账户。指定 cross_margin 则查询全仓杠杆账户。
统一账户只能指定 cross_margin

返回示例

200 返回

[
  {
    "id": "1232893232",
    "create_time": "1548000000",
    "create_time_ms": "1548000000123.456",
    "order_id": "4128442423",
    "side": "buy",
    "role": "maker",
    "amount": "0.15",
    "price": "0.03",
    "fee": "0.0005",
    "fee_currency": "ETH",
    "point_fee": "0",
    "gt_fee": "0"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» id	string	成交记录 ID
» create_time	string	成交时间
» create_time_ms	string	成交时间，毫秒精度
» currency_pair	string	交易货币对
» side	string	买单或者卖单
» role	string	交易角色，公共接口无此字段返回
» amount	string	交易数量
» price	string	交易价
» order_id	string	关联的订单 ID，公共接口无此字段返回
» fee	string	成交扣除的手续费，公共接口无此字段返回
» fee_currency	string	手续费计价单位，公共接口无此字段返回
» point_fee	string	手续费抵扣使用的点卡数量，公共接口无此字段返回
» gt_fee	string	手续费抵扣使用的 GT 数量，公共接口无此字段返回

枚举值列表

属性	值
side	buy
side	sell
role	taker
role	maker

WARNING

该请求需要 API key 和 secret 认证

获取服务器当前时间

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/time'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/spot/time \
  -H 'Accept: application/json'

GET /spot/time

获取服务器当前时间

返回示例

200 返回

{
  "server_time": 1597026383085
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	成功查询	Inline

返回格式

状态码 200

SystemTime

名称	类型	描述
» server_time	integer(int64)	服务器当前时间(ms)

该请求不需要认证

创建价格触发订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/price_orders'
query_param = ''
body='{"trigger":{"price":"100","rule":">=","expiration":3600},"put":{"type":"limit","side":"buy","price":"2.15","amount":"2.00000000","account":"normal","time_in_force":"gtc"},"market":"GT_USDT"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/price_orders"
query_param=""
body_param='{"trigger":{"price":"100","rule":">=","expiration":3600},"put":{"type":"limit","side":"buy","price":"2.15","amount":"2.00000000","account":"normal","time_in_force":"gtc"},"market":"GT_USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /spot/price_orders

创建价格触发订单

请求体示例

{
  "trigger": {
    "price": "100",
    "rule": ">=",
    "expiration": 3600
  },
  "put": {
    "type": "limit",
    "side": "buy",
    "price": "2.15",
    "amount": "2.00000000",
    "account": "normal",
    "time_in_force": "gtc"
  },
  "market": "GT_USDT"
}

参数

名称	位置	类型	必选	描述
body	body	SpotPriceTriggeredOrder	是
» trigger	body	object	是
»» price	body	string	是	触发价格
»» rule	body	string	是	价格条件类型
»» expiration	body	integer	是	最长等待触发时间，超时则取消该订单，单位是秒 s
» put	body	object	是
»» type	body	string	否	订单类型,目前默认为限价单
»» side	body	string	是	买卖方向
»» price	body	string	是	挂单价格
»» amount	body	string	是	挂单数量
»» account	body	string	是	交易账户类型，统一账户只能设置 cross_margin
»» time_in_force	body	string	否	time_in_force
» market	body	string	是	市场

详细描述

»» rule: 价格条件类型

• =: 表示市场价格大于等于 price时触发

• <=: 表示市场价格小于等于 price时触发

»» side: 买卖方向

• buy: 买
• sell: 卖

»» account: 交易账户类型，统一账户只能设置 cross_margin

• normal: 现货交易
• margin: 杠杆交易
• cross_margin: 全仓杠杆交易

»» time_in_force: time_in_force

• gtc: GoodTillCancelled
• ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单

枚举值列表

参数	值
»» rule	>=
»» rule	<=
»» side	buy
»» side	sell
»» account	normal
»» account	margin
»» account	cross_margin
»» time_in_force	gtc
»» time_in_force	ioc

返回示例

201 返回

{
  "id": 1432329
}

返回

状态码	含义	描述	格式
201	Created (opens new window)	成功下单	Inline

返回格式

状态码 201

TriggerOrderResponse

名称	类型	描述
» id	integer(int64)	自动订单 ID

WARNING

该请求需要 API key 和 secret 认证

查询进行中自动订单列表

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/price_orders'
query_param = 'status=open'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/price_orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /spot/price_orders

查询进行中自动订单列表

参数

名称	位置	类型	必选	描述
status	请求参数	string	是	基于状态查询订单列表
market	请求参数	string	否	交易市场
account	请求参数	string	否	交易账户类型，统一账户只能设置 cross_margin
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始

枚举值列表

参数	值
status	open
status	finished
account	normal
account	margin
account	cross_margin

返回示例

200 返回

[
  {
    "trigger": {
      "price": "100",
      "rule": ">=",
      "expiration": 3600
    },
    "put": {
      "type": "limit",
      "side": "buy",
      "price": "2.15",
      "amount": "2.00000000",
      "account": "normal",
      "time_in_force": "gtc"
    },
    "id": 1283293,
    "user": 1234,
    "market": "GT_USDT",
    "ctime": 1616397800,
    "ftime": 1616397801,
    "fired_order_id": 0,
    "status": "",
    "reason": ""
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[SpotPriceTriggeredOrder]

WARNING

该请求需要 API key 和 secret 认证

批量取消自动订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/price_orders'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/spot/price_orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /spot/price_orders

批量取消自动订单

参数

名称	位置	类型	必选	描述
market	请求参数	string	否	交易市场
account	请求参数	string	否	交易账户类型，统一账户只能设置 cross_margin

枚举值列表

参数	值
account	normal
account	margin
account	cross_margin

返回示例

200 返回

[
  {
    "trigger": {
      "price": "100",
      "rule": ">=",
      "expiration": 3600
    },
    "put": {
      "type": "limit",
      "side": "buy",
      "price": "2.15",
      "amount": "2.00000000",
      "account": "normal",
      "time_in_force": "gtc"
    },
    "id": 1283293,
    "user": 1234,
    "market": "GT_USDT",
    "ctime": 1616397800,
    "ftime": 1616397801,
    "fired_order_id": 0,
    "status": "",
    "reason": ""
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	批量撤销请求接收并处理，是否成功根据订单列表来决定	[SpotPriceTriggeredOrder]

WARNING

该请求需要 API key 和 secret 认证

查询单个订单详情

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/price_orders/string'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /spot/price_orders/{order_id}

查询单个订单详情

参数

名称	位置	类型	必选	描述
order_id	URL	string	是	成功创建订单时返回的 ID

返回示例

200 返回

{
  "trigger": {
    "price": "100",
    "rule": ">=",
    "expiration": 3600
  },
  "put": {
    "type": "limit",
    "side": "buy",
    "price": "2.15",
    "amount": "2.00000000",
    "account": "normal",
    "time_in_force": "gtc"
  },
  "id": 1283293,
  "user": 1234,
  "market": "GT_USDT",
  "ctime": 1616397800,
  "ftime": 1616397801,
  "fired_order_id": 0,
  "status": "",
  "reason": ""
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	自动订单详情	SpotPriceTriggeredOrder

WARNING

该请求需要 API key 和 secret 认证

撤销单个自动订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/price_orders/string'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/spot/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /spot/price_orders/{order_id}

撤销单个自动订单

参数

名称	位置	类型	必选	描述
order_id	URL	string	是	成功创建订单时返回的 ID

返回示例

200 返回

{
  "trigger": {
    "price": "100",
    "rule": ">=",
    "expiration": 3600
  },
  "put": {
    "type": "limit",
    "side": "buy",
    "price": "2.15",
    "amount": "2.00000000",
    "account": "normal",
    "time_in_force": "gtc"
  },
  "id": 1283293,
  "user": 1234,
  "market": "GT_USDT",
  "ctime": 1616397800,
  "ftime": 1616397801,
  "fired_order_id": 0,
  "status": "",
  "reason": ""
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	自动订单详情	SpotPriceTriggeredOrder

WARNING

该请求需要 API key 和 secret 认证

Margin

杠杆借贷；杠杆交易直接使用现货交易 API

查询支持杠杆交易的所有交易对

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/currency_pairs'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/margin/currency_pairs \
  -H 'Accept: application/json'

GET /margin/currency_pairs

查询支持杠杆交易的所有交易对

返回示例

200 返回

[
  {
    "id": "ETH_USDT",
    "base": "ETH",
    "quote": "USDT",
    "leverage": 3,
    "min_base_amount": "0.01",
    "min_quote_amount": "100",
    "max_quote_amount": "1000000",
    "status": 1
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表成功查询	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» id	string	交易对
» base	string	交易货币
» quote	string	计价货币
» leverage	integer	杠杆交易倍数
» min_base_amount	string	交易货币最小借入借出数额, null 表示无限制
» min_quote_amount	string	计价货币最小借入借出数额, null 表示无限制
» max_quote_amount	string	单个用户允许借入的计价货币总额，交易货币最大借入数额根据市场价来计算, null 表示无限制
» status	integer(int32)	交易对状态 - 0: 禁用 - 1: 启用

该请求不需要认证

查询单个杠杆交易对

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/currency_pairs/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/margin/currency_pairs/BTC_USDT \
  -H 'Accept: application/json'

GET /margin/currency_pairs/{currency_pair}

查询单个杠杆交易对

参数

名称	位置	类型	必选	描述
currency_pair	URL	string	是	杠杆交易对

返回示例

200 返回

{
  "id": "ETH_USDT",
  "base": "ETH",
  "quote": "USDT",
  "leverage": 3,
  "min_base_amount": "0.01",
  "min_quote_amount": "100",
  "max_quote_amount": "1000000",
  "status": 1
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

名称	类型	描述
» id	string	交易对
» base	string	交易货币
» quote	string	计价货币
» leverage	integer	杠杆交易倍数
» min_base_amount	string	交易货币最小借入借出数额, null 表示无限制
» min_quote_amount	string	计价货币最小借入借出数额, null 表示无限制
» max_quote_amount	string	单个用户允许借入的计价货币总额，交易货币最大借入数额根据市场价来计算, null 表示无限制
» status	integer(int32)	交易对状态 - 0: 禁用 - 1: 启用

该请求不需要认证

借出市场的深度

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/funding_book'
query_param = 'currency=BTC'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/margin/funding_book?currency=BTC \
  -H 'Accept: application/json'

GET /margin/funding_book

借出市场的深度

参数

名称	位置	类型	必选	描述
currency	请求参数	string	是	指定币种名称查询

返回示例

200 返回

[
  {
    "rate": "0.002",
    "amount": "320.03",
    "days": 10
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	深度查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» rate	string	借贷利率
» amount	string	可借数量
» days	integer	理财期限

该请求不需要认证

杠杆账户列表

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/accounts'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/accounts

杠杆账户列表

参数

名称	位置	类型	必选	描述
currency_pair	请求参数	string	否	交易对

返回示例

200 返回

[
  {
    "currency_pair": "ETH_BTC",
    "locked": false,
    "risk": "1.1",
    "base": {
      "currency": "ETH",
      "available": "30.1",
      "locked": "0",
      "borrowed": "10.1",
      "interest": "0"
    },
    "quote": {
      "currency": "BTC",
      "available": "10",
      "locked": "0",
      "borrowed": "1.5",
      "interest": "0"
    }
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» None	object	某交易对的杠杆账户信息，base 对应交易货币的账户信息，quote 对应计价货币的账户信息
»» currency_pair	string	交易对
»» locked	boolean	账户是否被锁定
»» risk	string	杠杆账户当前风险率
»» base	object	货币账户信息
»»» currency	string	货币名称
»»» available	string	可用于杠杆交易的额度，available = 保证金 + borrowed
»»» locked	string	冻结资金，如已经放在杠杆市场里挂单交易的数额
»»» borrowed	string	借入资金
»»» interest	string	未还利息
»» quote	object	货币账户信息
»»» currency	string	货币名称
»»» available	string	可用于杠杆交易的额度，available = 保证金 + borrowed
»»» locked	string	冻结资金，如已经放在杠杆市场里挂单交易的数额
»»» borrowed	string	借入资金
»»» interest	string	未还利息

WARNING

该请求需要 API key 和 secret 认证

查询杠杆账户变动历史

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/account_book'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/account_book"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/account_book

查询杠杆账户变动历史

当前只提供转入转出到杠杆账户的变动历史，记录查询时间范围不允许超过 30 天

参数

名称	位置	类型	必选	描述
currency	请求参数	string	否	指定币种查询历史，如果指定 currency ，必须同时指定 currency_pair
currency_pair	请求参数	string	否	指定杠杆账户交易对，该字段与 currency 配合使用，如果不指定 currency，该字段忽略
from	请求参数	integer(int64)	否	查询记录的起始时间
to	请求参数	integer(int64)	否	查询记录的结束时间，不指定则默认为当前时间
page	请求参数	integer	否	列表页数
limit	请求参数	integer	否	列表返回的最大数量

返回示例

200 返回

[
  {
    "id": "123456",
    "time": "1547633726",
    "time_ms": 1547633726123,
    "currency": "BTC",
    "currency_pair": "BTC_USDT",
    "change": "1.03",
    "balance": "4.59316525194"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» id	string	账户变更记录 ID
» time	string	账户变更时间戳
» time_ms	integer(int64)	账户变更时间戳，毫秒单位
» currency	string	变更币种
» currency_pair	string	账户交易对
» change	string	变更金额，正数表示转入，负数表示转出
» balance	string	变更后账户余额

WARNING

该请求需要 API key 和 secret 认证

理财账户列表

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/funding_accounts'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/funding_accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/funding_accounts

理财账户列表

参数

名称	位置	类型	必选	描述
currency	请求参数	string	否	指定币种名称查询

返回示例

200 返回

[
  {
    "currency": "BTC",
    "available": "1.238",
    "locked": "0",
    "lent": "3.32",
    "total_lent": "3.32"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» currency	string	账户货币名称
» available	string	理财账户可以用于借出的资金，与现货账户里对应币种的 available 保持一致
» locked	string	冻结资金数额，如正在借出的资金
» lent	string	已借出但仍未归还的资金数额
» total_lent	string	用于借出的资金总额, total_lent = lent + locked

WARNING

该请求需要 API key 和 secret 认证

借入或借出

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/loans'
query_param = ''
body='{"side":"borrow","currency":"BTC","rate":"0.002","amount":"1.5","days":10,"auto_renew":true,"currency_pair":"ETH_BTC","fee_rate":"0.18","orig_id":"123424","text":"t-abc"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/margin/loans"
query_param=""
body_param='{"side":"borrow","currency":"BTC","rate":"0.002","amount":"1.5","days":10,"auto_renew":true,"currency_pair":"ETH_BTC","fee_rate":"0.18","orig_id":"123424","text":"t-abc"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /margin/loans

借入或借出

请求体示例

{
  "side": "borrow",
  "currency": "BTC",
  "rate": "0.002",
  "amount": "1.5",
  "days": 10,
  "auto_renew": true,
  "currency_pair": "ETH_BTC",
  "fee_rate": "0.18",
  "orig_id": "123424",
  "text": "t-abc"
}

参数

名称	位置	类型	必选	描述
body	body	Loan	是
» side	body	string	是	lend - 借出，borrow - 借入
» currency	body	string	是	贷款币种
» rate	body	string	否	贷款利率，当前支持 0.0002 - 0.002 这个范围的利率。
» amount	body	string	是	贷款额度
» days	body	integer	否	贷款天数，目前只支持设置为 10
» auto_renew	body	boolean	否	贷款到期之后自动续借
» currency_pair	body	string	否	贷款借入的交易对，借入时该字段为必选
» fee_rate	body	string	否	该贷款的手续费率
» orig_id	body	string	否	续借贷款的原始贷款 ID，如果不是续借贷款，该字段同 id
» text	body	string	否	用户自定义 ID

详细描述

» rate: 贷款利率，当前支持 0.0002 - 0.002 这个范围的利率。

借出时可不设置该字段，由系统根据该币种最近的市场利率来设置。

枚举值列表

参数	值
» side	lend
» side	borrow

返回示例

201 返回

{
  "id": "123435",
  "create_time": "1548000000",
  "expire_time": "1548100000",
  "side": "borrow",
  "status": "loaned",
  "currency": "BTC",
  "rate": "0.002",
  "amount": "1.5",
  "days": 10,
  "auto_renew": true,
  "currency_pair": "ETH_BTC",
  "left": "0",
  "repaid": "0",
  "paid_interest": "0",
  "unpaid_interest": "0",
  "fee_rate": "0.18",
  "orig_id": "123424",
  "text": "t-abc"
}

返回

状态码	含义	描述	格式
201	Created (opens new window)	成功挂出借款或者成功借入	Loan

WARNING

该请求需要 API key 和 secret 认证

查询借贷订单列表

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/loans'
query_param = 'status=open&side=lend'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/loans"
query_param="status=open&side=lend"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/loans

查询借贷订单列表

参数

名称	位置	类型	必选	描述
status	请求参数	string	是	借贷订单状态
side	请求参数	string	是	借入或借出
currency	请求参数	string	否	指定币种名称查询
currency_pair	请求参数	string	否	交易对
sort_by	请求参数	string	否	指定排序的字段名，当前支持 create_time 或 rate ，默认是 create_time
reverse_sort	请求参数	boolean	否	是否倒序排列，默认为 true ，即按倒序排列
page	请求参数	integer	否	列表页数
limit	请求参数	integer	否	列表返回的最大数量

枚举值列表

参数	值
status	open
status	loaned
status	finished
status	auto_repaid
side	lend
side	borrow
sort_by	create_time
sort_by	rate

返回示例

200 返回

[
  {
    "id": "123435",
    "create_time": "1548000000",
    "expire_time": "1548100000",
    "side": "borrow",
    "status": "loaned",
    "currency": "BTC",
    "rate": "0.002",
    "amount": "1.5",
    "days": 10,
    "auto_renew": true,
    "currency_pair": "ETH_BTC",
    "left": "0",
    "repaid": "0",
    "paid_interest": "0",
    "unpaid_interest": "0",
    "fee_rate": "0.18",
    "orig_id": "123424",
    "text": "t-abc"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Loan]

WARNING

该请求需要 API key 和 secret 认证

合并多个借贷订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/merged_loans'
query_param = 'currency=BTC&ids=123,234,345'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/margin/merged_loans"
query_param="currency=BTC&ids=123,234,345"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /margin/merged_loans

合并多个借贷订单

参数

名称	位置	类型	必选	描述
currency	请求参数	string	是	指定币种名称查询
ids	请求参数	string	是	用 "," 分隔的多个借贷订单 ID，上限 20 个

返回示例

201 返回

{
  "id": "123435",
  "create_time": "1548000000",
  "expire_time": "1548100000",
  "side": "borrow",
  "status": "loaned",
  "currency": "BTC",
  "rate": "0.002",
  "amount": "1.5",
  "days": 10,
  "auto_renew": true,
  "currency_pair": "ETH_BTC",
  "left": "0",
  "repaid": "0",
  "paid_interest": "0",
  "unpaid_interest": "0",
  "fee_rate": "0.18",
  "orig_id": "123424",
  "text": "t-abc"
}

返回

状态码	含义	描述	格式
201	Created (opens new window)	订单合并成功	Loan

WARNING

该请求需要 API key 和 secret 认证

查询借贷订单详情

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/loans/12345'
query_param = 'side=lend'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/loans/12345"
query_param="side=lend"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/loans/{loan_id}

查询借贷订单详情

参数

名称	位置	类型	必选	描述
side	请求参数	string	是	借入或借出
loan_id	URL	string	是	创建借贷订单时返回的 ID

枚举值列表

参数	值
side	lend
side	borrow

返回示例

200 返回

{
  "id": "123435",
  "create_time": "1548000000",
  "expire_time": "1548100000",
  "side": "borrow",
  "status": "loaned",
  "currency": "BTC",
  "rate": "0.002",
  "amount": "1.5",
  "days": 10,
  "auto_renew": true,
  "currency_pair": "ETH_BTC",
  "left": "0",
  "repaid": "0",
  "paid_interest": "0",
  "unpaid_interest": "0",
  "fee_rate": "0.18",
  "orig_id": "123424",
  "text": "t-abc"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	订单查询成功	Loan

WARNING

该请求需要 API key 和 secret 认证

修改借贷订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/loans/12345'
query_param = ''
body='{"currency":"BTC","side":"borrow","currency_pair":"BTC_USDT","auto_renew":false}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PATCH', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="PATCH"
url="/margin/loans/12345"
query_param=""
body_param='{"currency":"BTC","side":"borrow","currency_pair":"BTC_USDT","auto_renew":false}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

PATCH /margin/loans/{loan_id}

修改借贷订单

目前仅支持修改 auto_renew 字段，即订单是否自动续借

请求体示例

{
  "currency": "BTC",
  "side": "borrow",
  "currency_pair": "BTC_USDT",
  "auto_renew": false
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» currency	body	string	是	贷款币种
» side	body	string	是	借出或借入，lend - 借出, borrow - 借入，借出记录(LoanRecord)只支持 lend
» auto_renew	body	boolean	是	自动续借
» currency_pair	body	string	否	交易对，side 为借入时必选
» loan_id	body	string	否	借贷订单 ID，修改借出记录(LoanRecord)时该字段必选
loan_id	URL	string	是	创建借贷订单时返回的 ID

枚举值列表

参数	值
» side	lend
» side	borrow

返回示例

200 返回

{
  "id": "123435",
  "create_time": "1548000000",
  "expire_time": "1548100000",
  "side": "borrow",
  "status": "loaned",
  "currency": "BTC",
  "rate": "0.002",
  "amount": "1.5",
  "days": 10,
  "auto_renew": true,
  "currency_pair": "ETH_BTC",
  "left": "0",
  "repaid": "0",
  "paid_interest": "0",
  "unpaid_interest": "0",
  "fee_rate": "0.18",
  "orig_id": "123424",
  "text": "t-abc"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	修改成功	Loan

WARNING

该请求需要 API key 和 secret 认证

撤销借出贷款订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/loans/12345'
query_param = 'currency=BTC'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/margin/loans/12345"
query_param="currency=BTC"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /margin/loans/{loan_id}

撤销借出贷款订单

贷款订单撤销只适用于借出

参数

名称	位置	类型	必选	描述
currency	请求参数	string	是	指定币种名称查询
loan_id	URL	string	是	创建借贷订单时返回的 ID

返回示例

200 返回

{
  "id": "123435",
  "create_time": "1548000000",
  "expire_time": "1548100000",
  "side": "borrow",
  "status": "loaned",
  "currency": "BTC",
  "rate": "0.002",
  "amount": "1.5",
  "days": 10,
  "auto_renew": true,
  "currency_pair": "ETH_BTC",
  "left": "0",
  "repaid": "0",
  "paid_interest": "0",
  "unpaid_interest": "0",
  "fee_rate": "0.18",
  "orig_id": "123424",
  "text": "t-abc"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	订单撤销成功	Loan

WARNING

该请求需要 API key 和 secret 认证

归还借贷

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/loans/12345/repayment'
query_param = ''
body='{"currency_pair":"ETH_BTC","currency":"ETH","mode":"partial","amount":"100"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/margin/loans/12345/repayment"
query_param=""
body_param='{"currency_pair":"ETH_BTC","currency":"ETH","mode":"partial","amount":"100"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /margin/loans/{loan_id}/repayment

归还借贷

请求体示例

{
  "currency_pair": "ETH_BTC",
  "currency": "ETH",
  "mode": "partial",
  "amount": "100"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» currency_pair	body	string	是	交易对
» currency	body	string	是	贷款币种
» mode	body	string	是	还款模式, all - 全部归还, partial - 部分归还
» amount	body	string	否	归还数额，mode 指定 partial 时必选
loan_id	URL	string	是	创建借贷订单时返回的 ID

枚举值列表

参数	值
» mode	all
» mode	partial

返回示例

200 返回

{
  "id": "123435",
  "create_time": "1548000000",
  "expire_time": "1548100000",
  "side": "borrow",
  "status": "loaned",
  "currency": "BTC",
  "rate": "0.002",
  "amount": "1.5",
  "days": 10,
  "auto_renew": true,
  "currency_pair": "ETH_BTC",
  "left": "0",
  "repaid": "0",
  "paid_interest": "0",
  "unpaid_interest": "0",
  "fee_rate": "0.18",
  "orig_id": "123424",
  "text": "t-abc"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	还款成功	Loan

WARNING

该请求需要 API key 和 secret 认证

查询借贷归还记录

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/loans/12345/repayment'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/loans/12345/repayment"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/loans/{loan_id}/repayment

查询借贷归还记录

参数

名称	位置	类型	必选	描述
loan_id	URL	string	是	创建借贷订单时返回的 ID

返回示例

200 返回

[
  {
    "id": "12342323",
    "create_time": "1578000000",
    "principal": "100",
    "interest": "2"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» id	string	还款记录 ID
» create_time	string	还款时间
» principal	string	归还本金
» interest	string	归还利息

WARNING

该请求需要 API key 和 secret 认证

查看某个借贷订单的借出记录

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/loan_records'
query_param = 'loan_id=12345'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/loan_records"
query_param="loan_id=12345"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/loan_records

查看某个借贷订单的借出记录

参数

名称	位置	类型	必选	描述
loan_id	请求参数	string	是	借贷订单 ID
status	请求参数	string	否	借出记录状态
page	请求参数	integer	否	列表页数
limit	请求参数	integer	否	列表返回的最大数量

枚举值列表

参数	值
status	loaned
status	finished

返回示例

200 返回

[
  {
    "id": "122342323",
    "loan_id": "12840282",
    "create_time": "1548000000",
    "expire_time": "1548100000",
    "status": "loaned",
    "borrow_user_id": "******12",
    "currency": "BTC",
    "rate": "0.002",
    "amount": "1.5",
    "days": 10,
    "auto_renew": false,
    "repaid": "0",
    "paid_interest": "0",
    "unpaid_interest": "0"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[LoanRecord]

WARNING

该请求需要 API key 和 secret 认证

查看单个借出记录

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/loan_records/12345'
query_param = 'loan_id=12345'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/loan_records/12345"
query_param="loan_id=12345"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/loan_records/{loan_record_id}

查看单个借出记录

参数

名称	位置	类型	必选	描述
loan_id	请求参数	string	是	借贷订单 ID
loan_record_id	URL	string	是	借出记录 ID

返回示例

200 返回

{
  "id": "122342323",
  "loan_id": "12840282",
  "create_time": "1548000000",
  "expire_time": "1548100000",
  "status": "loaned",
  "borrow_user_id": "******12",
  "currency": "BTC",
  "rate": "0.002",
  "amount": "1.5",
  "days": 10,
  "auto_renew": false,
  "repaid": "0",
  "paid_interest": "0",
  "unpaid_interest": "0"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	详情查询成功	LoanRecord

WARNING

该请求需要 API key 和 secret 认证

修改单个借出记录

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/loan_records/12345'
query_param = ''
body='{"currency":"BTC","side":"borrow","currency_pair":"BTC_USDT","auto_renew":false}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PATCH', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="PATCH"
url="/margin/loan_records/12345"
query_param=""
body_param='{"currency":"BTC","side":"borrow","currency_pair":"BTC_USDT","auto_renew":false}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

PATCH /margin/loan_records/{loan_record_id}

修改单个借出记录

当前只支持对 auto_renew 的修改，即调整该借出记录是否自动续借

请求体示例

{
  "currency": "BTC",
  "side": "borrow",
  "currency_pair": "BTC_USDT",
  "auto_renew": false
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» currency	body	string	是	贷款币种
» side	body	string	是	借出或借入，lend - 借出, borrow - 借入，借出记录(LoanRecord)只支持 lend
» auto_renew	body	boolean	是	自动续借
» currency_pair	body	string	否	交易对，side 为借入时必选
» loan_id	body	string	否	借贷订单 ID，修改借出记录(LoanRecord)时该字段必选
loan_record_id	URL	string	是	借出记录 ID

枚举值列表

参数	值
» side	lend
» side	borrow

返回示例

200 返回

{
  "id": "122342323",
  "loan_id": "12840282",
  "create_time": "1548000000",
  "expire_time": "1548100000",
  "status": "loaned",
  "borrow_user_id": "******12",
  "currency": "BTC",
  "rate": "0.002",
  "amount": "1.5",
  "days": 10,
  "auto_renew": false,
  "repaid": "0",
  "paid_interest": "0",
  "unpaid_interest": "0"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	记录修改成功	LoanRecord

WARNING

该请求需要 API key 和 secret 认证

修改用户自动还款设置

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/auto_repay'
query_param = 'status=on'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/margin/auto_repay"
query_param="status=on"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /margin/auto_repay

修改用户自动还款设置

参数

名称	位置	类型	必选	描述
status	请求参数	string	是	是否开启自动还款，on - 开启, off - 关闭

返回示例

200 返回

{
  "status": "on"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	用户当前自动还款设置	Inline

返回格式

状态码 200

AutoRepaySetting

名称	类型	描述
» status	string	自动还款状态, on - 开启，off - 关闭

枚举值列表

属性	值
status	on
status	off

WARNING

该请求需要 API key 和 secret 认证

查询用户自动还款设置

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/auto_repay'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/auto_repay"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/auto_repay

查询用户自动还款设置

返回示例

200 返回

{
  "status": "on"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	用户当前自动还款设置	Inline

返回格式

状态码 200

AutoRepaySetting

名称	类型	描述
» status	string	自动还款状态, on - 开启，off - 关闭

枚举值列表

属性	值
status	on
status	off

WARNING

该请求需要 API key 和 secret 认证

逐仓杠杆允许的最大转出

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/transferable'
query_param = 'currency=BTC'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/transferable"
query_param="currency=BTC"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/transferable

逐仓杠杆允许的最大转出

参数

名称	位置	类型	必选	描述
currency	请求参数	string	是	指定币种名称查询
currency_pair	请求参数	string	否	交易对

返回示例

200 返回

{
  "currency": "ETH",
  "currency_pair": "ETH_USDT",
  "amount": "10000"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

MarginTransferable

名称	类型	描述
» currency	string	币种信息
» currency_pair	string	交易对
» amount	string	最大可转出的额度

WARNING

该请求需要 API key 和 secret 认证

逐仓杠杆用户最多可借入

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/borrowable'
query_param = 'currency=BTC'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/borrowable"
query_param="currency=BTC"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/borrowable

逐仓杠杆用户最多可借入

参数

名称	位置	类型	必选	描述
currency	请求参数	string	是	指定币种名称查询
currency_pair	请求参数	string	否	交易对

返回示例

200 返回

{
  "currency": "ETH",
  "currency_pair": "ETH_USDT",
  "amount": "10000"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

MarginBorrowable

名称	类型	描述
» currency	string	币种信息
» currency_pair	string	交易对
» amount	string	最多可借入的额度

WARNING

该请求需要 API key 和 secret 认证

全仓杠杆支持的币种列表

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/cross/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/margin/cross/currencies \
  -H 'Accept: application/json'

GET /margin/cross/currencies

全仓杠杆支持的币种列表

返回示例

200 返回

[
  {
    "name": "BTC",
    "rate": "0.0002",
    "prec": "0.000001",
    "discount": "1",
    "min_borrow_amount": "0.01",
    "user_max_borrow_amount": "1000000",
    "total_max_borrow_amount": "10000000",
    "price": "63015.5214",
    "status": 1
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» name	string	币种名称
» rate	string	借贷利率
» prec	string	币种精度
» discount	string	币种价值折扣，计算账户总资产时使用的折扣系数
» min_borrow_amount	string	该币种最小的借入数量，单位是币
» user_max_borrow_amount	string	用户最大允许的借入数额，单位是 USDT
» total_max_borrow_amount	string	该币种允许借入的最大数额，单位是 USDT
» price	string	该币种兑换 USDT 的价格
» status	integer	币种状态 - 0 : 禁用 - 1 : 启用

该请求不需要认证

查询单个全仓杠杆支持的币种

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/cross/currencies/BTC'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/margin/cross/currencies/BTC \
  -H 'Accept: application/json'

GET /margin/cross/currencies/{currency}

查询单个全仓杠杆支持的币种

参数

名称	位置	类型	必选	描述
currency	URL	string	是	币种名称

返回示例

200 返回

{
  "name": "BTC",
  "rate": "0.0002",
  "prec": "0.000001",
  "discount": "1",
  "min_borrow_amount": "0.01",
  "user_max_borrow_amount": "1000000",
  "total_max_borrow_amount": "10000000",
  "price": "63015.5214",
  "status": 1
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

名称	类型	描述
» name	string	币种名称
» rate	string	借贷利率
» prec	string	币种精度
» discount	string	币种价值折扣，计算账户总资产时使用的折扣系数
» min_borrow_amount	string	该币种最小的借入数量，单位是币
» user_max_borrow_amount	string	用户最大允许的借入数额，单位是 USDT
» total_max_borrow_amount	string	该币种允许借入的最大数额，单位是 USDT
» price	string	该币种兑换 USDT 的价格
» status	integer	币种状态 - 0 : 禁用 - 1 : 启用

该请求不需要认证

查询全仓杠杆账户

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/cross/accounts'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/cross/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/cross/accounts

查询全仓杠杆账户

返回示例

200 返回

{
  "user_id": 10001,
  "locked": false,
  "balances": {
    "ETH": {
      "available": "0",
      "freeze": "0",
      "borrowed": "0.075393666654",
      "interest": "0.0000106807603333"
    },
    "POINT": {
      "available": "9999999999.017023138734",
      "freeze": "0",
      "borrowed": "0",
      "interest": "0"
    },
    "USDT": {
      "available": "0.00000062023",
      "freeze": "0",
      "borrowed": "0",
      "interest": "0"
    }
  },
  "total": "230.94621713",
  "borrowed": "161.66395521",
  "interest": "0.02290237",
  "risk": "1.4284",
  "total_initial_margin": "1025.0524665088",
  "total_margin_balance": "3382495.944473949183",
  "total_maintenance_margin": "205.01049330176",
  "total_initial_margin_rate": "3299.827135672679",
  "total_maintenance_margin_rate": "16499.135678363399",
  "total_available_margin": "3381470.892007440383"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

名称	类型	描述
» user_id	integer(int64)	用户 ID
» locked	boolean	账户是否被锁定
» balances	object
»» CrossMarginBalance	object
»»» available	string	可用额度
»»» freeze	string	被锁定的额度
»»» borrowed	string	借入额度
»»» interest	string	未还利息
»» total	string	折算成 USDT 的账户总资产，即所有币种(不包括点卡)的 (available+freeze)*price*discount 之和
»» borrowed	string	折算成 USDT 的账户总借入数量，即所有币种(不包括点卡)的 borrowed*price*discount 之和
»» interest	string	折算成 USDT 的账户未接利息的总和，即所有币种(不包括点卡)的 interest*price*discount 之和
»» risk	string	风险率，风险率小于 110% 会被爆仓，计算方式 total / (borrowed+interest)
»» total_initial_margin	string	总初始保证金
»» total_margin_balance	string	总保证金余额
»» total_maintenance_margin	string	总维持保证金
»» total_initial_margin_rate	string	总初始保证金率
»» total_maintenance_margin_rate	string	总维持保证金率
»» total_available_margin	string	可用的保证金额度

WARNING

该请求需要 API key 和 secret 认证

查询全仓杠杆账户变动历史

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/cross/account_book'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/cross/account_book"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/cross/account_book

查询全仓杠杆账户变动历史

记录查询时间范围不允许超过 30 天

参数

名称	位置	类型	必选	描述
currency	请求参数	string	否	指定币种查询历史
from	请求参数	integer(int64)	否	查询记录的起始时间
to	请求参数	integer(int64)	否	查询记录的结束时间，不指定则默认为当前时间
page	请求参数	integer	否	列表页数
limit	请求参数	integer	否	列表返回的最大数量
type	请求参数	string	否	指定账户变动类型查询，不指定则包含全部变动类型

返回示例

200 返回

[
  {
    "id": "123456",
    "time": 1547633726123,
    "currency": "BTC",
    "change": "1.03",
    "balance": "4.59316525194",
    "type": "in"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» id	string	账户变更记录 ID
» time	integer(int64)	账户变更时间戳，毫秒单位
» currency	string	变更币种
» change	string	变更金额，正数表示转入，负数表示转出
» balance	string	变更后账户余额
» type	string	账户变更类型，包括： - in: 转入 - out: 转出 - repay: 还款 - borrow: 借入 - new_order: 下单 - order_fill: 委托成交 - referral_fee: 推荐人手续费 - order_fee: 委托成交手续费 - unknown: 未知类型

枚举值列表

属性	值
type	in
type	out
type	repay
type	borrow
type	new_order
type	order_fill
type	referral_fee
type	order_fee
type	unknown

WARNING

该请求需要 API key 和 secret 认证

全仓杠杆借入

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/cross/loans'
query_param = ''
body='{"currency":"EOS","amount":"110.553635","text":"web"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/margin/cross/loans"
query_param=""
body_param='{"currency":"EOS","amount":"110.553635","text":"web"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /margin/cross/loans

全仓杠杆借入

借入时必须保证不能少于币种最小借入量

请求体示例

{
  "currency": "EOS",
  "amount": "110.553635",
  "text": "web"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» currency	body	string	是	币种名称
» amount	body	string	是	借入数量
» text	body	string	否	用户自定义 ID

返回示例

200 返回

{
  "id": "17",
  "create_time": 1620381696159,
  "update_time": 1620381696159,
  "currency": "EOS",
  "amount": "110.553635",
  "text": "web",
  "status": 2,
  "repaid": "110.506649705159",
  "repaid_interest": "0.046985294841",
  "unpaid_interest": "0.0000074393366667"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	成功借入	Inline

返回格式

状态码 200

名称	类型	描述
» id	string	借入订单 ID
» create_time	integer(int64)	创建时间，单位 ms
» update_time	integer(int64)	更新时间，单位 ms
» currency	string	币种名称
» amount	string	借入数量
» text	string	用户自定义 ID
» status	integer(int32)	借入单状态，可选值包括： - 1: 未借入成功 - 2: 已借入，未归还 - 3: 归还完成
» repaid	string	已归还数额
» repaid_interest	string	已归还的利息
» unpaid_interest	string	未归还的利息

枚举值列表

属性	值
status	1
status	2
status	3

WARNING

该请求需要 API key 和 secret 认证

查询全仓杠杆借入历史

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/cross/loans'
query_param = 'status=0'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/cross/loans"
query_param="status=0"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/cross/loans

查询全仓杠杆借入历史

默认按创建时间逆序排列，可以设置 reverse=false 正序排列

参数

名称	位置	类型	必选	描述
status	请求参数	integer	是	指定状态查询，支持的状态包括 2 和 3
currency	请求参数	string	否	指定币种查询，不指定则包含全部币种
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
reverse	请求参数	boolean	否	是否逆序查询。默认开启逆序，可以设置 reverse=false 正序排列

返回示例

200 返回

[
  {
    "id": "17",
    "create_time": 1620381696159,
    "update_time": 1620381696159,
    "currency": "EOS",
    "amount": "110.553635",
    "text": "web",
    "status": 2,
    "repaid": "110.506649705159",
    "repaid_interest": "0.046985294841",
    "unpaid_interest": "0.0000074393366667"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» id	string	借入订单 ID
» create_time	integer(int64)	创建时间，单位 ms
» update_time	integer(int64)	更新时间，单位 ms
» currency	string	币种名称
» amount	string	借入数量
» text	string	用户自定义 ID
» status	integer(int32)	借入单状态，可选值包括： - 1: 未借入成功 - 2: 已借入，未归还 - 3: 归还完成
» repaid	string	已归还数额
» repaid_interest	string	已归还的利息
» unpaid_interest	string	未归还的利息

枚举值列表

属性	值
status	1
status	2
status	3

WARNING

该请求需要 API key 和 secret 认证

查询单个借入单详情

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/cross/loans/12345'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/cross/loans/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/cross/loans/{loan_id}

查询单个借入单详情

参数

名称	位置	类型	必选	描述
loan_id	URL	string	是	借入单 ID

返回示例

200 返回

{
  "id": "17",
  "create_time": 1620381696159,
  "update_time": 1620381696159,
  "currency": "EOS",
  "amount": "110.553635",
  "text": "web",
  "status": 2,
  "repaid": "110.506649705159",
  "repaid_interest": "0.046985294841",
  "unpaid_interest": "0.0000074393366667"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

名称	类型	描述
» id	string	借入订单 ID
» create_time	integer(int64)	创建时间，单位 ms
» update_time	integer(int64)	更新时间，单位 ms
» currency	string	币种名称
» amount	string	借入数量
» text	string	用户自定义 ID
» status	integer(int32)	借入单状态，可选值包括： - 1: 未借入成功 - 2: 已借入，未归还 - 3: 归还完成
» repaid	string	已归还数额
» repaid_interest	string	已归还的利息
» unpaid_interest	string	未归还的利息

枚举值列表

属性	值
status	1
status	2
status	3

WARNING

该请求需要 API key 和 secret 认证

全仓杠杆还款

币种流动性不足，交易风险高时，币种会被禁用，无法转入资金，全仓还款可用余额不足时，可使用现货账户余额一同还款，请确保现货账户余额充足，优先使用全仓杠杆账户可用余额还款

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/cross/repayments'
query_param = ''
body='{"currency":"EOS","amount":"110.553635"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/margin/cross/repayments"
query_param=""
body_param='{"currency":"EOS","amount":"110.553635"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /margin/cross/repayments

*全仓杠杆还款 币种流动性不足，交易风险高时，币种会被禁用，无法转入资金，全仓还款可用余额不足时，可使用现货账户余额一同还款，请确保现货账户余额充足，优先使用全仓杠杆账户可用余额还款 *

请求体示例

{
  "currency": "EOS",
  "amount": "110.553635"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» currency	body	string	是	还款币种
» amount	body	string	是	还款数量

返回示例

200 返回

[
  {
    "id": "17",
    "create_time": 1620381696159,
    "update_time": 1620381696159,
    "currency": "EOS",
    "amount": "110.553635",
    "text": "web",
    "status": 2,
    "repaid": "110.506649705159",
    "repaid_interest": "0.046985294841",
    "unpaid_interest": "0.0000074393366667"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	还款成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» id	string	借入订单 ID
» create_time	integer(int64)	创建时间，单位 ms
» update_time	integer(int64)	更新时间，单位 ms
» currency	string	币种名称
» amount	string	借入数量
» text	string	用户自定义 ID
» status	integer(int32)	借入单状态，可选值包括： - 1: 未借入成功 - 2: 已借入，未归还 - 3: 归还完成
» repaid	string	已归还数额
» repaid_interest	string	已归还的利息
» unpaid_interest	string	未归还的利息

枚举值列表

属性	值
status	1
status	2
status	3

WARNING

该请求需要 API key 和 secret 认证

全仓杠杆还款查询

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/cross/repayments'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/cross/repayments"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/cross/repayments

全仓杠杆还款查询

默认按创建时间逆序排列，可以设置 reverse=false 正序排列

参数

名称	位置	类型	必选	描述
currency	请求参数	string	否
loan_id	请求参数	string	否
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
reverse	请求参数	boolean	否	是否逆序查询。默认开启逆序，可以设置 reverse=false 正序排列

返回示例

200 返回

[
  {
    "id": "51",
    "create_time": 1620696347990,
    "loan_id": "30",
    "currency": "BTC",
    "principal": "5.385542",
    "interest": "0.000044879516"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» id	string	还款记录 ID
» create_time	integer(int64)	还款时间
» loan_id	string	借入单 ID
» currency	string	币种名称
» principal	string	归还本金
» interest	string	归还利息

WARNING

该请求需要 API key 和 secret 认证

全仓杠杆允许的最大转出

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/cross/transferable'
query_param = 'currency=BTC'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/cross/transferable"
query_param="currency=BTC"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/cross/transferable

全仓杠杆允许的最大转出

参数

名称	位置	类型	必选	描述
currency	请求参数	string	是	指定币种名称查询

返回示例

200 返回

{
  "currency": "ETH",
  "amount": "10000"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

CrossMarginTransferable

名称	类型	描述
» currency	string	币种信息
» amount	string	最大可转出的额度

WARNING

该请求需要 API key 和 secret 认证

全仓杠杆用户最多可借入

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/margin/cross/borrowable'
query_param = 'currency=BTC'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/cross/borrowable"
query_param="currency=BTC"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /margin/cross/borrowable

全仓杠杆用户最多可借入

参数

名称	位置	类型	必选	描述
currency	请求参数	string	是	指定币种名称查询

返回示例

200 返回

{
  "currency": "ETH",
  "amount": "10000"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

CrossMarginBorrowable

名称	类型	描述
» currency	string	币种信息
» amount	string	最多可借入的额度

WARNING

该请求需要 API key 和 secret 认证

Flash_swap

闪兑

查询支持闪兑的所有货币列表

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/flash_swap/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/flash_swap/currencies \
  -H 'Accept: application/json'

GET /flash_swap/currencies

查询支持闪兑的所有货币列表

返回示例

200 返回

[
  {
    "currency": "BTC",
    "min_amount": "0.000001",
    "max_amount": "1.000000",
    "swappable": [
      "USDT",
      "GT",
      "ETH"
    ]
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» None	object	闪兑的币种列表
»» currency	string	币种名称
»» min_amount	string	闪兑的最小数量
»» max_amount	string	闪兑的最大数量
»» swappable	array	该币种支持兑换的币种列表

该请求不需要认证

创建闪兑订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/flash_swap/orders'
query_param = ''
body='{"preview_id":"4564564","sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT","buy_amount":"10"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/flash_swap/orders"
query_param=""
body_param='{"preview_id":"4564564","sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT","buy_amount":"10"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /flash_swap/orders

创建闪兑订单

需要先进行闪兑预览，创建闪兑订单时需要传入预览结果

请求体示例

{
  "preview_id": "4564564",
  "sell_currency": "BTC",
  "sell_amount": "0.1",
  "buy_currency": "USDT",
  "buy_amount": "10"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» preview_id	body	string	否	预览结果id
» sell_currency	body	string	是	卖出的资产名称，
» sell_amount	body	string	否	卖出的资产数量，
» buy_currency	body	string	是	买入的资产名称，
» buy_amount	body	string	否	买入的资产数量，

详细描述

» sell_currency: 卖出的资产名称， 根据接口查询支持闪兑的货币列表 GET /flash_swap/currencies获取

» sell_amount: 卖出的资产数量， sell_amount和buy_amount二选一必填

» buy_currency: 买入的资产名称， 根据接口查询支持闪兑的货币列表 GET /flash_swap/currencies获取

» buy_amount: 买入的资产数量， sell_amount和buy_amount二选一必填

返回示例

201 返回

{
  "id": 54646,
  "create_time": 1651116876378,
  "update_time": 1651116876378,
  "user_id": 11135567,
  "sell_currency": "BTC",
  "sell_amount": "0.01",
  "buy_currency": "USDT",
  "buy_amount": "10",
  "price": "100",
  "status": 1
}

返回

状态码	含义	描述	格式
201	Created (opens new window)	创建闪兑订单成功	Inline

返回格式

状态码 201

闪兑订单

名称	类型	描述
» id	integer(int64)	闪兑订单id
» create_time	integer(int64)	订单创建时间，毫秒精度
» user_id	integer(int64)	用户id
» sell_currency	string	卖出的资产名称
» sell_amount	string	卖出的资产数量
» buy_currency	string	买入的资产名称
» buy_amount	string	买入的资产数量
» price	string	价格
» status	integer	闪兑订单状态 - 1: 成功 - 2: 失败

WARNING

该请求需要 API key 和 secret 认证

闪兑订单列表查询

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/flash_swap/orders'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/flash_swap/orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /flash_swap/orders

闪兑订单列表查询

参数

名称	位置	类型	必选	描述
status	请求参数	integer	否	闪兑订单状态
sell_currency	请求参数	string	否	卖出的资产名称，
buy_currency	请求参数	string	否	买入的资产名称，
reverse	请求参数	boolean	否	根据id正序或反向排列，默认true
limit	请求参数	integer	否	列表返回的最大数量
page	请求参数	integer	否	列表页数

详细描述

status: 闪兑订单状态

• 1: 成功
• 2: 失败

sell_currency: 卖出的资产名称， 根据接口查询支持闪兑的货币列表 GET /flash_swap/currencies获取

buy_currency: 买入的资产名称， 根据接口查询支持闪兑的货币列表 GET /flash_swap/currencies获取

reverse: 根据id正序或反向排列，默认true

• true ： id反序（最近时间的数据）
• false ： id正序（最远时间的数据）

返回示例

200 返回

[
  {
    "id": 54646,
    "create_time": 1651116876378,
    "update_time": 1651116876378,
    "user_id": 11135567,
    "sell_currency": "BTC",
    "sell_amount": "0.01",
    "buy_currency": "USDT",
    "buy_amount": "10",
    "price": "100",
    "status": 1
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array	[闪兑订单]
» None	object	闪兑订单
»» id	integer(int64)	闪兑订单id
»» create_time	integer(int64)	订单创建时间，毫秒精度
»» user_id	integer(int64)	用户id
»» sell_currency	string	卖出的资产名称
»» sell_amount	string	卖出的资产数量
»» buy_currency	string	买入的资产名称
»» buy_amount	string	买入的资产数量
»» price	string	价格
»» status	integer	闪兑订单状态 - 1: 成功 - 2: 失败

WARNING

该请求需要 API key 和 secret 认证

查询单张闪兑订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/flash_swap/orders/1'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/flash_swap/orders/1"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /flash_swap/orders/{order_id}

查询单张闪兑订单

参数

名称	位置	类型	必选	描述
order_id	URL	integer	是	闪兑订单id

返回示例

200 返回

{
  "id": 54646,
  "create_time": 1651116876378,
  "update_time": 1651116876378,
  "user_id": 11135567,
  "sell_currency": "BTC",
  "sell_amount": "0.01",
  "buy_currency": "USDT",
  "buy_amount": "10",
  "price": "100",
  "status": 1
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

闪兑订单

名称	类型	描述
» id	integer(int64)	闪兑订单id
» create_time	integer(int64)	订单创建时间，毫秒精度
» user_id	integer(int64)	用户id
» sell_currency	string	卖出的资产名称
» sell_amount	string	卖出的资产数量
» buy_currency	string	买入的资产名称
» buy_amount	string	买入的资产数量
» price	string	价格
» status	integer	闪兑订单状态 - 1: 成功 - 2: 失败

WARNING

该请求需要 API key 和 secret 认证

闪兑订单预览

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/flash_swap/orders/preview'
query_param = ''
body='{"preview_id":"4564564","sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT","buy_amount":"10"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/flash_swap/orders/preview"
query_param=""
body_param='{"preview_id":"4564564","sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT","buy_amount":"10"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /flash_swap/orders/preview

闪兑订单预览

请求体示例

{
  "preview_id": "4564564",
  "sell_currency": "BTC",
  "sell_amount": "0.1",
  "buy_currency": "USDT",
  "buy_amount": "10"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» preview_id	body	string	否	预览结果id
» sell_currency	body	string	是	卖出的资产名称，
» sell_amount	body	string	否	卖出的资产数量，
» buy_currency	body	string	是	买入的资产名称，
» buy_amount	body	string	否	买入的资产数量，

详细描述

» sell_currency: 卖出的资产名称， 根据接口查询支持闪兑的货币列表 GET /flash_swap/currencies获取

» sell_amount: 卖出的资产数量， sell_amount和buy_amount二选一必填

» buy_currency: 买入的资产名称， 根据接口查询支持闪兑的货币列表 GET /flash_swap/currencies获取

» buy_amount: 买入的资产数量， sell_amount和buy_amount二选一必填

返回示例

200 返回

{
  "preview_id": "3453434",
  "sell_currency": "BTC",
  "sell_amount": "0.1",
  "buy_currency": "USDT",
  "buy_amount": "10",
  "price": "100"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	闪兑订单预览成功	Inline

返回格式

状态码 200

闪兑订单预览

名称	类型	描述
» preview_id	string	预览结果id
» sell_currency	string	卖出的资产名称， 根据接口查询支持闪兑的货币列表 GET /flash_swap/currencies获取
» sell_amount	string	卖出的资产数量
» buy_currency	string	买入的资产名称， 根据接口查询支持闪兑的货币列表 GET /flash_swap/currencies获取
» buy_amount	string	买入的资产数量
» price	string	价格

WARNING

该请求需要 API key 和 secret 认证

Futures

永续合约

查询所有的合约信息

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/contracts'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/futures/usdt/contracts \
  -H 'Accept: application/json'

GET /futures/{settle}/contracts

查询所有的合约信息

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "name": "BTC_USDT",
    "type": "direct",
    "quanto_multiplier": "0.0001",
    "ref_discount_rate": "0",
    "order_price_deviate": "0.5",
    "maintenance_rate": "0.005",
    "mark_type": "index",
    "last_price": "38026",
    "mark_price": "37985.6",
    "index_price": "37954.92",
    "funding_rate_indicative": "0.000219",
    "mark_price_round": "0.01",
    "funding_offset": 0,
    "in_delisting": false,
    "risk_limit_base": "1000000",
    "interest_rate": "0.0003",
    "order_price_round": "0.1",
    "order_size_min": 1,
    "ref_rebate_rate": "0.2",
    "funding_interval": 28800,
    "risk_limit_step": "1000000",
    "leverage_min": "1",
    "leverage_max": "100",
    "risk_limit_max": "8000000",
    "maker_fee_rate": "-0.00025",
    "taker_fee_rate": "0.00075",
    "funding_rate": "0.002053",
    "order_size_max": 1000000,
    "funding_next_apply": 1610035200,
    "short_users": 977,
    "config_change_time": 1609899548,
    "trade_size": 28530850594,
    "position_size": 5223816,
    "long_users": 455,
    "funding_impact_value": "60000",
    "orders_limit": 50,
    "trade_id": 10851092,
    "orderbook_id": 2129638396
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Contract]

该请求不需要认证

查询单个合约信息

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/contracts/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/futures/usdt/contracts/BTC_USDT \
  -H 'Accept: application/json'

GET /futures/{settle}/contracts/{contract}

查询单个合约信息

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	URL	string	是	合约标识

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "name": "BTC_USDT",
  "type": "direct",
  "quanto_multiplier": "0.0001",
  "ref_discount_rate": "0",
  "order_price_deviate": "0.5",
  "maintenance_rate": "0.005",
  "mark_type": "index",
  "last_price": "38026",
  "mark_price": "37985.6",
  "index_price": "37954.92",
  "funding_rate_indicative": "0.000219",
  "mark_price_round": "0.01",
  "funding_offset": 0,
  "in_delisting": false,
  "risk_limit_base": "1000000",
  "interest_rate": "0.0003",
  "order_price_round": "0.1",
  "order_size_min": 1,
  "ref_rebate_rate": "0.2",
  "funding_interval": 28800,
  "risk_limit_step": "1000000",
  "leverage_min": "1",
  "leverage_max": "100",
  "risk_limit_max": "8000000",
  "maker_fee_rate": "-0.00025",
  "taker_fee_rate": "0.00075",
  "funding_rate": "0.002053",
  "order_size_max": 1000000,
  "funding_next_apply": 1610035200,
  "short_users": 977,
  "config_change_time": 1609899548,
  "trade_size": 28530850594,
  "position_size": 5223816,
  "long_users": 455,
  "funding_impact_value": "60000",
  "orders_limit": 50,
  "trade_id": 10851092,
  "orderbook_id": 2129638396
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	合约信息	Contract

该请求不需要认证

查询合约市场深度信息

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/order_book'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/futures/usdt/order_book?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /futures/{settle}/order_book

查询合约市场深度信息

买单会按照价格从高到低排序，卖单反之

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	是	合约标识
interval	请求参数	string	否	合并深度指定的价格精度，0 为不合并，不指定则默认为 0
limit	请求参数	integer	否	深度档位数量
with_id	请求参数	boolean	否	是否返回深度更新 ID。深度每发生一次变化，该 ID 自增 1

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd
interval	0
interval	0.1
interval	0.01

返回示例

200 返回

{
  "id": 123456,
  "current": 1623898993.123,
  "update": 1623898993.121,
  "asks": [
    {
      "p": "1.52",
      "s": 100
    },
    {
      "p": "1.53",
      "s": 40
    }
  ],
  "bids": [
    {
      "p": "1.17",
      "s": 150
    },
    {
      "p": "1.16",
      "s": 203
    }
  ]
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	深度查询成功	Inline

返回格式

状态码 200

名称	类型	描述
» id	integer(int64)	深度更新 ID，深度每发生一次变化，该 ID 加 1，只有设置 with_id=true 时才返回
» current	number(double)	接口数据返回时间戳
» update	number(double)	深度变化时间戳
» asks	array	卖方深度列表
»» futures_order_book_item	object
»»» p	string	价格
»»» s	integer(int64)	数量
»» bids	array	买方深度列表
»»» futures_order_book_item	object
»»»» p	string	价格
»»»» s	integer(int64)	数量

该请求不需要认证

合约市场成交记录

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/trades'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/futures/usdt/trades?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /futures/{settle}/trades

合约市场成交记录

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	是	合约标识
limit	请求参数	integer	否	列表返回的最大数量
last_id	请求参数	string	否	以上个列表的最后一条记录的 ID 作为下个列表的起点。
from	请求参数	integer(int64)	否	指定起始时间，时间格式为秒(s)精度的 Unix 时间戳。 不指定则按照 to 和 limit 来限定返回的数量。
to	请求参数	integer(int64)	否	指定结束时间，不指定则默认当前时间，时间格式为秒(s)精度的 Unix 时间戳

详细描述

last_id: 以上个列表的最后一条记录的 ID 作为下个列表的起点。

该字段不再继续支持，新的请求请使用 from 和 to 字段来限定时间范围

from: 指定起始时间，时间格式为秒(s)精度的 Unix 时间戳。 不指定则按照 to 和 limit 来限定返回的数量。 如果 from 和 to 指定的时间范围内的数量超过 limit，只返回 limit 数量

to: 指定结束时间，不指定则默认当前时间，时间格式为秒(s)精度的 Unix 时间戳

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "id": 121234231,
    "create_time": 1514764800,
    "contract": "BTC_USDT",
    "size": -100,
    "price": "100.123"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» id	integer(int64)	成交记录 ID
» create_time	number(double)	成交时间
» create_time_ms	number(double)	成交时间，保留 3 位小数的毫秒精度
» contract	string	合约标识
» size	integer(int64)	成交数量
» price	string	成交价格

该请求不需要认证

合约市场 K 线图

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/candlesticks'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/futures/usdt/candlesticks?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /futures/{settle}/candlesticks

合约市场 K 线图

如果 contract 字段在合约标识前增加了 mark_ 前缀则返回标记价格数据(如mark_BTC_USD)， 如果增加了 index_ 则返回指数价格的数据(如index_BTC_USD)

K 线图数据单次请求最大返回 2000 个点，指定 from, to 和 interval 的时候注意点数不能过多。

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	是	合约标识
from	请求参数	integer(int64)	否	指定 K 线图的起始时间，注意时间格式为秒(s)精度的 Unix 时间戳，
to	请求参数	integer(int64)	否	指定 K 线图的结束时间，不指定则默认当前时间，注意时间格式为秒(s)精度的 Unix 时间戳
limit	请求参数	integer	否	指定数据点的数量，适用于取最近 limit 数量的数据，该字段与 from, to 互斥，如果指定了
interval	请求参数	string	否	数据点的时间间隔，注意 1w 代表一个自然周，7d 的时间是和 Unix 初始时间对齐

详细描述

from: 指定 K 线图的起始时间，注意时间格式为秒(s)精度的 Unix 时间戳， 不指定则默认为 to - 100 * interval，即向前最多 100 个点的时间

to: 指定 K 线图的结束时间，不指定则默认当前时间，注意时间格式为秒(s)精度的 Unix 时间戳

limit: 指定数据点的数量，适用于取最近 limit 数量的数据，该字段与 from, to 互斥，如果指定了 from, to 中的任意字段，该字段会被拒绝

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd
interval	10s
interval	30s
interval	1m
interval	5m
interval	15m
interval	30m
interval	1h
interval	2h
interval	4h
interval	6h
interval	8h
interval	12h
interval	1d
interval	7d
interval	1w
interval	30d

返回示例

200 返回

[
  {
    "t": 1539852480,
    "v": 97151,
    "c": "1.032",
    "h": "1.032",
    "l": "1.032",
    "o": "1.032"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	成功查询	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array	[每个时间粒度的 K 线数据]
» None	object	每个时间粒度的 K 线数据
»» t	number(double)	秒 s 精度的 Unix 时间戳
»» v	integer(int64)	交易量，只有市场行情的 K 线数据里有该值
»» c	string	收盘价
»» h	string	最高价
»» l	string	最低价
»» o	string	开盘价

该请求不需要认证

获取所有合约交易行情统计

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/tickers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/futures/usdt/tickers \
  -H 'Accept: application/json'

GET /futures/{settle}/tickers

获取所有合约交易行情统计

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	否	合约标识，如果指定则只返回该合约相关数据

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "contract": "BTC_USDT",
    "last": "6432",
    "low_24h": "6278",
    "high_24h": "6790",
    "change_percentage": "4.43",
    "total_size": "32323904",
    "volume_24h": "184040233284",
    "volume_24h_btc": "28613220",
    "volume_24h_usd": "184040233284",
    "volume_24h_base": "28613220",
    "volume_24h_quote": "184040233284",
    "volume_24h_settle": "28613220",
    "mark_price": "6534",
    "funding_rate": "0.0001",
    "funding_rate_indicative": "0.0001",
    "index_price": "6531"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» contract	string	合约标识
» last	string	最新成交价
» change_percentage	string	涨跌百分比，跌用负数标识，如 -7.45
» total_size	string	当前合约总持仓量
» low_24h	string	最近24小时最低价
» high_24h	string	最近24小时最高价
» volume_24h	string	最近24小时成交总量
» volume_24h_btc	string	最近24小时成交总量，BTC单位(即将废弃，建议使用 volume_24h_base, volume_24h_quote, volume_24h_settle)
» volume_24h_usd	string	最近24小时成交总量，USD单位(即将废弃，建议使用 volume_24h_base, volume_24h_quote, volume_24h_settle)
» volume_24h_base	string	最近24小时成交量，以基础货币为单位
» volume_24h_quote	string	最近24小时成交量，以计价货币为单位
» volume_24h_settle	string	最近24小时成交量，以结算货币为单位
» mark_price	string	最近标记价格
» funding_rate	string	资金费率
» funding_rate_indicative	string	下一周期预测资金费率
» index_price	string	指数价格
» quanto_base_rate	string	双币种合约中，基础货币和结算货币的汇率。其他类型合约中此字段不存在。
» basis_rate	string	基差率
» basis_value	string	基差数值

该请求不需要认证

合约市场历史资金费率

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/funding_rate'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/futures/usdt/funding_rate?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /futures/{settle}/funding_rate

合约市场历史资金费率

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	是	合约标识
limit	请求参数	integer	否	列表返回的最大数量

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "t": 1543968000,
    "r": "0.000157"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	历史查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» t	integer(int64)	秒 s 精度的 Unix 时间戳
» r	string	资金费率

该请求不需要认证

合约市场保险基金历史

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/insurance'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/futures/usdt/insurance \
  -H 'Accept: application/json'

GET /futures/{settle}/insurance

合约市场保险基金历史

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
limit	请求参数	integer	否	列表返回的最大数量

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "t": 1543968000,
    "b": "83.0031"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» t	integer(int64)	秒 s 精度的 Unix 时间戳
» b	string	保险基金余额

该请求不需要认证

合约统计信息

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/contract_stats'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/futures/usdt/contract_stats?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /futures/{settle}/contract_stats

合约统计信息

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	是	合约标识
from	请求参数	integer(int64)	否	开始时间戳
interval	请求参数	string	否
limit	请求参数	integer	否

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd
interval	5m
interval	15m
interval	30m
interval	1h
interval	4h
interval	1d

返回示例

200 返回

[
  {
    "time": 1603865400,
    "lsr_taker": 100,
    "lsr_account": 0.5,
    "long_liq_size": 0,
    "short_liq_size": 0,
    "open_interest": 124724,
    "short_liq_usd": 0,
    "mark_price": "8865",
    "top_lsr_size": 1.02,
    "short_liq_amount": 0,
    "long_liq_amount": 0,
    "open_interest_usd": 1511,
    "top_lsr_account": 1.5,
    "long_liq_usd": 0
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» time	integer(int64)	统计时间
» lsr_taker	number	多空吃单比
» lsr_account	number	多空持仓用户比
» long_liq_size	integer(int64)	做多爆仓量（张）
» long_liq_amount	number(double)	做多爆仓量（交易币种）
» long_liq_usd	number(double)	做多爆仓量（计价币种）
» short_liq_size	integer(int64)	做空爆仓量（张）
» short_liq_amount	number(double)	做空爆仓量（交易币种）
» short_liq_usd	number(double)	做空爆仓量（计价币种）
» open_interest	integer(int64)	总持仓量（张）
» open_interest_usd	number(double)	总持仓量（计价币种）
» top_lsr_account	number(double)	大户多空账户比
» top_lsr_size	number(double)	大户多空持仓比

该请求不需要认证

查询指数来源

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/index_constituents/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/futures/usdt/index_constituents/BTC_USDT \
  -H 'Accept: application/json'

GET /futures/{settle}/index_constituents/{index}

查询指数来源

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
index	URL	string	是	指数名称

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "index": "BTC_USDT",
  "constituents": [
    {
      "exchange": "Binance",
      "symbols": [
        "BTC_USDT"
      ]
    },
    {
      "exchange": "Gate.io",
      "symbols": [
        "BTC_USDT"
      ]
    },
    {
      "exchange": "Huobi",
      "symbols": [
        "BTC_USDT"
      ]
    }
  ]
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

名称	类型	描述
» index	string	指数名称
» constituents	array	成分
»» IndexConstituent	object
»»» exchange	string	交易所
»»» symbols	array	交易对列表

该请求不需要认证

查询强平委托历史

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/liq_orders'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/futures/usdt/liq_orders \
  -H 'Accept: application/json'

GET /futures/{settle}/liq_orders

查询强平委托历史

from 和 to 的时间间隔最大为 3600。部分私有字段公共接口不会返回，具体参照字段描述

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	否	合约标识，如果指定则只返回该合约相关数据
from	请求参数	integer(int64)	否	起始时间戳
to	请求参数	integer(int64)	否	终止时间戳
limit	请求参数	integer	否	列表返回的最大数量

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "time": 1548654951,
    "contract": "BTC_USDT",
    "size": 600,
    "leverage": "25",
    "margin": "0.006705256878",
    "entry_price": "3536.123",
    "liq_price": "3421.54",
    "mark_price": "3420.27",
    "order_id": 317393847,
    "order_price": "3405",
    "fill_price": "3424",
    "left": 0
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» time	integer(int64)	强制平仓时间
» contract	string	合约标识
» leverage	string	杠杆倍数，公共接口无该字段返回
» size	integer(int64)	仓位大小
» margin	string	保证金，公共接口无该字段返回
» entry_price	string	平均开仓价，公共接口无该字段返回
» liq_price	string	强制平仓价，公共接口无该字段返回
» mark_price	string	市场标记价，公共接口无该字段返回
» order_id	integer(int64)	强平委托ID，公共接口无该字段返回
» order_price	string	强平委托价
» fill_price	string	强平委托吃单平均成交价
» left	integer(int64)	强平委托挂单大小

该请求不需要认证

获取合约账号

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/accounts'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/accounts

获取合约账号

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "user": 1666,
  "currency": "USDT",
  "total": "9707.803567115145",
  "unrealised_pnl": "3371.248828",
  "position_margin": "38.712189181",
  "order_margin": "0",
  "available": "9669.091377934145",
  "point": "0",
  "bonus": "0",
  "in_dual_mode": false,
  "history": {
    "dnw": "10000",
    "pnl": "68.3685",
    "fee": "-1.645812875",
    "refr": "0",
    "fund": "-358.919120009855",
    "point_dnw": "0",
    "point_fee": "0",
    "point_refr": "0",
    "bonus_dnw": "0",
    "bonus_offset": "0"
  }
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	Inline

返回格式

状态码 200

名称	类型	描述
» total	string	账户总资产，total = position_margin + order_margin + available
» unrealised_pnl	string	未实现盈亏
» position_margin	string	头寸保证金
» order_margin	string	未完成订单的保证金
» available	string	可用的转出或交易的额度，统一账户下包含授信额度的可用额度
» point	string	点卡数额
» currency	string	结算币种
» in_dual_mode	boolean	是否为双向持仓模式
» enable_credit	boolean	是否开启统一账户模式
» position_initial_margin	string	头寸占用的起始保证金，适用于统一账户模式
» maintenance_margin	string	头寸占用的维持保证金，适用于统一账户模式
» bonus	string	体验金
» history	object	累计统计数据
»» dnw	string	累计转入转出
»» pnl	string	累计交易盈亏
»» fee	string	累计手续费
»» refr	string	累计获取的推荐人返佣
»» fund	string	累计资金费用
»» point_dnw	string	累计点卡转入转出
»» point_fee	string	累计点卡抵扣手续费
»» point_refr	string	累计获取的点卡推荐人返佣
»» bonus_dnw	string	累计体验金转入转出
»» bonus_offset	string	累计体验金抵扣

WARNING

该请求需要 API key 和 secret 认证

查询合约账户变更历史

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/account_book'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/account_book"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/account_book

查询合约账户变更历史

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
limit	请求参数	integer	否	列表返回的最大数量
from	请求参数	integer(int64)	否	起始时间戳
to	请求参数	integer(int64)	否	终止时间戳
type	请求参数	string	否	变更类型：

详细描述

type: 变更类型：

• dnw: 转入转出
• pnl: 减仓盈亏
• fee: 交易手续费
• refr: 推荐人返佣
• fund: 资金费用
• point_dnw: 点卡转入转出
• point_fee: 点卡交易手续费
• point_refr: 点卡推荐人返佣

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd
type	dnw
type	pnl
type	fee
type	refr
type	fund
type	point_dnw
type	point_fee
type	point_refr

返回示例

200 返回

[
  {
    "time": 1547633726,
    "change": "0.000010152188",
    "balance": "4.59316525194",
    "text": "ETH_USD:6086261",
    "type": "fee"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» time	number(double)	时间
» change	string	变更金额
» balance	string	变更后账户余额
» type	string	变更类型： - dnw: 转入转出 - pnl: 减仓盈亏 - fee: 交易手续费 - refr: 推荐人返佣 - fund: 资金费用 - point_dnw: 点卡转入转出 - point_fee: 点卡交易手续费 - point_refr: 点卡推荐人返佣
» text	string	注释

枚举值列表

属性	值
type	dnw
type	pnl
type	fee
type	refr
type	fund
type	point_dnw
type	point_fee
type	point_refr

WARNING

该请求需要 API key 和 secret 认证

获取用户仓位列表

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/positions'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/positions"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/positions

获取用户仓位列表

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "user": 10000,
    "contract": "BTC_USDT",
    "size": -9440,
    "leverage": "0",
    "risk_limit": "100",
    "leverage_max": "100",
    "maintenance_rate": "0.005",
    "value": "2.497143098997",
    "margin": "4.431548146258",
    "entry_price": "3779.55",
    "liq_price": "99999999",
    "mark_price": "3780.32",
    "unrealised_pnl": "-0.000507486844",
    "realised_pnl": "0.045543982432",
    "history_pnl": "0",
    "last_close_pnl": "0",
    "realised_point": "0",
    "history_point": "0",
    "adl_ranking": 5,
    "pending_orders": 16,
    "close_order": {
      "id": 232323,
      "price": "3779",
      "is_liq": false
    },
    "mode": "single",
    "cross_leverage_limit": "0"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Position]

WARNING

该请求需要 API key 和 secret 认证

获取单个仓位信息

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/positions/BTC_USDT'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/positions/BTC_USDT"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/positions/{contract}

获取单个仓位信息

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	URL	string	是	合约标识

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "user": 10000,
  "contract": "BTC_USDT",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  },
  "mode": "single",
  "cross_leverage_limit": "0"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	仓位信息	Position

WARNING

该请求需要 API key 和 secret 认证

更新仓位保证金

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/positions/BTC_USDT/margin'
query_param = 'change=0.01'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/positions/BTC_USDT/margin"
query_param="change=0.01"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/positions/{contract}/margin

更新仓位保证金

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	URL	string	是	合约标识
change	请求参数	string	是	保证金变化数额，正数增加，负数减少

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "user": 10000,
  "contract": "BTC_USDT",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  },
  "mode": "single",
  "cross_leverage_limit": "0"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	仓位信息	Position

WARNING

该请求需要 API key 和 secret 认证

更新仓位杠杆

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/positions/BTC_USDT/leverage'
query_param = 'leverage=10'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/positions/BTC_USDT/leverage"
query_param="leverage=10"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/positions/{contract}/leverage

更新仓位杠杆

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	URL	string	是	合约标识
leverage	请求参数	string	是	新的杠杆倍数
cross_leverage_limit	请求参数	string	否	全仓模式下的杠杆倍数（即 leverage 为 0 时）

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "user": 10000,
  "contract": "BTC_USDT",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  },
  "mode": "single",
  "cross_leverage_limit": "0"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	仓位信息	Position

WARNING

该请求需要 API key 和 secret 认证

更新仓位风险限额

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/positions/BTC_USDT/risk_limit'
query_param = 'risk_limit=10'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/positions/BTC_USDT/risk_limit"
query_param="risk_limit=10"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/positions/{contract}/risk_limit

更新仓位风险限额

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	URL	string	是	合约标识
risk_limit	请求参数	string	是	新的风险限额

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "user": 10000,
  "contract": "BTC_USDT",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  },
  "mode": "single",
  "cross_leverage_limit": "0"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	仓位信息	Position

WARNING

该请求需要 API key 和 secret 认证

设置持仓模式

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/dual_mode'
query_param = 'dual_mode=true'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_mode"
query_param="dual_mode=true"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/dual_mode

设置持仓模式

变更模式的前提是，所有仓位没有持仓，并且没有挂单

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
dual_mode	请求参数	boolean	是	是否设置为双向持仓

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "user": 1666,
  "currency": "USDT",
  "total": "9707.803567115145",
  "unrealised_pnl": "3371.248828",
  "position_margin": "38.712189181",
  "order_margin": "0",
  "available": "9669.091377934145",
  "point": "0",
  "bonus": "0",
  "in_dual_mode": false,
  "history": {
    "dnw": "10000",
    "pnl": "68.3685",
    "fee": "-1.645812875",
    "refr": "0",
    "fund": "-358.919120009855",
    "point_dnw": "0",
    "point_fee": "0",
    "point_refr": "0",
    "bonus_dnw": "0",
    "bonus_offset": "0"
  }
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	修改成功	Inline

返回格式

状态码 200

名称	类型	描述
» total	string	账户总资产，total = position_margin + order_margin + available
» unrealised_pnl	string	未实现盈亏
» position_margin	string	头寸保证金
» order_margin	string	未完成订单的保证金
» available	string	可用的转出或交易的额度，统一账户下包含授信额度的可用额度
» point	string	点卡数额
» currency	string	结算币种
» in_dual_mode	boolean	是否为双向持仓模式
» enable_credit	boolean	是否开启统一账户模式
» position_initial_margin	string	头寸占用的起始保证金，适用于统一账户模式
» maintenance_margin	string	头寸占用的维持保证金，适用于统一账户模式
» bonus	string	体验金
» history	object	累计统计数据
»» dnw	string	累计转入转出
»» pnl	string	累计交易盈亏
»» fee	string	累计手续费
»» refr	string	累计获取的推荐人返佣
»» fund	string	累计资金费用
»» point_dnw	string	累计点卡转入转出
»» point_fee	string	累计点卡抵扣手续费
»» point_refr	string	累计获取的点卡推荐人返佣
»» bonus_dnw	string	累计体验金转入转出
»» bonus_offset	string	累计体验金抵扣

WARNING

该请求需要 API key 和 secret 认证

获取双仓模式下的持仓信息

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/dual_comp/positions/BTC_USDT'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/dual_comp/positions/BTC_USDT"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/dual_comp/positions/{contract}

获取双仓模式下的持仓信息

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	URL	string	是	合约标识

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "user": 10000,
    "contract": "BTC_USDT",
    "size": -9440,
    "leverage": "0",
    "risk_limit": "100",
    "leverage_max": "100",
    "maintenance_rate": "0.005",
    "value": "2.497143098997",
    "margin": "4.431548146258",
    "entry_price": "3779.55",
    "liq_price": "99999999",
    "mark_price": "3780.32",
    "unrealised_pnl": "-0.000507486844",
    "realised_pnl": "0.045543982432",
    "history_pnl": "0",
    "last_close_pnl": "0",
    "realised_point": "0",
    "history_point": "0",
    "adl_ranking": 5,
    "pending_orders": 16,
    "close_order": {
      "id": 232323,
      "price": "3779",
      "is_liq": false
    },
    "mode": "single",
    "cross_leverage_limit": "0"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	[Position]

WARNING

该请求需要 API key 和 secret 认证

更新双仓模式下的保证金

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/dual_comp/positions/BTC_USDT/margin'
query_param = 'change=0.01&dual_side=dual_long'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_comp/positions/BTC_USDT/margin"
query_param="change=0.01&dual_side=dual_long"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/dual_comp/positions/{contract}/margin

更新双仓模式下的保证金

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	URL	string	是	合约标识
change	请求参数	string	是	保证金变化数额，正数增加，负数减少
dual_side	请求参数	string	是	多头或空头仓位

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd
dual_side	dual_long
dual_side	dual_short

返回示例

200 返回

[
  {
    "user": 10000,
    "contract": "BTC_USDT",
    "size": -9440,
    "leverage": "0",
    "risk_limit": "100",
    "leverage_max": "100",
    "maintenance_rate": "0.005",
    "value": "2.497143098997",
    "margin": "4.431548146258",
    "entry_price": "3779.55",
    "liq_price": "99999999",
    "mark_price": "3780.32",
    "unrealised_pnl": "-0.000507486844",
    "realised_pnl": "0.045543982432",
    "history_pnl": "0",
    "last_close_pnl": "0",
    "realised_point": "0",
    "history_point": "0",
    "adl_ranking": 5,
    "pending_orders": 16,
    "close_order": {
      "id": 232323,
      "price": "3779",
      "is_liq": false
    },
    "mode": "single",
    "cross_leverage_limit": "0"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	[Position]

WARNING

该请求需要 API key 和 secret 认证

更新双仓模式下的杠杆

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/dual_comp/positions/BTC_USDT/leverage'
query_param = 'leverage=10'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_comp/positions/BTC_USDT/leverage"
query_param="leverage=10"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/dual_comp/positions/{contract}/leverage

更新双仓模式下的杠杆

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	URL	string	是	合约标识
leverage	请求参数	string	是	新的杠杆倍数
cross_leverage_limit	请求参数	string	否	全仓模式下的杠杆倍数（即 leverage 为 0 时）

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "user": 10000,
    "contract": "BTC_USDT",
    "size": -9440,
    "leverage": "0",
    "risk_limit": "100",
    "leverage_max": "100",
    "maintenance_rate": "0.005",
    "value": "2.497143098997",
    "margin": "4.431548146258",
    "entry_price": "3779.55",
    "liq_price": "99999999",
    "mark_price": "3780.32",
    "unrealised_pnl": "-0.000507486844",
    "realised_pnl": "0.045543982432",
    "history_pnl": "0",
    "last_close_pnl": "0",
    "realised_point": "0",
    "history_point": "0",
    "adl_ranking": 5,
    "pending_orders": 16,
    "close_order": {
      "id": 232323,
      "price": "3779",
      "is_liq": false
    },
    "mode": "single",
    "cross_leverage_limit": "0"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	[Position]

WARNING

该请求需要 API key 和 secret 认证

更新双仓模式下的风险限额

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/dual_comp/positions/BTC_USDT/risk_limit'
query_param = 'risk_limit=10'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_comp/positions/BTC_USDT/risk_limit"
query_param="risk_limit=10"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/dual_comp/positions/{contract}/risk_limit

更新双仓模式下的风险限额

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	URL	string	是	合约标识
risk_limit	请求参数	string	是	新的风险限额

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "user": 10000,
    "contract": "BTC_USDT",
    "size": -9440,
    "leverage": "0",
    "risk_limit": "100",
    "leverage_max": "100",
    "maintenance_rate": "0.005",
    "value": "2.497143098997",
    "margin": "4.431548146258",
    "entry_price": "3779.55",
    "liq_price": "99999999",
    "mark_price": "3780.32",
    "unrealised_pnl": "-0.000507486844",
    "realised_pnl": "0.045543982432",
    "history_pnl": "0",
    "last_close_pnl": "0",
    "realised_point": "0",
    "history_point": "0",
    "adl_ranking": 5,
    "pending_orders": 16,
    "close_order": {
      "id": 232323,
      "price": "3779",
      "is_liq": false
    },
    "mode": "single",
    "cross_leverage_limit": "0"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	[Position]

WARNING

该请求需要 API key 和 secret 认证

合约交易下单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/orders'
query_param = ''
body='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/orders"
query_param=""
body_param='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/orders

合约交易下单

• 下单时指定的是合约张数 size ，而非币的数量，每一张合约对应的币的数量是合约详情接口里返回的 quanto_multiplier
• 0 成交的订单在撤单 10 分钟之后无法再获取到，会提到订单不存在
• 设置 reduce_only 为 true 可以防止在减仓的时候穿仓
• 单仓模式下，如果需要平仓，需要设置 size 为 0 ，close 为 true
• 双仓模式下，平仓需要使用 auto_size 来设置平仓方向，并同时设置 reduce_only 为 true，size 为 0

请求体示例

{
  "contract": "BTC_USDT",
  "size": 6024,
  "iceberg": 0,
  "price": "3765",
  "tif": "gtc",
  "text": "t-my-custom-id"
}

参数

名称	位置	类型	必选	描述
body	body	FuturesOrder	是
» contract	body	string	是	合约标识
» size	body	integer(int64)	是	必选。交易数量，正数为买入，负数为卖出。平仓委托则设置为0。
» iceberg	body	integer(int64)	否	冰山委托显示数量。0为完全不隐藏。注意，隐藏部分成交按照taker收取手续费。
» price	body	string	否	委托价。价格为0并且tif为ioc，代表市价委托。
» close	body	boolean	否	设置为 true 的时候执行平仓操作，并且size应设置为0
» reduce_only	body	boolean	否	设置为 true 的时候，为只减仓委托
» tif	body	string	否	Time in force 策略，市价单当前只支持 ioc 模式
» text	body	string	否	订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件：
» auto_size	body	string	否	双仓模式下用于设置平仓的方向，close_long 平多头， close_short 平空头，需要同时设置 size 为 0
settle	URL	string	是	结算货币

详细描述

» tif: Time in force 策略，市价单当前只支持 ioc 模式

• gtc: GoodTillCancelled
• ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单
• poc: PendingOrCancelled，被动委托，只挂单不吃单
• fok: FillOrKill, 完全成交，或者完全取消

» text: 订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件：

1. 必须以 t- 开头
2. 不计算 t- ，长度不能超过 28 字节
3. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.)

除用户自定义信息以外，以下为内部保留字段，标识订单来源:

• web: 网页
• api: API 调用
• app: 移动端
• auto_deleveraging: 自动减仓
• liquidation: 强制平仓
• insurance: 保险

枚举值列表

参数	值
» tif	gtc
» tif	ioc
» tif	poc
» tif	fok
» auto_size	close_long
» auto_size	close_short
settle	btc
settle	usdt
settle	usd

返回示例

201 返回

{
  "id": 15675394,
  "user": 100000,
  "contract": "BTC_USDT",
  "create_time": 1546569968,
  "size": 6024,
  "iceberg": 0,
  "left": 6024,
  "price": "3765",
  "fill_price": "0",
  "mkfr": "-0.00025",
  "tkfr": "0.00075",
  "tif": "gtc",
  "refu": 0,
  "is_reduce_only": false,
  "is_close": false,
  "is_liq": false,
  "text": "t-my-custom-id",
  "status": "finished",
  "finish_time": 1514764900,
  "finish_as": "cancelled"
}

返回

状态码	含义	描述	格式
201	Created (opens new window)	订单详情	FuturesOrder

WARNING

该请求需要 API key 和 secret 认证

查询合约订单列表

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/orders'
query_param = 'contract=BTC_USDT&status=open'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/orders"
query_param="contract=BTC_USDT&status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/orders

查询合约订单列表

0 成交的订单在撤单 10 分钟之后无法获取

参数

名称	位置	类型	必选	描述
contract	请求参数	string	是	合约标识
status	请求参数	string	是	基于状态查询订单列表
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
last_id	请求参数	string	否	以上个列表的最后一条记录的 ID 作为下个列表的起点
count_total	请求参数	integer	否	是否需要返回列表总数，默认为 0 不返回
settle	URL	string	是	结算货币

枚举值列表

参数	值
status	open
status	finished
count_total	0
count_total	1
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "id": 15675394,
    "user": 100000,
    "contract": "BTC_USDT",
    "create_time": 1546569968,
    "size": 6024,
    "iceberg": 0,
    "left": 6024,
    "price": "3765",
    "fill_price": "0",
    "mkfr": "-0.00025",
    "tkfr": "0.00075",
    "tif": "gtc",
    "refu": 0,
    "is_reduce_only": false,
    "is_close": false,
    "is_liq": false,
    "text": "t-my-custom-id",
    "status": "finished",
    "finish_time": 1514764900,
    "finish_as": "cancelled"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[FuturesOrder]

返回头部

状态码	头部	类型	格式	描述
200	X-Pagination-Limit	integer		分页时指定的 limit
200	X-Pagination-Offset	integer		分页时指定的 offset
200	X-Pagination-Total	integer		满足条件的列表总数，只有设置 count_total 为 1 时才返回

WARNING

该请求需要 API key 和 secret 认证

批量取消状态为 open 的订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/orders'
query_param = 'contract=BTC_USDT'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/usdt/orders"
query_param="contract=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /futures/{settle}/orders

批量取消状态为 open 的订单

0 成交的订单在撤单 10 分钟之后无法获取

参数

名称	位置	类型	必选	描述
contract	请求参数	string	是	合约标识
side	请求参数	string	否	指定全部买单或全部卖单，不指定则两者都包括
settle	URL	string	是	结算货币

枚举值列表

参数	值
side	ask
side	bid
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "id": 15675394,
    "user": 100000,
    "contract": "BTC_USDT",
    "create_time": 1546569968,
    "size": 6024,
    "iceberg": 0,
    "left": 6024,
    "price": "3765",
    "fill_price": "0",
    "mkfr": "-0.00025",
    "tkfr": "0.00075",
    "tif": "gtc",
    "refu": 0,
    "is_reduce_only": false,
    "is_close": false,
    "is_liq": false,
    "text": "t-my-custom-id",
    "status": "finished",
    "finish_time": 1514764900,
    "finish_as": "cancelled"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	批量撤销成功	[FuturesOrder]

WARNING

该请求需要 API key 和 secret 认证

合约交易批量下单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/batch_orders'
query_param = ''
body='[{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}]'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/batch_orders"
query_param=""
body_param='[{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/batch_orders

合约交易批量下单

• 最多指定10个委托
• 如果有某个委托的参数缺失或格式错误，则全部不执行，并直接返回400错误
• 如果参数检查通过，则全部执行。即便中间有业务逻辑错误（比如资金不足），也不会影响其他执行委托
• 返回结果是数组格式，顺序跟请求体中的委托一一对应
• 返回结果的数组成员中，通过bool类型的successed字段，代表是否执行成功
• 如果执行成功，则包含正常委托内容；如果执行失败，则包括label字段表示错误原因
• 在访问频率限制中，每个委托都单独计一次

请求体示例

[
  {
    "contract": "BTC_USDT",
    "size": 6024,
    "iceberg": 0,
    "price": "3765",
    "tif": "gtc",
    "text": "t-my-custom-id"
  }
]

参数

名称	位置	类型	必选	描述
body	body	array[object]	是
settle	URL	string	是	结算货币

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "succeeded": true,
    "id": 15675394,
    "user": 100000,
    "contract": "BTC_USDT",
    "create_time": 1546569968,
    "size": 6024,
    "iceberg": 0,
    "left": 6024,
    "price": "3765",
    "fill_price": "0",
    "mkfr": "-0.00025",
    "tkfr": "0.00075",
    "tif": "gtc",
    "refu": 0,
    "is_reduce_only": false,
    "is_close": false,
    "is_liq": false,
    "text": "t-my-custom-id",
    "status": "finished",
    "finish_time": 1514764900,
    "finish_as": "cancelled"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	请求执行完成	[Inline]

返回格式

状态码 200

名称	类型	描述
» None	object	合约订单详情
»» succeeded	boolean	请求执行结果
»» label	string	错误标识，仅当执行失败时存在
»» detail	string	错误详情，仅当执行失败并需要给出详情时存在
»» id	integer(int64)	合约订单 ID
»» user	integer	用户 ID
»» create_time	number(double)	订单创建时间
»» finish_time	number(double)	订单结束时间，未结束订单无此字段返回
»» finish_as	string	结束方式，包括： - filled: 完全成交 - cancelled: 用户撤销 - liquidated: 强制平仓撤销 - ioc: 未立即完全成交，因为tif设置为ioc - auto_deleveraged: 自动减仓撤销 - reduce_only: 增持仓位撤销，因为设置reduce_only或平仓 - position_closed: 因为仓位平掉了，所以挂单被撤掉 - reduce_out: 只减仓被排除的不容易成交的挂单
»» status	string	订单状态。 - open: 等待处理 - finished: 已结束的订单
»» contract	string	合约标识
»» size	integer(int64)	必选。交易数量，正数为买入，负数为卖出。平仓委托则设置为0。
»» iceberg	integer(int64)	冰山委托显示数量。0为完全不隐藏。注意，隐藏部分成交按照taker收取手续费。
»» price	string	委托价。价格为0并且tif为ioc，代表市价委托。
»» is_close	boolean	是否为平仓委托。对应请求中的close。
»» is_reduce_only	boolean	是否为只减仓委托。对应请求中的reduce_only。
»» is_liq	boolean	是否为强制平仓委托
»» tif	string	Time in force 策略，市价单当前只支持 ioc 模式 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单 - poc: PendingOrCancelled，被动委托，只挂单不吃单 - fok: FillOrKill, 完全成交，或者完全取消
»» left	integer(int64)	未成交数量
»» fill_price	string	成交价
»» text	string	订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件： 1. 必须以 t- 开头 2. 不计算 t- ，长度不能超过 28 字节 3. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.) 除用户自定义信息以外，以下为内部保留字段，标识订单来源: - web: 网页 - api: API 调用 - app: 移动端 - auto_deleveraging: 自动减仓 - liquidation: 强制平仓 - insurance: 保险
»» tkfr	string	吃单费率
»» mkfr	string	做单费率
»» refu	integer	推荐人用户 ID

枚举值列表

属性	值
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok

WARNING

该请求需要 API key 和 secret 认证

查询单个订单详情

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/orders/12345'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/orders/{order_id}

查询单个订单详情

0 成交的订单在撤单 10 分钟之后无法获取

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
order_id	URL	string	是	成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID（即 text 字段）。

详细描述

order_id: 成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID（即 text 字段）。 基于自定义 ID 的操作只在订单创建之后的 30 分钟之内有效，过期之后只能使用订单 ID

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "id": 15675394,
  "user": 100000,
  "contract": "BTC_USDT",
  "create_time": 1546569968,
  "size": 6024,
  "iceberg": 0,
  "left": 6024,
  "price": "3765",
  "fill_price": "0",
  "mkfr": "-0.00025",
  "tkfr": "0.00075",
  "tif": "gtc",
  "refu": 0,
  "is_reduce_only": false,
  "is_close": false,
  "is_liq": false,
  "text": "t-my-custom-id",
  "status": "finished",
  "finish_time": 1514764900,
  "finish_as": "cancelled"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	订单详情	FuturesOrder

WARNING

该请求需要 API key 和 secret 认证

撤销单个订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/orders/12345'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/usdt/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /futures/{settle}/orders/{order_id}

撤销单个订单

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
order_id	URL	string	是	成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID（即 text 字段）。

详细描述

order_id: 成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID（即 text 字段）。 基于自定义 ID 的操作只在订单创建之后的 30 分钟之内有效，过期之后只能使用订单 ID

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "id": 15675394,
  "user": 100000,
  "contract": "BTC_USDT",
  "create_time": 1546569968,
  "size": 6024,
  "iceberg": 0,
  "left": 6024,
  "price": "3765",
  "fill_price": "0",
  "mkfr": "-0.00025",
  "tkfr": "0.00075",
  "tif": "gtc",
  "refu": 0,
  "is_reduce_only": false,
  "is_close": false,
  "is_liq": false,
  "text": "t-my-custom-id",
  "status": "finished",
  "finish_time": 1514764900,
  "finish_as": "cancelled"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	订单详情	FuturesOrder

WARNING

该请求需要 API key 和 secret 认证

修改单个订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/orders/12345'
query_param = ''
body='{"size":100,"price":"54321"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('PUT', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="PUT"
url="/futures/usdt/orders/12345"
query_param=""
body_param='{"size":100,"price":"54321"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

PUT /futures/{settle}/orders/{order_id}

修改单个订单

请求体示例

{
  "size": 100,
  "price": "54321"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» size	body	integer(int64)	否	新的委托大小。包括已成交委托的部分。
» price	body	string	否	新的委托价格。
settle	URL	string	是	结算货币
order_id	URL	string	是	成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID（即 text 字段）。

详细描述

» size: 新的委托大小。包括已成交委托的部分。

• 如果小于等于已成交数量，则撤销委托。
• 新的委托买卖方向必须跟原有的一致。
• 不能修改平仓单的size。
• 对于只减仓委托，如果调大size，则可能踢出其他只减仓委托。
• 如果不修改价格，则调小size不会影响深度排队，调大size会排到当前价位最后。

order_id: 成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID（即 text 字段）。 基于自定义 ID 的操作只在订单创建之后的 30 分钟之内有效，过期之后只能使用订单 ID

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "id": 15675394,
  "user": 100000,
  "contract": "BTC_USDT",
  "create_time": 1546569968,
  "size": 6024,
  "iceberg": 0,
  "left": 6024,
  "price": "3765",
  "fill_price": "0",
  "mkfr": "-0.00025",
  "tkfr": "0.00075",
  "tif": "gtc",
  "refu": 0,
  "is_reduce_only": false,
  "is_close": false,
  "is_liq": false,
  "text": "t-my-custom-id",
  "status": "finished",
  "finish_time": 1514764900,
  "finish_as": "cancelled"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	订单详情	FuturesOrder

WARNING

该请求需要 API key 和 secret 认证

查询个人成交记录

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/my_trades'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/my_trades"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/my_trades

查询个人成交记录

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	否	合约标识，如果指定则只返回该合约相关数据
order	请求参数	integer(int64)	否	委托ID，如果指定则返回该委托相关数据
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
last_id	请求参数	string	否	以上个列表的最后一条记录的 ID 作为下个列表的起点
count_total	请求参数	integer	否	是否需要返回列表总数，默认为 0 不返回

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd
count_total	0
count_total	1

返回示例

200 返回

[
  {
    "id": 121234231,
    "create_time": 1514764800.123,
    "contract": "BTC_USDT",
    "order_id": "21893289839",
    "size": 100,
    "price": "100.123",
    "text": "t-123456",
    "fee": "0.01",
    "point_fee": "0",
    "role": "taker"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» id	integer(int64)	成交记录 ID
» create_time	number(double)	成交时间
» contract	string	合约标识
» order_id	string	成交记录关联订单 ID
» size	integer(int64)	成交数量
» price	string	成交价格
» role	string	成交角色， taker - 吃单, maker - 做单
» text	string	订单的自定义信息
» fee	string	成交手续费
» point_fee	string	成交点卡手续费

枚举值列表

属性	值
role	taker
role	maker

返回头部

状态码	头部	类型	格式	描述
200	X-Pagination-Limit	integer		分页时指定的 limit
200	X-Pagination-Offset	integer		分页时指定的 offset
200	X-Pagination-Total	integer		满足条件的列表总数，只有设置 count_total 为 1 时才返回

WARNING

该请求需要 API key 和 secret 认证

查询平仓历史

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/position_close'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/position_close"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/position_close

查询平仓历史

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	否	合约标识，如果指定则只返回该合约相关数据
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
from	请求参数	integer(int64)	否	起始时间戳
to	请求参数	integer(int64)	否	终止时间戳

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "time": 1546487347,
    "pnl": "0.00013",
    "side": "long",
    "contract": "BTC_USDT",
    "text": "web"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» time	number(double)	平仓时间
» contract	string	合约标识
» side	string	多空方向 - long: 做多 - short: 做空
» pnl	string	盈亏
» text	string	平仓委托的来源，具体取值参见order.text字段

枚举值列表

属性	值
side	long
side	short

WARNING

该请求需要 API key 和 secret 认证

查询强制平仓历史

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/liquidates'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/liquidates"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/liquidates

查询强制平仓历史

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	否	合约标识，如果指定则只返回该合约相关数据
limit	请求参数	integer	否	列表返回的最大数量
at	请求参数	integer	否	指定时间戳的强平历史

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "time": 1548654951,
    "contract": "BTC_USDT",
    "size": 600,
    "leverage": "25",
    "margin": "0.006705256878",
    "entry_price": "3536.123",
    "liq_price": "3421.54",
    "mark_price": "3420.27",
    "order_id": 317393847,
    "order_price": "3405",
    "fill_price": "3424",
    "left": 0
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» time	integer(int64)	强制平仓时间
» contract	string	合约标识
» leverage	string	杠杆倍数，公共接口无该字段返回
» size	integer(int64)	仓位大小
» margin	string	保证金，公共接口无该字段返回
» entry_price	string	平均开仓价，公共接口无该字段返回
» liq_price	string	强制平仓价，公共接口无该字段返回
» mark_price	string	市场标记价，公共接口无该字段返回
» order_id	integer(int64)	强平委托ID，公共接口无该字段返回
» order_price	string	强平委托价
» fill_price	string	强平委托吃单平均成交价
» left	integer(int64)	强平委托挂单大小

WARNING

该请求需要 API key 和 secret 认证

创建价格触发订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/price_orders'
query_param = ''
body='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/price_orders"
query_param=""
body_param='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/price_orders

创建价格触发订单

请求体示例

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  },
  "order_type": "close-long-order"
}

参数

名称	位置	类型	必选	描述
body	body	FuturesPriceTriggeredOrder	是
» initial	body	object	是
»» contract	body	string	是	合约标识
»» size	body	integer(int64)	否	交易数量，正数为买入，负数为卖出，平仓操作必须为0
»» price	body	string	是	交易价，当价格为 0 时，表示通过市价方式来下单
»» close	body	boolean	否	设置为 true 的时候执行平仓操作
»» tif	body	string	否	Time in force 策略，市价单当前只支持 ioc 模式
»» text	body	string	否	订单的来源，包括：
»» reduce_only	body	boolean	否	设置为 true 的时候执行自动减仓操作
»» auto_size	body	string	否	双仓模式下用于设置平仓的方向，close_long 平多头， close_short 平空头，需要同时设置 size 为 0
» trigger	body	object	是
»» strategy_type	body	integer	否	触发策略
»» price_type	body	integer(int32)	否	参考价格类型。 0 - 最新成交价，1 - 标记价格，2 - 指数价格
»» price	body	string	否	价格触发时为价格，价差触发时为价差
»» rule	body	integer(int32)	否	价格条件类型
»» expiration	body	integer	否	最长等待触发时间，超时则取消该订单，单位是秒 s
» order_type	body	string	否	止盈止损的类型，包括：
settle	URL	string	是	结算货币

详细描述

»» tif: Time in force 策略，市价单当前只支持 ioc 模式

• gtc: GoodTillCancelled
• ioc: ImmediateOrCancelled

»» text: 订单的来源，包括：

• web: 网页
• api: API 调用
• app: 移动端

»» strategy_type: 触发策略

• 0: 价格触发，即当价格满足条件时触发
• 1: 价差触发，即指定 price_type 的最近一次价格减去倒数第二个价格的差值 目前暂时只支持0价格触发

»» rule: 价格条件类型

• 1: 表示根据 strategy_type 和 price_type 算出的价格大于等于 price
• 2: 表示根据 strategy_type 和 price_type 算出的价格小于等于 price

» order_type: 止盈止损的类型，包括：

• close-long-order: 委托单止盈止损，平做多仓
• close-short-order: 委托单止盈止损，平做空仓
• close-long-position: 仓位止盈止损，平多仓
• close-short-position: 仓位止盈止损，平空仓
• plan-close-long-position: 仓位计划止盈止损，平多仓
• plan-close-short-position: 仓位计划止盈止损，平空仓

其中委托单止盈止损的两种类型只读，不能通过请求传入

枚举值列表

参数	值
»» tif	gtc
»» tif	ioc
»» strategy_type	0
»» strategy_type	1
»» price_type	0
»» price_type	1
»» price_type	2
»» rule	1
»» rule	2
settle	btc
settle	usdt
settle	usd

返回示例

201 返回

{
  "id": 1432329
}

返回

状态码	含义	描述	格式
201	Created (opens new window)	成功下单	Inline

返回格式

状态码 201

TriggerOrderResponse

名称	类型	描述
» id	integer(int64)	自动订单 ID

WARNING

该请求需要 API key 和 secret 认证

查询自动订单列表

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/price_orders'
query_param = 'status=open'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/price_orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/price_orders

查询自动订单列表

参数

名称	位置	类型	必选	描述
status	请求参数	string	是	基于状态查询订单列表
contract	请求参数	string	否	合约标识，如果指定则只返回该合约相关数据
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
settle	URL	string	是	结算货币

枚举值列表

参数	值
status	open
status	finished
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "initial": {
      "contract": "BTC_USDT",
      "size": 100,
      "price": "5.03"
    },
    "trigger": {
      "strategy_type": 0,
      "price_type": 0,
      "price": "3000",
      "rule": 1,
      "expiration": 86400
    },
    "id": 1283293,
    "user": 1234,
    "create_time": 1514764800,
    "finish_time": 1514764900,
    "trade_id": 13566,
    "status": "finished",
    "finish_as": "cancelled",
    "reason": "",
    "order_type": "close-long-order"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[FuturesPriceTriggeredOrder]

WARNING

该请求需要 API key 和 secret 认证

批量取消自动订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/price_orders'
query_param = 'contract=BTC_USDT'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/usdt/price_orders"
query_param="contract=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /futures/{settle}/price_orders

批量取消自动订单

参数

名称	位置	类型	必选	描述
contract	请求参数	string	是	合约标识
settle	URL	string	是	结算货币

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "initial": {
      "contract": "BTC_USDT",
      "size": 100,
      "price": "5.03"
    },
    "trigger": {
      "strategy_type": 0,
      "price_type": 0,
      "price": "3000",
      "rule": 1,
      "expiration": 86400
    },
    "id": 1283293,
    "user": 1234,
    "create_time": 1514764800,
    "finish_time": 1514764900,
    "trade_id": 13566,
    "status": "finished",
    "finish_as": "cancelled",
    "reason": "",
    "order_type": "close-long-order"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	批量撤销请求接收并处理，是否成功根据订单列表来决定	[FuturesPriceTriggeredOrder]

WARNING

该请求需要 API key 和 secret 认证

查询单个订单详情

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/price_orders/string'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/price_orders/{order_id}

查询单个订单详情

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
order_id	URL	string	是	成功创建订单时返回的 ID

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  },
  "id": 1283293,
  "user": 1234,
  "create_time": 1514764800,
  "finish_time": 1514764900,
  "trade_id": 13566,
  "status": "finished",
  "finish_as": "cancelled",
  "reason": "",
  "order_type": "close-long-order"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	自动订单详情	FuturesPriceTriggeredOrder

WARNING

该请求需要 API key 和 secret 认证

撤销单个自动订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/price_orders/string'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/usdt/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /futures/{settle}/price_orders/{order_id}

撤销单个自动订单

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
order_id	URL	string	是	成功创建订单时返回的 ID

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  },
  "id": 1283293,
  "user": 1234,
  "create_time": 1514764800,
  "finish_time": 1514764900,
  "trade_id": 13566,
  "status": "finished",
  "finish_as": "cancelled",
  "reason": "",
  "order_type": "close-long-order"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	自动订单详情	FuturesPriceTriggeredOrder

WARNING

该请求需要 API key 和 secret 认证

Delivery

交割合约

查询所有的合约信息

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/contracts'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/contracts \
  -H 'Accept: application/json'

GET /delivery/{settle}/contracts

查询所有的合约信息

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "name": "BTC_USDT_20200814",
    "underlying": "BTC_USDT",
    "cycle": "WEEKLY",
    "type": "direct",
    "quanto_multiplier": "0.0001",
    "mark_type": "index",
    "last_price": "9017",
    "mark_price": "9019",
    "index_price": "9005.3",
    "basis_rate": "0.185095",
    "basis_value": "13.7",
    "basis_impact_value": "100000",
    "settle_price": "0",
    "settle_price_interval": 60,
    "settle_price_duration": 1800,
    "settle_fee_rate": "0.0015",
    "expire_time": 1593763200,
    "order_price_round": "0.1",
    "mark_price_round": "0.1",
    "leverage_min": "1",
    "leverage_max": "100",
    "maintenance_rate": "1000000",
    "risk_limit_base": "140.726652109199",
    "risk_limit_step": "1000000",
    "risk_limit_max": "8000000",
    "maker_fee_rate": "-0.00025",
    "taker_fee_rate": "0.00075",
    "ref_discount_rate": "0",
    "ref_rebate_rate": "0.2",
    "order_price_deviate": "0.5",
    "order_size_min": 1,
    "order_size_max": 1000000,
    "orders_limit": 50,
    "orderbook_id": 63,
    "trade_id": 26,
    "trade_size": 435,
    "position_size": 130,
    "config_change_time": 1593158867,
    "in_delisting": false
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[DeliveryContract]

该请求不需要认证

查询单个合约信息

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/contracts/BTC_USDT_20200814'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/contracts/BTC_USDT_20200814 \
  -H 'Accept: application/json'

GET /delivery/{settle}/contracts/{contract}

查询单个合约信息

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	URL	string	是	合约标识

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "name": "BTC_USDT_20200814",
  "underlying": "BTC_USDT",
  "cycle": "WEEKLY",
  "type": "direct",
  "quanto_multiplier": "0.0001",
  "mark_type": "index",
  "last_price": "9017",
  "mark_price": "9019",
  "index_price": "9005.3",
  "basis_rate": "0.185095",
  "basis_value": "13.7",
  "basis_impact_value": "100000",
  "settle_price": "0",
  "settle_price_interval": 60,
  "settle_price_duration": 1800,
  "settle_fee_rate": "0.0015",
  "expire_time": 1593763200,
  "order_price_round": "0.1",
  "mark_price_round": "0.1",
  "leverage_min": "1",
  "leverage_max": "100",
  "maintenance_rate": "1000000",
  "risk_limit_base": "140.726652109199",
  "risk_limit_step": "1000000",
  "risk_limit_max": "8000000",
  "maker_fee_rate": "-0.00025",
  "taker_fee_rate": "0.00075",
  "ref_discount_rate": "0",
  "ref_rebate_rate": "0.2",
  "order_price_deviate": "0.5",
  "order_size_min": 1,
  "order_size_max": 1000000,
  "orders_limit": 50,
  "orderbook_id": 63,
  "trade_id": 26,
  "trade_size": 435,
  "position_size": 130,
  "config_change_time": 1593158867,
  "in_delisting": false
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	合约信息	DeliveryContract

该请求不需要认证

查询合约市场深度信息

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/order_book'
query_param = 'contract=BTC_USDT_20200814'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/order_book?contract=BTC_USDT_20200814 \
  -H 'Accept: application/json'

GET /delivery/{settle}/order_book

查询合约市场深度信息

买单会按照价格从高到低排序，卖单反之

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	是	合约标识
interval	请求参数	string	否	合并深度指定的价格精度，0 为不合并，不指定则默认为 0
limit	请求参数	integer	否	深度档位数量
with_id	请求参数	boolean	否	是否返回深度更新 ID。深度每发生一次变化，该 ID 自增 1

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd
interval	0
interval	0.1
interval	0.01

返回示例

200 返回

{
  "id": 123456,
  "current": 1623898993.123,
  "update": 1623898993.121,
  "asks": [
    {
      "p": "1.52",
      "s": 100
    },
    {
      "p": "1.53",
      "s": 40
    }
  ],
  "bids": [
    {
      "p": "1.17",
      "s": 150
    },
    {
      "p": "1.16",
      "s": 203
    }
  ]
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	深度查询成功	Inline

返回格式

状态码 200

名称	类型	描述
» id	integer(int64)	深度更新 ID，深度每发生一次变化，该 ID 加 1，只有设置 with_id=true 时才返回
» current	number(double)	接口数据返回时间戳
» update	number(double)	深度变化时间戳
» asks	array	卖方深度列表
»» futures_order_book_item	object
»»» p	string	价格
»»» s	integer(int64)	数量
»» bids	array	买方深度列表
»»» futures_order_book_item	object
»»»» p	string	价格
»»»» s	integer(int64)	数量

该请求不需要认证

合约市场成交记录

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/trades'
query_param = 'contract=BTC_USDT_20200814'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/trades?contract=BTC_USDT_20200814 \
  -H 'Accept: application/json'

GET /delivery/{settle}/trades

合约市场成交记录

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	是	合约标识
limit	请求参数	integer	否	列表返回的最大数量
last_id	请求参数	string	否	以上个列表的最后一条记录的 ID 作为下个列表的起点。
from	请求参数	integer(int64)	否	指定起始时间，时间格式为秒(s)精度的 Unix 时间戳。 不指定则按照 to 和 limit 来限定返回的数量。
to	请求参数	integer(int64)	否	指定结束时间，不指定则默认当前时间，时间格式为秒(s)精度的 Unix 时间戳

详细描述

last_id: 以上个列表的最后一条记录的 ID 作为下个列表的起点。

该字段不再继续支持，新的请求请使用 from 和 to 字段来限定时间范围

from: 指定起始时间，时间格式为秒(s)精度的 Unix 时间戳。 不指定则按照 to 和 limit 来限定返回的数量。 如果 from 和 to 指定的时间范围内的数量超过 limit，只返回 limit 数量

to: 指定结束时间，不指定则默认当前时间，时间格式为秒(s)精度的 Unix 时间戳

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "id": 121234231,
    "create_time": 1514764800,
    "contract": "BTC_USDT",
    "size": -100,
    "price": "100.123"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» id	integer(int64)	成交记录 ID
» create_time	number(double)	成交时间
» create_time_ms	number(double)	成交时间，保留 3 位小数的毫秒精度
» contract	string	合约标识
» size	integer(int64)	成交数量
» price	string	成交价格

该请求不需要认证

合约市场 K 线图

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/candlesticks'
query_param = 'contract=BTC_USDT_20200814'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/candlesticks?contract=BTC_USDT_20200814 \
  -H 'Accept: application/json'

GET /delivery/{settle}/candlesticks

合约市场 K 线图

如果 contract 字段在合约标识前增加了 mark_ 前缀则返回标记价格数据(如mark_BTC_USD)， 如果增加了 index_ 则返回指数价格的数据(如index_BTC_USD)

K 线图数据单次请求最大返回 2000 个点，指定 from, to 和 interval 的时候注意点数不能过多。

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	是	合约标识
from	请求参数	integer(int64)	否	指定 K 线图的起始时间，注意时间格式为秒(s)精度的 Unix 时间戳，
to	请求参数	integer(int64)	否	指定 K 线图的结束时间，不指定则默认当前时间，注意时间格式为秒(s)精度的 Unix 时间戳
limit	请求参数	integer	否	指定数据点的数量，适用于取最近 limit 数量的数据，该字段与 from, to 互斥，如果指定了
interval	请求参数	string	否	数据点的时间间隔，注意 1w 代表一个自然周，7d 的时间是和 Unix 初始时间对齐

详细描述

from: 指定 K 线图的起始时间，注意时间格式为秒(s)精度的 Unix 时间戳， 不指定则默认为 to - 100 * interval，即向前最多 100 个点的时间

to: 指定 K 线图的结束时间，不指定则默认当前时间，注意时间格式为秒(s)精度的 Unix 时间戳

limit: 指定数据点的数量，适用于取最近 limit 数量的数据，该字段与 from, to 互斥，如果指定了 from, to 中的任意字段，该字段会被拒绝

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd
interval	10s
interval	30s
interval	1m
interval	5m
interval	15m
interval	30m
interval	1h
interval	2h
interval	4h
interval	6h
interval	8h
interval	12h
interval	1d
interval	7d
interval	1w
interval	30d

返回示例

200 返回

[
  {
    "t": 1539852480,
    "v": 97151,
    "c": "1.032",
    "h": "1.032",
    "l": "1.032",
    "o": "1.032"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	成功查询	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array	[每个时间粒度的 K 线数据]
» None	object	每个时间粒度的 K 线数据
»» t	number(double)	秒 s 精度的 Unix 时间戳
»» v	integer(int64)	交易量，只有市场行情的 K 线数据里有该值
»» c	string	收盘价
»» h	string	最高价
»» l	string	最低价
»» o	string	开盘价

该请求不需要认证

获取所有合约交易行情统计

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/tickers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/tickers \
  -H 'Accept: application/json'

GET /delivery/{settle}/tickers

获取所有合约交易行情统计

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	否	合约标识

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "contract": "BTC_USDT",
    "last": "6432",
    "low_24h": "6278",
    "high_24h": "6790",
    "change_percentage": "4.43",
    "total_size": "32323904",
    "volume_24h": "184040233284",
    "volume_24h_btc": "28613220",
    "volume_24h_usd": "184040233284",
    "volume_24h_base": "28613220",
    "volume_24h_quote": "184040233284",
    "volume_24h_settle": "28613220",
    "mark_price": "6534",
    "funding_rate": "0.0001",
    "funding_rate_indicative": "0.0001",
    "index_price": "6531"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» contract	string	合约标识
» last	string	最新成交价
» change_percentage	string	涨跌百分比，跌用负数标识，如 -7.45
» total_size	string	当前合约总持仓量
» low_24h	string	最近24小时最低价
» high_24h	string	最近24小时最高价
» volume_24h	string	最近24小时成交总量
» volume_24h_btc	string	最近24小时成交总量，BTC单位(即将废弃，建议使用 volume_24h_base, volume_24h_quote, volume_24h_settle)
» volume_24h_usd	string	最近24小时成交总量，USD单位(即将废弃，建议使用 volume_24h_base, volume_24h_quote, volume_24h_settle)
» volume_24h_base	string	最近24小时成交量，以基础货币为单位
» volume_24h_quote	string	最近24小时成交量，以计价货币为单位
» volume_24h_settle	string	最近24小时成交量，以结算货币为单位
» mark_price	string	最近标记价格
» funding_rate	string	资金费率
» funding_rate_indicative	string	下一周期预测资金费率
» index_price	string	指数价格
» quanto_base_rate	string	双币种合约中，基础货币和结算货币的汇率。其他类型合约中此字段不存在。
» basis_rate	string	基差率
» basis_value	string	基差数值

该请求不需要认证

合约市场保险基金历史

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/insurance'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/insurance \
  -H 'Accept: application/json'

GET /delivery/{settle}/insurance

合约市场保险基金历史

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
limit	请求参数	integer	否	列表返回的最大数量

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "t": 1543968000,
    "b": "83.0031"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» t	integer(int64)	秒 s 精度的 Unix 时间戳
» b	string	保险基金余额

该请求不需要认证

获取合约账号

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/accounts'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/accounts

获取合约账号

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "user": 1666,
  "currency": "USDT",
  "total": "9707.803567115145",
  "unrealised_pnl": "3371.248828",
  "position_margin": "38.712189181",
  "order_margin": "0",
  "available": "9669.091377934145",
  "point": "0",
  "bonus": "0",
  "in_dual_mode": false,
  "history": {
    "dnw": "10000",
    "pnl": "68.3685",
    "fee": "-1.645812875",
    "refr": "0",
    "fund": "-358.919120009855",
    "point_dnw": "0",
    "point_fee": "0",
    "point_refr": "0",
    "bonus_dnw": "0",
    "bonus_offset": "0"
  }
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	Inline

返回格式

状态码 200

名称	类型	描述
» total	string	账户总资产，total = position_margin + order_margin + available
» unrealised_pnl	string	未实现盈亏
» position_margin	string	头寸保证金
» order_margin	string	未完成订单的保证金
» available	string	可用的转出或交易的额度，统一账户下包含授信额度的可用额度
» point	string	点卡数额
» currency	string	结算币种
» in_dual_mode	boolean	是否为双向持仓模式
» enable_credit	boolean	是否开启统一账户模式
» position_initial_margin	string	头寸占用的起始保证金，适用于统一账户模式
» maintenance_margin	string	头寸占用的维持保证金，适用于统一账户模式
» bonus	string	体验金
» history	object	累计统计数据
»» dnw	string	累计转入转出
»» pnl	string	累计交易盈亏
»» fee	string	累计手续费
»» refr	string	累计获取的推荐人返佣
»» fund	string	累计资金费用
»» point_dnw	string	累计点卡转入转出
»» point_fee	string	累计点卡抵扣手续费
»» point_refr	string	累计获取的点卡推荐人返佣
»» bonus_dnw	string	累计体验金转入转出
»» bonus_offset	string	累计体验金抵扣

WARNING

该请求需要 API key 和 secret 认证

查询合约账户变更历史

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/account_book'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/account_book"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/account_book

查询合约账户变更历史

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
limit	请求参数	integer	否	列表返回的最大数量
from	请求参数	integer(int64)	否	起始时间戳
to	请求参数	integer(int64)	否	终止时间戳
type	请求参数	string	否	变更类型：

详细描述

type: 变更类型：

• dnw: 转入转出
• pnl: 减仓盈亏
• fee: 交易手续费
• refr: 推荐人返佣
• fund: 资金费用
• point_dnw: 点卡转入转出
• point_fee: 点卡交易手续费
• point_refr: 点卡推荐人返佣

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd
type	dnw
type	pnl
type	fee
type	refr
type	fund
type	point_dnw
type	point_fee
type	point_refr

返回示例

200 返回

[
  {
    "time": 1547633726,
    "change": "0.000010152188",
    "balance": "4.59316525194",
    "text": "ETH_USD:6086261",
    "type": "fee"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» time	number(double)	时间
» change	string	变更金额
» balance	string	变更后账户余额
» type	string	变更类型： - dnw: 转入转出 - pnl: 减仓盈亏 - fee: 交易手续费 - refr: 推荐人返佣 - fund: 资金费用 - point_dnw: 点卡转入转出 - point_fee: 点卡交易手续费 - point_refr: 点卡推荐人返佣
» text	string	注释

枚举值列表

属性	值
type	dnw
type	pnl
type	fee
type	refr
type	fund
type	point_dnw
type	point_fee
type	point_refr

WARNING

该请求需要 API key 和 secret 认证

获取用户仓位列表

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/positions'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/positions"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/positions

获取用户仓位列表

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "user": 10000,
    "contract": "BTC_USDT",
    "size": -9440,
    "leverage": "0",
    "risk_limit": "100",
    "leverage_max": "100",
    "maintenance_rate": "0.005",
    "value": "2.497143098997",
    "margin": "4.431548146258",
    "entry_price": "3779.55",
    "liq_price": "99999999",
    "mark_price": "3780.32",
    "unrealised_pnl": "-0.000507486844",
    "realised_pnl": "0.045543982432",
    "history_pnl": "0",
    "last_close_pnl": "0",
    "realised_point": "0",
    "history_point": "0",
    "adl_ranking": 5,
    "pending_orders": 16,
    "close_order": {
      "id": 232323,
      "price": "3779",
      "is_liq": false
    },
    "mode": "single",
    "cross_leverage_limit": "0"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Position]

WARNING

该请求需要 API key 和 secret 认证

获取单个仓位信息

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/positions/BTC_USDT_20200814'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/positions/BTC_USDT_20200814"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/positions/{contract}

获取单个仓位信息

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	URL	string	是	合约标识

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "user": 10000,
  "contract": "BTC_USDT",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  },
  "mode": "single",
  "cross_leverage_limit": "0"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	仓位信息	Position

WARNING

该请求需要 API key 和 secret 认证

更新仓位保证金

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/positions/BTC_USDT_20200814/margin'
query_param = 'change=0.01'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/positions/BTC_USDT_20200814/margin"
query_param="change=0.01"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /delivery/{settle}/positions/{contract}/margin

更新仓位保证金

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	URL	string	是	合约标识
change	请求参数	string	是	保证金变化数额，正数增加，负数减少

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "user": 10000,
  "contract": "BTC_USDT",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  },
  "mode": "single",
  "cross_leverage_limit": "0"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	仓位信息	Position

WARNING

该请求需要 API key 和 secret 认证

更新仓位杠杆

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/positions/BTC_USDT_20200814/leverage'
query_param = 'leverage=10'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/positions/BTC_USDT_20200814/leverage"
query_param="leverage=10"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /delivery/{settle}/positions/{contract}/leverage

更新仓位杠杆

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	URL	string	是	合约标识
leverage	请求参数	string	是	新的杠杆倍数

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "user": 10000,
  "contract": "BTC_USDT",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  },
  "mode": "single",
  "cross_leverage_limit": "0"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	仓位信息	Position

WARNING

该请求需要 API key 和 secret 认证

更新仓位风险限额

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/positions/BTC_USDT_20200814/risk_limit'
query_param = 'risk_limit=10'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/positions/BTC_USDT_20200814/risk_limit"
query_param="risk_limit=10"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /delivery/{settle}/positions/{contract}/risk_limit

更新仓位风险限额

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	URL	string	是	合约标识
risk_limit	请求参数	string	是	新的风险限额

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "user": 10000,
  "contract": "BTC_USDT",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  },
  "mode": "single",
  "cross_leverage_limit": "0"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	仓位信息	Position

WARNING

该请求需要 API key 和 secret 认证

合约交易下单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/orders'
query_param = ''
body='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/orders"
query_param=""
body_param='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /delivery/{settle}/orders

合约交易下单

0 成交的订单在撤单 10 分钟之后无法获取

请求体示例

{
  "contract": "BTC_USDT",
  "size": 6024,
  "iceberg": 0,
  "price": "3765",
  "tif": "gtc",
  "text": "t-my-custom-id"
}

参数

名称	位置	类型	必选	描述
body	body	FuturesOrder	是
» contract	body	string	是	合约标识
» size	body	integer(int64)	是	必选。交易数量，正数为买入，负数为卖出。平仓委托则设置为0。
» iceberg	body	integer(int64)	否	冰山委托显示数量。0为完全不隐藏。注意，隐藏部分成交按照taker收取手续费。
» price	body	string	否	委托价。价格为0并且tif为ioc，代表市价委托。
» close	body	boolean	否	设置为 true 的时候执行平仓操作，并且size应设置为0
» reduce_only	body	boolean	否	设置为 true 的时候，为只减仓委托
» tif	body	string	否	Time in force 策略，市价单当前只支持 ioc 模式
» text	body	string	否	订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件：
» auto_size	body	string	否	双仓模式下用于设置平仓的方向，close_long 平多头， close_short 平空头，需要同时设置 size 为 0
settle	URL	string	是	结算货币

详细描述

» tif: Time in force 策略，市价单当前只支持 ioc 模式

• gtc: GoodTillCancelled
• ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单
• poc: PendingOrCancelled，被动委托，只挂单不吃单
• fok: FillOrKill, 完全成交，或者完全取消

» text: 订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件：

1. 必须以 t- 开头
2. 不计算 t- ，长度不能超过 28 字节
3. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.)

除用户自定义信息以外，以下为内部保留字段，标识订单来源:

• web: 网页
• api: API 调用
• app: 移动端
• auto_deleveraging: 自动减仓
• liquidation: 强制平仓
• insurance: 保险

枚举值列表

参数	值
» tif	gtc
» tif	ioc
» tif	poc
» tif	fok
» auto_size	close_long
» auto_size	close_short
settle	btc
settle	usdt
settle	usd

返回示例

201 返回

{
  "id": 15675394,
  "user": 100000,
  "contract": "BTC_USDT",
  "create_time": 1546569968,
  "size": 6024,
  "iceberg": 0,
  "left": 6024,
  "price": "3765",
  "fill_price": "0",
  "mkfr": "-0.00025",
  "tkfr": "0.00075",
  "tif": "gtc",
  "refu": 0,
  "is_reduce_only": false,
  "is_close": false,
  "is_liq": false,
  "text": "t-my-custom-id",
  "status": "finished",
  "finish_time": 1514764900,
  "finish_as": "cancelled"
}

返回

状态码	含义	描述	格式
201	Created (opens new window)	订单详情	FuturesOrder

WARNING

该请求需要 API key 和 secret 认证

查询合约订单列表

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/orders'
query_param = 'status=open'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/orders

查询合约订单列表

0 成交的订单在撤单 10 分钟之后无法获取

参数

名称	位置	类型	必选	描述
contract	请求参数	string	否	合约标识
status	请求参数	string	是	基于状态查询订单列表
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
last_id	请求参数	string	否	以上个列表的最后一条记录的 ID 作为下个列表的起点
count_total	请求参数	integer	否	是否需要返回列表总数，默认为 0 不返回
settle	URL	string	是	结算货币

枚举值列表

参数	值
status	open
status	finished
count_total	0
count_total	1
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "id": 15675394,
    "user": 100000,
    "contract": "BTC_USDT",
    "create_time": 1546569968,
    "size": 6024,
    "iceberg": 0,
    "left": 6024,
    "price": "3765",
    "fill_price": "0",
    "mkfr": "-0.00025",
    "tkfr": "0.00075",
    "tif": "gtc",
    "refu": 0,
    "is_reduce_only": false,
    "is_close": false,
    "is_liq": false,
    "text": "t-my-custom-id",
    "status": "finished",
    "finish_time": 1514764900,
    "finish_as": "cancelled"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[FuturesOrder]

返回头部

状态码	头部	类型	格式	描述
200	X-Pagination-Limit	integer		分页时指定的 limit
200	X-Pagination-Offset	integer		分页时指定的 offset
200	X-Pagination-Total	integer		满足条件的列表总数，只有设置 count_total 为 1 时才返回

WARNING

该请求需要 API key 和 secret 认证

批量取消状态为 open 的订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/orders'
query_param = 'contract=BTC_USDT_20200814'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/delivery/usdt/orders"
query_param="contract=BTC_USDT_20200814"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /delivery/{settle}/orders

批量取消状态为 open 的订单

0 成交的订单在撤单 10 分钟之后无法获取

参数

名称	位置	类型	必选	描述
contract	请求参数	string	是	合约标识
side	请求参数	string	否	指定全部买单或全部卖单，不指定则两者都包括
settle	URL	string	是	结算货币

枚举值列表

参数	值
side	ask
side	bid
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "id": 15675394,
    "user": 100000,
    "contract": "BTC_USDT",
    "create_time": 1546569968,
    "size": 6024,
    "iceberg": 0,
    "left": 6024,
    "price": "3765",
    "fill_price": "0",
    "mkfr": "-0.00025",
    "tkfr": "0.00075",
    "tif": "gtc",
    "refu": 0,
    "is_reduce_only": false,
    "is_close": false,
    "is_liq": false,
    "text": "t-my-custom-id",
    "status": "finished",
    "finish_time": 1514764900,
    "finish_as": "cancelled"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	批量撤销成功	[FuturesOrder]

WARNING

该请求需要 API key 和 secret 认证

查询单个订单详情

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/orders/12345'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/orders/{order_id}

查询单个订单详情

0 成交的订单在撤单 10 分钟之后无法获取

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
order_id	URL	string	是	成功创建订单时返回的 ID

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "id": 15675394,
  "user": 100000,
  "contract": "BTC_USDT",
  "create_time": 1546569968,
  "size": 6024,
  "iceberg": 0,
  "left": 6024,
  "price": "3765",
  "fill_price": "0",
  "mkfr": "-0.00025",
  "tkfr": "0.00075",
  "tif": "gtc",
  "refu": 0,
  "is_reduce_only": false,
  "is_close": false,
  "is_liq": false,
  "text": "t-my-custom-id",
  "status": "finished",
  "finish_time": 1514764900,
  "finish_as": "cancelled"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	订单详情	FuturesOrder

WARNING

该请求需要 API key 和 secret 认证

撤销单个订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/orders/12345'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/delivery/usdt/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /delivery/{settle}/orders/{order_id}

撤销单个订单

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
order_id	URL	string	是	成功创建订单时返回的 ID

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "id": 15675394,
  "user": 100000,
  "contract": "BTC_USDT",
  "create_time": 1546569968,
  "size": 6024,
  "iceberg": 0,
  "left": 6024,
  "price": "3765",
  "fill_price": "0",
  "mkfr": "-0.00025",
  "tkfr": "0.00075",
  "tif": "gtc",
  "refu": 0,
  "is_reduce_only": false,
  "is_close": false,
  "is_liq": false,
  "text": "t-my-custom-id",
  "status": "finished",
  "finish_time": 1514764900,
  "finish_as": "cancelled"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	订单详情	FuturesOrder

WARNING

该请求需要 API key 和 secret 认证

查询个人成交记录

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/my_trades'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/my_trades"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/my_trades

查询个人成交记录

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	否	合约标识
order	请求参数	integer(int64)	否	委托ID，如果指定则返回该委托相关数据
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
last_id	请求参数	string	否	以上个列表的最后一条记录的 ID 作为下个列表的起点
count_total	请求参数	integer	否	是否需要返回列表总数，默认为 0 不返回

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd
count_total	0
count_total	1

返回示例

200 返回

[
  {
    "id": 121234231,
    "create_time": 1514764800.123,
    "contract": "BTC_USDT",
    "order_id": "21893289839",
    "size": 100,
    "price": "100.123",
    "text": "t-123456",
    "fee": "0.01",
    "point_fee": "0",
    "role": "taker"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» id	integer(int64)	成交记录 ID
» create_time	number(double)	成交时间
» contract	string	合约标识
» order_id	string	成交记录关联订单 ID
» size	integer(int64)	成交数量
» price	string	成交价格
» role	string	成交角色， taker - 吃单, maker - 做单
» text	string	订单的自定义信息
» fee	string	成交手续费
» point_fee	string	成交点卡手续费

枚举值列表

属性	值
role	taker
role	maker

返回头部

状态码	头部	类型	格式	描述
200	X-Pagination-Limit	integer		分页时指定的 limit
200	X-Pagination-Offset	integer		分页时指定的 offset
200	X-Pagination-Total	integer		满足条件的列表总数，只有设置 count_total 为 1 时才返回

WARNING

该请求需要 API key 和 secret 认证

查询平仓历史

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/position_close'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/position_close"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/position_close

查询平仓历史

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	否	合约标识
limit	请求参数	integer	否	列表返回的最大数量

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "time": 1546487347,
    "pnl": "0.00013",
    "side": "long",
    "contract": "BTC_USDT",
    "text": "web"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» time	number(double)	平仓时间
» contract	string	合约标识
» side	string	多空方向 - long: 做多 - short: 做空
» pnl	string	盈亏
» text	string	平仓委托的来源，具体取值参见order.text字段

枚举值列表

属性	值
side	long
side	short

WARNING

该请求需要 API key 和 secret 认证

查询强制平仓历史

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/liquidates'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/liquidates"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/liquidates

查询强制平仓历史

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	否	合约标识
limit	请求参数	integer	否	列表返回的最大数量
at	请求参数	integer	否	指定时间戳的强平历史

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "time": 1548654951,
    "contract": "BTC_USDT",
    "size": 600,
    "leverage": "25",
    "margin": "0.006705256878",
    "entry_price": "3536.123",
    "liq_price": "3421.54",
    "mark_price": "3420.27",
    "order_id": 317393847,
    "order_price": "3405",
    "fill_price": "3424",
    "left": 0
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» time	integer(int64)	强制平仓时间
» contract	string	合约标识
» leverage	string	杠杆倍数，公共接口无该字段返回
» size	integer(int64)	仓位大小
» margin	string	保证金，公共接口无该字段返回
» entry_price	string	平均开仓价，公共接口无该字段返回
» liq_price	string	强制平仓价，公共接口无该字段返回
» mark_price	string	市场标记价，公共接口无该字段返回
» order_id	integer(int64)	强平委托ID，公共接口无该字段返回
» order_price	string	强平委托价
» fill_price	string	强平委托吃单平均成交价
» left	integer(int64)	强平委托挂单大小

WARNING

该请求需要 API key 和 secret 认证

查询结算记录

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/settlements'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/settlements"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/settlements

查询结算记录

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	否	合约标识
limit	请求参数	integer	否	列表返回的最大数量
at	请求参数	integer	否	指定时间戳的结算历史

枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "time": 1548654951,
    "contract": "BTC_USDT",
    "size": 600,
    "leverage": "25",
    "margin": "0.006705256878",
    "entry_price": "3536.123",
    "settle_price": "3421.54",
    "profit": "-6.87498",
    "fee": "0.03079386"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» time	integer(int64)	强制平仓时间
» contract	string	合约标识
» leverage	string	杠杆倍数
» size	integer(int64)	仓位大小
» margin	string	保证金
» entry_price	string	平均开仓价
» settle_price	string	结算价
» profit	string	盈利
» fee	string	结算费

WARNING

该请求需要 API key 和 secret 认证

创建价格触发订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/price_orders'
query_param = ''
body='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/price_orders"
query_param=""
body_param='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /delivery/{settle}/price_orders

创建价格触发订单

请求体示例

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  },
  "order_type": "close-long-order"
}

参数

名称	位置	类型	必选	描述
body	body	FuturesPriceTriggeredOrder	是
» initial	body	object	是
»» contract	body	string	是	合约标识
»» size	body	integer(int64)	否	交易数量，正数为买入，负数为卖出，平仓操作必须为0
»» price	body	string	是	交易价，当价格为 0 时，表示通过市价方式来下单
»» close	body	boolean	否	设置为 true 的时候执行平仓操作
»» tif	body	string	否	Time in force 策略，市价单当前只支持 ioc 模式
»» text	body	string	否	订单的来源，包括：
»» reduce_only	body	boolean	否	设置为 true 的时候执行自动减仓操作
»» auto_size	body	string	否	双仓模式下用于设置平仓的方向，close_long 平多头， close_short 平空头，需要同时设置 size 为 0
» trigger	body	object	是
»» strategy_type	body	integer	否	触发策略
»» price_type	body	integer(int32)	否	参考价格类型。 0 - 最新成交价，1 - 标记价格，2 - 指数价格
»» price	body	string	否	价格触发时为价格，价差触发时为价差
»» rule	body	integer(int32)	否	价格条件类型
»» expiration	body	integer	否	最长等待触发时间，超时则取消该订单，单位是秒 s
» order_type	body	string	否	止盈止损的类型，包括：
settle	URL	string	是	结算货币

详细描述

»» tif: Time in force 策略，市价单当前只支持 ioc 模式

• gtc: GoodTillCancelled
• ioc: ImmediateOrCancelled

»» text: 订单的来源，包括：

• web: 网页
• api: API 调用
• app: 移动端

»» strategy_type: 触发策略

• 0: 价格触发，即当价格满足条件时触发
• 1: 价差触发，即指定 price_type 的最近一次价格减去倒数第二个价格的差值 目前暂时只支持0价格触发

»» rule: 价格条件类型

• 1: 表示根据 strategy_type 和 price_type 算出的价格大于等于 price
• 2: 表示根据 strategy_type 和 price_type 算出的价格小于等于 price

» order_type: 止盈止损的类型，包括：

• close-long-order: 委托单止盈止损，平做多仓
• close-short-order: 委托单止盈止损，平做空仓
• close-long-position: 仓位止盈止损，平多仓
• close-short-position: 仓位止盈止损，平空仓
• plan-close-long-position: 仓位计划止盈止损，平多仓
• plan-close-short-position: 仓位计划止盈止损，平空仓

其中委托单止盈止损的两种类型只读，不能通过请求传入

枚举值列表

参数	值
»» tif	gtc
»» tif	ioc
»» strategy_type	0
»» strategy_type	1
»» price_type	0
»» price_type	1
»» price_type	2
»» rule	1
»» rule	2
settle	usdt
settle	btc

返回示例

201 返回

{
  "id": 1432329
}

返回

状态码	含义	描述	格式
201	Created (opens new window)	成功下单	Inline

返回格式

状态码 201

TriggerOrderResponse

名称	类型	描述
» id	integer(int64)	自动订单 ID

WARNING

该请求需要 API key 和 secret 认证

查询自动订单列表

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/price_orders'
query_param = 'status=open'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/price_orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/price_orders

查询自动订单列表

参数

名称	位置	类型	必选	描述
status	请求参数	string	是	基于状态查询订单列表
contract	请求参数	string	否	合约标识，如果指定则只返回该合约相关数据
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
settle	URL	string	是	结算货币

枚举值列表

参数	值
status	open
status	finished
settle	usdt
settle	btc

返回示例

200 返回

[
  {
    "initial": {
      "contract": "BTC_USDT",
      "size": 100,
      "price": "5.03"
    },
    "trigger": {
      "strategy_type": 0,
      "price_type": 0,
      "price": "3000",
      "rule": 1,
      "expiration": 86400
    },
    "id": 1283293,
    "user": 1234,
    "create_time": 1514764800,
    "finish_time": 1514764900,
    "trade_id": 13566,
    "status": "finished",
    "finish_as": "cancelled",
    "reason": "",
    "order_type": "close-long-order"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[FuturesPriceTriggeredOrder]

WARNING

该请求需要 API key 和 secret 认证

批量取消自动订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/price_orders'
query_param = 'contract=BTC_USDT'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/delivery/usdt/price_orders"
query_param="contract=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /delivery/{settle}/price_orders

批量取消自动订单

参数

名称	位置	类型	必选	描述
contract	请求参数	string	是	合约标识
settle	URL	string	是	结算货币

枚举值列表

参数	值
settle	usdt
settle	btc

返回示例

200 返回

[
  {
    "initial": {
      "contract": "BTC_USDT",
      "size": 100,
      "price": "5.03"
    },
    "trigger": {
      "strategy_type": 0,
      "price_type": 0,
      "price": "3000",
      "rule": 1,
      "expiration": 86400
    },
    "id": 1283293,
    "user": 1234,
    "create_time": 1514764800,
    "finish_time": 1514764900,
    "trade_id": 13566,
    "status": "finished",
    "finish_as": "cancelled",
    "reason": "",
    "order_type": "close-long-order"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	批量撤销请求接收并处理，是否成功根据订单列表来决定	[FuturesPriceTriggeredOrder]

WARNING

该请求需要 API key 和 secret 认证

查询单个订单详情

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/price_orders/string'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/price_orders/{order_id}

查询单个订单详情

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
order_id	URL	string	是	成功创建订单时返回的 ID

枚举值列表

参数	值
settle	usdt
settle	btc

返回示例

200 返回

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  },
  "id": 1283293,
  "user": 1234,
  "create_time": 1514764800,
  "finish_time": 1514764900,
  "trade_id": 13566,
  "status": "finished",
  "finish_as": "cancelled",
  "reason": "",
  "order_type": "close-long-order"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	自动订单详情	FuturesPriceTriggeredOrder

WARNING

该请求需要 API key 和 secret 认证

撤销单个自动订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/price_orders/string'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/delivery/usdt/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /delivery/{settle}/price_orders/{order_id}

撤销单个自动订单

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
order_id	URL	string	是	成功创建订单时返回的 ID

枚举值列表

参数	值
settle	usdt
settle	btc

返回示例

200 返回

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  },
  "id": 1283293,
  "user": 1234,
  "create_time": 1514764800,
  "finish_time": 1514764900,
  "trade_id": 13566,
  "status": "finished",
  "finish_as": "cancelled",
  "reason": "",
  "order_type": "close-long-order"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	自动订单详情	FuturesPriceTriggeredOrder

WARNING

该请求需要 API key 和 secret 认证

Options

期权接口

列出所有标的

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/underlyings'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/underlyings \
  -H 'Accept: application/json'

GET /options/underlyings

列出所有标的

返回示例

200 返回

[
  {
    "name": "BTC_USDT",
    "index_price": "70000"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» name	string	标的名
» index_price	string	现货指数价格

该请求不需要认证

列出所有到期时间

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/expirations'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/expirations?underlying=BTC_USDT \
  -H 'Accept: application/json'

GET /options/expirations

列出所有到期时间

参数

名称	位置	类型	必选	描述
underlying	请求参数	string	是	标的物

返回示例

200 返回

[
  1637913600
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列出指定标的下的到期时间	[integer]

返回格式

状态码 200

名称	类型	描述
» None	integer(int64)	到期时间的Unix时间戳

该请求不需要认证

列出指定标的和到期时间下的所有合约

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/contracts'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/contracts?underlying=BTC_USDT \
  -H 'Accept: application/json'

GET /options/contracts

列出指定标的和到期时间下的所有合约

参数

名称	位置	类型	必选	描述
underlying	请求参数	string	是	标的物
expiration	请求参数	integer(int64)	否	到期时间的Unix时间戳

返回示例

200 返回

[
  {
    "name": "BTC_USDT-20211130-65000-C",
    "tag": "WEEK",
    "create_time": 1636702700,
    "expiration_time": 1637913600,
    "is_call": true,
    "strike_price": "65000",
    "last_price": "13000",
    "mark_price": "14010",
    "orderbook_id": 9,
    "trade_id": 1,
    "trade_size": 10,
    "position_size": 10,
    "underlying": "BTC_USDT",
    "underlying_price": "70000",
    "multiplier": "0.0001",
    "order_price_round": "0.1",
    "mark_price_round": "0.1",
    "maker_fee_rate": "0.0004",
    "taker_fee_rate": "0.0004",
    "price_limit_fee_rate": "0.1",
    "ref_discount_rate": "0",
    "ref_rebate_rate": "0",
    "order_price_deviate": "0.5",
    "order_size_min": 1,
    "order_size_max": 100000,
    "orders_limit": 50
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array	[合约详情]
» None	object	合约详情
»» name	string	合约标识
»» tag	string	标记
»» create_time	number(double)	创建时间
»» expiration_time	number(double)	到期时间
»» is_call	boolean	true为Call看涨, false为Put看跌
»» multiplier	string	计价货币兑换为结算货币的乘数
»» underlying	string	标的物
»» underlying_price	string	标的价格
»» last_price	string	上一次成交价格
»» mark_price	string	当前标记价格
»» index_price	string	当前指数价格
»» maker_fee_rate	string	挂单成交的手续费率，负数代表返还后续费
»» taker_fee_rate	string	吃单成交的手续费率
»» order_price_round	string	委托价格最小单位
»» mark_price_round	string	标记、强平等价格最小单位
»» order_size_min	integer(int64)	最小下单数量
»» order_size_max	integer(int64)	最大下单数量
»» order_price_deviate	string	下单价与当前标记价格允许的正负偏移量， 即下单价 order_price 需满足如下条件: abs(order_price - mark_price) <= mark_price * order_price_deviate
»» ref_discount_rate	string	被推荐人享受交易费率折扣
»» ref_rebate_rate	string	推荐人享受交易费率返佣比例
»» orderbook_id	integer(int64)	orderbook更新ID
»» trade_id	integer(int64)	当前成交ID
»» trade_size	integer(int64)	历史累计成交
»» position_size	integer(int64)	当前做多用户持有仓位总和
»» orders_limit	integer	最多挂单数量

该请求不需要认证

请求指定合约

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/contracts/BTC_USDT-20211130-65000-C'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/contracts/BTC_USDT-20211130-65000-C \
  -H 'Accept: application/json'

GET /options/contracts/{contract}

请求指定合约

参数

名称	位置	类型	必选	描述
contract	URL	string	是

返回示例

200 返回

{
  "name": "BTC_USDT-20211130-65000-C",
  "tag": "WEEK",
  "create_time": 1636702700,
  "expiration_time": 1637913600,
  "is_call": true,
  "strike_price": "65000",
  "last_price": "13000",
  "mark_price": "14010",
  "orderbook_id": 9,
  "trade_id": 1,
  "trade_size": 10,
  "position_size": 10,
  "underlying": "BTC_USDT",
  "underlying_price": "70000",
  "multiplier": "0.0001",
  "order_price_round": "0.1",
  "mark_price_round": "0.1",
  "maker_fee_rate": "0.0004",
  "taker_fee_rate": "0.0004",
  "price_limit_fee_rate": "0.1",
  "ref_discount_rate": "0",
  "ref_rebate_rate": "0",
  "order_price_deviate": "0.5",
  "order_size_min": 1,
  "order_size_max": 100000,
  "orders_limit": 50
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

合约详情

名称	类型	描述
» name	string	合约标识
» tag	string	标记
» create_time	number(double)	创建时间
» expiration_time	number(double)	到期时间
» is_call	boolean	true为Call看涨, false为Put看跌
» multiplier	string	计价货币兑换为结算货币的乘数
» underlying	string	标的物
» underlying_price	string	标的价格
» last_price	string	上一次成交价格
» mark_price	string	当前标记价格
» index_price	string	当前指数价格
» maker_fee_rate	string	挂单成交的手续费率，负数代表返还后续费
» taker_fee_rate	string	吃单成交的手续费率
» order_price_round	string	委托价格最小单位
» mark_price_round	string	标记、强平等价格最小单位
» order_size_min	integer(int64)	最小下单数量
» order_size_max	integer(int64)	最大下单数量
» order_price_deviate	string	下单价与当前标记价格允许的正负偏移量， 即下单价 order_price 需满足如下条件: abs(order_price - mark_price) <= mark_price * order_price_deviate
» ref_discount_rate	string	被推荐人享受交易费率折扣
» ref_rebate_rate	string	推荐人享受交易费率返佣比例
» orderbook_id	integer(int64)	orderbook更新ID
» trade_id	integer(int64)	当前成交ID
» trade_size	integer(int64)	历史累计成交
» position_size	integer(int64)	当前做多用户持有仓位总和
» orders_limit	integer	最多挂单数量

该请求不需要认证

列出结算历史

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/settlements'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/settlements?underlying=BTC_USDT \
  -H 'Accept: application/json'

GET /options/settlements

列出结算历史

参数

名称	位置	类型	必选	描述
underlying	请求参数	string	是	标的物
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
from	请求参数	integer(int64)	否	起始时间戳
to	请求参数	integer(int64)	否	终止时间戳

返回示例

200 返回

[
  {
    "time": 1598839200,
    "profit": "312.35",
    "fee": "0.3284",
    "settle_price": "11687.65",
    "contract": "BTC-WEEKLY-200824-11000-P",
    "strike_price": "12000"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» time	number(double)	配置最后更新时间
» contract	string	合约名
» profit	string	单张结算盈利
» fee	string	单张结算手续费
» strike_price	string	行权价格
» settle_price	string	结算价格

该请求不需要认证

请求指定合约结算信息

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/settlements/BTC_USDT-20211130-65000-C'
query_param = 'underlying=BTC_USDT&at=0'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/settlements/BTC_USDT-20211130-65000-C?underlying=BTC_USDT&at=0 \
  -H 'Accept: application/json'

GET /options/settlements/{contract}

请求指定合约结算信息

参数

名称	位置	类型	必选	描述
contract	URL	string	是
underlying	请求参数	string	是	标的物
at	请求参数	integer(int64)	是

返回示例

200 返回

{
  "time": 1598839200,
  "profit": "312.35",
  "fee": "0.3284",
  "settle_price": "11687.65",
  "contract": "BTC-WEEKLY-200824-11000-P",
  "strike_price": "12000"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

名称	类型	描述
» time	number(double)	配置最后更新时间
» contract	string	合约名
» profit	string	单张结算盈利
» fee	string	单张结算手续费
» strike_price	string	行权价格
» settle_price	string	结算价格

该请求不需要认证

查询个人结算记录

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/my_settlements'
query_param = 'underlying=BTC_USDT'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/my_settlements"
query_param="underlying=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/my_settlements

查询个人结算记录

参数

名称	位置	类型	必选	描述
underlying	请求参数	string	是	标的物
contract	请求参数	string	否	合约名称
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
from	请求参数	integer(int64)	否	起始时间戳
to	请求参数	integer(int64)	否	终止时间戳

返回示例

200 返回

[
  {
    "size": -1,
    "settle_profit": "0",
    "contract": "BTC_USDT-20220624-26000-C",
    "strike_price": "26000",
    "time": 1656057600,
    "settle_price": "20917.461281337048",
    "underlying": "BTC_USDT",
    "realised_pnl": "-0.00116042",
    "fee": "0"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» time	number(double)	结算时间
» underlying	string	标的
» contract	string	合约标识
» strike_price	string	行权价格
» settle_price	string	结算价格
» size	integer(int64)	结算张数
» settle_profit	string	结算收益
» fee	string	结算费用
» realised_pnl	string	开仓累计盈亏，包括权益金，手续费，结算盈利等。

WARNING

该请求需要 API key 和 secret 认证

查询合约市场深度信息

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/order_book'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/order_book?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /options/order_book

查询合约市场深度信息

买单会按照价格从高到低排序，卖单反之

参数

名称	位置	类型	必选	描述
contract	请求参数	string	是	合约标识
interval	请求参数	string	否	合并深度指定的价格精度，0 为不合并，不指定则默认为 0
limit	请求参数	integer	否	深度档位数量
with_id	请求参数	boolean	否	是否返回深度更新 ID。深度每发生一次变化，该 ID 自增 1

枚举值列表

参数	值
interval	0
interval	0.1
interval	0.01

返回示例

200 返回

{
  "id": 123456,
  "current": 1623898993.123,
  "update": 1623898993.121,
  "asks": [
    {
      "p": "1.52",
      "s": 100
    },
    {
      "p": "1.53",
      "s": 40
    }
  ],
  "bids": [
    {
      "p": "1.17",
      "s": 150
    },
    {
      "p": "1.16",
      "s": 203
    }
  ]
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	深度查询成功	Inline

返回格式

状态码 200

名称	类型	描述
» id	integer(int64)	深度更新 ID，深度每发生一次变化，该 ID 加 1，只有设置 with_id=true 时才返回
» current	number(double)	接口数据返回时间戳
» update	number(double)	深度变化时间戳
» asks	array	卖方深度列表
»» futures_order_book_item	object
»»» p	string	价格
»»» s	integer(int64)	数量
»» bids	array	买方深度列表
»»» futures_order_book_item	object
»»»» p	string	价格
»»»» s	integer(int64)	数量

该请求不需要认证

查询期权市场ticker信息

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/tickers'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/tickers?underlying=BTC_USDT \
  -H 'Accept: application/json'

GET /options/tickers

查询期权市场ticker信息

参数

名称	位置	类型	必选	描述
underlying	请求参数	string	是	标的物

返回示例

200 返回

[
  {
    "name": "BTC_USDT-20211130-65000-C",
    "last_price": "13000",
    "mark_price": "14010",
    "position_size": 10,
    "ask1_size": 0,
    "ask1_price": "0",
    "bid1_size": 1,
    "bid1_price": "11",
    "vega": "41.41202",
    "theta": "-120.1506",
    "rho": "6.52485",
    "gamma": "0.00004",
    "delta": "0.33505",
    "mark_iv": "0.123",
    "bid_iv": "0.023",
    "ask_iv": "0.342",
    "leverage": "13"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» None	object	期权合约详情
»» name	string	期权合约标识
»» last_price	string	上一次成交价格
»» mark_price	string	当前标记价格
»» index_price	string	当前指数价格
»» ask1_size	integer(int64)	卖1深度大小
»» ask1_price	string	卖1深度价格
»» bid1_size	integer(int64)	买1深度大小
»» bid1_price	string	买1深度价格
»» position_size	integer(int64)	当前做多用户持有仓位总和
»» mark_iv	string	隐含波动率
»» bid_iv	string	买方隐含波动率
»» ask_iv	string	卖方隐含波动率
»» leverage	string	当前杠杆率，公式：underlying_price / mark_price * delta
»» delta	string	希腊字母delta
»» gamma	string	希腊字母gamma
»» vega	string	希腊字母vega
»» theta	string	希腊字母theta
»» rho	string	希腊字母rho

该请求不需要认证

查询标的ticker信息

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/underlying/tickers/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/underlying/tickers/BTC_USDT \
  -H 'Accept: application/json'

GET /options/underlying/tickers/{underlying}

查询标的ticker信息

参数

名称	位置	类型	必选	描述
underlying	URL	string	是	标的物

返回示例

200 返回

{
  "trade_put": 33505,
  "trade_call": 123,
  "index_price": "76543.3"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

期权标的详情

名称	类型	描述
» trade_put	integer(int64)	所有看跌合约24小时总成交量
» trade_call	integer(int64)	所有看涨合约24小时总成交量
» index_price	string	指数价格

该请求不需要认证

合约市场 K 线图

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/candlesticks'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/candlesticks?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /options/candlesticks

合约市场 K 线图

参数

名称	位置	类型	必选	描述
contract	请求参数	string	是	合约标识
limit	请求参数	integer	否	列表返回的最大数量
from	请求参数	integer(int64)	否	起始时间戳
to	请求参数	integer(int64)	否	终止时间戳
interval	请求参数	string	否	数据点的时间间隔

枚举值列表

参数	值
interval	1m
interval	5m
interval	15m
interval	30m
interval	1h

返回示例

200 返回

[
  {
    "t": 1539852480,
    "v": 97151,
    "c": "1.032",
    "h": "1.032",
    "l": "1.032",
    "o": "1.032"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	成功查询	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array	[每个时间粒度的 K 线数据]
» None	object	每个时间粒度的 K 线数据
»» t	number(double)	秒 s 精度的 Unix 时间戳
»» v	integer(int64)	交易量，只有市场行情的 K 线数据里有该值
»» c	string	收盘价
»» h	string	最高价
»» l	string	最低价
»» o	string	开盘价

该请求不需要认证

标的指数价格 K 线图

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/underlying/candlesticks'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/underlying/candlesticks?underlying=BTC_USDT \
  -H 'Accept: application/json'

GET /options/underlying/candlesticks

标的指数价格 K 线图

参数

名称	位置	类型	必选	描述
underlying	请求参数	string	是	标的物
limit	请求参数	integer	否	列表返回的最大数量
from	请求参数	integer(int64)	否	起始时间戳
to	请求参数	integer(int64)	否	终止时间戳
interval	请求参数	string	否	数据点的时间间隔

枚举值列表

参数	值
interval	1m
interval	5m
interval	15m
interval	30m
interval	1h

返回示例

200 返回

[
  {
    "t": 1539852480,
    "v": 97151,
    "c": "1.032",
    "h": "1.032",
    "l": "1.032",
    "o": "1.032"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	成功查询	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array	[每个时间粒度的 K 线数据]
» None	object	每个时间粒度的 K 线数据
»» t	number(double)	秒 s 精度的 Unix 时间戳
»» v	integer(int64)	交易量，只有市场行情的 K 线数据里有该值
»» c	string	收盘价
»» h	string	最高价
»» l	string	最低价
»» o	string	开盘价

该请求不需要认证

市场成交记录

示例代码

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/trades'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/trades \
  -H 'Accept: application/json'

GET /options/trades

市场成交记录

参数

名称	位置	类型	必选	描述
contract	请求参数	string	否	合约名称
type	请求参数	string(P)	否	C为看涨，P为看跌
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
from	请求参数	integer(int64)	否	起始时间戳
to	请求参数	integer(int64)	否	终止时间戳

返回示例

200 返回

[
  {
    "id": 121234231,
    "create_time": 1514764800,
    "contract": "BTC_USDT",
    "size": -100,
    "price": "100.123"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» id	integer(int64)	成交记录 ID
» create_time	number(double)	成交时间
» create_time_ms	number(double)	成交时间，保留 3 位小数的毫秒精度
» contract	string	合约标识
» size	integer(int64)	成交数量
» price	string	成交价格

该请求不需要认证

查询账户信息

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/accounts'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/accounts

查询账户信息

返回示例

200 返回

{
  "user": 666,
  "currency": "USDT",
  "short_enabled": true,
  "total": "170",
  "unrealised_pnl": "-600",
  "init_margin": "1300",
  "maint_margin": "1125",
  "order_margin": "0",
  "available": "0",
  "point": "0"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

名称	类型	描述
» user	integer	用户 ID
» total	string	账户总资产
» short_enabled	boolean	是否允许做空
» unrealised_pnl	string	未实现盈亏
» init_margin	string	仓位初始保证金
» maint_margin	string	仓位维持保证金
» order_margin	string	未完成订单的保证金
» available	string	可用的转出或交易的额度
» point	string	点卡数额
» currency	string	结算币种

WARNING

该请求需要 API key 和 secret 认证

查询账户变更历史

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/account_book'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/account_book"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/account_book

查询账户变更历史

参数

名称	位置	类型	必选	描述
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
from	请求参数	integer(int64)	否	起始时间戳
to	请求参数	integer(int64)	否	终止时间戳
type	请求参数	string	否	变更类型：

详细描述

type: 变更类型：

• dnw: 转入转出
• prem: 交易权利金
• fee: 手续费
• refr: 推荐人返佣
• set: 结算盈亏

枚举值列表

参数	值
type	dnw
type	prem
type	fee
type	refr
type	set

返回示例

200 返回

[
  {
    "time": 1636426005,
    "change": "-0.16",
    "balance": "7378.189",
    "text": "BTC_USDT-20211216-5000-P:25",
    "type": "fee"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» time	number(double)	时间
» change	string	变更数量
» balance	string	变更后账户总资产
» type	string	变更类型： - dnw, 充提 - prem, 交易权益金 - fee, 交易手续费 - set, 结算 - refr, 推荐人返佣 - point_dnw - point_fee - point_refr
» text	string	备注

WARNING

该请求需要 API key 和 secret 认证

列出指定标的下的用户仓位

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/positions'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/positions"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/positions

列出指定标的下的用户仓位

参数

名称	位置	类型	必选	描述
underlying	请求参数	string	否	标的物

返回示例

200 返回

[
  {
    "user": 11027586,
    "contract": "BTC_USDT-20211216-5000-P",
    "size": 10,
    "entry_price": "1234",
    "realised_pnl": "120",
    "mark_price": "6000",
    "unrealised_pnl": "-320",
    "pending_orders": 1,
    "close_order": {
      "id": 232323,
      "price": "5779",
      "is_liq": false
    }
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array	[合约仓位详情]
» None	object	合约仓位详情
»» user	integer	用户ID
»» contract	string	合约标识
»» size	integer(int64)	头寸大小
»» entry_price	string	开仓价格
»» mark_price	string	合约当前标记价格
»» realised_pnl	string	已实现盈亏
»» unrealised_pnl	string	未实现盈亏
»» pending_orders	integer	当前未完成委托数量
»» close_order	object|null	当前平仓委托信息，如果没有平仓则为null
»»» id	integer(int64)	委托ID
»»» price	string	委托价格
»»» is_liq	boolean	是否为强制平仓

WARNING

该请求需要 API key 和 secret 认证

请求指定仓位

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/positions/BTC_USDT-20211130-65000-C'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/positions/BTC_USDT-20211130-65000-C"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/positions/{contract}

请求指定仓位

参数

名称	位置	类型	必选	描述
contract	URL	string	是

返回示例

200 返回

{
  "user": 11027586,
  "contract": "BTC_USDT-20211216-5000-P",
  "size": 10,
  "entry_price": "1234",
  "realised_pnl": "120",
  "mark_price": "6000",
  "unrealised_pnl": "-320",
  "pending_orders": 1,
  "close_order": {
    "id": 232323,
    "price": "5779",
    "is_liq": false
  }
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	查询成功	Inline

返回格式

状态码 200

合约仓位详情

名称	类型	描述
» user	integer	用户ID
» contract	string	合约标识
» size	integer(int64)	头寸大小
» entry_price	string	开仓价格
» mark_price	string	合约当前标记价格
» realised_pnl	string	已实现盈亏
» unrealised_pnl	string	未实现盈亏
» pending_orders	integer	当前未完成委托数量
» close_order	object|null	当前平仓委托信息，如果没有平仓则为null
»» id	integer(int64)	委托ID
»» price	string	委托价格
»» is_liq	boolean	是否为强制平仓

WARNING

该请求需要 API key 和 secret 认证

列出指定标的下的用户平仓历史

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/position_close'
query_param = 'underlying=BTC_USDT'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/position_close"
query_param="underlying=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/position_close

列出指定标的下的用户平仓历史

参数

名称	位置	类型	必选	描述
underlying	请求参数	string	是	标的物
contract	请求参数	string	否	合约名称

返回示例

200 返回

[
  {
    "time": 1631764800,
    "pnl": "-42914.291",
    "settle_size": "-10001",
    "side": "short",
    "contract": "BTC_USDT-20210916-5000-C",
    "text": "settled"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» time	number(double)	平仓时间
» contract	string	合约标识
» side	string	多空方向 - long: 做多 - short: 做空
» pnl	string	盈亏
» text	string	平仓委托的来源，具体取值参见order.text字段
» settle_size	string	结算仓位大小

枚举值列表

属性	值
side	long
side	short

WARNING

该请求需要 API key 和 secret 认证

交易下单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/orders'
query_param = ''
body='{"size":-1,"iceberg":0,"contract":"BTC_USDT-20210916-5000-C","text":"-","tif":"gtc","price":"100"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/options/orders"
query_param=""
body_param='{"size":-1,"iceberg":0,"contract":"BTC_USDT-20210916-5000-C","text":"-","tif":"gtc","price":"100"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /options/orders

交易下单

请求体示例

{
  "size": -1,
  "iceberg": 0,
  "contract": "BTC_USDT-20210916-5000-C",
  "text": "-",
  "tif": "gtc",
  "price": "100"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» contract	body	string	是	期权标识
» size	body	integer(int64)	是	必选。交易数量，正数为买入，负数为卖出。平仓委托则设置为0。
» iceberg	body	integer(int64)	否	冰山委托显示数量。0为完全不隐藏。注意，隐藏部分成交按照taker收取手续费。
» price	body	string	否	委托价。价格为0并且tif为ioc，代表市价委托。
» close	body	boolean	否	设置为 true 的时候执行平仓操作，并且size应设置为0
» reduce_only	body	boolean	否	设置为 true 的时候，为只减仓委托
» tif	body	string	否	Time in force 策略，市价单当前只支持 ioc 模式
» text	body	string	否	订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件：

详细描述

» tif: Time in force 策略，市价单当前只支持 ioc 模式

• gtc: GoodTillCancelled
• ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单
• poc: PendingOrCancelled，被动委托，只挂单不吃单

» text: 订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件：

1. 必须以 t- 开头
2. 不计算 t- ，长度不能超过 28 字节
3. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.)

除用户自定义信息以外，以下为内部保留字段，标识订单来源:

• web: 网页
• api: API 调用
• app: 移动端
• auto_deleveraging: 自动减仓
• liquidation: 强制平仓
• insurance: 保险

枚举值列表

参数	值
» tif	gtc
» tif	ioc
» tif	poc

返回示例

201 返回

{
  "status": "finished",
  "size": -1,
  "id": 2,
  "iceberg": 0,
  "is_liq": false,
  "is_close": false,
  "contract": "BTC_USDT-20210916-5000-C",
  "text": "-",
  "fill_price": "100",
  "finish_as": "filled",
  "left": 0,
  "tif": "gtc",
  "is_reduce_only": false,
  "create_time": 1631763361,
  "finish_time": 1631763397,
  "price": "100"
}

返回

状态码	含义	描述	格式
201	Created (opens new window)	订单信息	Inline

返回格式

状态码 201

期权订单详情

名称	类型	描述
» id	integer(int64)	期权订单 ID
» user	integer	用户 ID
» create_time	number(double)	订单创建时间
» finish_time	number(double)	订单结束时间，未结束订单无此字段返回
» finish_as	string	结束方式，包括： - filled: 完全成交 - cancelled: 用户撤销 - liquidated: 强制平仓撤销 - ioc: 未立即完全成交，因为tif设置为ioc - auto_deleveraged: 自动减仓撤销 - reduce_only: 增持仓位撤销，因为设置reduce_only或平仓 - position_closed: 因为仓位平掉了，所以挂单被撤掉 - reduce_out: 只减仓被排除的不容易成交的挂单
» status	string	订单状态。 - open: 等待处理 - finished: 已结束的订单
» contract	string	期权标识
» size	integer(int64)	必选。交易数量，正数为买入，负数为卖出。平仓委托则设置为0。
» iceberg	integer(int64)	冰山委托显示数量。0为完全不隐藏。注意，隐藏部分成交按照taker收取手续费。
» price	string	委托价。价格为0并且tif为ioc，代表市价委托。
» is_close	boolean	是否为平仓委托。对应请求中的close。
» is_reduce_only	boolean	是否为只减仓委托。对应请求中的reduce_only。
» is_liq	boolean	是否为强制平仓委托
» tif	string	Time in force 策略，市价单当前只支持 ioc 模式 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单 - poc: PendingOrCancelled，被动委托，只挂单不吃单
» left	integer(int64)	未成交数量
» fill_price	string	成交价
» text	string	订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件： 1. 必须以 t- 开头 2. 不计算 t- ，长度不能超过 28 字节 3. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.) 除用户自定义信息以外，以下为内部保留字段，标识订单来源: - web: 网页 - api: API 调用 - app: 移动端 - auto_deleveraging: 自动减仓 - liquidation: 强制平仓 - insurance: 保险
» tkfr	string	吃单费率
» mkfr	string	做单费率
» refu	integer	推荐人用户 ID

枚举值列表

属性	值
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
status	open
status	finished
tif	gtc
tif	ioc
tif	poc

WARNING

该请求需要 API key 和 secret 认证

查询合约订单列表

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/orders'
query_param = 'status=open'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/orders

查询合约订单列表

参数

名称	位置	类型	必选	描述
contract	请求参数	string	否	合约名称
underlying	请求参数	string	否	标的物
status	请求参数	string	是	基于状态查询订单列表
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
from	请求参数	integer(int64)	否	起始时间戳
to	请求参数	integer(int64)	否	终止时间戳

枚举值列表

参数	值
status	open
status	finished

返回示例

200 返回

[
  {
    "status": "finished",
    "size": -1,
    "id": 2,
    "iceberg": 0,
    "is_liq": false,
    "is_close": false,
    "contract": "BTC_USDT-20210916-5000-C",
    "text": "-",
    "fill_price": "100",
    "finish_as": "filled",
    "left": 0,
    "tif": "gtc",
    "is_reduce_only": false,
    "create_time": 1631763361,
    "finish_time": 1631763397,
    "price": "100"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array	[期权订单详情]
» None	object	期权订单详情
»» id	integer(int64)	期权订单 ID
»» user	integer	用户 ID
»» create_time	number(double)	订单创建时间
»» finish_time	number(double)	订单结束时间，未结束订单无此字段返回
»» finish_as	string	结束方式，包括： - filled: 完全成交 - cancelled: 用户撤销 - liquidated: 强制平仓撤销 - ioc: 未立即完全成交，因为tif设置为ioc - auto_deleveraged: 自动减仓撤销 - reduce_only: 增持仓位撤销，因为设置reduce_only或平仓 - position_closed: 因为仓位平掉了，所以挂单被撤掉 - reduce_out: 只减仓被排除的不容易成交的挂单
»» status	string	订单状态。 - open: 等待处理 - finished: 已结束的订单
»» contract	string	期权标识
»» size	integer(int64)	必选。交易数量，正数为买入，负数为卖出。平仓委托则设置为0。
»» iceberg	integer(int64)	冰山委托显示数量。0为完全不隐藏。注意，隐藏部分成交按照taker收取手续费。
»» price	string	委托价。价格为0并且tif为ioc，代表市价委托。
»» is_close	boolean	是否为平仓委托。对应请求中的close。
»» is_reduce_only	boolean	是否为只减仓委托。对应请求中的reduce_only。
»» is_liq	boolean	是否为强制平仓委托
»» tif	string	Time in force 策略，市价单当前只支持 ioc 模式 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单 - poc: PendingOrCancelled，被动委托，只挂单不吃单
»» left	integer(int64)	未成交数量
»» fill_price	string	成交价
»» text	string	订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件： 1. 必须以 t- 开头 2. 不计算 t- ，长度不能超过 28 字节 3. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.) 除用户自定义信息以外，以下为内部保留字段，标识订单来源: - web: 网页 - api: API 调用 - app: 移动端 - auto_deleveraging: 自动减仓 - liquidation: 强制平仓 - insurance: 保险
»» tkfr	string	吃单费率
»» mkfr	string	做单费率
»» refu	integer	推荐人用户 ID

枚举值列表

属性	值
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
status	open
status	finished
tif	gtc
tif	ioc
tif	poc

WARNING

该请求需要 API key 和 secret 认证

批量取消状态为 open 的订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/orders'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/options/orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /options/orders

批量取消状态为 open 的订单

参数

名称	位置	类型	必选	描述
contract	请求参数	string	否	合约名称
underlying	请求参数	string	否	标的物
side	请求参数	string	否	指定全部买单或全部卖单，不指定则两者都包括

枚举值列表

参数	值
side	ask
side	bid

返回示例

200 返回

[
  {
    "status": "finished",
    "size": -1,
    "id": 2,
    "iceberg": 0,
    "is_liq": false,
    "is_close": false,
    "contract": "BTC_USDT-20210916-5000-C",
    "text": "-",
    "fill_price": "100",
    "finish_as": "filled",
    "left": 0,
    "tif": "gtc",
    "is_reduce_only": false,
    "create_time": 1631763361,
    "finish_time": 1631763397,
    "price": "100"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	批量撤销成功	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array	[期权订单详情]
» None	object	期权订单详情
»» id	integer(int64)	期权订单 ID
»» user	integer	用户 ID
»» create_time	number(double)	订单创建时间
»» finish_time	number(double)	订单结束时间，未结束订单无此字段返回
»» finish_as	string	结束方式，包括： - filled: 完全成交 - cancelled: 用户撤销 - liquidated: 强制平仓撤销 - ioc: 未立即完全成交，因为tif设置为ioc - auto_deleveraged: 自动减仓撤销 - reduce_only: 增持仓位撤销，因为设置reduce_only或平仓 - position_closed: 因为仓位平掉了，所以挂单被撤掉 - reduce_out: 只减仓被排除的不容易成交的挂单
»» status	string	订单状态。 - open: 等待处理 - finished: 已结束的订单
»» contract	string	期权标识
»» size	integer(int64)	必选。交易数量，正数为买入，负数为卖出。平仓委托则设置为0。
»» iceberg	integer(int64)	冰山委托显示数量。0为完全不隐藏。注意，隐藏部分成交按照taker收取手续费。
»» price	string	委托价。价格为0并且tif为ioc，代表市价委托。
»» is_close	boolean	是否为平仓委托。对应请求中的close。
»» is_reduce_only	boolean	是否为只减仓委托。对应请求中的reduce_only。
»» is_liq	boolean	是否为强制平仓委托
»» tif	string	Time in force 策略，市价单当前只支持 ioc 模式 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单 - poc: PendingOrCancelled，被动委托，只挂单不吃单
»» left	integer(int64)	未成交数量
»» fill_price	string	成交价
»» text	string	订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件： 1. 必须以 t- 开头 2. 不计算 t- ，长度不能超过 28 字节 3. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.) 除用户自定义信息以外，以下为内部保留字段，标识订单来源: - web: 网页 - api: API 调用 - app: 移动端 - auto_deleveraging: 自动减仓 - liquidation: 强制平仓 - insurance: 保险
»» tkfr	string	吃单费率
»» mkfr	string	做单费率
»» refu	integer	推荐人用户 ID

枚举值列表

属性	值
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
status	open
status	finished
tif	gtc
tif	ioc
tif	poc

WARNING

该请求需要 API key 和 secret 认证

查询单个订单详情

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/orders/12345'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/orders/{order_id}

查询单个订单详情

参数

名称	位置	类型	必选	描述
order_id	URL	integer(int64)	是	成功创建订单时返回的订单 ID

返回示例

200 返回

{
  "status": "finished",
  "size": -1,
  "id": 2,
  "iceberg": 0,
  "is_liq": false,
  "is_close": false,
  "contract": "BTC_USDT-20210916-5000-C",
  "text": "-",
  "fill_price": "100",
  "finish_as": "filled",
  "left": 0,
  "tif": "gtc",
  "is_reduce_only": false,
  "create_time": 1631763361,
  "finish_time": 1631763397,
  "price": "100"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	订单信息	Inline

返回格式

状态码 200

期权订单详情

名称	类型	描述
» id	integer(int64)	期权订单 ID
» user	integer	用户 ID
» create_time	number(double)	订单创建时间
» finish_time	number(double)	订单结束时间，未结束订单无此字段返回
» finish_as	string	结束方式，包括： - filled: 完全成交 - cancelled: 用户撤销 - liquidated: 强制平仓撤销 - ioc: 未立即完全成交，因为tif设置为ioc - auto_deleveraged: 自动减仓撤销 - reduce_only: 增持仓位撤销，因为设置reduce_only或平仓 - position_closed: 因为仓位平掉了，所以挂单被撤掉 - reduce_out: 只减仓被排除的不容易成交的挂单
» status	string	订单状态。 - open: 等待处理 - finished: 已结束的订单
» contract	string	期权标识
» size	integer(int64)	必选。交易数量，正数为买入，负数为卖出。平仓委托则设置为0。
» iceberg	integer(int64)	冰山委托显示数量。0为完全不隐藏。注意，隐藏部分成交按照taker收取手续费。
» price	string	委托价。价格为0并且tif为ioc，代表市价委托。
» is_close	boolean	是否为平仓委托。对应请求中的close。
» is_reduce_only	boolean	是否为只减仓委托。对应请求中的reduce_only。
» is_liq	boolean	是否为强制平仓委托
» tif	string	Time in force 策略，市价单当前只支持 ioc 模式 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单 - poc: PendingOrCancelled，被动委托，只挂单不吃单
» left	integer(int64)	未成交数量
» fill_price	string	成交价
» text	string	订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件： 1. 必须以 t- 开头 2. 不计算 t- ，长度不能超过 28 字节 3. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.) 除用户自定义信息以外，以下为内部保留字段，标识订单来源: - web: 网页 - api: API 调用 - app: 移动端 - auto_deleveraging: 自动减仓 - liquidation: 强制平仓 - insurance: 保险
» tkfr	string	吃单费率
» mkfr	string	做单费率
» refu	integer	推荐人用户 ID

枚举值列表

属性	值
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
status	open
status	finished
tif	gtc
tif	ioc
tif	poc

WARNING

该请求需要 API key 和 secret 认证

撤销单个订单

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/orders/12345'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/options/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /options/orders/{order_id}

撤销单个订单

参数

名称	位置	类型	必选	描述
order_id	URL	integer(int64)	是	成功创建订单时返回的订单 ID

返回示例

200 返回

{
  "status": "finished",
  "size": -1,
  "id": 2,
  "iceberg": 0,
  "is_liq": false,
  "is_close": false,
  "contract": "BTC_USDT-20210916-5000-C",
  "text": "-",
  "fill_price": "100",
  "finish_as": "filled",
  "left": 0,
  "tif": "gtc",
  "is_reduce_only": false,
  "create_time": 1631763361,
  "finish_time": 1631763397,
  "price": "100"
}

返回

状态码	含义	描述	格式
200	OK (opens new window)	订单信息	Inline

返回格式

状态码 200

期权订单详情

名称	类型	描述
» id	integer(int64)	期权订单 ID
» user	integer	用户 ID
» create_time	number(double)	订单创建时间
» finish_time	number(double)	订单结束时间，未结束订单无此字段返回
» finish_as	string	结束方式，包括： - filled: 完全成交 - cancelled: 用户撤销 - liquidated: 强制平仓撤销 - ioc: 未立即完全成交，因为tif设置为ioc - auto_deleveraged: 自动减仓撤销 - reduce_only: 增持仓位撤销，因为设置reduce_only或平仓 - position_closed: 因为仓位平掉了，所以挂单被撤掉 - reduce_out: 只减仓被排除的不容易成交的挂单
» status	string	订单状态。 - open: 等待处理 - finished: 已结束的订单
» contract	string	期权标识
» size	integer(int64)	必选。交易数量，正数为买入，负数为卖出。平仓委托则设置为0。
» iceberg	integer(int64)	冰山委托显示数量。0为完全不隐藏。注意，隐藏部分成交按照taker收取手续费。
» price	string	委托价。价格为0并且tif为ioc，代表市价委托。
» is_close	boolean	是否为平仓委托。对应请求中的close。
» is_reduce_only	boolean	是否为只减仓委托。对应请求中的reduce_only。
» is_liq	boolean	是否为强制平仓委托
» tif	string	Time in force 策略，市价单当前只支持 ioc 模式 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单 - poc: PendingOrCancelled，被动委托，只挂单不吃单
» left	integer(int64)	未成交数量
» fill_price	string	成交价
» text	string	订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件： 1. 必须以 t- 开头 2. 不计算 t- ，长度不能超过 28 字节 3. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.) 除用户自定义信息以外，以下为内部保留字段，标识订单来源: - web: 网页 - api: API 调用 - app: 移动端 - auto_deleveraging: 自动减仓 - liquidation: 强制平仓 - insurance: 保险
» tkfr	string	吃单费率
» mkfr	string	做单费率
» refu	integer	推荐人用户 ID

枚举值列表

属性	值
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
status	open
status	finished
tif	gtc
tif	ioc
tif	poc

WARNING

该请求需要 API key 和 secret 认证

查询个人成交记录

示例代码

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/my_trades'
query_param = 'underlying=BTC_USDT'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/my_trades"
query_param="underlying=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/my_trades

查询个人成交记录

参数

名称	位置	类型	必选	描述
underlying	请求参数	string	是	标的物
contract	请求参数	string	否	合约名称
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
from	请求参数	integer(int64)	否	起始时间戳
to	请求参数	integer(int64)	否	终止时间戳

返回示例

200 返回

[
  {
    "underlying_price": "48000",
    "size": 1,
    "contract": "BTC_USDT-20210916-5000-C",
    "id": 1,
    "role": "taker",
    "create_time": 1631763397,
    "order_id": 4,
    "price": "100"
  }
]

返回

状态码	含义	描述	格式
200	OK (opens new window)	列表查询成功	[Inline]

返回格式

状态码 200

名称	类型	描述
» id	integer(int64)	成交记录 ID
» create_time	number(double)	成交时间
» contract	string	合约标识
» order_id	integer	成交记录关联订单 ID
» size	integer(int64)	成交数量
» price	string	成交价格
» underlying_price	string	标的价格
» role	string	成交角色， taker - 吃单, maker - 做单

枚举值列表

属性	值
role	taker
role	maker

WARNING

该请求需要 API key 和 secret 认证

模型

CurrencyPair

{
  "id": "string",
  "base": "string",
  "quote": "string",
  "fee": "string",
  "min_base_amount": "string",
  "min_quote_amount": "string",
  "amount_precision": 0,
  "precision": 0,
  "trade_status": "untradable",
  "sell_start": 0,
  "buy_start": 0
}

现货交易对

属性

名称	类型	必选	限制	描述
id	string	false	none	交易对
base	string	false	none	交易货币
quote	string	false	none	计价货币
fee	string	false	none	交易费率
min_base_amount	string	false	none	交易货币最低交易数量，null 表示无限制
min_quote_amount	string	false	none	计价货币最低交易数量，null 表示无限制
amount_precision	integer	false	none	数量精度
precision	integer	false	none	价格精度
trade_status	string	false	none	交易状态 - untradable: 不可交易 - buyable: 可买 - sellable: 可卖 - tradable: 买卖均可交易
sell_start	integer(int64)	false	none	允许卖出时间，秒级 Unix 时间戳
buy_start	integer(int64)	false	none	允许买入时间，秒级 Unix 时间戳

枚举值列表

属性	值
trade_status	untradable
trade_status	buyable
trade_status	sellable
trade_status	tradable

Order

{
  "id": "string",
  "text": "string",
  "create_time": "string",
  "update_time": "string",
  "create_time_ms": 0,
  "update_time_ms": 0,
  "status": "open",
  "currency_pair": "string",
  "type": "limit",
  "account": "spot",
  "side": "buy",
  "amount": "string",
  "price": "string",
  "time_in_force": "gtc",
  "iceberg": "string",
  "auto_borrow": true,
  "auto_repay": true,
  "left": "string",
  "fill_price": "string",
  "filled_total": "string",
  "fee": "string",
  "fee_currency": "string",
  "point_fee": "string",
  "gt_fee": "string",
  "gt_discount": true,
  "rebated_fee": "string",
  "rebated_fee_currency": "string"
}

现货单详情

属性

名称	类型	必选	限制	描述
id	string	false	只读	订单 ID
text	string	false	none	订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件： 1. 必须以 t- 开头 2. 不计算 t- ，长度不能超过 28 字节 3. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.)
create_time	string	false	只读	订单创建时间
update_time	string	false	只读	订单最新修改时间
create_time_ms	integer(int64)	false	只读	订单创建时间，毫秒精度
update_time_ms	integer(int64)	false	只读	订单最近修改时间，毫秒精度
status	string	false	只读	订单状态。 - open: 等待处理 - closed: 全部成交 - cancelled: 订单撤销
currency_pair	string	true	none	交易货币对
type	string	false	none	订单类型，limit - 限价单
account	string	false	none	账户类型，spot - 现货账户，margin - 杠杆账户，cross_margin - 全仓杠杆账户 统一账户只能设置 cross_margin
side	string	true	none	买单或者卖单
amount	string	true	none	交易数量
price	string	true	none	交易价
time_in_force	string	false	none	Time in force 策略。 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单 - poc: PendingOrCancelled，被动委托，只挂单不吃单 - fok: FillOrKill，全部成交或者全部取消
iceberg	string	false	none	冰山下单显示的数量，不指定或传 0 都默认为普通下单。如果需要全部冰山，设置为 -1
auto_borrow	boolean	false	只写	杠杆(包括逐仓全仓)交易时，如果账户余额不足，是否由系统自动借入不足部分
auto_repay	boolean	false	none	全仓杠杆下单是否开启自动还款，默认关闭。需要注意的是: 1. 此字段仅针对全仓杠杆有效。逐仓杠杆不支持订单级别的自动还款设置，只能通过 POST /margin/auto_repay 修改用户级别的设置 2. auto_borrow 与 auto_repay 不支持同时开启
left	string	false	只读	交易货币未成交数量
fill_price	string	false	只读	已成交的计价币种总额，该字段废弃，建议使用相同意义的 filled_total
filled_total	string	false	只读	已成交总金额
fee	string	false	只读	成交扣除的手续费
fee_currency	string	false	只读	手续费计价单位
point_fee	string	false	只读	手续费抵扣使用的点卡数量
gt_fee	string	false	只读	手续费抵扣使用的 GT 数量
gt_discount	boolean	false	只读	是否开启GT抵扣
rebated_fee	string	false	只读	返还的手续费
rebated_fee_currency	string	false	只读	返还手续费计价单位

枚举值列表

属性	值
status	open
status	closed
status	cancelled
type	limit
account	spot
account	margin
account	cross_margin
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok

Loan

{
  "id": "string",
  "create_time": "string",
  "expire_time": "string",
  "status": "open",
  "side": "lend",
  "currency": "string",
  "rate": "string",
  "amount": "string",
  "days": 0,
  "auto_renew": false,
  "currency_pair": "string",
  "left": "string",
  "repaid": "string",
  "paid_interest": "string",
  "unpaid_interest": "string",
  "fee_rate": "string",
  "orig_id": "string",
  "text": "string"
}

杠杆借入借出单

属性

名称	类型	必选	限制	描述
id	string	false	只读	贷款订单 ID
create_time	string	false	只读	创建时间
expire_time	string	false	只读	借入贷款的到期时间，借出订单此字段无效
status	string	false	只读	借贷订单状态 open - 未全部借出 loaned - 全部借出 / 已借入 finished - 借贷关系结束，如借贷全部归还或者被借出人取消 auto_repaid - 已由系统自动归还
side	string	true	none	lend - 借出，borrow - 借入
currency	string	true	none	贷款币种
rate	string	false	none	贷款利率，当前支持 0.0002 - 0.002 这个范围的利率。 借出时可不设置该字段，由系统根据该币种最近的市场利率来设置。
amount	string	true	none	贷款额度
days	integer	false	none	贷款天数，目前只支持设置为 10
auto_renew	boolean	false	none	贷款到期之后自动续借
currency_pair	string	false	none	贷款借入的交易对，借入时该字段为必选
left	string	false	只读	未借出的额度
repaid	string	false	只读	借出人已归还数额
paid_interest	string	false	只读	已归还的利息
unpaid_interest	string	false	只读	未归还的利息
fee_rate	string	false	none	该贷款的手续费率
orig_id	string	false	none	续借贷款的原始贷款 ID，如果不是续借贷款，该字段同 id
text	string	false	none	用户自定义 ID

枚举值列表

属性	值
status	open
status	loaned
status	finished
status	auto_repaid
side	lend
side	borrow

LoanRecord

{
  "id": "string",
  "loan_id": "string",
  "create_time": "string",
  "expire_time": "string",
  "status": "loaned",
  "borrow_user_id": "string",
  "currency": "string",
  "rate": "string",
  "amount": "string",
  "days": 0,
  "auto_renew": false,
  "repaid": "string",
  "paid_interest": "string",
  "unpaid_interest": "string"
}

杠杆借入借出记录

属性

名称	类型	必选	限制	描述
id	string	false	none	借出记录 ID
loan_id	string	false	none	对应的借贷订单 ID
create_time	string	false	none	借出时间
expire_time	string	false	none	到期时间
status	string	false	none	借出记录状态，loaned - 已借出, finished - 已归还
borrow_user_id	string	false	none	脱敏后的借入用户 ID
currency	string	false	none	贷款币种
rate	string	false	none	贷款利率
amount	string	false	none	借出数量
days	integer	false	none	贷款天数
auto_renew	boolean	false	none	本借出记录到期之后是否自动续借
repaid	string	false	none	借出人已归还数额
paid_interest	string	false	只读	已归还的利息
unpaid_interest	string	false	只读	未归还的利息

枚举值列表

属性	值
status	loaned
status	finished

SpotPriceTriggeredOrder

{
  "trigger": {
    "price": "string",
    "rule": ">=",
    "expiration": 0
  },
  "put": {
    "type": "limit",
    "side": "buy",
    "price": "string",
    "amount": "string",
    "account": "normal",
    "time_in_force": "gtc"
  },
  "id": 0,
  "user": 0,
  "market": "string",
  "ctime": 0,
  "ftime": 0,
  "fired_order_id": 0,
  "status": "string",
  "reason": "string"
}

现货价格单详情

属性

名称	类型	必选	限制	描述
trigger	object	true	none	none
» price	string	true	none	触发价格
» rule	string	true	none	价格条件类型 - >=: 表示市场价格大于等于 price时触发 - <=: 表示市场价格小于等于 price时触发
» expiration	integer	true	none	最长等待触发时间，超时则取消该订单，单位是秒 s
put	object	true	none	none
» type	string	false	none	订单类型,目前默认为限价单
» side	string	true	none	买卖方向 - buy: 买 - sell: 卖
» price	string	true	none	挂单价格
» amount	string	true	none	挂单数量
» account	string	true	none	交易账户类型，统一账户只能设置 cross_margin - normal: 现货交易 - margin: 杠杆交易 - cross_margin: 全仓杠杆交易
» time_in_force	string	false	none	time_in_force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单
id	integer(int64)	false	只读	自动订单 ID
user	integer	false	只读	用户 ID
market	string	true	none	市场
ctime	integer(int64)	false	只读	创建时间
ftime	integer(int64)	false	只读	结束时间
fired_order_id	integer(int64)	false	只读	触发后委托单ID
status	string	false	只读	状态 - open: 正在运行 - cancelled: 被取消 - finish: 成功结束 - failed: 失败 - expired - 过期
reason	string	false	只读	订单结束的附加描述信息

枚举值列表

属性	值
rule	>=
rule	<=
side	buy
side	sell
account	normal
account	margin
account	cross_margin
time_in_force	gtc
time_in_force	ioc

Contract

{
  "name": "string",
  "type": "inverse",
  "quanto_multiplier": "string",
  "leverage_min": "string",
  "leverage_max": "string",
  "maintenance_rate": "string",
  "mark_type": "internal",
  "mark_price": "string",
  "index_price": "string",
  "last_price": "string",
  "maker_fee_rate": "string",
  "taker_fee_rate": "string",
  "order_price_round": "string",
  "mark_price_round": "string",
  "funding_rate": "string",
  "funding_interval": 0,
  "funding_next_apply": 0,
  "risk_limit_base": "string",
  "risk_limit_step": "string",
  "risk_limit_max": "string",
  "order_size_min": 0,
  "order_size_max": 0,
  "order_price_deviate": "string",
  "ref_discount_rate": "string",
  "ref_rebate_rate": "string",
  "orderbook_id": 0,
  "trade_id": 0,
  "trade_size": 0,
  "position_size": 0,
  "config_change_time": 0,
  "in_delisting": true,
  "orders_limit": 0
}

*合约详情。

每张合约 USD 价值的计算方法：

• USDT 结算的合约： quanto_multiplier x 币种价格
• BTC 结算的合约：quanto_multiplier x BTC价格 x 币种价格

属性

名称	类型	必选	限制	描述
name	string	false	none	合约标识
type	string	false	none	合约类型, inverse - 反向合约, direct - 正向合约
quanto_multiplier	string	false	none	计价货币兑换为结算货币的乘数
leverage_min	string	false	none	最小杠杆
leverage_max	string	false	none	最大杠杆
maintenance_rate	string	false	none	维持保证金比例
mark_type	string	false	none	价格标记方式, internal - 内盘成交价格, index - 外部指数价格
mark_price	string	false	none	当前标记价格
index_price	string	false	none	当前指数价格
last_price	string	false	none	上一次成交价格
maker_fee_rate	string	false	none	挂单成交的手续费率，负数代表返还后续费
taker_fee_rate	string	false	none	吃单成交的手续费率
order_price_round	string	false	none	委托价格最小单位
mark_price_round	string	false	none	标记、强平等价格最小单位
funding_rate	string	false	none	当前资金费率
funding_interval	integer	false	none	资金费率应用间隔，以秒为单位
funding_next_apply	number(double)	false	none	下次资金费率应用时间
risk_limit_base	string	false	none	基础风险限额
risk_limit_step	string	false	none	风险限额调整步长
risk_limit_max	string	false	none	合约允许的最大风险限额
order_size_min	integer(int64)	false	none	最小下单数量
order_size_max	integer(int64)	false	none	最大下单数量
order_price_deviate	string	false	none	下单价与当前标记价格允许的正负偏移量， 即下单价 order_price 需满足如下条件: abs(order_price - mark_price) <= mark_price * order_price_deviate
ref_discount_rate	string	false	none	被推荐人享受交易费率折扣
ref_rebate_rate	string	false	none	推荐人享受交易费率返佣比例
orderbook_id	integer(int64)	false	none	orderbook更新ID
trade_id	integer(int64)	false	none	当前成交ID
trade_size	integer(int64)	false	none	历史累计成交
position_size	integer(int64)	false	none	当前做多用户持有仓位总和
config_change_time	number(double)	false	none	配置最后更新时间
in_delisting	boolean	false	none	合约下线中
orders_limit	integer	false	none	最多挂单数量

枚举值列表

属性	值
type	inverse
type	direct
mark_type	internal
mark_type	index

Position

{
  "user": 0,
  "contract": "string",
  "size": 0,
  "leverage": "string",
  "risk_limit": "string",
  "leverage_max": "string",
  "maintenance_rate": "string",
  "value": "string",
  "margin": "string",
  "entry_price": "string",
  "liq_price": "string",
  "mark_price": "string",
  "initial_margin": "string",
  "maintenance_margin": "string",
  "unrealised_pnl": "string",
  "realised_pnl": "string",
  "history_pnl": "string",
  "last_close_pnl": "string",
  "realised_point": "string",
  "history_point": "string",
  "adl_ranking": 0,
  "pending_orders": 0,
  "close_order": {
    "id": 0,
    "price": "string",
    "is_liq": true
  },
  "mode": "single",
  "cross_leverage_limit": "string"
}

合约仓位详情

属性

名称	类型	必选	限制	描述
user	integer(int64)	false	只读	用户ID
contract	string	false	只读	合约标识
size	integer(int64)	false	只读	头寸大小
leverage	string	false	none	杠杆倍数，0代表全仓，正数代表逐仓
risk_limit	string	false	none	风险限额
leverage_max	string	false	只读	当前风险限额下，允许的最大杠杆倍数
maintenance_rate	string	false	只读	当前风险限额下，维持保证金比例
value	string	false	只读	按结算币种标记价格计算的合约价值
margin	string	false	none	保证金
entry_price	string	false	只读	开仓价格
liq_price	string	false	只读	爆仓价格
mark_price	string	false	只读	合约当前标记价格
initial_margin	string	false	只读	仓位占用的起始保证金，适用于统一账户
maintenance_margin	string	false	只读	仓位所需的维持保证金，适用于统一账户
unrealised_pnl	string	false	只读	未实现盈亏
realised_pnl	string	false	只读	已实现盈亏
history_pnl	string	false	只读	已平仓的仓位总盈亏
last_close_pnl	string	false	只读	最近一次平仓的盈亏
realised_point	string	false	只读	点卡已实现盈亏
history_point	string	false	只读	已平仓的点卡总盈亏
adl_ranking	integer	false	只读	自动减仓排名，共1-5个等级
pending_orders	integer	false	只读	当前未完成委托数量
close_order	object|null	false	只读	当前平仓委托信息，如果没有平仓则为null
» id	integer(int64)	false	none	委托ID
» price	string	false	none	委托价格
» is_liq	boolean	false	none	是否为强制平仓
mode	string	false	none	持仓模式。包括： - single: 单向持仓模式 - dual_long: 双向持仓模式下的做多仓位 - dual_short: 双向持仓模式下的做空仓位
cross_leverage_limit	string	false	none	全仓模式下的杠杆倍数（即 leverage 为 0 时）

枚举值列表

属性	值
mode	single
mode	dual_long
mode	dual_short

FuturesOrder

{
  "id": 0,
  "user": 0,
  "create_time": 0,
  "finish_time": 0,
  "finish_as": "filled",
  "status": "open",
  "contract": "string",
  "size": 0,
  "iceberg": 0,
  "price": "string",
  "close": false,
  "is_close": true,
  "reduce_only": false,
  "is_reduce_only": true,
  "is_liq": true,
  "tif": "gtc",
  "left": 0,
  "fill_price": "string",
  "text": "string",
  "tkfr": "string",
  "mkfr": "string",
  "refu": 0,
  "auto_size": "close_long"
}

合约订单详情

属性

名称	类型	必选	限制	描述
id	integer(int64)	false	只读	合约订单 ID
user	integer	false	只读	用户 ID
create_time	number(double)	false	只读	订单创建时间
finish_time	number(double)	false	只读	订单结束时间，未结束订单无此字段返回
finish_as	string	false	只读	结束方式，包括： - filled: 完全成交 - cancelled: 用户撤销 - liquidated: 强制平仓撤销 - ioc: 未立即完全成交，因为tif设置为ioc - auto_deleveraged: 自动减仓撤销 - reduce_only: 增持仓位撤销，因为设置reduce_only或平仓 - position_closed: 因为仓位平掉了，所以挂单被撤掉 - reduce_out: 只减仓被排除的不容易成交的挂单
status	string	false	只读	订单状态。 - open: 等待处理 - finished: 已结束的订单
contract	string	true	none	合约标识
size	integer(int64)	true	none	必选。交易数量，正数为买入，负数为卖出。平仓委托则设置为0。
iceberg	integer(int64)	false	none	冰山委托显示数量。0为完全不隐藏。注意，隐藏部分成交按照taker收取手续费。
price	string	false	none	委托价。价格为0并且tif为ioc，代表市价委托。
close	boolean	false	只写	设置为 true 的时候执行平仓操作，并且size应设置为0
is_close	boolean	false	只读	是否为平仓委托。对应请求中的close。
reduce_only	boolean	false	只写	设置为 true 的时候，为只减仓委托
is_reduce_only	boolean	false	只读	是否为只减仓委托。对应请求中的reduce_only。
is_liq	boolean	false	只读	是否为强制平仓委托
tif	string	false	none	Time in force 策略，市价单当前只支持 ioc 模式 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单 - poc: PendingOrCancelled，被动委托，只挂单不吃单 - fok: FillOrKill, 完全成交，或者完全取消
left	integer(int64)	false	只读	未成交数量
fill_price	string	false	只读	成交价
text	string	false	none	订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件： 1. 必须以 t- 开头 2. 不计算 t- ，长度不能超过 28 字节 3. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.) 除用户自定义信息以外，以下为内部保留字段，标识订单来源: - web: 网页 - api: API 调用 - app: 移动端 - auto_deleveraging: 自动减仓 - liquidation: 强制平仓 - insurance: 保险
tkfr	string	false	只读	吃单费率
mkfr	string	false	只读	做单费率
refu	integer	false	只读	推荐人用户 ID
auto_size	string	false	只写	双仓模式下用于设置平仓的方向，close_long 平多头， close_short 平空头，需要同时设置 size 为 0

枚举值列表

属性	值
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok
auto_size	close_long
auto_size	close_short

FuturesPriceTriggeredOrder

{
  "initial": {
    "contract": "string",
    "size": 0,
    "price": "string",
    "close": false,
    "tif": "gtc",
    "text": "string",
    "reduce_only": false,
    "auto_size": "string",
    "is_reduce_only": true,
    "is_close": true
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "string",
    "rule": 1,
    "expiration": 0
  },
  "id": 0,
  "user": 0,
  "create_time": 0,
  "finish_time": 0,
  "trade_id": 0,
  "status": "open",
  "finish_as": "cancelled",
  "reason": "string",
  "order_type": "string",
  "me_order_id": "string"
}

合约价格单详情

属性

名称	类型	必选	限制	描述
initial	object	true	none	none
» contract	string	true	none	合约标识
» size	integer(int64)	false	none	交易数量，正数为买入，负数为卖出，平仓操作必须为0
» price	string	true	none	交易价，当价格为 0 时，表示通过市价方式来下单
» close	boolean	false	只写	设置为 true 的时候执行平仓操作
» tif	string	false	none	Time in force 策略，市价单当前只支持 ioc 模式 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled
» text	string	false	none	订单的来源，包括： - web: 网页 - api: API 调用 - app: 移动端
» reduce_only	boolean	false	none	设置为 true 的时候执行自动减仓操作
» auto_size	string	false	只写	双仓模式下用于设置平仓的方向，close_long 平多头， close_short 平空头，需要同时设置 size 为 0
» is_reduce_only	boolean	false	只读	是否为只减仓委托。对应请求中的reduce_only。
» is_close	boolean	false	只读	是否为平仓委托。对应请求中的close。
trigger	object	true	none	none
» strategy_type	integer	false	none	触发策略 - 0: 价格触发，即当价格满足条件时触发 - 1: 价差触发，即指定 price_type 的最近一次价格减去倒数第二个价格的差值 目前暂时只支持0价格触发
» price_type	integer(int32)	false	none	参考价格类型。 0 - 最新成交价，1 - 标记价格，2 - 指数价格
» price	string	false	none	价格触发时为价格，价差触发时为价差
» rule	integer(int32)	false	none	价格条件类型 - 1: 表示根据 strategy_type 和 price_type 算出的价格大于等于 price - 2: 表示根据 strategy_type 和 price_type 算出的价格小于等于 price
» expiration	integer	false	none	最长等待触发时间，超时则取消该订单，单位是秒 s
id	integer(int64)	false	只读	自动订单 ID
user	integer	false	只读	用户 ID
create_time	number(double)	false	只读	创建时间
finish_time	number(double)	false	只读	结束时间
trade_id	integer(int64)	false	只读	触发后委托单ID
status	string	false	只读	订单状态 - open: 活跃中 - finished: 已结束 - inactive: 未生效，只针对委托单止盈止损 - invalid: 无效，只针对委托单止盈止损
finish_as	string	false	只读	结束状态，cancelled - 被取消；succeeded - 成功；failed - 失败；expired - 过期
reason	string	false	只读	订单结束的附加描述信息
order_type	string	false	none	止盈止损的类型，包括： - close-long-order: 委托单止盈止损，平做多仓 - close-short-order: 委托单止盈止损，平做空仓 - close-long-position: 仓位止盈止损，平多仓 - close-short-position: 仓位止盈止损，平空仓 - plan-close-long-position: 仓位计划止盈止损，平多仓 - plan-close-short-position: 仓位计划止盈止损，平空仓 其中委托单止盈止损的两种类型只读，不能通过请求传入
me_order_id	string	false	只读	委托单止盈止损对应的委托 ID

枚举值列表

属性	值
tif	gtc
tif	ioc
strategy_type	0
strategy_type	1
price_type	0
price_type	1
price_type	2
rule	1
rule	2
status	open
status	finished
status	inactive
status	invalid
finish_as	cancelled
finish_as	succeeded
finish_as	failed
finish_as	expired

DeliveryContract

{
  "name": "string",
  "underlying": "string",
  "cycle": "WEEKLY",
  "type": "inverse",
  "quanto_multiplier": "string",
  "leverage_min": "string",
  "leverage_max": "string",
  "maintenance_rate": "string",
  "mark_type": "internal",
  "mark_price": "string",
  "index_price": "string",
  "last_price": "string",
  "maker_fee_rate": "string",
  "taker_fee_rate": "string",
  "order_price_round": "string",
  "mark_price_round": "string",
  "basis_rate": "string",
  "basis_value": "string",
  "basis_impact_value": "string",
  "settle_price": "string",
  "settle_price_interval": 0,
  "settle_price_duration": 0,
  "expire_time": 0,
  "risk_limit_base": "string",
  "risk_limit_step": "string",
  "risk_limit_max": "string",
  "order_size_min": 0,
  "order_size_max": 0,
  "order_price_deviate": "string",
  "ref_discount_rate": "string",
  "ref_rebate_rate": "string",
  "orderbook_id": 0,
  "trade_id": 0,
  "trade_size": 0,
  "position_size": 0,
  "config_change_time": 0,
  "in_delisting": true,
  "orders_limit": 0
}

合约详情

属性

名称	类型	必选	限制	描述
name	string	false	none	合约标识
underlying	string	false	none	标的物
cycle	string	false	none	周期类型, 季度合约, 周合约等
type	string	false	none	合约类型, inverse - 反向合约, direct - 正向合约
quanto_multiplier	string	false	none	计价货币兑换为结算货币的乘数
leverage_min	string	false	none	最小杠杆
leverage_max	string	false	none	最大杠杆
maintenance_rate	string	false	none	维持保证金比例
mark_type	string	false	none	价格标记方式, internal - 内盘成交价格, index - 外部指数价格
mark_price	string	false	none	当前标记价格
index_price	string	false	none	当前指数价格
last_price	string	false	none	上一次成交价格
maker_fee_rate	string	false	none	挂单成交的手续费率，负数代表返还后续费
taker_fee_rate	string	false	none	吃单成交的手续费率
order_price_round	string	false	none	委托价格最小单位
mark_price_round	string	false	none	标记、强平等价格最小单位
basis_rate	string	false	none	当前合理基差率
basis_value	string	false	none	当前合理基差值
basis_impact_value	string	false	none	计算合理基差率时加权深度影响额
settle_price	string	false	none	预计结算价格
settle_price_interval	integer	false	none	结算价格更新间隔
settle_price_duration	integer	false	none	加权平均计算结算价格时长, 单位秒
expire_time	integer(int64)	false	none	合约到期时间戳
risk_limit_base	string	false	none	基础风险限额
risk_limit_step	string	false	none	风险限额调整步长
risk_limit_max	string	false	none	合约允许的最大风险限额
order_size_min	integer(int64)	false	none	最小下单数量
order_size_max	integer(int64)	false	none	最大下单数量
order_price_deviate	string	false	none	下单价与当前标记价格允许的正负偏移量， 即下单价 order_price 需满足如下条件: abs(order_price - mark_price) <= mark_price * order_price_deviate
ref_discount_rate	string	false	none	被推荐人享受交易费率折扣
ref_rebate_rate	string	false	none	推荐人享受交易费率返佣比例
orderbook_id	integer(int64)	false	none	orderbook更新ID
trade_id	integer(int64)	false	none	当前成交ID
trade_size	integer(int64)	false	none	历史累计成交
position_size	integer(int64)	false	none	当前做多用户持有仓位总和
config_change_time	number(double)	false	none	配置最后更新时间
in_delisting	boolean	false	none	合约下线中
orders_limit	integer	false	none	最多挂单数量

枚举值列表

属性	值
cycle	WEEKLY
cycle	BI-WEEKLY
cycle	QUARTERLY
cycle	BI-QUARTERLY
type	inverse
type	direct
mark_type	internal
mark_type	index