现货&杠杆
公告

# Gate API v4 v4.59.0

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

欢迎使用 Gate.hk 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:

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

# 关于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 在使用上有如下区别：

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

如何选择：

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

# 市商申请

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

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

提供以上内容提交至 [email protected] ，我们将在3个工作日内受理。

TIP

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

# 技术支持

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

提交工单反馈
在线工单反馈
将您的联系方式与问题发送至 [email protected] ，我们将为您分配技术专员为您服务

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

问题描述
Gateio UID
请求的地址与参数
错误代码
返回结果

DANGER

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

# Changelog

v4.59.0

2023-11-22

GET /futures/{settle}/contracts 接口，返回值增加 funding_cap_ratio 字段
GET /delivery/{settle}/account_book 接口，返回值增加 contract 字段
GET /wallet/withdraw_status 接口，返回值增加 withdraw_percent_on_chains 字段
GET /portfolio/accounts 接口，返回值增加 leverage 字段

v4.58.0

2023-11-03

GET /margin/cross/currencies 接口，返回值增加 loanable 字段
GET /futures/{settle}/orders/{order_id} 接口, 返回值新增 biz_info 字段
GET /account/detail 接口, 返回值新增 tier 字段
GET /spot/currency_pairs 接口, 返回值新增 max_base_amount、max_quote_amount 字段

v4.57.0

2023-10-20

新增进出网关时间记录，详情参考网关入出站时间
POST /spot/orders 接口，新增支持保证金帐户类型
GET /spot/trades 接口，返回值新增 sequence_id 字段
GET /spot/account_book 接口，返回值新增 text 字段
GET /spot/my_trades 接口，返回值新增 text 字段
新增 POST /spot/amend_batch_orders 接口，用户可以批量修改订单
新增 PUT /earn/uni/interest_reinvest 接口，用户可以设置利息复投开关
GET /portfolio/spot/orders、 GET /portfolio/spot/orders、GET /portfolio/spot/orders/{order_id}、DELETE /portfolio/spot/orders/{order_id} and PATCH /portfolio/spot/orders/{order_id} 这些接口将被弃用, 我们预计在十月底移除这些接口的支持, 用户可以转用 /spot/orders 相关接口来替代

v4.56.0

2023-09-25

GET /margin/cross/repayments 和 GET /portfolio/loan_records 接口，新增 repayment_type 字段
GET /futures/{settle}/positions 接口, 请求参数新增 holding 字段
GET /futures/{settle}/my_trades_timerange 接口, 请求参数新增 role 字段
GET /futures/{settle}/position_close 接口, 请求参数新增 side and pnl 字段

v4.55.0

2023-09-12

新增 POST /portfolio/account_mode 接口，新增模式切换

v4.54.0

2023-08-28

GET /wallet/currency_chains 接口，新增 contract_address 字段
GET /portfolio/spot/currency_pairs 与 GET /portfolio/spot/currency_pairs/{currency_pair}，新增查询保证金现货市场列表

v4.53.0

2023-08-14

DELETE /account/stp_groups/{stp_id}/users，新增删除 STP Group 用户接口

v4.52.0

2023-08-07

新增抵押借币相关 API

v4.51.0

2023-07-29

调整优化资产流水类型
GET /account/detail 接口，新增 mode 字段

v4.50.0

2023-07-14

新增保证金账户体系相关的API，目前服务只对白名单用户开放，有兴趣的用户可以聯繫機構部門
新增 GET /flash_swap/currency_pairs 接口，查询支持闪兑的所有交易对列表

v4.49.0

2023-07-03

新增新版限频规则，新版预计于 2023-07-10 (utc+8) 开始生效
GET /futures/{settle}/orders接口，调整请求字段 contract 改为非必填

v4.48.0

2023-06-16

GET /wallet/sub_account_transfers接口，新增 client_order_id 请求字段

v4.47.0

2023-05-23

GET /margin/uni/estimate_rate 和 GET /margin/cross/estimate_rate，新增全仓和逐仓借贷利率查询接口
GET /futures/{settle}/orders_timerange，新增查询合约历史订单列表(时间区间)接口
GET /options/positions/{contract}接口，新增 underlying、underlying_price、mark_iv、delta、gamma、vega、theta 等字段
新增 STP Group 管理 API 接口

v4.46.0

2023-05-08

GET /spot/account_book，新增查询现货账户变动历史接口
GET /futures/{settle}/fee，新增查询合约市场交易费率接口
GET /futures/{settle}/trades接口，新增 is_internal 字段

v4.45.0

2023-04-21

逐仓借贷迁移到余币宝，详细资讯可参考逐仓迁移说明
GET /margin/cross/interest_records 接口，新增全仓账户扣息记录
GET /margin/cross/account_book 接口，新增 futures_in、futures_out 两种帐户变更类型
POST /futures/{settle}/batch_orders 接口，新增 STP 功能

v4.44.0

2023-04-07

新增 ORDER_BOOK_NOT_FOUND、FAILED_RETRIEVE_ASSETS 错误信息

v4.43.0

2023-03-27

现货下单接口，新增 Self-Trade Prevention 功能，详细资讯可参考STP介绍
GET /account/detail，新增查询 API Key 的 IP 白名单接口
PATCH /spot/orders/{order_id} 接口，新增 amend_text 字段
GET /futures/{settle}/tickers 接口，新增 lowest_ask 和 highest_bid 字段

v4.42.0

2023-03-13

新增余币宝接口
合约下单接口，新增 Self-Trade Prevention 功能，详细资讯可参考STP介绍
POST /wallet/sub_account_transfers 接口，新增 交割合约账户 类型支持
PUT /futures/{settle}/orders/{order_id} 接口，新增 amend_text 字段

v4.41.0

2023-03-03

GET /margin/cross/accounts 接口，新增 negative_liab, futures_pos_liab, equity, total_freeze, total_liab, portfolio_margin_total_liab, portfolio_margin_total_equity 字段

v4.40.0

2023-02-24

GET /futures/{settle}/candlesticks 接口，新增 sum 字段
GET /futures/{settle}/auto_deleverages 接口，新增查询ADL自动减仓订单信息

v4.39.0

2023-02-09

GET /spot/batch_fee 接口，新增批量查询账户费率接口
GET /futures/{settle}/contracts 接口，新增 enable_bonus、enable_credit 字段

v4.38.0

2023-02-04

GET /futures/{settle}/my_trades_timerange 接口，新增时间范围查询合約成交记录接口
POST /withdrawals 接口，新增 withdraw_order_id 字段

v4.37.0

2023-01-20

新增查询反佣相关接口

v4.36.0

2022-12-23

POST /spot/orders 和 POST /spot/batch_orders 接口，下单的时候 iceberg 字段不再支持全部订单隐藏

v4.35.0

2022-12-09

GET /spot/orders 接口, 新增订单平均价格字段
PATCH /spot/orders/{order_id} 接口, 新增订单修改单
GET /margin/cross/accounts 接口, 新增 portfolio_margin_total 字段
POST /spot/batch_orders 接口, 新增现货市价单类型

v4.34.0

2022-11-25

POST /spot/orders 接口, 现货下单增加市价单

v4.33.0

2022-11-11

K 线图接口 GET /futures/{settle}/premium_index
创建子帐号的时候可以指定密码与 Eamil

v4.32.0

2022-10-28

优化期权API文档

v4.31.0

2022-10-14

POST /wallet/sub_account_to_sub_account 子帐号划转接口，新增合约与全仓杠杆划转

v4.30.0

2022-09-23

新增管理子帐号 API Key 接口
新增子帐号冻结与解冻接口
POST /wallet/sub_account_to_sub_account 接口，新增子帐号与子帐号划转

v4.29.0

2022-09-09

新增创建、查询子帐号功能
GET /wallet/fee 接口，新增 settle 查询字段
期权订单新增 refr 字段
创建 API Key 数量上限调整至 20

v4.28.0

2022-08-12

GET /futures/{settle}/trades 接口，新增 offset 查询字段
新增现货与合约的定时取消订单接口

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

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

v4.23.2

2022-01-21

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

v4.23.1

2021-12-23

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

v4.23.0

2021-12-09

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

v4.22.4

2021-11-01

SpotPriceTriggeredOrder 字段 ctime 和 ftime 更正为 int64

v4.22.3

2021-10-27

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

v4.22.2

2021-09-29

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

v4.22.1

2021-09-07

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

v4.22.0

2021-08-13

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

v4.21.6

2021-08-12

修复 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.hk 订单匹配遵循价格优先 > 时间优先的原则

假设订单簿情况如下：

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

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

# 订单生命周期

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

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

# 数据中心

Gate.hk 数据中心位于 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/*`	提现	数字货币提现

# 逐仓迁移说明

平台于 2023 年 4 月 13 日 14:00（UTC+8）到 2023 年 4 月 23 日 14:00（UTC+8）期间陆续对币币理财市场中未被借贷的资产进行系统自动迁移，迁移至余币宝市场，同时也会对已经被借贷出去的资产进行取消自动放贷处理，迁移完成后您可到余币宝市场中，查看您的理财详情。在此期间将暂停通过币币理财借出资金，您也可以手动将资产从币币理财转到余币宝市场，提前获得理财收益。
自动迁移后老版本的借贷接口将被弃用，新版借贷使用/margin/uni接口组，详细的接口迁移可以参考下表

逐仓杠杆账户相关接口:

接口名称	路径	接口是否下线	新路径
杠杆账户列表	GET /margin/accounts	否	`-`
查询杠杆账户变动历史	GET /margin/account_book	否	`-`
理财账户列表	GET /margin/funding_accounts	否	`-`
修改用户自动还款设置	POST /margin/auto_repay	否	`-`
查询用户自动还款设置	GET /margin/auto_repay	否	`-`
逐仓杠杆允许的最大转出	GET /margin/transferable	否	`-`

逐仓杠杆借贷相关接口（迁移至/margin/uni接口组）:

接口名称	路径	接口是否下线	新路径
查询支持杠杆交易的所有交易对	GET /margin/currency_pairs	是	GET /margin/uni/currency_pairs
查询单个杠杆交易对	GET /margin/currency_pairs/{currency_pair}	是	GET /margin/uni/currency_pairs/{currency_pair}
借入或借出	POST /margin/loans	是	POST /margin/uni/loans
查询借贷订单详情	GET /margin/loans/{loan_id}	是	`-`
查询借贷订单列表	GET /margin/loans	是	GET /margin/uni/loans
归还借贷	POST /margin/loans/{loan_id}/repayment	是	POST /margin/uni/loans
查询借贷归还记录	GET /margin/loans/{loan_id}/repayment	是	GET /margin/uni/loan_records
逐仓杠杆用户最多可借入	GET /margin/borrowable	是	GET /margin/uni/borrowable
查询扣息记录	`-`	`-`	GET /margin/uni/interest_records

理财相关接口(迁移至/earn/uni接口组）:

接口名称	路径	接口是否下线	新路径
查询支持杠杆交易的所有交易对	GET /margin/currency_pairs	是	GET /earn/uni/currencies
查询单个杠杆交易对	GET /margin/currency_pairs/{currency_pair}	是	GET /earn/uni/currencies/{currency}
借入或借出	POST /margin/loans	是	POST /earn/uni/lends
查询借贷订单列表	GET /margin/loans	是	GET /earn/uni/lends
借出市场的深度	GET /margin/funding_book	是	-
合并多个借贷订单	POST /margin/merged_loans	是	-
修改借贷订单	PATCH /margin/loans/{loan_id}	是	PATCH /earn/uni/lends
撤销借出贷款订单	DELETE /margin/loans/{loan_id}	是	POST /earn/uni/lends
查看某个借贷订单的借出记录	GET /margin/loan_records	是	GET /earn/uni/lend_records
查看单个借出记录	GET /margin/loan_records/{loan_record_id}	是	`-`
修改单个借出记录	PATCH /margin/loan_records/{loan_record_id}	是	`-`
查询用户派息记录	`-`	`-`	GET /earn/uni/interest_records

# 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 会对不同格式的时间字段按照相应格式做好反序列化处理。

# 网关入出站时间

每次请求API响应头(response header)中都会包含如下字段：

X-In-Time: API网关接收请求时的时间戳，格式:Unix的时间戳,单位微秒。
X-Out-Time: API网关返回响应时的时间戳，格式:Unix的时间戳,单位微秒

例如：

X-In-Time: 1695715091540163
X-Out-Time: 1695715091551905

# 分页

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

page, limit 方式
limit, offset 方式

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

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

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

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

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

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

limit=100&offset=0
limit=100&offset=100
limit=100&offset=200

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

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

# 限频规则

市场	入口	限速	依据	包含
公共接口	公共接口	单个接口 200r/10s	IP	深度、K线、交易对信息等
钱包	私有接口	提现接口(POST /withdrawals) 1r/1s 交易账户互转接口 (POST /wallet/transfers) 80r/10s 主子账号互转 (POST /wallet/sub_account_transfers) 80r/10s 子账号与子帐号互转 (POST /wallet/sub_account_to_sub_account) 80r/10s 查询个人账户总额 (GET /wallet/total_balance) 80r/10s 查询子账号余额信息 (GET /wallet/sub_account_balances) 80r/10s 查询子账号逐仓杠杆账户余额信息 (GET /wallet/sub_account_margin_balances) 80r/10s 查询子账号永续合约账户余额信息 (GET /wallet/sub_account_futures_balances) 80r/10s 查询子账号全仓杠杆账户余额信息 (GET /wallet/sub_account_cross_margin_balances) 80r/10s 钱包其他单个接口 200r/10s	UID	提现个人账户余额查询子账户余额查询
现货	私有接口	现货批量/单个下单/单个修改接口一共 500r/10s(uid), 订单数10单/s (uid+市场) 现货批量/单个撤单接口一共 750r/10s 现货其他单个接口 200r/10s	UID	现货下单、撤单成交历史、费率查询等
永续合约	私有接口	合约批量/单个下单接口一共 500r/10s 合约批量/单个撤单接口一共 750r/10s 永续合约其他单个接口 200r/10s	UID	合约下单、撤单成交历史、费率查询等
子账户	私有接口	单个子账户相关接口 80r/10s	UID	创建普通子账户查询子账户列表禁用、启用子账户APIKEY
保证金	私有接口	借入或还款 15/10s	UID	借入或还款(POST /portfolio/loans)
其他私有接口	私有接口	单个接口 150r/10s	UID	理财、期权、交割合约等

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

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.hk新⼀代的交易系统，主要功能在于打破经典账户 (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 做跟踪。

# Self-Trade Prevention(STP)

# 名词解释

Self-Trade Prevention: 自成交保护机制，后文中都简称为STP

CN: Cancel new,取消新订单，保留老订单

CO: Cancel old,取消⽼订单，保留新订单

CB: Cancel both,新旧订单都取消

# 成交策略

目前支持三种自成交保护策略，分别是CN、CO、CB。

我们实现了STP用户组来提供给用户，被添加到同一个组内的多个用户账户ID，自成交或彼此成交会受到限制，限制策略取决于用户账户以taker 角色下单时指定的stp_act参数。

当用户的账户ID添加到指定STP用户组后，下单时可以自定义stp_act参数，系统会按照用户传入的策略进行STP用户组 内撮合成交的限制；如果下单时没有指定stp_act策略，成交时默认按照CN策略执行。

当下单用户的账户ID没有进入任何STP用户组，同时下单又指定了stp_act参数，此时系统会报错，无法下单。用户需要去掉stp_act 参数，此时用户成交不受任何自成交策略限制。

# 接口参数调整

以合约下单为例，有如下调整：

POST /futures/{settle}/orders

新增请求参数

名称	位置	类型	必选	描述
stp_act	body	string	否	stp策略，包括： - cn 取消新订单，保留旧订单 - co 取消老订单，保留新订单 - cb 取消老订单和新订单

新增返回参数（查询订单列表接口同理）

名称	类型	必选	限制	描述
stp_act	string	否	none	STP策略，包括： - `cn` 取消新订单，保留旧订单 - `co` 取消老订单，保留新订单 - `cb` 取消老订单和新订单
stp_id	integer(int64)	否	只读	用户所在`STP用户组`的id，是引擎判断用户之间订单是否可以成交的依据。如果账户没有进入`STP用户组`，`stp_id`不返回。
finish_as	string	否	只读	结束方式： - stp: 订单发生自成交限制而被撤销

# 使用场景

组织A下有多个账户，其中几个账户id分别为101,102,103。

为了防止组织内部账户下单发生自成交，管理员创建了一个STP用户组，用户组id为100，将账户101和102加入到该STP用户组 中，此时组内成员为[101,102]

T1: STP策略版本上线。

T2: 组织A账户101下做空单后，市场订单深度没有与之匹配的订单可以撮合成交，此时下单角色是maker，订单状态是open 。返回参数会增加如下信息返回

{
	"status":"open",
	"stp_act":"cn",
	"stp_id":100
}

T3: 组织A账户101/102下做多单后，市场深度匹配到101账户下的做空订单可以撮合成交，当前角色是taker ，系统判断到两个订单的stp_id均为100，此时会限制成交，限制策略以taker为准。

如果选择了cn，taker下的订单会被取消，订单会结束，返回关键参数为：

{
	"status":"finished",
	"stp_act":"cn",
	"stp_id":100,
	"finish_as":"stp"
}

如果选择了co，taker下的订单会被保留，订单状态为open，系统默认会取消maker的订单（maker可以通过查询订单列表，订单状态会跟上一种情况一致。）
如果选择了cb，taker下的订单会被取消，订单会结束。系统默认会取消maker的订单（maker 可以通过查询订单列表）。两者的订单结束原因都为stp

{
	"status":"finished",
	"stp_act":"cb",
	"stp_id":100,
	"finish_as":"stp"
}

T3': 组织A账户103下做多单后，市场深度匹配到101账户下的做空订单可以撮合成交，由于103用户没有被添加到组里，stp_id 为0，系统判断两边的stp_id不一致，可以成交。订单信息为：

{
	"status":"finished",
	"stp_id":0,
	"finish_as":"filled"
}

# 保证金账户体系

# 说明

用户升级保证金账户后，可以使用现货账户中的资产作为交易的保证金，账户内的各币种资产将会根据其流动性，定义相应的调整系数，再统一折算为USD，来统一计算账户的资产及持仓价值。

保证金交易最大可借贷额度是用户对于当前交易市场的最大借贷额度。平台将根据用户的可用保证金数量以及平台风控规则等限制，计算用户当前的最大借贷额度。保证金交易产生自动借款后，平台即时对所借数字资产开始计息。

目前支持升级全仓保证金账户，后续陆续支持永续合约、交割合约、期权等多种组合保证金，敬请期待。

相关的接口请查看文档保证金接口，升级保证金账户后可进行调用。

# 保证金公式

名称	全仓保证金
账户权益	账户权益= ∑(币种权益 x 币种指数价格）
总保证金余额	总保证金余额 = ∑(正币种权益 x 币种指数价格 x 币种保证金系数) + ∑(负币种权益 x 币种指数价格)-挂单损失
总起始保证金率	总起始保证金率=总保证金余额/总起始保证金
总维持保证金率	总维持保证金率=总保证金余额/总维持保证金
总起始保证金	总起始保证金=负债*现货起始保证金率
总维持保证金	总维持保证金=负债*现货维持保证金率
币种权益	币种权益=币种余额-现货已借
可用余额	可用余额=本金+已借
占用	占用=现货挂单占用

# 资产流水类型

# 通用

unknown : 未知
login : 登陆
withdraw : 提现
ch_pass : 修改密码
ch_fund_pass : 修改资金密码
login_failed : 登录失败
axs_account : 访问账号
req_pass_ch : 修改密码请求
req_fund_pass_ch : 修改资金密码请求
fund_pass_ent : 输入交易密码
bank_card_add : 绑定银行卡
frw : 提现人脸验证

# 订单

new_order : 下单
cancel_order : 取消订单
order_fill : 成交
order_rej : 订单退回
order_fee : 成交手续费
system_fee : 系统成交手续费

# 充提

withdraw : 提现
deposit : 充值
deposit_rej : 充值退回
withdraw_rej : 提现退回
cancel_withdraw : 取消提现
withdraw_gatecode : 充值码提现
withdraw_fireblock : Fireblock提现
withdraw_copper : Copper提现
startup_withdraw : Startup项目提现
deposit_gatecode : 充值码充值
deposit_fireblock : Fireblock充值
deposit_copper : Copper充值
buy_cl : 法币入金 Legend
buy_cc : 法币入金 Cabital
deposit_finmo : Finmo充值

# Startup

startup_prtcp : 参加Startup
startup_refund : 退回Startup
startup_sale : Startup认购
startup_sale_rb : Startup认购退回

# 返佣

referral_rebate : 推荐奖励
sec_rebate_out : 二级返佣系统账户转出
sec_rebate_in : 用户获得二级返佣
ab_rebate : API Broker返佣上级收入
eb_rebate : Exchange Broker返佣上级收入
u_rebate : 普通邀请返佣用户收入
ads_rebate : 代理商直接上级返佣收入
au_rebate : 代理商返佣用户收入
pis_rebate : 合伙人间接上级返佣收入
pds_rebate : 合伙人直接上级返佣收入
pu_rebate : 合伙人用户返佣收入

# 兑换

eth_swap : ETH分叉兑换
dust_swap_dctd : 小额资产兑换
dust_swap_gt_add : 小额资产GT增加
dust_swap_fee : 小额币种手续费扣除
cv_buy : 闪兑买入
cv_sell : 闪兑卖出

# C2C

c2c_mop : C2C商家下单
c2c_moc : C2C取消商家单
c2c_rop : C2C用户下单
c2c_roc : C2C取消用户单
c2c_om : C2C成交
c2c_or : C2C退回
c2c_fee : C2C手续费

# 奖励

deposit_bonus : 充值奖励
trading_rewards : 交易奖励
purchase_bonus : 买入奖励
airdrop : 空投奖励
award : 限时奖励
mining_rewards : 挖矿奖励

# 账户出入金

margin_in : 逐仓杠杆转入
margin_out : 逐仓杠杆转出
spot_settle_out: 现货同币种结算转出
spot_settle_in: 现货同币种结算转入
lending_in : 理财转入
lending_out : 理财转出
cross_in : 统一账户转入
cross_out : 统一账户转出
perp_in : 永续合约转入
perp_out : 永续合约转出
perp_settle_in: 永续合约多币种结算转入
perp_settle_out: 永续合约多币种结算转出
delivery_in : 交割合约转入
delivery_out : 交割合约转出
ai_in : 定投转入
ai_out : 定投转出
e_options_in : 短时期权转入
e_options_out : 短时期权转出
options_in : 期权转入
options_out : 期权转出
cbbc_in : 牛熊证转入
cbbc_out : 牛熊证转出
warrant_in : 窝轮转入
warrant_out : 窝轮转出
subaccount_trf : 子账户资金划转
quant_in : 量化交易转入
quant_out : 量化交易转出
pay_in : 支付账户转入
pay_out : 支付账户转出
fct_in : 合约跟单交易转入
fct_out : 合约跟单交易转出

# 点卡

points_purchase : 购买点卡
points_expiration : 限时点卡
points_trf : 点卡转让
points_trf_rej : 点卡转让退回

# 金融

lending_lent : 理财借出
collected : 收款
interest_in : 利息收入
lending_fee : 理财手续费抵扣
hodl_int : PoS利息收益
redeem : 赎回
lend : 借出
dual_purchased : 双币理财申购
dual_settled : 双币理财结算
liq_add : 流动性添加
liq_rm : 流动性赎回
liq_rebalanced : 流动性调仓
slot_int_in : 插槽解锁利息收益
str_int_in : 结构性理财利息收益

# 借贷

borrow : 借款
repay : 还款
margin_borrow : 逐仓杠杆借入
margin_repay : 逐仓杠杆还款
margin_interest_out : 逐仓杠杆扣息
cl_borrow : 抵押借入
cl_repay : 抵押还款
cl_dctd : 抵押扣除
cl_rtd : 抵押退还
cross_borrow : 统一账户借入
cross_repay : 统一账户还款
interest_out : 利息

# 币圈

donation : 捐款
rp_sent : 发送红包
rp_rcvd : 收取红包
rp_rej : 红包退回
ls_offered : 直播打赏
ls_rcvd : 直播被打赏
pt_offered : 币圈打赏
pt_rcvd : 币圈被打赏
subs_deduct : 订阅扣费
subs_in : 订阅费入账
subs_refund : 订阅费退回
subs_in_rcvd : 订阅费用退回入账

# PUSH交易

push_dctd : push扣除
push_rcvd_dctd : push接收扣除
push_canceled : push撤单
push_rej : push拒绝
push_sent : push转让
push_rcvd : push接收

# 量化跟单

quant_return : 量化交易退回
quant_cmn_in : 量化复制分红转入
quant_cmn_out : 量化复制分红转出
quant_cmn_rtd : 量化复制分红退回
fct_refund : 合约跟单交易资金退回
fct_rcvd : 合约带单分红转入
fct_fee : 合约跟单分红转出
fct_fee_refund : 合约跟单分红资金退回

# NFT

nft_mp : 拍卖支付保证金
nft_bm : 拍卖购买
nft_om : 拍卖出售
ntf_mr : 拍卖保证金退回
nft_amr : 拍卖流拍获得保证金
nft_ocb : 订单取消退回
nft_fb : 一口价购买
nft_fs : 一口价出售
nft_ob : 报价购买
nft_os : 报价出售
nft_cr : 取消报价退款
nft_ir : 报价失效退款
nft_wf : 提现服务费
nft_wfr : 提现手续费退回
ntf_mf : 多副本创作服务费
ntf_mfr : 多副本创作服务费退回
ntf_royalty : 用户版税收入
nft_cd : 订单取消扣款
nft_crd : 交易撤销版税扣款
nft_cf : 众筹差额扣款
nft_cfr : 众筹差额退款
nft_ammf : 流动性池充值冻结
nft_ammw : 流动性池提现
nft_ammdf : 流动性池手续费
nft_ammd : 流动性池交易成功打款

# 异常处理

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	超出提现额度
DUPLICATE_REQUEST	重复请求
ORDER_EXISTS	订单已存在
INVALID_CLIENT_ORDER_ID	无效的client_order_id

现货和杠杆相关

`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	找不到能够合并的借贷订单
ORDER_BOOK_NOT_FOUND	市场深度不足
FAILED_RETRIEVE_ASSETS	获取账户资产失败

合约相关

`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`	含义
COL_NOT_ENOUGH	质押物余额不足
COL_TOO_MUCH	超过质押币种质押额度
INIT_LTV_TOO_HIGH	初始质押率过高
REDEEMED_LTV_TOO_HIGH	提取后质押率过高
BORROWABLE_NOT_ENOUGH	剩余可借余额不足
ORDER_TOO_MANY_TOTAL	超过平台每天下单数量
ORDER_TOO_MANY_DAILY	超过单一用户每天下单数量
ORDER_TOO_MANY_USER	超过单一用户总下单数量
ORDER_NOT_EXIST	订单不存在
ORDER_FINISHED	订单已结束
ORDER_NO_PAY	订单待还金额为0
ORDER_EXIST	订单已存在
ORDER_HISTORY_EXIST	订单历史记录已存在
ORDER_REPAYING	订单已在还款中
ORDER_LIQUIDATING	订单已在平仓中
BORROW_TOO_LITTLE	小于币种最小可借
BORROW_TOO_LARGE	借款金额超过最大剩余可借
REPAY_AMOUNT_INVALID	还款金额无效
REPAY_GREATER_THAN_AVAILABLE	还款数额大于剩余可用
POOL_BALANCE_NOT_ENOUGH	资金池余额不足

现货保证金相关

`label`	含义
USER_LIAB	用户存在负债
USER_PENDING_ORDERS	用户存在挂单
MODE_SET	保证金模式已设置

服务异常

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

# 认证

# 生成 API key

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

每个账户最多可以创建 20 个 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 验签请求接口发送要求

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

查询所有合约订单

	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

创建合约委托

	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='{"withdraw_order_id":"order_123456","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='{"withdraw_order_id":"order_123456","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

提现

请求体示例

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

参数

名称	位置	类型	必选	描述
body	body	object	是
» withdraw_order_id	body	string	否	用户端订单编号,最长32个，输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.)
» amount	body	string	是	币的数量
» currency	body	string	是	币种名称
» address	body	string	否	提现地址。提现操作必填
» memo	body	string	否	转账memo等备注信息
» chain	body	string	是	提现的链名称

返回示例

202 返回

{
  "id": "210496",
  "timestamp": "1542000000",
  "withdraw_order_id": "order_123456",
  "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	区块转账哈希记录
» withdraw_order_id	string	用户端订单编号,最长32个，输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.)
» 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	提现的链名称

# 枚举值列表

属性	值
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",
  "withdraw_order_id": "order_123456",
  "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	区块转账哈希记录
» withdraw_order_id	string	用户端订单编号,最长32个，输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.)
» 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	提现的链名称

# 枚举值列表

属性	值
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	链的英文名称
» contract_address	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",
    "withdraw_order_id": "order_123456",
    "currency": "USDT",
    "address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
    "txid": "128988928203223323290",
    "amount": "222.61",
    "fee": "0.01",
    "memo": "",
    "status": "DONE",
    "chain": "TRX"
  }
]

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

返回格式

状态码 200

名称	类型	描述
» id	string	交易记录 ID
» txid	string	区块转账哈希记录
» withdraw_order_id	string	用户端订单编号,最长32个，输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.)
» timestamp	string	操作时间
» amount	string	币的数量
» fee	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	提现的链名称

# 枚举值列表

属性	值
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",
    "withdraw_order_id": "order_123456",
    "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	区块转账哈希记录
» withdraw_order_id	string	用户端订单编号,最长32个，输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.)
» 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	提现的链名称

# 枚举值列表

属性	值
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

交易账户互转

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

现货账户 - 杠杆账户
现货账户 - 永续合约账户
现货账户 - 交割合约账户
现货账户 - 全仓杠杆账户
现货账户 - 期权账户

请求体示例

{
  "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='{"client_order_id":"da3ce7a088c8b0372b741419c7829033","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='{"client_order_id":"da3ce7a088c8b0372b741419c7829033","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

主子账号互转

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

请求体示例

{
  "client_order_id": "da3ce7a088c8b0372b741419c7829033",
  "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	是	转账额度
» client_order_id	body	string	否	客户自定义ID，防止重复划转，字母（区分大小写）、数字、连字符'-'和下划线'_'的组合，可以是纯字母、纯数字且长度要在1-64位之间
» sub_account_type	body	string	否	操作的子账号交易账户， spot - 现货账户， futures - 永续合约账户, cross_margin - 全仓杠杆账户， delivery - 交割合约账户

# 枚举值列表

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

状态码	含义	描述	格式
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",
    "client_order_id": "da3ce7a088c8b0372b741419c7829033",
    "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
» client_order_id	string	客户自定义ID，防止重复划转，字母（区分大小写）、数字、连字符'-'和下划线'_'的组合，可以是纯字母、纯数字且长度要在1-64位之间
» timest	string	转账时间戳
» source	string	转账操作来源
» sub_account_type	string	操作的子账号交易账户， spot - 现货账户， futures - 永续合约账户, cross_margin - 全仓杠杆账户， delivery - 交割合约账户

# 枚举值列表

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

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_to_sub_account'
query_param = ''
body='{"currency":"usdt","sub_account_from":"10001","sub_account_from_type":"spot","sub_account_to":"10002","sub_account_to_type":"spot","amount":"1"}'
# `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_to_sub_account"
query_param=""
body_param='{"currency":"usdt","sub_account_from":"10001","sub_account_from_type":"spot","sub_account_to":"10002","sub_account_to_type":"spot","amount":"1"}'
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_to_sub_account

子账号与子帐号互转

支持同一个主账户下的两个子账户之间进行余额互转，可以使用主账户API Key或者转出子账户API Key进行操作

请求体示例

{
  "currency": "usdt",
  "sub_account_from": "10001",
  "sub_account_from_type": "spot",
  "sub_account_to": "10002",
  "sub_account_to_type": "spot",
  "amount": "1"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» currency	body	string	是	转账货币名称
» sub_account_type	body	string	否	转出的子账号交易账户 (已弃用, 改用 `sub_account_from_type` 和 `sub_account_to_type`)
» sub_account_from	body	string	是	转出子账号用户 ID
» sub_account_from_type	body	string	是	转出的子账号交易账户， spot - 现货账户， futures - 永续合约账户, cross_margin - 全仓杠杆账户
» sub_account_to	body	string	是	转入子账号用户 ID
» sub_account_to_type	body	string	是	转入的子账号交易账户， spot - 现货账户， futures - 永续合约账户, cross_margin - 全仓杠杆账户
» amount	body	string	是	转账额度

# 枚举值列表

参数	值
» sub_account_from_type	spot
» sub_account_from_type	futures
» sub_account_from_type	cross_margin
» sub_account_to_type	spot
» sub_account_to_type	futures
» sub_account_to_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/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"
    },
    "withdraw_percent_on_chains": {
      "ETH": "0%",
      "GTEVM": "0%"
    }
  }
]

状态码	含义	描述	格式
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	多链的固定提现手续费用
» withdraw_percent_on_chains	object	多链的百分比提现手续费用

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 = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund)
»»» 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)pricediscount` 之和
»»» borrowed	string	折算成 USDT 的账户总借入数量，即所有币种(不包括点卡)的 `borrowedpricediscount` 之和
»»» borrowed_net	string	折算成 USDT 的账户总借入数量 * 放大系数
»»» net	string	折算成 USDT 的净资产
»»» leverage	string	杠杆倍数
»»» interest	string	折算成 USDT 的账户未接利息的总和，即所有币种(不包括点卡)的 `interestpricediscount` 之和
»»» 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	否	指定交易对获取更准确的费率设置。
settle	请求参数	string	否	指定合约的结算币种获取更准确的费率设置。

# 详细描述

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

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

settle: 指定合约的结算币种获取更准确的费率设置。

该字段可选，通常情况下所有结算币种的费率设置是一样的。

# 枚举值列表

参数	值
settle	BTC
settle	USDT
settle	USD

返回示例

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",
  "delivery_taker_fee": "0.00016",
  "delivery_maker_fee": "-0.00015"
}

状态码	含义	描述	格式
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 费率
» delivery_taker_fee	string	交割合约 taker 费率
» delivery_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 认证

# SubAccount

子账户管理

# 创建新的子账户

示例代码

# 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 = '/sub_accounts'
query_param = ''
body='{"remark":"remark","login_name":"sub_account_for_trades"}'
# `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="/sub_accounts"
query_param=""
body_param='{"remark":"remark","login_name":"sub_account_for_trades"}'
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 /sub_accounts

创建新的子账户

请求体示例

{
  "remark": "remark",
  "login_name": "sub_account_for_trades"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» remark	body	string	否	备注
» login_name	body	string	是	子账户登陆名：仅支持字母、数字、下划线，不可包含其他非法字符。
» password	body	string	否	子账户密码
» email	body	string	否	子账户邮箱

# 详细描述

» password: 子账户密码不传默认跟随主账户

» email: 子账户邮箱不传默认跟随主账户

返回示例

201 返回

{
  "remark": "remark",
  "login_name": "sub_account_for_trades",
  "user_id": 10001,
  "state": 1,
  "create_time": 168888888
}

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

返回格式

状态码 201

名称	类型	描述
» remark	string	备注
» login_name	string	子账户登陆名：仅支持字母、数字、下划线，不可包含其他非法字符。
» password	string	子账户密码不传默认跟随主账户
» email	string	子账户邮箱不传默认跟随主账户
» state	integer(int32)	子账户状态 1正常,2冻结
» type	integer(int32)	子账号类型 1-普通子账号 3-全仓杠杆子账户
» user_id	integer(int64)	子账户 user_id
» create_time	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 = '/sub_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="/sub_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 /sub_accounts

获取子账户列表

参数

名称	位置	类型	必选	描述
type	请求参数	string	否	输入 0 则列出所有类型子账户（目前支持全仓杠杆子账户和普通子账户）输入1查询普通子账户,如果不传默认只查询普通子账户。

返回示例

200 返回

[
  {
    "remark": "remark",
    "login_name": "sub_account_for_trades",
    "user_id": 10001,
    "state": 1,
    "create_time": 168888888
  }
]

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

返回格式

状态码 200

名称	类型	描述
None	array
» remark	string	备注
» login_name	string	子账户登陆名：仅支持字母、数字、下划线，不可包含其他非法字符。
» password	string	子账户密码不传默认跟随主账户
» email	string	子账户邮箱不传默认跟随主账户
» state	integer(int32)	子账户状态 1正常,2冻结
» type	integer(int32)	子账号类型 1-普通子账号 3-全仓杠杆子账户
» user_id	integer(int64)	子账户 user_id
» create_time	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 = '/sub_accounts/0'
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="/sub_accounts/0"
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 /sub_accounts/{user_id}

获取子账户

参数

名称	位置	类型	必选	描述
user_id	URL	integer(int64)	是	子账户 UserID

返回示例

200 返回

{
  "remark": "remark",
  "login_name": "sub_account_for_trades",
  "user_id": 10001,
  "state": 1,
  "create_time": 168888888
}

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

返回格式

状态码 200

名称	类型	描述
» remark	string	备注
» login_name	string	子账户登陆名：仅支持字母、数字、下划线，不可包含其他非法字符。
» password	string	子账户密码不传默认跟随主账户
» email	string	子账户邮箱不传默认跟随主账户
» state	integer(int32)	子账户状态 1正常,2冻结
» type	integer(int32)	子账号类型 1-普通子账号 3-全仓杠杆子账户
» user_id	integer(int64)	子账户 user_id
» create_time	integer(int64)	创建时间戳

WARNING

该请求需要 API key 和 secret 认证

# 创建新的子账户 API 密钥对

示例代码

# 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 = '/sub_accounts/0/keys'
query_param = ''
body='{"mode":1,"name":"spot","perms":[{"read_only":false,"name":"options"},{"read_only":false,"name":"spot"},{"read_only":false,"name":"delivery"},{"read_only":false,"name":"wallet"},{"read_only":false,"name":"futures"}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
# `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="/sub_accounts/0/keys"
query_param=""
body_param='{"mode":1,"name":"spot","perms":[{"read_only":false,"name":"options"},{"read_only":false,"name":"spot"},{"read_only":false,"name":"delivery"},{"read_only":false,"name":"wallet"},{"read_only":false,"name":"futures"}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
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 /sub_accounts/{user_id}/keys

创建新的子账户 API 密钥对

请求体示例

{
  "mode": 1,
  "name": "spot",
  "perms": [
    {
      "read_only": false,
      "name": "options"
    },
    {
      "read_only": false,
      "name": "spot"
    },
    {
      "read_only": false,
      "name": "delivery"
    },
    {
      "read_only": false,
      "name": "wallet"
    },
    {
      "read_only": false,
      "name": "futures"
    }
  ],
  "ip_whitelist": [
    "127.0.0.1",
    "127.0.0.2"
  ]
}

参数

名称	位置	类型	必选	描述
user_id	URL	integer(int64)	是	子账户 UserID
body	body	SubAccountKey	是
» mode	body	integer(int32)	否	模式 1 - 经典帐户 2 - 统一账户
» name	body	string	否	API Key名称
» perms	body	array	否
»» ApiV4KeyPerm	body	object	否
»»» name	body	string	否	权限功能名称（不传值即为清空）
»»» read_only	body	boolean	否	该功能是否只读
»» ip_whitelist	body	array	否	IP白名单列表（不传值即为清空）

# 详细描述

»»» name: 权限功能名称（不传值即为清空）

wallet: 钱包
spot: 现货/杠杆
futures: 永续合约
delivery: 交割合约
earn: 理财
options: 期权
account: 账户信息
portfolio: 保证金
loan: 借贷

# 枚举值列表

参数	值
»»» name	wallet
»»» name	spot
»»» name	futures
»»» name	delivery
»»» name	earn
»»» name	options
»»» name	account
»»» name	portfolio
»»» name	loan

返回示例

200 返回

{
  "state": 1,
  "name": "spot",
  "user_id": 100000,
  "perms": [
    {
      "name": "options",
      "read_only": false
    },
    {
      "name": "spot",
      "read_only": false
    },
    {
      "name": "delivery",
      "read_only": false
    },
    {
      "name": "wallet",
      "read_only": false
    },
    {
      "name": "futures",
      "read_only": false
    }
  ],
  "ip_whitelist": [
    "127.0.0.1",
    "127.0.0.2"
  ],
  "mode": 1,
  "secret": "cddcc6e5e78060e013860bdbe5e737830b96821c027664586fb38b411808f4fd",
  "key": "eb8815bf99d7bb5f8ad6497bdc4774a8",
  "created_at": 1663683330,
  "updated_at": 1663683330
}

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

返回格式

状态码 200

名称	类型	描述
» user_id	string	用户ID
» mode	integer(int32)	模式 1 - 经典帐户 2 - 统一账户
» name	string	API Key名称
» perms	array
»» ApiV4KeyPerm	object
»»» name	string	权限功能名称（不传值即为清空） - wallet: 钱包 - spot: 现货/杠杆 - futures: 永续合约 - delivery: 交割合约 - earn: 理财 - options: 期权 - account: 账户信息 - portfolio: 保证金 - loan: 借贷
»»» read_only	boolean	该功能是否只读
»» ip_whitelist	array	IP白名单列表（不传值即为清空）
»» key	string	API Key
»» state	integer(int32)	状态 1 - 正常 2 - 冻结 3 - 锁定
»» created_at	string	创建时间
»» updated_at	string	最近更新时间

# 枚举值列表

属性	值
name	wallet
name	spot
name	futures
name	delivery
name	earn
name	options
name	account
name	portfolio
name	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 = '/sub_accounts/0/keys'
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="/sub_accounts/0/keys"
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 /sub_accounts/{user_id}/keys

获取子账户所有密钥对

参数

名称	位置	类型	必选	描述
user_id	URL	integer	是	子账户 UserID

返回示例

200 返回

[
  {
    "state": 1,
    "name": "spot",
    "user_id": 1000000,
    "perms": [
      {
        "name": "futures",
        "read_only": false
      },
      {
        "name": "wallet",
        "read_only": false
      },
      {
        "name": "delivery",
        "read_only": false
      },
      {
        "name": "options",
        "read_only": false
      },
      {
        "name": "spot",
        "read_only": false
      }
    ],
    "mode": 1,
    "ip_whitelist": [
      "127.0.0.1",
      "127.0.0.2"
    ],
    "key": "75c3264105b74693d8cb5c7f1a8e2420",
    "created_at": 1663642892,
    "update_at": 1663642892
  }
]

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

WARNING

该请求需要 API key 和 secret 认证

# 修改子账户 API 密钥对

示例代码

# 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 = '/sub_accounts/0/keys/string'
query_param = ''
body='{"mode":1,"name":"spot","perms":[{"read_only":false,"name":"options"},{"read_only":false,"name":"spot"},{"read_only":false,"name":"delivery"},{"read_only":false,"name":"wallet"},{"read_only":false,"name":"futures"}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
# `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="/sub_accounts/0/keys/string"
query_param=""
body_param='{"mode":1,"name":"spot","perms":[{"read_only":false,"name":"options"},{"read_only":false,"name":"spot"},{"read_only":false,"name":"delivery"},{"read_only":false,"name":"wallet"},{"read_only":false,"name":"futures"}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
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 /sub_accounts/{user_id}/keys/{key}

修改子账户 API 密钥对

请求体示例

{
  "mode": 1,
  "name": "spot",
  "perms": [
    {
      "read_only": false,
      "name": "options"
    },
    {
      "read_only": false,
      "name": "spot"
    },
    {
      "read_only": false,
      "name": "delivery"
    },
    {
      "read_only": false,
      "name": "wallet"
    },
    {
      "read_only": false,
      "name": "futures"
    }
  ],
  "ip_whitelist": [
    "127.0.0.1",
    "127.0.0.2"
  ]
}

参数

名称	位置	类型	必选	描述
user_id	URL	integer	是	子账户 UserID
key	URL	string	是	子账户 APIKey
body	body	SubAccountKey	是
» mode	body	integer(int32)	否	模式 1 - 经典帐户 2 - 统一账户
» name	body	string	否	API Key名称
» perms	body	array	否
»» ApiV4KeyPerm	body	object	否
»»» name	body	string	否	权限功能名称（不传值即为清空）
»»» read_only	body	boolean	否	该功能是否只读
»» ip_whitelist	body	array	否	IP白名单列表（不传值即为清空）

# 详细描述

»»» name: 权限功能名称（不传值即为清空）

wallet: 钱包
spot: 现货/杠杆
futures: 永续合约
delivery: 交割合约
earn: 理财
options: 期权
account: 账户信息
portfolio: 保证金
loan: 借贷

# 枚举值列表

参数	值
»»» name	wallet
»»» name	spot
»»» name	futures
»»» name	delivery
»»» name	earn
»»» name	options
»»» name	account
»»» name	portfolio
»»» name	loan

状态码	含义	描述	格式
204	No Content (opens new window)	修改成功	无

WARNING

该请求需要 API key 和 secret 认证

# 删除子账户 API 密钥对

示例代码

# 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 = '/sub_accounts/0/keys/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="/sub_accounts/0/keys/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 /sub_accounts/{user_id}/keys/{key}

删除子账户 API 密钥对

参数

名称	位置	类型	必选	描述
user_id	URL	integer	是	子账户 UserID
key	URL	string	是	子账户 APIKey

状态码	含义	描述	格式
204	No Content (opens new window)	删除成功	无

WARNING

该请求需要 API key 和 secret 认证

# 获取子账户 API 特定密钥对

示例代码

# 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 = '/sub_accounts/0/keys/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="/sub_accounts/0/keys/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 /sub_accounts/{user_id}/keys/{key}

获取子账户 API 特定密钥对

参数

名称	位置	类型	必选	描述
user_id	URL	integer	是	子账户 UserID
key	URL	string	是	子账户 APIKey

返回示例

200 返回

{
  "state": 1,
  "name": "spot",
  "user_id": 1000000,
  "perms": [
    {
      "name": "futures",
      "read_only": false
    },
    {
      "name": "wallet",
      "read_only": false
    },
    {
      "name": "delivery",
      "read_only": false
    },
    {
      "name": "options",
      "read_only": false
    },
    {
      "name": "spot",
      "read_only": false
    }
  ],
  "mode": 1,
  "ip_whitelist": [
    "127.0.0.1",
    "127.0.0.2"
  ],
  "key": "75c3264105b74693d8cb5c7f1a8e2420",
  "created_at": 1663642892,
  "update_at": 1663642892
}

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

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 = '/sub_accounts/0/lock'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', 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="POST"
url="/sub_accounts/0/lock"
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"

POST /sub_accounts/{user_id}/lock

锁定子账户

参数

名称	位置	类型	必选	描述
user_id	URL	integer(int64)	是	子账户UserID

状态码	含义	描述	格式
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 = '/sub_accounts/0/unlock'
query_param = ''
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', 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="POST"
url="/sub_accounts/0/unlock"
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"

POST /sub_accounts/{user_id}/unlock

解锁子账户

参数

名称	位置	类型	必选	描述
user_id	URL	integer(int64)	是	子账户UserID

状态码	含义	描述	格式
204	No Content (opens new window)	解锁成功	无

WARNING

该请求需要 API key 和 secret 认证

# Portfolio

保证金交易

# 获取保证金账户信息

示例代码

# 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 = '/portfolio/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="/portfolio/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 /portfolio/accounts

获取保证金账户信息

账户内的各币种资产将会根据其流动性，定义相应的调整系数，再统一折算为USD，来统一计算账户的资产及持仓价值

具体公式可查询保证金公式

参数

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

返回示例

200 返回

{
  "user_id": 10001,
  "locked": false,
  "balances": {
    "ETH": {
      "available": "0",
      "freeze": "0",
      "borrowed": "0.075393666654",
      "interest": "0.0000106807603333",
      "negative_liab": "0",
      "futures_pos_liab": "0",
      "equity": "1016.1",
      "total_freeze": "0",
      "total_liab": "0"
    },
    "POINT": {
      "available": "9999999999.017023138734",
      "freeze": "0",
      "borrowed": "0",
      "interest": "0",
      "negative_liab": "0",
      "futures_pos_liab": "0",
      "equity": "12016.1",
      "total_freeze": "0",
      "total_liab": "0"
    },
    "USDT": {
      "available": "0.00000062023",
      "freeze": "0",
      "borrowed": "0",
      "interest": "0",
      "negative_liab": "0",
      "futures_pos_liab": "0",
      "equity": "16.1",
      "total_freeze": "0",
      "total_liab": "0"
    }
  },
  "total": "230.94621713",
  "borrowed": "161.66395521",
  "interest": "0.02290237",
  "risk": "1.4284",
  "leverage": "2",
  "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",
  "portfolio_margin_total": "3381470.892007440383",
  "portfolio_margin_total_liab": "0",
  "portfolio_margin_total_equity": "100016.1"
}

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

返回格式

状态码 200

名称	类型	描述
» user_id	integer(int64)	用户 ID
» refresh_time	integer(int64)	最近一次刷新时间
» locked	boolean	账户是否被锁定
» balances	object
»» PortfolioMarginBalance	object
»»» available	string	可用额度
»»» freeze	string	被锁定的额度
»»» borrowed	string	借入额度
»»» interest	string	未还利息
»»» negative_liab	string	负余额借贷
»»» futures_pos_liab	string	合约开仓借币
»»» equity	string	权益
»»» total_freeze	string	总占用
»»» total_liab	string	总借款
»» total	string	折算成 USDT 的账户总资产，即所有币种(不包括点卡)之和
»» borrowed	string	折算成 USDT 的账户总借入数量，即所有币种(不包括点卡)之和
»» interest	string	折算成 USDT 的账户未接利息的总和，即所有币种(不包括点卡)之和
»» leverage	string	当前用户的杠杆倍数
»» 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	可用的保证金额度
»» portfolio_margin_total	string	保证金账户总资产
»» portfolio_margin_total_liab	string	保证金账户总借贷
»» portfolio_margin_total_equity	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 = '/portfolio/account_mode'
query_param = ''
body='{"mode":"cross_margin","enabled":true}'
# `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="/portfolio/account_mode"
query_param=""
body_param='{"mode":"cross_margin","enabled":true}'
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 /portfolio/account_mode

设置账户保证金模式

请求体示例

{
  "mode": "cross_margin",
  "enabled": true
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» mode	body	string	是	保证金模式
» enabled	body	boolean	是	是否启用

# 详细描述

» mode: 保证金模式

cross_margin : 现货全仓保证金
usdt_futures : USDT永续合约组合保证金

返回示例

200 返回

{
  "cross_margin": true,
  "usdt_futures": true
}

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

返回格式

状态码 200

名称	类型	描述
» additionalProperties	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 = '/portfolio/account_mode'
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="/portfolio/account_mode"
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 /portfolio/account_mode

查询账户保证金模式

cross_margin - 现货全仓保证金, usdt_futures - USDT永续合约组合保证金

返回示例

200 返回

{
  "cross_margin": true
}

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

返回格式

状态码 200

名称	类型	描述
» additionalProperties	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 = '/portfolio/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="/portfolio/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 /portfolio/borrowable

查询保证金账户最多可借入

参数

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

返回示例

200 返回

{
  "currency": "ETH",
  "amount": "10000"
}

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

返回格式

状态码 200

PortfolioBorrowable

名称	类型	描述
» 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 = '/portfolio/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="/portfolio/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 /portfolio/transferable

查询保证金账户最多可转出

参数

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

返回示例

200 返回

{
  "currency": "ETH",
  "amount": "10000"
}

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

返回格式

状态码 200

PortfolioTransferable

名称	类型	描述
» 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 = '/portfolio/loans'
query_param = ''
body='{"currency":"BTC","amount":"0.1","type":"borrow","repaid_all":false,"text":"t-test"}'
# `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="/portfolio/loans"
query_param=""
body_param='{"currency":"BTC","amount":"0.1","type":"borrow","repaid_all":false,"text":"t-test"}'
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 /portfolio/loans

借入或还款

借入时必须保证不能少于币种最小借入量，不能超过平台及用户最大可借数量

借款利息会定期从账户自动扣除，用户需自主处理借款部分的还款

还款支持repaid_all=true全部还款

请求体示例

{
  "currency": "BTC",
  "amount": "0.1",
  "type": "borrow",
  "repaid_all": false,
  "text": "t-test"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» currency	body	string	是	币种
» type	body	string	是	类型 , borrow - 借入 , repay - 还款
» amount	body	string	是	借入或还款数量
» repaid_all	body	boolean	否	全部还款，仅还款操作使用，为`true`时覆盖`amount` ，直接全部还款
» text	body	string	否	用户自定义 ID

# 枚举值列表

参数	值
» type	borrow
» type	repay

状态码	含义	描述	格式
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 = '/portfolio/loans'
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="/portfolio/loans"
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 /portfolio/loans

查询借贷

参数

名称	位置	类型	必选	描述
currency	请求参数	string	否	指定币种名称查询
page	请求参数	integer	否	列表页数
limit	请求参数	integer(int32)	否	列表返回的最大数量。默认为100，最小1，最大100。

返回示例

200 返回

[
  {
    "currency": "USDT",
    "currency_pari": "GT_USDT",
    "amount": "1",
    "change_time": 1673247054000,
    "create_time": 1673247054000
  }
]

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

返回格式

状态码 200

名称	类型	描述
None	array	[借贷]
» None	object	借贷
»» currency	string	币种
»» currency_pair	string	交易对
»» amount	string	待归还数量
»» create_time	integer(int64)	创建时间戳
»» update_time	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 = '/portfolio/loan_records'
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="/portfolio/loan_records"
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 /portfolio/loan_records

查询借贷记录

参数

名称	位置	类型	必选	描述
type	请求参数	string	否	借贷记录类型 , borrow - 借入 , repay - 还款
currency	请求参数	string	否	指定币种名称查询
page	请求参数	integer	否	列表页数
limit	请求参数	integer(int32)	否	列表返回的最大数量。默认为100，最小1，最大100。

# 枚举值列表

参数	值
type	borrow
type	repay

返回示例

200 返回

[
  {
    "id": 16442,
    "type": "borrow",
    "margin_mode": "cross",
    "currency_pair": "AE_USDT",
    "currency": "USDT",
    "amount": "1000",
    "create_time": 1673247054000,
    "repayment_type": "auto_repay"
  }
]

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

返回格式

状态码 200

名称	类型	描述
» None	object	借贷记录
»» id	integer(int64)	id
»» type	string	类型 , borrow - 借入 , repay - 还款
»» repayment_type	string	还款类型 , none - 无还款类型, manual_repay - 手动还款 , auto_repay - 自动还款, cancel_auto_repay - 撤单后自动还款
»» currency_pair	string	交易对
»» currency	string	币种
»» amount	string	借入或还款数量
»» create_time	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 = '/portfolio/interest_records'
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="/portfolio/interest_records"
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 /portfolio/interest_records

查询扣息记录

参数

名称	位置	类型	必选	描述
currency	请求参数	string	否	指定币种名称查询
page	请求参数	integer	否	列表页数
limit	请求参数	integer(int32)	否	列表返回的最大数量。默认为100，最小1，最大100。

返回示例

200 返回

[
  {
    "status": 1,
    "currency_pair": "BTC_USDT",
    "currency": "USDT",
    "actual_rate": "0.00000236",
    "interest": "0.00006136",
    "create_time": 1673247054000
  }
]

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

返回格式

状态码 200

名称	类型	描述
None	array	[扣息记录]
» None	object	扣息记录
»» currency	string	币种名称
»» currency_pair	string	交易对
»» actual_rate	string	实际利率
»» interest	string	利息
»» status	integer	状态 0 - 失败 , 1 - 成功
»» create_time	integer(int64)	创建时间戳

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

查询所有币种信息

币种标识有两种类型：

仅币种名称，如 BTC, USDT
<币>_<链>，如 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",
    "max_base_amount": "10000",
    "max_quote_amount": "10000000",
    "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",
  "max_base_amount": "10000",
  "max_quote_amount": "10000000",
  "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(int32)	否	列表返回的最大数量。默认为100，最小1，最大1000。
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",
    "sequence_id": "588018",
    "text": "t-test"
  }
]

状态码	含义	描述	格式
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 数量，公共接口无此字段返回
» amend_text	string	用户修改订单时备注的信息
» sequence_id	string	单市场连续成交ID
» text	string	订单的自定义信息，公共接口无此字段返回

# 枚举值列表

属性	值
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`, `to` 中的任意字段，该字段会被拒绝
from	请求参数	integer(int64)	否	指定 K 线图的起始时间，注意时间格式为秒(s)精度的 Unix 时间戳，不指定则默认为 to - 100 * interval，即向前最多 100 个点的时间
to	请求参数	integer(int64)	否	指定 K 线图的结束时间，不指定则默认当前时间，注意时间格式为秒(s)精度的 Unix 时间戳
interval	请求参数	string	否	数据点的时间间隔，注意 `30d` 代表的是自然月，不是按30天对齐

# 详细描述

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

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",
  "delivery_taker_fee": "0.00016",
  "delivery_maker_fee": "-0.00015"
}

状态码	含义	描述	格式
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 费率
» delivery_taker_fee	string	交割合约 taker 费率
» delivery_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/batch_fee'
query_param = 'currency_pairs=BTC_USDT,ETH_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/batch_fee"
query_param="currency_pairs=BTC_USDT,ETH_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/batch_fee

批量查询账户费率

参数

名称	位置	类型	必选	描述
currency_pairs	请求参数	string	是	一次请求最多只能查询 50 个交易对

返回示例

200 返回

{
  "BTC_USDT": {
    "user_id": 10001,
    "taker_fee": "0.002",
    "maker_fee": "0.002",
    "gt_discount": false,
    "gt_taker_fee": "0",
    "gt_maker_fee": "0",
    "loan_fee": "0.18",
    "point_type": "1",
    "currency_pair": "BTC_USDT"
  },
  "GT_USDT": {
    "user_id": 10001,
    "taker_fee": "0.002",
    "maker_fee": "0.002",
    "gt_discount": false,
    "gt_taker_fee": "0",
    "gt_maker_fee": "0",
    "loan_fee": "0.18",
    "point_type": "1",
    "currency_pair": "GT_USDT"
  },
  "ETH_USDT": {
    "user_id": 10001,
    "taker_fee": "0.002",
    "maker_fee": "0.002",
    "gt_discount": false,
    "gt_taker_fee": "0",
    "gt_maker_fee": "0",
    "loan_fee": "0.18",
    "point_type": "1",
    "currency_pair": "ETH_USDT"
  }
}

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

返回格式

状态码 200

名称	类型	描述
» additionalProperties	object
»» 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 启用的新点卡
»» currency_pair	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/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/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="/spot/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 /spot/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": "margin_in",
    "text": "3815099"
  }
]

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

返回格式

状态码 200

名称	类型	描述
» id	string	账户变更记录 ID
» time	integer(int64)	账户变更时间戳，毫秒单位
» currency	string	变更币种
» change	string	变更金额，正数表示转入，负数表示转出
» balance	string	变更后账户余额
» type	string	账户变更类型 , 详见资产流水类型
» 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 = '/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,"stp_act":"cn"}]'
# `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,"stp_act":"cn"}]'
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

批量下单

批量下单要求：

用户自定义订单信息 text 必须指定
每次只能下最多 4 个交易对且每个交易对只可批量下 10 个单
现货交易和杠杆交易不能同时存在，即同个请求里所有 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,
    "stp_act": "cn"
  }
]

参数

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

返回示例

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",
    "stp_act": "cn",
    "finish_as": "stp",
    "stp_id": 10240
  }
]

状态码	含义	描述	格式
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 : 限价单 - market : 市价单
»» account	string	账户类型，spot - 现货账户，margin - 杠杆账户，cross_margin - 全仓杠杆账户，portfolio - 保证金账户
»» side	string	买单或者卖单
»» amount	string	交易数量
»» price	string	交易价
»» time_in_force	string	Time in force 策略。 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单 - poc: PendingOrCancelled，被动委托，只挂单不吃单 - fok: FillOrKill，全部成交或者全部取消
»» iceberg	string	冰山下单显示的数量，不指定或传 0 都默认为普通下单。目前不支持全部冰山。
»» 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	返还手续费计价单位
»» stp_id	integer	订单所属的`STP用户组`id，同一个`STP用户组`内用户之间的订单不允许发生自成交。 1. 如果撮合时两个订单的 `stp_id` 非 `0` 且相等，则不成交，而是根据 `taker` 的 `stp_act` 执行相应策略。 2. 没有设置`STP用户组`成交的订单，`stp_id` 默认返回 `0`。
»» stp_act	string	Self-Trading Prevention Action,用户可以用该字段设置自定义限制自成交策略。 1. 用户在设置加入`STP用户组`后，可以通过传递 `stp_act` 来限制用户发生自成交的策略，没有传递 `stp_act` 默认按照 `cn` 的策略。 2. 用户在没有设置加入`STP用户组`时，传递 `stp_act` 参数会报错。 3. 用户没有使用 `stp_act` 发生成交的订单，`stp_act` 返回`-`。 - cn: Cancel newest,取消新订单，保留老订单 - co: Cancel oldest,取消⽼订单，保留新订单 - cb: Cancel both,新旧订单都取消
»» finish_as	string	订单结束方式，包括： - open: 等待处理 - filled: 完全成交 - cancelled: 用户撤销 - ioc: 未立即完全成交，因为 tif 设置为 ioc - stp: 订单发生自成交限制而被撤销

# 枚举值列表

属性	值
status	open
status	closed
status	cancelled
type	limit
type	market
account	spot
account	margin
account	cross_margin
account	portfolio
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	ioc
finish_as	stp

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. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.) 除用户自定义信息以外，以下为内部保留字段，标识订单来源: 101 代表 `android` 下单 102 代表 `IOS` 下单 103 代表 `IPAD` 下单 104 代表 `webapp` 下单 3 代表 `web` 下单 2 代表 `apiv2` 下单 apiv4 代表 `apiv4` 下单
»»» amend_text	string	用户修改订单时备注的信息
»»» 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 : 限价单 - market : 市价单
»»» account	string	账户类型，spot - 现货账户，margin - 杠杆账户，cross_margin - 全仓杠杆账户，portfolio - 保证金账户统一账户只能设置 `cross_margin`
»»» side	string	买单或者卖单
»»» amount	string	交易数量 `type`为`limit`时，指交易货币，即需要交易的货币，如`BTC_USDT`中指`BTC`。 `type`为`market`时，根据买卖不同指代不同 - `side` : `buy` 指代计价货币，`BTC_USDT`中指`USDT` - `side` : `sell` 指代交易货币，`BTC_USDT`中指`BTC`
»»» price	string	交易价,`type`=`limit`时必填
»»» time_in_force	string	Time in force 策略。 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单 - poc: PendingOrCancelled，被动委托，只挂单不吃单 - fok: FillOrKill，全部成交或者全部取消 `type`=`market`时仅支持`ioc`和`fok`
»»» iceberg	string	冰山下单显示的数量，不指定或传 0 都默认为普通下单。目前不支持全部冰山。
»»» auto_repay	boolean	全仓杠杆下单是否开启自动还款，默认关闭。需要注意的是: 1. 此字段仅针对全仓杠杆有效。逐仓杠杆不支持订单级别的自动还款设置，只能通过 `POST /margin/auto_repay` 修改用户级别的设置 2. `auto_borrow` 与 `auto_repay` 不支持同时开启
»»» left	string	交易货币未成交数量
»»» fill_price	string	已成交的计价币种总额，该字段废弃，建议使用相同意义的 `filled_total`
»»» filled_total	string	已成交总金额
»»» avg_deal_price	string	平均成交价
»»» fee	string	成交扣除的手续费
»»» fee_currency	string	手续费计价单位
»»» point_fee	string	手续费抵扣使用的点卡数量
»»» gt_fee	string	手续费抵扣使用的 GT 数量
»»» gt_maker_fee	string	手续费maker抵扣使用的 GT 数量
»»» gt_taker_fee	string	手续费taker抵扣使用的 GT 数量
»»» gt_discount	boolean	是否开启GT抵扣
»»» rebated_fee	string	返还的手续费
»»» rebated_fee_currency	string	返还手续费计价单位
»»» stp_id	integer	订单所属的`STP用户组`id，同一个`STP用户组`内用户之间的订单不允许发生自成交。 1. 如果撮合时两个订单的 `stp_id` 非 `0` 且相等，则不成交，而是根据 `taker` 的 `stp_act` 执行相应策略。 2. 没有设置`STP用户组`成交的订单，`stp_id` 默认返回 `0`。
»»» stp_act	string	Self-Trading Prevention Action,用户可以用该字段设置自定义限制自成交策略。 1. 用户在设置加入`STP用户组`后，可以通过传递 `stp_act` 来限制用户发生自成交的策略，没有传递 `stp_act` 默认按照 `cn` 的策略。 2. 用户在没有设置加入`STP用户组`时，传递 `stp_act` 参数会报错。 3. 用户没有使用 `stp_act` 发生成交的订单，`stp_act` 返回 `-`。 - cn: Cancel newest,取消新订单，保留老订单 - co: Cancel oldest,取消⽼订单，保留新订单 - cb: Cancel both,新旧订单都取消
»»» finish_as	string	订单结束方式，包括： - open: 等待处理 - filled: 完全成交 - cancelled: 用户撤销 - ioc: 未立即完全成交，因为 tif 设置为 ioc - stp: 订单发生自成交限制而被撤销

# 枚举值列表

属性	值
status	open
status	closed
status	cancelled
type	limit
type	market
account	spot
account	margin
account	cross_margin
account	portfolio
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	ioc
finish_as	stp

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，用户自定义字段必须满足以下条件：

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

返回示例

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",
  "avg_deal_price": "5.00032",
  "fee": "0.005",
  "fee_currency": "ETH",
  "point_fee": "0",
  "gt_fee": "0",
  "gt_discount": false,
  "rebated_fee": "0",
  "rebated_fee_currency": "BTC",
  "stp_act": "cn",
  "finish_as": "stp",
  "stp_id": 10240
}

状态码	含义	描述	格式
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,"stp_act":"cn"}'
# `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,"stp_act":"cn"}'
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 ，即使用现货账户下单，如果用户是portfolio账户，默认是用保证金账户下单

使用杠杆账户交易，即 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 的手续费率收取。

限制用户自成交

设置 stp_act 来决定使用限制用户自成交的策略

请求体示例

{
  "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,
  "stp_act": "cn"
}

参数

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

# 详细描述

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

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

除用户自定义信息以外，以下为内部保留字段，标识订单来源: 101 代表 android 下单 102 代表 IOS 下单 103 代表 IPAD 下单 104 代表 webapp 下单 3 代表 web 下单 2 代表 apiv2 下单 apiv4 代表 apiv4 下单

» type: 订单类型

limit : 限价单
market : 市价单

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

» amount: 交易数量
type为limit时，指交易货币，即需要交易的货币，如BTC_USDT中指BTC。
type为market时，根据买卖不同指代不同

side : buy 指代计价货币，BTC_USDT中指USDT
side : sell 指代交易货币，BTC_USDT中指BTC

» time_in_force: Time in force 策略。

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

type=market时仅支持ioc和fok

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

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

» stp_act: Self-Trading Prevention Action,用户可以用该字段设置自定义限制自成交策略。

用户在设置加入STP用户组后，可以通过传递 stp_act 来限制用户发生自成交的策略，没有传递 stp_act 默认按照 cn 的策略。
用户在没有设置加入STP用户组时，传递 stp_act 参数会报错。
用户没有使用 stp_act 发生成交的订单，stp_act 返回 -。

cn: Cancel newest,取消新订单，保留老订单
co: Cancel oldest,取消⽼订单，保留新订单
cb: Cancel both,新旧订单都取消

# 枚举值列表

参数	值
» type	limit
» type	market
» account	spot
» account	margin
» account	cross_margin
» account	portfolio
» side	buy
» side	sell
» time_in_force	gtc
» time_in_force	ioc
» time_in_force	poc
» time_in_force	fok
» stp_act	cn
» stp_act	co
» stp_act	cb
» stp_act	-

返回示例

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",
  "avg_deal_price": "5.00032",
  "fee": "0.005",
  "fee_currency": "ETH",
  "point_fee": "0",
  "gt_fee": "0",
  "gt_discount": false,
  "rebated_fee": "0",
  "rebated_fee_currency": "BTC",
  "stp_act": "cn",
  "finish_as": "stp",
  "stp_id": 10240
}

状态码	含义	描述	格式
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",
    "avg_deal_price": "5.00032",
    "fee": "0.005",
    "fee_currency": "ETH",
    "point_fee": "0",
    "gt_fee": "0",
    "gt_discount": false,
    "rebated_fee": "0",
    "rebated_fee_currency": "BTC",
    "stp_act": "cn",
    "finish_as": "stp",
    "stp_id": 10240
  }
]

状态码	含义	描述	格式
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",
    "avg_deal_price": "5.00032",
    "fee": "0.005",
    "fee_currency": "ETH",
    "point_fee": "0",
    "gt_fee": "0",
    "gt_discount": false,
    "rebated_fee": "0",
    "rebated_fee_currency": "BTC",
    "stp_act": "cn",
    "finish_as": "stp",
    "stp_id": 10240
  }
]

状态码	含义	描述	格式
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[CancelBatchOrder]	是

返回示例

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 的操作只在挂单中可查，当结束订单（成交/取消）后，在结束之后1小时内可查，过期之后只能使用订单 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",
  "avg_deal_price": "5.00032",
  "fee": "0.005",
  "fee_currency": "ETH",
  "point_fee": "0",
  "gt_fee": "0",
  "gt_discount": false,
  "rebated_fee": "0",
  "rebated_fee_currency": "BTC",
  "stp_act": "cn",
  "finish_as": "stp",
  "stp_id": 10240
}

状态码	含义	描述	格式
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'
body='{"amount":"1","price":"14"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PATCH', host + prefix + url + "?" + query_param, 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="/spot/orders/12345"
query_param="currency_pair=BTC_USDT"
body_param='{"amount":"1","price":"14"}'
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 -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

PATCH /spot/orders/{order_id}

修改单个订单

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

目前只支持修改价格或数量（二选一）

关于限速：修改订单和创建订单共享限速规则

关于匹配优先级：只修改数量变小不影响匹配优先级，修改价格或修改数量变大则优先级将调整到新价格最后面

注意事项:修改数量小于已成交数量会触发撤单操作

请求体示例

{
  "amount": "1",
  "price": "14"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» amount	body	string	否	交易数量，`amount`和`price`必须指定其中一个
» price	body	string	否	交易价，`amount`和`price`必须指定其中一个
» amend_text	body	string	否	用户可以备注这次修改的信息。
order_id	URL	string	是	成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID（即 `text` 字段）。
currency_pair	请求参数	string	是	交易对
account	请求参数	string	否	指定查询账户。不指定默认现货，保证金和逐仓杠杆账户。指定 `cross_margin` 则查询全仓杠杆账户。

# 详细描述

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",
  "avg_deal_price": "5.00032",
  "fee": "0.005",
  "fee_currency": "ETH",
  "point_fee": "0",
  "gt_fee": "0",
  "gt_discount": false,
  "rebated_fee": "0",
  "rebated_fee_currency": "BTC",
  "stp_act": "cn",
  "finish_as": "stp",
  "stp_id": 10240
}

状态码	含义	描述	格式
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` 则查询全仓杠杆账户。

# 详细描述

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",
  "avg_deal_price": "5.00032",
  "fee": "0.005",
  "fee_currency": "ETH",
  "point_fee": "0",
  "gt_fee": "0",
  "gt_discount": false,
  "rebated_fee": "0",
  "rebated_fee_currency": "BTC",
  "stp_act": "cn",
  "finish_as": "stp",
  "stp_id": 10240
}

状态码	含义	描述	格式
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 = ''
# `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/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 /spot/my_trades

查询个人成交记录

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

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

如果不指定任何时间参数，只能获取最近 7 天的数据。
如果只指定 from 或 to 的任一参数，也同样只返回指定时间开始（或结束）的 7 天范围的数据。
from 和 to 的范围不允许超过 30 天。

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

参数

名称	位置	类型	必选	描述
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",
    "sequence_id": "588018",
    "text": "t-test"
  }
]

状态码	含义	描述	格式
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 数量，公共接口无此字段返回
» amend_text	string	用户修改订单时备注的信息
» sequence_id	string	单市场连续成交ID
» text	string	订单的自定义信息，公共接口无此字段返回

# 枚举值列表

属性	值
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/countdown_cancel_all'
query_param = ''
body='{"timeout":30,"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="/spot/countdown_cancel_all"
query_param=""
body_param='{"timeout":30,"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 /spot/countdown_cancel_all

倒计时取消订单

现货订单心跳检测，在到达用户设置的timeout时间时如果没有取消既有倒计时或设置新的倒计时将会自动取消相关的现货挂单。
该接口可重复调用，以便设置新的倒计时或取消倒计时。用法示例：以30s的间隔重复此接口，每次倒计时timeout设置为30(秒)。如果在30秒内未再次调用此接口，则您指定market上的所有挂单都会被自动撤销，如果未指定market，则撤销所有市场挂单。如果在30秒内以将timeout设置为0，则倒数计时器将终止，自动撤单功能取消。

请求体示例

{
  "timeout": 30,
  "currency_pair": "BTC_USDT"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» timeout	body	integer(int32)	是	倒计时时间，单位秒
» currency_pair	body	string	否	交易货币对

# 详细描述

» timeout: 倒计时时间，单位秒
至少5秒，为0时表示取消倒计时

返回示例

200 返回

{
  "triggerTime": "1660039145000"
}

状态码	含义	描述	格式
200	OK (opens new window)	设置倒计时成功	Inline

返回格式

状态码 200

triggerTime

名称	类型	描述
» triggerTime	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 = '/spot/amend_batch_orders'
query_param = ''
body='[{"order_id":"121212","currency_pair":"BTC_USDT","account":"spot","amount":"1","amend_text":"test"}]'
# `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/amend_batch_orders"
query_param=""
body_param='[{"order_id":"121212","currency_pair":"BTC_USDT","account":"spot","amount":"1","amend_text":"test"}]'
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/amend_batch_orders

批量修改订单

默认修改现货、保证金和逐仓杠杆账户的订单，如果需要修改全仓杠杆账户订单，必须指定 account 为 cross_margin，统一账户 account 只能指定为 cross_margin。目前只支持修改价格或数量（二选一）修改未完成的订单，一次最多可批量修改5个订单。请求参数应该按数组格式传递。批量修改过程中有订单修改失败会继续执行下个订单的修改，执行后返回会携带相应订单的失败信息批量修改订单的调用顺序与订单列表顺序一致批量修改订单的返回内容顺序,与订单列表顺序一致

请求体示例

[
  {
    "order_id": "121212",
    "currency_pair": "BTC_USDT",
    "account": "spot",
    "amount": "1",
    "amend_text": "test"
  }
]

参数

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

返回示例

200 返回

[
  {
    "order_id": "121212",
    "amount": "1",
    "price": "14",
    "status": "SUCCESS"
  }
]

状态码	含义	描述	格式
200	OK (opens new window)	修改订单执行完成	[Inline]

返回格式

状态码 200

名称	类型	描述
» None	object	订单批量修改结果
»» order_id	string	订单 ID
»» amount	string	交易数量
»» price	string	交易价
»» amend_text	string	用户修改订单时备注的信息
»» succeeded	boolean	是否更新成功
»» label	string	修改失败时的错误标识，成功时为空
»» message	string	修改失败时的错误描述，成功时为空
»» account	string	账户类型，spot - 现货账户，margin - 杠杆账户，portfolio - 保证金账户，cross_margin - 全仓杠杆账户，统一账户只能设置 `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/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时触发

»» type: 订单类型，默认为限价单

limit : 限价单
market : 市价单

»» side: 买卖方向

buy: 买
sell: 卖

»» amount: 交易数量
type为limit时，指交易货币，即需要交易的货币，如BTC_USDT中指BTC。
type为market时，根据买卖不同指代不同

side : buy 指代计价货币，BTC_USDT中指USDT
side : sell 指代交易货币，BTC_USDT中指BTC

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

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

»» time_in_force: time_in_force

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

# 枚举值列表

参数	值
»» rule	>=
»» rule	<=
»» type	limit
»» type	market
»» 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
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`，该字段忽略
type	请求参数	string	否	指定账户变动类型查询，不指定则包含全部变动类型
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	变更后账户余额
» type	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/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

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/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.0001 - 0.01 这个范围的利率。
» 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.0001 - 0.01 这个范围的利率。

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

# 枚举值列表

参数	值
» 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/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",
    "loanable": true,
    "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 的价格
» loanable	boolean	该币种是否可借贷
» 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",
  "loanable": true,
  "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 的价格
» loanable	boolean	该币种是否可借贷
» 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",
      "negative_liab": "0",
      "futures_pos_liab": "0",
      "equity": "1016.1",
      "total_freeze": "0",
      "total_liab": "0"
    },
    "POINT": {
      "available": "9999999999.017023138734",
      "freeze": "0",
      "borrowed": "0",
      "interest": "0",
      "negative_liab": "0",
      "futures_pos_liab": "0",
      "equity": "12016.1",
      "total_freeze": "0",
      "total_liab": "0"
    },
    "USDT": {
      "available": "0.00000062023",
      "freeze": "0",
      "borrowed": "0",
      "interest": "0",
      "negative_liab": "0",
      "futures_pos_liab": "0",
      "equity": "16.1",
      "total_freeze": "0",
      "total_liab": "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",
  "portfolio_margin_total": "3381470.892007440383",
  "portfolio_margin_total_liab": "0",
  "portfolio_margin_total_equity": "100016.1"
}

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

返回格式

状态码 200

名称	类型	描述
» user_id	integer(int64)	用户 ID
» refresh_time	integer(int64)	最近一次刷新时间
» locked	boolean	账户是否被锁定
» balances	object
»» CrossMarginBalance	object
»»» available	string	可用额度
»»» freeze	string	被锁定的额度
»»» borrowed	string	借入额度
»»» interest	string	未还利息
»»» negative_liab	string	负余额借贷, 公式：Min[available+total+unrealized_pnl,0]
»»» futures_pos_liab	string	合约开仓借币
»»» equity	string	权益, 公式：available + freeze - borrowed + futures account's total + unrealized_pnl
»»» total_freeze	string	总占用, 公式：freeze + position_initial_margin + order_margin
»»» total_liab	string	总借款, 公式：Max[Abs[Min[quity - total_freeze,0], borrowed]] - futures_pos_liab
»» total	string	折算成 USDT 的账户总资产，即所有币种(不包括点卡)的 `(available+freeze)pricediscount` 之和
»» borrowed	string	折算成 USDT 的账户总借入数量，即所有币种(不包括点卡)的 `borrowedpricediscount` 之和
»» interest	string	折算成 USDT 的账户未接利息的总和，即所有币种(不包括点卡)的 `interestpricediscount` 之和
»» 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	可用的保证金额度
»» portfolio_margin_total	string	统一账户总资产
»» portfolio_margin_total_liab	string	统一账户总借贷
»» portfolio_margin_total_equity	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	账户变更类型 , 详见资产流水类型

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)	已弃用，借贷产品升级目前已取消状态管理，所有状态都为2 借入单状态，可选值包括： - 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)	已弃用，借贷产品升级目前已取消状态管理，所有状态都为2 借入单状态，可选值包括： - 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)	已弃用，借贷产品升级目前已取消状态管理，所有状态都为2 借入单状态，可选值包括： - 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)	已弃用，借贷产品升级目前已取消状态管理，所有状态都为2 借入单状态，可选值包括： - 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",
    "repayment_type": "auto_repay"
  }
]

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

返回格式

状态码 200

名称	类型	描述
» id	string	还款记录 ID
» create_time	integer(int64)	还款时间
» loan_id	string	还款记录 ID
» currency	string	币种名称
» principal	string	归还本金
» interest	string	归还利息
» repayment_type	string	还款类型 , none - 无还款类型, manual_repay - 手动还款 , auto_repay - 自动还款, cancel_auto_repay - 撤单后自动还款

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/interest_records'
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/interest_records"
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/interest_records

全仓账户扣息记录

参数

名称	位置	类型	必选	描述
currency	请求参数	string	否	指定币种名称查询
page	请求参数	integer	否	列表页数
limit	请求参数	integer(int32)	否	列表返回的最大数量。默认为100，最小1，最大100。

返回示例

200 返回

[
  {
    "status": 1,
    "currency_pair": "BTC_USDT",
    "currency": "USDT",
    "actual_rate": "0.00000236",
    "interest": "0.00006136",
    "create_time": 1673247054000
  }
]

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

返回格式

状态码 200

名称	类型	描述
None	array	[扣息记录]
» None	object	扣息记录
»» currency	string	币种名称
»» currency_pair	string	交易对
»» actual_rate	string	实际利率
»» interest	string	利息
»» status	integer	状态 0 - 失败 , 1 - 成功
»» create_time	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 = '/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/estimate_rate'
query_param = 'currencies=BTC,GT'
# `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/estimate_rate"
query_param="currencies=BTC,GT"
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/estimate_rate

查询全仓币种的预估利率

因为利率每小时会随借贷深度变化，不能提供完全精确的利率

参数

名称	位置	类型	必选	描述
currencies	请求参数	array[string]	是	指定币种名称查询数组，最大10个

返回示例

200 返回

{
  "BTC": "0.000002",
  "GT": "0.000001"
}

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

返回格式

状态码 200

预估当前小时的借贷利率，按币种进行返回

名称	类型	描述
» 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 = '/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 认证

# MarginUni

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

# 查询借贷市场列表

示例代码

# coding: utf-8
import requests

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

url = '/margin/uni/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/uni/currency_pairs \
  -H 'Accept: application/json'

GET /margin/uni/currency_pairs

查询借贷市场列表

返回示例

200 返回

[
  {
    "currency_pair": "AE_USDT",
    "base_min_borrow_amount": "100",
    "quote_min_borrow_amount": "100",
    "leverage": "3"
  }
]

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

返回格式

状态码 200

名称	类型	描述
None	array	[借贷交易对]
» None	object	借贷交易对
»» currency_pair	string	交易对
»» base_min_borrow_amount	string	交易货币最小借入数量
»» quote_min_borrow_amount	string	计价货币最小借入数量
»» leverage	string	杠杆倍数

# 查询借贷市场详情

示例代码

# coding: utf-8
import requests

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

url = '/margin/uni/currency_pairs/AE_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/uni/currency_pairs/AE_USDT \
  -H 'Accept: application/json'

GET /margin/uni/currency_pairs/{currency_pair}

查询借贷市场详情

参数

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

返回示例

200 返回

{
  "currency_pair": "AE_USDT",
  "base_min_borrow_amount": "100",
  "quote_min_borrow_amount": "100",
  "leverage": "3"
}

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

返回格式

状态码 200

借贷交易对

名称	类型	描述
» currency_pair	string	交易对
» base_min_borrow_amount	string	交易货币最小借入数量
» quote_min_borrow_amount	string	计价货币最小借入数量
» leverage	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 = '/margin/uni/estimate_rate'
query_param = 'currencies=BTC,GT'
# `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/uni/estimate_rate"
query_param="currencies=BTC,GT"
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/uni/estimate_rate

查询逐仓币种的预估利率

因为利率每小时会随借贷深度变化，不能提供完全精确的利率

参数

名称	位置	类型	必选	描述
currencies	请求参数	array[string]	是	指定币种名称查询数组，最大10个

返回示例

200 返回

{
  "BTC": "0.000002",
  "GT": "0.000001"
}

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

返回格式

状态码 200

预估当前小时的借贷利率，按币种进行返回

名称	类型	描述
» 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 = '/margin/uni/loans'
query_param = ''
body='{"currency":"BTC","amount":"0.1","type":"borrow","currency_pair":"BTC_USDT","repaid_all":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="/margin/uni/loans"
query_param=""
body_param='{"currency":"BTC","amount":"0.1","type":"borrow","currency_pair":"BTC_USDT","repaid_all":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 /margin/uni/loans

借入或还款

请求体示例

{
  "currency": "BTC",
  "amount": "0.1",
  "type": "borrow",
  "currency_pair": "BTC_USDT",
  "repaid_all": false
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» currency	body	string	是	币种
» type	body	string	是	类型 , borrow - 借入 , repay - 还款
» amount	body	string	是	借入或还款数量
» repaid_all	body	boolean	否	全部还款，仅还款操作使用，为`true`时覆盖`amount` ，直接全部还款
» currency_pair	body	string	是	交易对

# 枚举值列表

参数	值
» type	borrow
» type	repay

状态码	含义	描述	格式
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 = '/margin/uni/loans'
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/uni/loans"
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/uni/loans

查询借贷

参数

名称	位置	类型	必选	描述
currency_pair	请求参数	string	否	交易对
currency	请求参数	string	否	指定币种名称查询
page	请求参数	integer	否	列表页数
limit	请求参数	integer(int32)	否	列表返回的最大数量。默认为100，最小1，最大100。

返回示例

200 返回

[
  {
    "currency": "USDT",
    "currency_pari": "GT_USDT",
    "amount": "1",
    "change_time": 1673247054000,
    "create_time": 1673247054000
  }
]

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

返回格式

状态码 200

名称	类型	描述
None	array	[借贷]
» None	object	借贷
»» currency	string	币种
»» currency_pair	string	交易对
»» amount	string	待归还数量
»» create_time	integer(int64)	创建时间戳
»» update_time	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 = '/margin/uni/loan_records'
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/uni/loan_records"
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/uni/loan_records

查询借贷记录

参数

名称	位置	类型	必选	描述
type	请求参数	string	否	类型 , borrow - 借入 , repay - 还款
currency	请求参数	string	否	指定币种名称查询
currency_pair	请求参数	string	否	交易对
page	请求参数	integer	否	列表页数
limit	请求参数	integer(int32)	否	列表返回的最大数量。默认为100，最小1，最大100。

# 枚举值列表

参数	值
type	borrow
type	repay

返回示例

200 返回

[
  {
    "type": "borrow",
    "currency_pair": "AE_USDT",
    "currency": "USDT",
    "amount": "1000",
    "create_time": 1673247054000
  }
]

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

返回格式

状态码 200

名称	类型	描述
» None	object	借贷记录
»» type	string	类型 , borrow - 借入 , repay - 还款
»» currency_pair	string	交易对
»» currency	string	币种
»» amount	string	借入或还款数量
»» create_time	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 = '/margin/uni/interest_records'
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/uni/interest_records"
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/uni/interest_records

查询扣息记录

参数

名称	位置	类型	必选	描述
currency_pair	请求参数	string	否	交易对
currency	请求参数	string	否	指定币种名称查询
page	请求参数	integer	否	列表页数
limit	请求参数	integer(int32)	否	列表返回的最大数量。默认为100，最小1，最大100。

返回示例

200 返回

[
  {
    "status": 1,
    "currency_pair": "BTC_USDT",
    "currency": "USDT",
    "actual_rate": "0.00000236",
    "interest": "0.00006136",
    "create_time": 1673247054000
  }
]

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

返回格式

状态码 200

名称	类型	描述
None	array	[扣息记录]
» None	object	扣息记录
»» currency	string	币种名称
»» currency_pair	string	交易对
»» actual_rate	string	实际利率
»» interest	string	利息
»» status	integer	状态 0 - 失败 , 1 - 成功
»» create_time	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 = '/margin/uni/borrowable'
query_param = 'currency=BTC&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="/margin/uni/borrowable"
query_param="currency=BTC&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 /margin/uni/borrowable

查询币种最大可借

参数

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

返回示例

200 返回

{
  "currency": "AE",
  "borrowable": "1123.344",
  "currency_pair": "AE_USDT"
}

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

返回格式

状态码 200

MaxUniBorrowable

名称	类型	描述
» currency	string	币种
» currency_pair	string	交易对
» borrowable	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

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

url = '/flash_swap/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/flash_swap/currency_pairs \
  -H 'Accept: application/json'

GET /flash_swap/currency_pairs

查询支持闪兑的所有交易对列表

BTC_GT表示卖出BTC买入GT ，每个币种在每个交易对中的限额不同

两个能闪兑的币种不一定能相互兑换，比如可能存在卖出BTC买入GT ，不一定可以卖出GTBTC, 即支持BTC_GT不一定支持GT_BTC`

参数

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

返回示例

200 返回

[
  {
    "currency_pair": "BTC_USDT",
    "sell_currency": "BTC",
    "buy_currency": "USDT",
    "sell_min_amount": "0.00001",
    "sell_max_amount": "100",
    "buy_min_amount": "10",
    "buy_max_amount": "10000000"
  }
]

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

返回格式

状态码 200

名称	类型	描述
» None	object	查询闪兑的交易对列表
»» currency_pair	string	交易对， `BTC_USDT` 表示卖`BTC`买`USDT`
»» sell_currency	string	卖出币种
»» buy_currency	string	买入币种
»» sell_min_amount	string	卖出最小数量
»» sell_max_amount	string	卖出最大数量
»» buy_min_amount	string	买入最小数量
»» buy_max_amount	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 = '/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/currency_pairs获取

» buy_currency: 买入的资产名称，根据接口查询支持闪兑的所有交易对列表 GET /flash_swap/currency_pairs获取

返回示例

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='{"sell_currency":"BTC","sell_amount":"0.1","buy_currency":"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="/flash_swap/orders/preview"
query_param=""
body_param='{"sell_currency":"BTC","sell_amount":"0.1","buy_currency":"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 /flash_swap/orders/preview

闪兑订单预览

请求体示例

{
  "sell_currency": "BTC",
  "sell_amount": "0.1",
  "buy_currency": "USDT"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» sell_currency	body	string	是	卖出的资产名称，
» sell_amount	body	string	否	卖出的资产数量，
» buy_currency	body	string	是	买入的资产名称，
» buy_amount	body	string	否	买入的资产数量，

# 详细描述

» sell_currency: 卖出的资产名称，根据接口查询支持闪兑的所有交易对列表 GET /flash_swap/currency_pairs获取

» sell_amount: 卖出的资产数量， sell_amount和buy_amount二选一必填

» buy_currency: 买入的资产名称，根据接口查询支持闪兑的所有交易对列表 GET /flash_swap/currency_pairs获取

» 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,
    "enable_bonus": true,
    "enable_credit": true,
    "create_time": 1669688556,
    "funding_cap_ratio": "0.75"
  }
]

状态码	含义	描述	格式
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,
  "enable_bonus": true,
  "enable_credit": true,
  "create_time": 1669688556,
  "funding_cap_ratio": "0.75"
}

状态码	含义	描述	格式
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	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
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	成交价格 (计价货币)
» is_internal	boolean	是否为内部成交。内部成交是指保险基金和ADL用户对强平委托的接盘，由于不是在市场深度上的正常撮合，所以成交价格和市场有偏差，也不会计入K线。如果不是内部成交，则不返回这个字段。

# 合约市场 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 - 100 * interval，即向前最多 100 个点的时间
to	请求参数	integer(int64)	否	指定 K 线图的结束时间，不指定则默认当前时间，注意时间格式为秒(s)精度的 Unix 时间戳
limit	请求参数	integer	否	指定数据点的数量，适用于取最近 `limit` 数量的数据，该字段与 `from`, `to` 互斥，如果指定了 `from`, `to` 中的任意字段，该字段会被拒绝
interval	请求参数	string	否	数据点的时间间隔，注意 1w 代表一个自然周，7d 的时间是和 Unix 初始时间对齐, 30d 代表一个自然月

# 详细描述

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",
    "sum": "3580"
  }
]

状态码	含义	描述	格式
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	开盘价 (计价货币)
»» sum	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/premium_index'
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/premium_index?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /futures/{settle}/premium_index

合约溢价指数 K 线图

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

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	是	合约标识
from	请求参数	integer(int64)	否	指定 K 线图的起始时间，注意时间格式为秒(s)精度的 Unix 时间戳，不指定则默认为 to - 100 * interval，即向前最多 100 个点的时间
to	请求参数	integer(int64)	否	指定 K 线图的结束时间，不指定则默认当前时间，注意时间格式为秒(s)精度的 Unix 时间戳
limit	请求参数	integer	否	指定数据点的数量，适用于取最近 `limit` 数量的数据，该字段与 `from`, `to` 互斥，如果指定了 `from`, `to` 中的任意字段，该字段会被拒绝
interval	请求参数	string	否	数据点的时间间隔

# 详细描述

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

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

# 枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd
interval	1m
interval	5m
interval	15m
interval	30m
interval	1h
interval	4h
interval	6h
interval	8h
interval	1d
interval	7d
interval	30d

返回示例

200 返回

[
  {
    "t": 1539852480,
    "c": "0",
    "h": "0.00023",
    "l": "0",
    "o": "0"
  }
]

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

返回格式

状态码 200

名称	类型	描述
» None	object	每个时间粒度的 K 线数据
»» t	number(double)	秒 s 精度的 Unix 时间戳
»» 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",
    "highest_bid": "34089.7",
    "lowest_ask": "34217.9"
  }
]

状态码	含义	描述	格式
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	基差数值
» lowest_ask	string	最新卖方最低价
» highest_bid	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.hk",
      "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,
    "order_price": "3405",
    "fill_price": "3424",
    "left": 0
  }
]

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

返回格式

状态码 200

名称	类型	描述
» time	integer(int64)	强制平仓时间
» contract	string	合约标识
» size	integer(int64)	用户仓位大小
» 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 = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund)
» 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

查询合约账户变更历史

如果传入contract字段，只能筛选2023-10-30后包含该字段的记录。

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	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": 1682294400.123456,
    "change": "0.000010152188",
    "balance": "4.59316525194",
    "text": "ETH_USD:6086261",
    "type": "fee",
    "contract": "ETH_USD"
  }
]

状态码	含义	描述	格式
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	注释
» contract	string	合约标识，只有2023-10-30后的数据才有该字段

# 枚举值列表

属性	值
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	是	结算货币
holding	请求参数	boolean	否	只返回真实持仓-true,全部返回-false

# 枚举值列表

参数	值
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",
    "update_time": 1684994406,
    "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",
  "update_time": 1684994406,
  "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",
  "update_time": 1684994406,
  "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",
  "update_time": 1684994406,
  "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",
  "update_time": 1684994406,
  "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 = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund)
» 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",
    "update_time": 1684994406,
    "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",
    "update_time": 1684994406,
    "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",
    "update_time": 1684994406,
    "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",
    "update_time": 1684994406,
    "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","stp_act":"-"}'
# `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","stp_act":"-"}'
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
设置 stp_act 决定使用限制用户自成交的策略，详细用法参考body参数stp_act

请求体示例

{
  "contract": "BTC_USDT",
  "size": 6024,
  "iceberg": 0,
  "price": "3765",
  "tif": "gtc",
  "text": "t-my-custom-id",
  "stp_act": "-"
}

参数

名称	位置	类型	必选	描述
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
» stp_act	body	string	否	Self-Trading Prevention Action,用户可以用该字段设置自定义限制自成交策略。
settle	URL	string	是	结算货币

# 详细描述

» tif: Time in force 策略，市价单当前只支持 ioc 模式

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

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

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

除用户自定义信息以外，以下为内部保留字段，标识订单来源:

web: 网页
api: API 调用
app: 移动端
auto_deleveraging: 自动减仓
liquidation: 强制平仓
insurance: 保险

» stp_act: Self-Trading Prevention Action,用户可以用该字段设置自定义限制自成交策略。

用户在设置加入STP用户组后，可以通过传递 stp_act 来限制用户发生自成交的策略，没有传递 stp_act 默认按照 cn 的策略。
用户在没有设置加入STP用户组时，传递 stp_act 参数会报错。
用户没有使用 stp_act 发生成交的订单，stp_act 返回 -。

cn: Cancel newest,取消新订单，保留老订单
co: Cancel oldest,取消⽼订单，保留新订单
cb: Cancel both,新旧订单都取消

# 枚举值列表

参数	值
» tif	gtc
» tif	ioc
» tif	poc
» tif	fok
» auto_size	close_long
» auto_size	close_short
» stp_act	co
» stp_act	cn
» stp_act	cb
» stp_act	-
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",
  "stp_id": 0,
  "stp_act": "-",
  "amend_text": "-"
}

状态码	含义	描述	格式
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 = '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="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 分钟之后无法获取。
历史委托订单，默认只支持查询半年内的数据，如果需要查询更久的数据，请使用GET /futures/{settle}/orders_timerange

参数

名称	位置	类型	必选	描述
contract	请求参数	string	否	合约标识，如果指定则只返回该合约相关数据
status	请求参数	string	是	基于状态查询订单列表
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
last_id	请求参数	string	否	以上个列表的最后一条记录的 ID 作为下个列表的起点
settle	URL	string	是	结算货币

# 枚举值列表

参数	值
status	open
status	finished
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",
    "stp_id": 0,
    "stp_act": "-",
    "amend_text": "-"
  }
]

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

# 返回头部

状态码	头部	类型	格式	描述
200	X-Pagination-Limit	integer		分页时指定的 limit
200	X-Pagination-Offset	integer		分页时指定的 offset

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",
    "stp_id": 0,
    "stp_act": "-",
    "amend_text": "-"
  }
]

状态码	含义	描述	格式
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_timerange'
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_timerange"
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_timerange

查询合约订单列表(时间区间)

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	否	合约标识，如果指定则只返回该合约相关数据
from	请求参数	integer(int64)	否	起始时间戳
to	请求参数	integer(int64)	否	终止时间戳
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始

# 枚举值列表

参数	值
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",
    "stp_id": 0,
    "stp_act": "-",
    "amend_text": "-"
  }
]

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

# 返回头部

状态码	头部	类型	格式	描述
200	X-Pagination-Limit	integer		分页时指定的 limit
200	X-Pagination-Offset	integer		分页时指定的 offset

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","stp_act":"-"}]'
# `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","stp_act":"-"}]'
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",
    "stp_act": "-"
  }
]

参数

名称	位置	类型	必选	描述
body	body	array[FuturesOrder]	是
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",
    "stp_id": 0,
    "stp_act": "-",
    "amend_text": "-"
  }
]

状态码	含义	描述	格式
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: 只减仓被排除的不容易成交的挂单 - stp: 订单发生自成交限制而被撤销
»» 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
»» stp_act	string	Self-Trading Prevention Action,用户可以用该字段设置自定义限制自成交策略。 1. 用户在设置加入`STP用户组`后，可以通过传递 `stp_act` 来限制用户发生自成交的策略，没有传递 `stp_act` 默认按照 `cn` 的策略。 2. 用户在没有设置加入`STP用户组`时，传递 `stp_act` 参数会报错。 3. 用户没有使用 `stp_act` 发生成交的订单，`stp_act` 返回 `-`。 - cn: Cancel newest,取消新订单，保留老订单 - co: Cancel oldest,取消⽼订单，保留新订单 - cb: Cancel both,新旧订单都取消
»» stp_id	integer	订单所属的`STP用户组`id，同一个`STP用户组`内用户之间的订单不允许发生自成交。 1. 如果撮合时两个订单的 `stp_id` 非 `0` 且相等，则不成交，而是根据 `taker` 的 `stp_act` 执行相应策略。 2. 没有设置`STP用户组`成交的订单，`stp_id` 默认返回 `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
finish_as	stp
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok
stp_act	co
stp_act	cn
stp_act	cb
stp_act	-

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 的操作只在挂单中可查，当结束订单（成交/取消）后，在结束之后60秒内可查，过期之后只能使用订单 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",
  "stp_id": 0,
  "stp_act": "-",
  "amend_text": "-"
}

状态码	含义	描述	格式
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` 字段）。

# 详细描述

# 枚举值列表

参数	值
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",
  "stp_id": 0,
  "stp_act": "-",
  "amend_text": "-"
}

状态码	含义	描述	格式
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	否	新的委托价格。
» amend_text	body	string	否	用户可以备注这次修改的信息。
settle	URL	string	是	结算货币
order_id	URL	string	是	成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID（即 `text` 字段）。

# 详细描述

» size: 新的委托大小。包括已成交委托的部分。

如果小于等于已成交数量，则撤销委托。
新的委托买卖方向必须跟原有的一致。
不能修改平仓单的size。
对于只减仓委托，如果调大size，则可能踢出其他只减仓委托。
如果不修改价格，则调小size不会影响深度排队，调大size会排到当前价位最后。

# 枚举值列表

参数	值
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",
  "stp_id": 0,
  "stp_act": "-",
  "amend_text": "-"
}

状态码	含义	描述	格式
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

查询个人成交记录

默认只支持查询半年内的数据,如果需要查询更久的数据，请使用GET /futures/{settle}/my_trades_timerange

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	否	合约标识，如果指定则只返回该合约相关数据
order	请求参数	integer(int64)	否	委托ID，如果指定则返回该委托相关数据
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
last_id	请求参数	string	否	以上个列表的最后一条记录的 ID 作为下个列表的起点。

# 详细描述

last_id: 以上个列表的最后一条记录的 ID 作为下个列表的起点。

该字段不再继续支持，如果需要遍历查询更多记录，建议使用GET /futures/{settle}/my_trades_timerange

# 枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

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

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_timerange'
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_timerange"
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_timerange

查询个人成交记录(时间区间)

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	否	合约标识，如果指定则只返回该合约相关数据
from	请求参数	integer(int64)	否	起始时间戳
to	请求参数	integer(int64)	否	终止时间戳
limit	请求参数	integer	否	列表返回的最大数量
offset	请求参数	integer	否	列表返回的偏移量，从 0 开始
role	请求参数	string	否	查询角色，Maker 或 Taker

# 枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

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

名称	类型	描述
» trade_id	string	成交记录 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

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)	否	终止时间戳
side	请求参数	string	否	方向筛选，做多(long)或做空(short)
pnl	请求参数	string	否	盈亏判断，盈利(profit)或亏损(loss)

# 枚举值列表

参数	值
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 认证

# 查询ADL自动减仓订单信息

示例代码

# 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/auto_deleverages'
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/auto_deleverages"
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}/auto_deleverages

查询ADL自动减仓订单信息

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	否	合约标识，如果指定则只返回该合约相关数据
limit	请求参数	integer	否	列表返回的最大数量
at	请求参数	integer	否	指定时间戳的自动减仓订单信息

# 枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

[
  {
    "time": 1675841679,
    "contract": "ACH_USDT",
    "order_id": 73873128,
    "user": 1666,
    "cross_leverage_limit": "0",
    "leverage": "0",
    "entry_price": "2649.648633636364",
    "fill_price": "2790.8082",
    "position_size": 1,
    "trade_size": -10
  }
]

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

返回格式

状态码 200

名称	类型	描述
» time	integer(int64)	自动减仓时间
» user	integer(int64)	用户ID
» order_id	integer(int64)	减仓委托ID，2023-02-20之前的数据order_id为null
» contract	string	合约标识
» leverage	string	杠杆倍数
» cross_leverage_limit	string	全仓模式下的杠杆倍数（即 `leverage` 为 0 时）
» entry_price	string	平均开仓价
» fill_price	string	平均成交价
» trade_size	integer(int64)	成交数量
» position_size	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/countdown_cancel_all'
query_param = ''
body='{"timeout":30,"contract":"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="/futures/usdt/countdown_cancel_all"
query_param=""
body_param='{"timeout":30,"contract":"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 /futures/{settle}/countdown_cancel_all

倒计时取消订单

合约订单心跳检测，在到达用户设置的timeout时间时如果没有取消既有倒计时或设置新的倒计时将会自动取消相关的合约挂单。
该接口可重复调用，以便设置新的倒计时或取消倒计时。用法示例：以30s的间隔重复此接口，每次倒计时timeout设置为30(秒)。如果在30秒内未再次调用此接口，则您指定market上的所有挂单都会被自动撤销。如果在30秒内以将timeout设置为0，则倒数计时器将终止，自动撤单功能取消。

请求体示例

{
  "timeout": 30,
  "contract": "BTC_USDT"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» timeout	body	integer(int32)	是	倒计时时间，单位秒
» contract	body	string	否	合约标识
settle	URL	string	是	结算货币

# 详细描述

» timeout: 倒计时时间，单位秒
至少5秒，为0时表示取消倒计时

# 枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "triggerTime": "1660039145000"
}

状态码	含义	描述	格式
200	OK (opens new window)	设置倒计时成功	Inline

返回格式

状态码 200

triggerTime

名称	类型	描述
» triggerTime	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/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="/futures/usdt/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 /futures/{settle}/fee

查询合约市场交易费率

参数

名称	位置	类型	必选	描述
settle	URL	string	是	结算货币
contract	请求参数	string	否	合约标识，如果指定则只返回该合约相关数据

# 枚举值列表

参数	值
settle	btc
settle	usdt
settle	usd

返回示例

200 返回

{
  "1INCH_USDT": {
    "taker_fee": "0.00025",
    "maker_fee": "-0.00010"
  },
  "AAVE_USDT": {
    "taker_fee": "0.00025",
    "maker_fee": "-0.00010"
  }
}

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

返回格式

状态码 200

名称	类型	描述
» additionalProperties	object	返回结果是map类型，key是市场，value是吃单挂单费率
»» taker_fee	string	吃单费率
»» maker_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 = '/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	usdt

返回示例

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	usdt

返回示例

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	usdt
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 字段来限定时间范围

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

# 枚举值列表

参数	值
settle	usdt

返回示例

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	成交价格 (计价货币)
» is_internal	boolean	是否为内部成交。内部成交是指保险基金和ADL用户对强平委托的接盘，由于不是在市场深度上的正常撮合，所以成交价格和市场有偏差，也不会计入K线。如果不是内部成交，则不返回这个字段。

# 合约市场 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 - 100 * interval，即向前最多 100 个点的时间
to	请求参数	integer(int64)	否	指定 K 线图的结束时间，不指定则默认当前时间，注意时间格式为秒(s)精度的 Unix 时间戳
limit	请求参数	integer	否	指定数据点的数量，适用于取最近 `limit` 数量的数据，该字段与 `from`, `to` 互斥，如果指定了 `from`, `to` 中的任意字段，该字段会被拒绝
interval	请求参数	string	否	数据点的时间间隔，注意 1w 代表一个自然周，7d 的时间是和 Unix 初始时间对齐

# 详细描述

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

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

# 枚举值列表

参数	值
settle	usdt
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	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	usdt

返回示例

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",
    "highest_bid": "34089.7",
    "lowest_ask": "34217.9"
  }
]

状态码	含义	描述	格式
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	基差数值
» lowest_ask	string	最新卖方最低价
» highest_bid	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	usdt

返回示例

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	usdt

返回示例

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 = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund)
» 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	usdt
type	dnw
type	pnl
type	fee
type	refr
type	fund
type	point_dnw
type	point_fee
type	point_refr

返回示例

200 返回

[
  {
    "time": 1682294400.123456,
    "change": "0.000010152188",
    "balance": "4.59316525194",
    "text": "ETH_USD:6086261",
    "type": "fee",
    "contract": "ETH_USD"
  }
]

状态码	含义	描述	格式
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	注释
» contract	string	合约标识，只有2023-10-30后的数据才有该字段

# 枚举值列表

属性	值
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	usdt

返回示例

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",
    "update_time": 1684994406,
    "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	usdt

返回示例

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",
  "update_time": 1684994406,
  "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	usdt

返回示例

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",
  "update_time": 1684994406,
  "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	usdt

返回示例

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",
  "update_time": 1684994406,
  "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	usdt

返回示例

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",
  "update_time": 1684994406,
  "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","stp_act":"-"}'
# `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","stp_act":"-"}'
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",
  "stp_act": "-"
}

参数

名称	位置	类型	必选	描述
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
» stp_act	body	string	否	Self-Trading Prevention Action,用户可以用该字段设置自定义限制自成交策略。
settle	URL	string	是	结算货币

# 详细描述

» tif: Time in force 策略，市价单当前只支持 ioc 模式

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

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

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

除用户自定义信息以外，以下为内部保留字段，标识订单来源:

web: 网页
api: API 调用
app: 移动端
auto_deleveraging: 自动减仓
liquidation: 强制平仓
insurance: 保险

» stp_act: Self-Trading Prevention Action,用户可以用该字段设置自定义限制自成交策略。

用户在设置加入STP用户组后，可以通过传递 stp_act 来限制用户发生自成交的策略，没有传递 stp_act 默认按照 cn 的策略。
用户在没有设置加入STP用户组时，传递 stp_act 参数会报错。
用户没有使用 stp_act 发生成交的订单，stp_act 返回 -。

cn: Cancel newest,取消新订单，保留老订单
co: Cancel oldest,取消⽼订单，保留新订单
cb: Cancel both,新旧订单都取消

# 枚举值列表

参数	值
» tif	gtc
» tif	ioc
» tif	poc
» tif	fok
» auto_size	close_long
» auto_size	close_short
» stp_act	co
» stp_act	cn
» stp_act	cb
» stp_act	-
settle	usdt

返回示例

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",
  "stp_id": 0,
  "stp_act": "-",
  "amend_text": "-"
}

状态码	含义	描述	格式
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	usdt

返回示例

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",
    "stp_id": 0,
    "stp_act": "-",
    "amend_text": "-"
  }
]

状态码	含义	描述	格式
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	usdt

返回示例

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",
    "stp_id": 0,
    "stp_act": "-",
    "amend_text": "-"
  }
]

状态码	含义	描述	格式
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	usdt

返回示例

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",
  "stp_id": 0,
  "stp_act": "-",
  "amend_text": "-"
}

状态码	含义	描述	格式
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	usdt

返回示例

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",
  "stp_id": 0,
  "stp_act": "-",
  "amend_text": "-"
}

状态码	含义	描述	格式
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	usdt
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	usdt

返回示例

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	usdt

返回示例

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	usdt

返回示例

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

返回示例

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

返回示例

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

返回示例

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

返回示例

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

返回示例

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-20210916-5000-C'
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-20210916-5000-C \
  -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-20210916-5000-C'
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-20210916-5000-C \
  -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	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",
    "sum": "3580"
  }
]

状态码	含义	描述	格式
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	开盘价 (计价货币)
»» sum	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	成交价格 (计价货币)
» is_internal	boolean	是否为内部成交。内部成交是指保险基金和ADL用户对强平委托的接盘，由于不是在市场深度上的正常撮合，所以成交价格和市场有偏差，也不会计入K线。如果不是内部成交，则不返回这个字段。

# 查询账户信息

示例代码

# 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	变更数量 (USDT)
» balance	string	变更后账户总资产 (USDT)
» 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,
    "underlying": "BTC_USDT",
    "underlying_price": "70000",
    "contract": "BTC_USDT-20211216-5000-P",
    "size": 10,
    "entry_price": "1234",
    "realised_pnl": "120",
    "mark_price": "6000",
    "mark_iv": "0.9638",
    "unrealised_pnl": "-320",
    "pending_orders": 1,
    "close_order": {
      "id": 232323,
      "price": "5779",
      "is_liq": false
    },
    "delta": "-0.0046",
    "gamma": "0",
    "vega": "2.87656",
    "theta": "-1.00247"
  }
]

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

返回格式

状态码 200

名称	类型	描述
None	array	[期权合约仓位详情]
» None	object	期权合约仓位详情
»» user	integer	用户ID
»» underlying	string	标的物
»» underlying_price	string	标的价格 (计价货币)
»» contract	string	期权合约标识
»» size	integer(int64)	头寸大小 (合约张数)
»» entry_price	string	开仓价格 (计价货币)
»» mark_price	string	期权合约当前标记价格 (计价货币)
»» mark_iv	string	隐含波动率
»» realised_pnl	string	已实现盈亏
»» unrealised_pnl	string	未实现盈亏
»» pending_orders	integer	当前未完成委托数量
»» close_order	object\|null	当前平仓委托信息，如果没有平仓则为`null`
»»» id	integer(int64)	委托ID
»»» price	string	委托价格 (计价货币)
»»» is_liq	boolean	是否为强制平仓
»» delta	string	希腊字母delta
»» gamma	string	希腊字母gamma
»» vega	string	希腊字母vega
»» theta	string	希腊字母theta

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,
  "underlying": "BTC_USDT",
  "underlying_price": "70000",
  "contract": "BTC_USDT-20211216-5000-P",
  "size": 10,
  "entry_price": "1234",
  "realised_pnl": "120",
  "mark_price": "6000",
  "mark_iv": "0.9638",
  "unrealised_pnl": "-320",
  "pending_orders": 1,
  "close_order": {
    "id": 232323,
    "price": "5779",
    "is_liq": false
  },
  "delta": "-0.0046",
  "gamma": "0",
  "vega": "2.87656",
  "theta": "-1.00247"
}

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

返回格式

状态码 200

期权合约仓位详情

名称	类型	描述
» user	integer	用户ID
» underlying	string	标的物
» underlying_price	string	标的价格 (计价货币)
» contract	string	期权合约标识
» size	integer(int64)	头寸大小 (合约张数)
» entry_price	string	开仓价格 (计价货币)
» mark_price	string	期权合约当前标记价格 (计价货币)
» mark_iv	string	隐含波动率
» realised_pnl	string	已实现盈亏
» unrealised_pnl	string	未实现盈亏
» pending_orders	integer	当前未完成委托数量
» close_order	object\|null	当前平仓委托信息，如果没有平仓则为`null`
»» id	integer(int64)	委托ID
»» price	string	委托价格 (计价货币)
»» is_liq	boolean	是否为强制平仓
» delta	string	希腊字母delta
» gamma	string	希腊字母gamma
» vega	string	希腊字母vega
» theta	string	希腊字母theta

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，用户自定义字段必须满足以下条件：

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

除用户自定义信息以外，以下为内部保留字段，标识订单来源:

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
» refr	string	推荐人返佣

# 枚举值列表

属性	值
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
»» refr	string	推荐人返佣

# 枚举值列表

属性	值
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
»» refr	string	推荐人返佣

# 枚举值列表

属性	值
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
» refr	string	推荐人返佣

# 枚举值列表

属性	值
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
» refr	string	推荐人返佣

# 枚举值列表

属性	值
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 认证

# EarnUni

余币宝理财

# 查询理财币种列表

示例代码

# coding: utf-8
import requests

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

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


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

GET /earn/uni/currencies

查询理财币种列表

返回示例

200 返回

[
  {
    "currency": "AE",
    "min_lend_amount": "100",
    "max_lend_amount": "200000000",
    "max_rate": "0.00057",
    "min_rate": "0.000001"
  }
]

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

返回格式

状态码 200

名称	类型	描述
None	array	[借贷币种]
» None	object	借贷币种
»» currency	string	币种名称
»» min_lend_amount	string	最小借出数量,单位该币种
»» max_lend_amount	string	累计最大借出数量，单位USDT
»» max_rate	string	最大利率（小时）
»» min_rate	string	最小利率（小时）

# 查询单个理财币种详情

示例代码

# coding: utf-8
import requests

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

url = '/earn/uni/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/earn/uni/currencies/btc \
  -H 'Accept: application/json'

GET /earn/uni/currencies/{currency}

查询单个理财币种详情

参数

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

返回示例

200 返回

{
  "currency": "AE",
  "min_lend_amount": "100",
  "max_lend_amount": "200000000",
  "max_rate": "0.00057",
  "min_rate": "0.000001"
}

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

返回格式

状态码 200

借贷币种

名称	类型	描述
» currency	string	币种名称
» min_lend_amount	string	最小借出数量,单位该币种
» max_lend_amount	string	累计最大借出数量，单位USDT
» max_rate	string	最大利率（小时）
» min_rate	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 = '/earn/uni/lends'
query_param = ''
body='{"currency":"AE","amount":"100","min_rate":"0.00001","type":"lend"}'
# `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="/earn/uni/lends"
query_param=""
body_param='{"currency":"AE","amount":"100","min_rate":"0.00001","type":"lend"}'
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 /earn/uni/lends

创建理财或赎回

借出：在借出时需要设置最低借出利率，整点判定借出成功后按照判定的利率计算收益，
每个整点结算该小时收益，若由于利率过高导致借出失败则该小时无法获得利息，
若在整点判定前赎回资金则该小时无法获得利息。
关于优先级：相同利率下先创建或先修改的理财优先被借出。
赎回：借出失败的资金，赎回可立即到账，
对于借出成功的资金，享受该小时收益，赎回后将在下个整点到账。注意：整点前后两分钟为结算时间，禁止理财和赎回

请求体示例

{
  "currency": "AE",
  "amount": "100",
  "min_rate": "0.00001",
  "type": "lend"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» currency	body	string	是	币种名称
» amount	body	string	是	投入理财池数量
» type	body	string	是	操作类型 ; lend - 借出， redeem - 赎回
» min_rate	body	string	否	最小利率，如设置过高可能导致借出失败则该无法获得利息，借出时必填

# 枚举值列表

参数	值
» type	lend
» type	redeem

状态码	含义	描述	格式
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 = '/earn/uni/lends'
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="/earn/uni/lends"
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 /earn/uni/lends

查询用户币种理财列表

参数

名称	位置	类型	必选	描述
currency	请求参数	string	否	指定币种名称查询
page	请求参数	integer	否	列表页数
limit	请求参数	integer(int32)	否	列表返回的最大数量。默认为100，最小1，最大100。

返回示例

200 返回

[
  {
    "currency": "BTC",
    "current_amount": "20.999992",
    "amount": "20.999992",
    "lent_amount": "0",
    "frozen_amount": "0",
    "min_rate": "0.1",
    "interest_status": "interest_dividend",
    "reinvest_left_amount": 0,
    "create_time": 1673247054000,
    "update_time": 1673247054000
  }
]

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

返回格式

状态码 200

名称	类型	描述
» None	object	理财信息
»» currency	string	币种
»» current_amount	string	本次理财数量
»» amount	string	理财总数量
»» lent_amount	string	已借出数量
»» frozen_amount	string	已申请赎回未到账数量
»» min_rate	string	最小利率
»» interest_status	string	利息状态; interest_dividend - 正常派息, interest_reinvest - 利息复投
»» reinvest_left_amount	string	未复投金额
»» create_time	integer(int64)	理财创建时间
»» update_time	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 = '/earn/uni/lends'
query_param = ''
body='{"currency":"AE","min_rate":"0.0001"}'
# `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="/earn/uni/lends"
query_param=""
body_param='{"currency":"AE","min_rate":"0.0001"}'
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 /earn/uni/lends

修改用户理财信息

目前只支持修改最小利率（小时）

请求体示例

{
  "currency": "AE",
  "min_rate": "0.0001"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» currency	body	string	否	币种名称
» min_rate	body	string	否	最小利率

状态码	含义	描述	格式
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 = '/earn/uni/lend_records'
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="/earn/uni/lend_records"
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 /earn/uni/lend_records

查询理财的流水记录

参数

名称	位置	类型	必选	描述
currency	请求参数	string	否	指定币种名称查询
page	请求参数	integer	否	列表页数
limit	请求参数	integer(int32)	否	列表返回的最大数量。默认为100，最小1，最大100。
from	请求参数	integer(int64)	否	起始时间戳
to	请求参数	integer(int64)	否	终止时间戳
type	请求参数	string	否	操作类型 ; lend - 借出， redeem - 赎回

# 枚举值列表

参数	值
type	lend
type	redeem

返回示例

200 返回

[
  {
    "type": "lend",
    "currency": "BTC",
    "amount": "1",
    "last_wallet_amount": "0.2",
    "last_lent_amount": "0",
    "last_frozen_amount": "0",
    "create_time": 1673247054000
  }
]

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

返回格式

状态码 200

名称	类型	描述
» None	object	理财记录
»» currency	string	币种名称
»» amount	string	本次借出或赎回数量
»» last_wallet_amount	string	该记录之前待理财数量
»» last_lent_amount	string	该记录之前已借出数量
»» last_frozen_amount	string	该记录之前已冻结待待赎回数量
»» type	string	记录类型 lend - 借出 , redeem - 赎回
»» create_time	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 = '/earn/uni/interests/btc'
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="/earn/uni/interests/btc"
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 /earn/uni/interests/{currency}

查询用户单币种总利息收益

参数

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

返回示例

200 返回

{
  "currency": "AE",
  "interest": "123.345"
}

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

返回格式

状态码 200

UniLendInterest

名称	类型	描述
» currency	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 = '/earn/uni/interest_records'
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="/earn/uni/interest_records"
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 /earn/uni/interest_records

查询用户派息记录

参数

名称	位置	类型	必选	描述
currency	请求参数	string	否	指定币种名称查询
page	请求参数	integer	否	列表页数
limit	请求参数	integer(int32)	否	列表返回的最大数量。默认为100，最小1，最大100。

返回示例

200 返回

[
  {
    "status": 1,
    "currency": "AE",
    "actual_rate": "0.0005",
    "interest": "0.05",
    "interest_status": "interest_dividend",
    "create_time": 1673247054000
  }
]

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

返回格式

状态码 200

名称	类型	描述
» None	object	派息记录
»» status	integer	状态 0 - 失败 , 1 - 成功
»» currency	string	币种
»» actual_rate	string	真实利率
»» interest	string	利息
»» interest_status	string	利息状态; interest_dividend - 正常派息, interest_reinvest - 利息复投
»» create_time	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 = '/earn/uni/interest_reinvest'
query_param = ''
body='{"currency":"BTC","status":true}'
# `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="/earn/uni/interest_reinvest"
query_param=""
body_param='{"currency":"BTC","status":true}'
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 /earn/uni/interest_reinvest

设置利息复投开关

请求体示例

{
  "currency": "BTC",
  "status": true
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» currency	body	string	是	币种
» status	body	boolean	是	利息开关设置, true - 利息复投, false - 正常派息

状态码	含义	描述	格式
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 = '/earn/uni/interest_status/btc'
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="/earn/uni/interest_status/btc"
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 /earn/uni/interest_status/{currency}

查询币种利息复利状态

参数

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

返回示例

200 返回

{
  "currency": "BTC",
  "interest_status": "interest_dividend"
}

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

返回格式

状态码 200

UniCurrencyInterest

名称	类型	描述
» currency	string	币种
» interest_status	string	利息状态; interest_dividend - 正常派息, interest_reinvest - 利息复投

WARNING

该请求需要 API key 和 secret 认证

# Collateral-loan

抵押借币

# 抵押借币借贷下单

示例代码

# 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 = '/loan/collateral/orders'
query_param = ''
body='{"collateral_amount":"1","collateral_currency":"BTC","borrow_amount":"49","borrow_currency":"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="/loan/collateral/orders"
query_param=""
body_param='{"collateral_amount":"1","collateral_currency":"BTC","borrow_amount":"49","borrow_currency":"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 /loan/collateral/orders

抵押借币借贷下单

请求体示例

{
  "collateral_amount": "1",
  "collateral_currency": "BTC",
  "borrow_amount": "49",
  "borrow_currency": "USDT"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» collateral_amount	body	string	是	质押数量
» collateral_currency	body	string	是	质押币种
» borrow_amount	body	string	是	借款数量
» borrow_currency	body	string	是	借款币种

返回示例

200 返回

{
  "order_id": 123
}

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

返回格式

状态码 200

名称	类型	描述
» order_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 = '/loan/collateral/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="/loan/collateral/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 /loan/collateral/orders

查询抵押借币订单列表

参数

名称	位置	类型	必选	描述
page	请求参数	integer	否	列表页数
limit	请求参数	integer	否	列表返回的最大数量
collateral_currency	请求参数	string	否	质押币种
borrow_currency	请求参数	string	否	借款币种

返回示例

200 返回

[
  {
    "order_id": 10000421,
    "collateral_currency": "BTC",
    "borrow_currency": "USDT",
    "collateral_amount": "1",
    "borrow_amount": "1000",
    "repaid_amount": "10",
    "repaid_principal": "10",
    "repaid_interest": "0",
    "init_ltv": "0.0003934533764831",
    "current_ltv": "0.0004521768651985",
    "liquidate_ltv": "0.9",
    "status": "initial_status",
    "borrow_time": 1688462668,
    "left_repay_total": "990.0219384",
    "left_repay_interest": "0.0219384"
  }
]

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

返回格式

状态码 200

名称	类型	描述
None	array	[抵押借币订单]
» None	object	抵押借币订单
»» order_id	integer(int64)	订单id
»» collateral_currency	string	质押币种
»» collateral_amount	string	质押数量
»» borrow_currency	string	借款币种
»» borrow_amount	string	借款数量
»» repaid_amount	string	已还款数量
»» repaid_principal	string	已还本金
»» repaid_interest	string	已还利息
»» init_ltv	string	初始质押率
»» current_ltv	string	当前质押率
»» liquidate_ltv	string	平仓质押率
»» status	string	订单状态: - initial: 下单初始状态 - collateral_deducted: 扣除质押物成功 - collateral_returning: 放款失败-待退回质押物 - lent: 放款成功 - repaying: 还款中 - liquidating: 平仓中 - finished: 已完成 - closed_liquidated: 已结束-平仓还款结束
»» borrow_time	integer(int64)	借款时间，时间戳，单位秒
»» left_repay_total	string	待还本息（待还本金+待还利息）
»» left_repay_principal	string	待还本金
»» left_repay_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 = '/loan/collateral/orders/100001'
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="/loan/collateral/orders/100001"
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 /loan/collateral/orders/{order_id}

查询单个订单详情

参数

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

返回示例

200 返回

{
  "order_id": 10000421,
  "collateral_currency": "BTC",
  "borrow_currency": "USDT",
  "collateral_amount": "1",
  "borrow_amount": "1000",
  "repaid_amount": "10",
  "repaid_principal": "10",
  "repaid_interest": "0",
  "init_ltv": "0.0003934533764831",
  "current_ltv": "0.0004521768651985",
  "liquidate_ltv": "0.9",
  "status": "initial_status",
  "borrow_time": 1688462668,
  "left_repay_total": "990.0219384",
  "left_repay_interest": "0.0219384"
}

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

返回格式

状态码 200

抵押借币订单

名称	类型	描述
» order_id	integer(int64)	订单id
» collateral_currency	string	质押币种
» collateral_amount	string	质押数量
» borrow_currency	string	借款币种
» borrow_amount	string	借款数量
» repaid_amount	string	已还款数量
» repaid_principal	string	已还本金
» repaid_interest	string	已还利息
» init_ltv	string	初始质押率
» current_ltv	string	当前质押率
» liquidate_ltv	string	平仓质押率
» status	string	订单状态: - initial: 下单初始状态 - collateral_deducted: 扣除质押物成功 - collateral_returning: 放款失败-待退回质押物 - lent: 放款成功 - repaying: 还款中 - liquidating: 平仓中 - finished: 已完成 - closed_liquidated: 已结束-平仓还款结束
» borrow_time	integer(int64)	借款时间，时间戳，单位秒
» left_repay_total	string	待还本息（待还本金+待还利息）
» left_repay_principal	string	待还本金
» left_repay_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 = '/loan/collateral/repay'
query_param = ''
body='{"order_id":37438962,"repay_amount":"1000","repaid_all":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="/loan/collateral/repay"
query_param=""
body_param='{"order_id":37438962,"repay_amount":"1000","repaid_all":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 /loan/collateral/repay

抵押借币还款

请求体示例

{
  "order_id": 37438962,
  "repay_amount": "1000",
  "repaid_all": false
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» order_id	body	integer(int64)	是	订单id
» repay_amount	body	string	是	还款数量，部分还款时候是必须
» repaid_all	body	boolean	是	还款方式, 为`true`时全部还款, 为`false`时部分还款; 当为`false`部分还款时，不允许repay_amount参数大于用户剩余待还

返回示例

200 返回

{
  "repaid_principal": "11",
  "repaid_interest": "111"
}

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

返回格式

状态码 200

还款

名称	类型	描述
» repaid_principal	string	本金
» repaid_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 = '/loan/collateral/repay_records'
query_param = 'source=repay'
# `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="/loan/collateral/repay_records"
query_param="source=repay"
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 /loan/collateral/repay_records

查询抵押借币还款记录

参数

名称	位置	类型	必选	描述
source	请求参数	string	是	操作类型 ; repay - 普通还款, liquidate - 平仓
borrow_currency	请求参数	string	否	借款币种
collateral_currency	请求参数	string	否	质押币种
page	请求参数	integer	否	列表页数
limit	请求参数	integer	否	列表返回的最大数量
from	请求参数	integer(int64)	否	查询记录的起始时间
to	请求参数	integer(int64)	否	查询记录的结束时间，不指定则默认为当前时间

返回示例

200 返回

[
  {
    "order_id": 10000425,
    "record_id": 181,
    "repaid_amount": "10.00000000000000000000",
    "borrow_currency": "USDT",
    "collateral_currency": "BTC",
    "collateral_amount": "1.00000000000000000000",
    "init_ltv": "0.00039345337648310000",
    "borrow_time": 1688471851,
    "repay_time": 1688526310,
    "total_interest": "0.25446901544300000000",
    "before_left_principal": "11.00000000",
    "pre_left_principal": "990.00000000000000000000",
    "after_left_principal": "990.00000000000000000000",
    "before_left_collateral": "1.00000000000000000000",
    "after_left_collateral": "1.00000000000000000000"
  }
]

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

返回格式

状态码 200

名称	类型	描述
» None	object	还款记录
»» order_id	integer(int64)	订单id
»» record_id	integer(int64)	还款记录 id
»» repaid_amount	string	还款数量
»» borrow_currency	string	借款币种
»» collateral_currency	string	质押币种
»» init_ltv	string	初始质押率
»» borrow_time	integer(int64)	借款时间，时间戳
»» repay_time	integer(int64)	还款时间，时间戳
»» total_interest	string	总计息
»» before_left_principal	string	还款前待还本金
»» after_left_principal	string	还款后待还本金
»» before_left_collateral	string	还款前质押物数量
»» after_left_collateral	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 = '/loan/collateral/collaterals'
query_param = ''
body='{"collateral_amount":"1212","collateral_currency":"BTC","order_id":1130,"type":"append"}'
# `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="/loan/collateral/collaterals"
query_param=""
body_param='{"collateral_amount":"1212","collateral_currency":"BTC","order_id":1130,"type":"append"}'
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 /loan/collateral/collaterals

增加或赎回质押物

请求体示例

{
  "collateral_amount": "1212",
  "collateral_currency": "BTC",
  "order_id": 1130,
  "type": "append"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» order_id	body	integer(int64)	是	订单id
» collateral_currency	body	string	是	质押币种
» collateral_amount	body	string	是	质押数量
» type	body	string	是	操作类型, append - 补充 , redeem - 提取

状态码	含义	描述	格式
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 = '/loan/collateral/collaterals'
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="/loan/collateral/collaterals"
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 /loan/collateral/collaterals

查询质押物调整记录

参数

名称	位置	类型	必选	描述
page	请求参数	integer	否	列表页数
limit	请求参数	integer	否	列表返回的最大数量
from	请求参数	integer(int64)	否	查询记录的起始时间
to	请求参数	integer(int64)	否	查询记录的结束时间，不指定则默认为当前时间
borrow_currency	请求参数	string	否	借款币种
collateral_currency	请求参数	string	否	质押币种

返回示例

200 返回

[
  {
    "order_id": 10000417,
    "record_id": 10000452,
    "borrow_currency": "USDT",
    "borrow_amount": "1000.00000000000000000000",
    "collateral_currency": "BTC",
    "pre_collateral": "1.00000000000000000000",
    "after_collateral": "2.00000000000000000000",
    "pre_ltv": "0.00039345555621480000",
    "after_ltv": "0.00019672777810740000",
    "operate_time": 1688461924
  }
]

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

返回格式

状态码 200

名称	类型	描述
» None	object	质押物记录
»» order_id	integer(int64)	订单id
»» record_id	integer(int64)	质押物记录 id
»» borrow_currency	string	借款币种
»» borrow_amount	string	借款数量
»» collateral_currency	string	质押币种
»» before_collateral	string	调整前质押数量
»» after_collateral	string	调整后质押数量
»» before_ltv	string	调整前质押率
»» after_ltv	string	调整后质押率
»» operate_time	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 = '/loan/collateral/total_amount'
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="/loan/collateral/total_amount"
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 /loan/collateral/total_amount

查询用户总借贷与质押数量

返回示例

200 返回

{
  "borrow_amount": "11",
  "collateral_amount": "111"
}

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

返回格式

状态码 200

用户总借贷與质押金额

名称	类型	描述
» borrow_amount	string	借贷总额，以 USDT 计算
» collateral_amount	string	质押总额，以 USDT 计算

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 = '/loan/collateral/ltv'
query_param = 'collateral_currency=BTC&borrow_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="/loan/collateral/ltv"
query_param="collateral_currency=BTC&borrow_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 /loan/collateral/ltv

查询用户质押率和可借剩余币种

参数

名称	位置	类型	必选	描述
collateral_currency	请求参数	string	是	质押币种
borrow_currency	请求参数	string	是	借款币种

返回示例

200 返回

{
  "collateral_currency": "BTC",
  "borrow_currency": "USDT",
  "init_ltv": "0.7",
  "alert_ltv": "0.8",
  "liquidate_ltv": "0.9",
  "min_borrow_amount": "3",
  "left_borrowable_amount": "4233030.635065916703"
}

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

返回格式

状态码 200

用户币种统计数据

名称	类型	描述
» collateral_currency	string	质押币种
» borrow_currency	string	借款币种
» init_ltv	string	初始质押率
» alert_ltv	string	预警质押率
» liquidate_ltv	string	平仓质押率
» min_borrow_amount	string	借款币种的最小可借数量
» left_borrowable_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 = '/loan/collateral/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())


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

GET /loan/collateral/currencies

查询支持的借款币种和抵押币种

参数

名称	位置	类型	必选	描述
loan_currency	请求参数	string	否	借款币种参数,当loan_currency没传时会返回支持的所有借款币种,当传loan_currency时会查询该借款币种支持的抵押币种数组

返回示例

200 返回

[
  {
    "loan_currency": "BTC",
    "collateral_currency": [
      "BTC",
      "ETH",
      "GT"
    ]
  }
]

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

返回格式

状态码 200

名称	类型	描述
» None	object	支持的借款币种和抵押币种
»» loan_currency	string	借款币种
»» collateral_currency	array	支持的抵押币种列表

# Account

获取用户账户信息

# 获取用户账户信息

示例代码

# 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 = '/account/detail'
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="/account/detail"
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 /account/detail

获取用户账户信息

返回示例

200 返回

{
  "user_id": 1667201533,
  "ip_whitelist": [
    "127.0.0.1"
  ],
  "currency_pairs": [
    "USDT_BTC"
  ],
  "key": {
    "mode": 1
  },
  "tier": 2
}

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

返回格式

状态码 200

AccountDetail

名称	类型	描述
» ip_whitelist	array	IP 白名单
» currency_pairs	array	交易对白名单
» user_id	integer(int64)	用户ID
» tier	integer(int64)	用户 vip 等级
» key	object	API Key 详情
»» mode	integer(int32)	模式： 1 - 经典模式 2 - 统一模式

WARNING

该请求需要 API key 和 secret 认证

# 新建STP用户组

示例代码

# 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 = '/account/stp_groups'
query_param = ''
body='{"name":"stp_name"}'
# `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="/account/stp_groups"
query_param=""
body_param='{"name":"stp_name"}'
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 /account/stp_groups

新建STP用户组

只允许用户主账号新建STP用户组

请求体示例

{
  "name": "stp_name"
}

参数

名称	位置	类型	必选	描述
body	body	object	是
» id	body	integer(int64)	否	STP用户组ID
» name	body	string	是	STP用户组名称
» creator_id	body	integer(int64)	否	创建人账户ID
» create_time	body	integer(int64)	否	创建时间

返回示例

200 返回

{
  "id": 123435,
  "name": "group",
  "create_time": 1548000000,
  "creator_id": 10000
}

状态码	含义	描述	格式
200	OK (opens new window)	添加用户成功，返回当前STP组内用户	Inline

返回格式

状态码 200

名称	类型	描述
» id	integer(int64)	STP用户组ID
» name	string	STP用户组名称
» creator_id	integer(int64)	创建人账户ID
» create_time	integer(int64)	创建时间

WARNING

该请求需要 API key 和 secret 认证

# 查询用户创建的STP用户组

示例代码

# 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 = '/account/stp_groups'
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="/account/stp_groups"
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 /account/stp_groups

查询用户创建的STP用户组

只查询当前主账号用户新建的 STP 用户组列表

参数

名称	位置	类型	必选	描述
name	请求参数	string	否	根据名称模糊查询

返回示例

200 返回

[
  {
    "id": 123435,
    "name": "group",
    "create_time": 1548000000,
    "creator_id": 10000
  }
]

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

返回格式

状态码 200

名称	类型	描述
None	array
» id	integer(int64)	STP用户组ID
» name	string	STP用户组名称
» creator_id	integer(int64)	创建人账户ID
» create_time	integer(int64)	创建时间

WARNING

该请求需要 API key 和 secret 认证

# 查询STP用户组中的用户

示例代码

# 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 = '/account/stp_groups/1/users'
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="/account/stp_groups/1/users"
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 /account/stp_groups/{stp_id}/users

查询STP用户组中的用户

只允许创建此STP组的主账户查询当前STP组的账户ID列表

参数

名称	位置	类型	必选	描述
stp_id	URL	integer(int64)	是	STP用户组ID

返回示例

200 返回

[
  {
    "user_id": 10000,
    "stp_id": 1,
    "create_time": 1548000000
  }
]

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

返回格式

状态码 200

名称	类型	描述
None	array
» user_id	integer(int64)	用户ID
» stp_id	integer(int64)	STP用户组ID
» create_time	integer(int64)	创建时间

WARNING

该请求需要 API key 和 secret 认证

# STP用户组中添加用户

示例代码

# 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 = '/account/stp_groups/1/users'
query_param = ''
body='[1,2,3]'
# `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="/account/stp_groups/1/users"
query_param=""
body_param='[1,2,3]'
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 /account/stp_groups/{stp_id}/users

STP用户组中添加用户

只允许创建此STP组的主账号添加STP用户组用户
只允许添加当前主账户下的账户，不允许跨主账户

请求体示例

[
  1,
  2,
  3
]

参数

名称	位置	类型	必选	描述
stp_id	URL	integer(int64)	是	STP用户组ID
body	body	array[integer]	是	用户ID

返回示例

200 返回

[
  {
    "user_id": 10000,
    "stp_id": 1,
    "create_time": 1548000000
  }
]

状态码	含义	描述	格式
200	OK (opens new window)	添加用户成功，返回当前STP组内用户	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» user_id	integer(int64)	用户ID
» stp_id	integer(int64)	STP用户组ID
» create_time	integer(int64)	创建时间

WARNING

该请求需要 API key 和 secret 认证

# STP用户组中删除用户

示例代码

# 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 = '/account/stp_groups/1/users'
query_param = ''
body='[1,2,3]'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('DELETE', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('DELETE', 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="DELETE"
url="/account/stp_groups/1/users"
query_param=""
body_param='[1,2,3]'
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"

DELETE /account/stp_groups/{stp_id}/users

STP用户组中删除用户

只允许创建此STP组的主账号删除STP用户组用户
只允许删除当前主账户下的账户，不允许跨主账户

请求体示例

[
  1,
  2,
  3
]

参数

名称	位置	类型	必选	描述
stp_id	URL	integer(int64)	是	STP用户组ID
body	body	array[integer]	是	用户ID

返回示例

200 返回

[
  {
    "user_id": 10000,
    "stp_id": 1,
    "create_time": 1548000000
  }
]

状态码	含义	描述	格式
200	OK (opens new window)	删除用户成功，返回当前STP组内用户	[Inline]

返回格式

状态码 200

名称	类型	描述
None	array
» user_id	integer(int64)	用户ID
» stp_id	integer(int64)	STP用户组ID
» create_time	integer(int64)	创建时间

WARNING

该请求需要 API key 和 secret 认证

# Rebate

代理商接口

# 代理商获取推荐用户的交易记录

示例代码

# 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 = '/rebate/agency/transaction_history'
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="/rebate/agency/transaction_history"
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 /rebate/agency/transaction_history

代理商获取推荐用户的交易记录

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

参数

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

返回示例

200 返回

{
  "total": 100,
  "list": [
    {
      "transaction_time": 1539852480,
      "user_id": 10000,
      "group_name": "gateio",
      "fee": "1",
      "fee_asset": "GT",
      "currency_pair": "GT_USDT",
      "amount": "1000",
      "source": "SPOT",
      "amount_asset": "GT"
    }
  ]
}

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

返回格式

状态码 200

名称	类型	描述
» currency_pair	string	交易对
» total	integer(int64)	该查询下数据总数
» list	array	交易列表
»» AgencyTransaction	object
»»» transaction_time	integer(int64)	交易时间，秒级 Unix 时间戳
»»» user_id	integer(int64)	用户 ID
»»» group_name	string	分组名称
»»» fee	string	手续费数量
»»» fee_asset	string	手续费币种
»»» currency_pair	string	交易对
»»» amount	string	交易金额数量
»»» amount_asset	string	交易金额币种
»»» source	string	返佣交易类型, SPOT - 现货返佣, FUTURES - 合约返佣

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 = '/rebate/agency/commission_history'
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="/rebate/agency/commission_history"
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 /rebate/agency/commission_history

代理商获取推荐用户的返佣记录

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

参数

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

返回示例

200 返回

{
  "total": 100,
  "list": [
    {
      "commission_time": 1539852480,
      "user_id": 10000,
      "group_name": "gateio",
      "commission_amount": "1000",
      "source": "SPOT",
      "commission_asset": "GT"
    }
  ]
}

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

返回格式

状态码 200

名称	类型	描述
» currency_pair	string	交易对
» total	integer(int64)	该查询下数据总数
» list	array	返佣列表
»» AgencyCommission	object
»»» commission_time	integer(int64)	返佣时间，秒级 Unix 时间戳
»»» user_id	integer(int64)	用户ID
»»» group_name	string	分组名称
»»» commission_amount	string	交易金额数量
»»» commission_asset	string	交易金额币种
»»» source	string	返佣交易类型, SPOT - 现货返佣, FUTURES - 合约返佣

WARNING

该请求需要 API key 和 secret 认证

# 模型

# SubAccountKey

{
  "user_id": "string",
  "mode": 0,
  "name": "string",
  "perms": [
    {
      "name": "wallet",
      "read_only": true
    }
  ],
  "ip_whitelist": [
    "string"
  ],
  "key": "string",
  "state": 0,
  "created_at": "string",
  "updated_at": "string"
}

# 属性

名称	类型	必选	限制	描述
user_id	string	false	只读	用户ID
mode	integer(int32)	false	none	模式 1 - 经典帐户 2 - 统一账户
name	string	false	none	API Key名称
perms	array	false	none	none
» ApiV4KeyPerm	object	false	none	none
»» name	string	false	none	权限功能名称（不传值即为清空） - wallet: 钱包 - spot: 现货/杠杆 - futures: 永续合约 - delivery: 交割合约 - earn: 理财 - options: 期权 - account: 账户信息 - portfolio: 保证金 - loan: 借贷
»» read_only	boolean	false	none	该功能是否只读
» ip_whitelist	array	false	none	IP白名单列表（不传值即为清空）
» key	string	false	只读	API Key
» state	integer(int32)	false	只读	状态 1 - 正常 2 - 冻结 3 - 锁定
» created_at	string	false	只读	创建时间
» updated_at	string	false	只读	最近更新时间

# 枚举值列表

属性	值
name	wallet
name	spot
name	futures
name	delivery
name	earn
name	options
name	account
name	portfolio
name	loan

# CurrencyPair

{
  "id": "string",
  "base": "string",
  "quote": "string",
  "fee": "string",
  "min_base_amount": "string",
  "min_quote_amount": "string",
  "max_base_amount": "string",
  "max_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 表示无限制
max_base_amount	string	false	none	交易货币最大交易数量，null 表示无限制
max_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",
  "amend_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",
  "avg_deal_price": "string",
  "fee": "string",
  "fee_currency": "string",
  "point_fee": "string",
  "gt_fee": "string",
  "gt_maker_fee": "string",
  "gt_taker_fee": "string",
  "gt_discount": true,
  "rebated_fee": "string",
  "rebated_fee_currency": "string",
  "stp_id": 0,
  "stp_act": "cn",
  "finish_as": "open"
}

现货单详情

# 属性

名称	类型	必选	限制	描述
id	string	false	只读	订单 ID
text	string	false	none	订单自定义信息，用户可以用该字段设置自定义 ID，用户自定义字段必须满足以下条件： 1. 必须以 `t-` 开头 2. 不计算 `t-` ，长度不能超过 28 字节 3. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.) 除用户自定义信息以外，以下为内部保留字段，标识订单来源: 101 代表 `android` 下单 102 代表 `IOS` 下单 103 代表 `IPAD` 下单 104 代表 `webapp` 下单 3 代表 `web` 下单 2 代表 `apiv2` 下单 apiv4 代表 `apiv4` 下单
amend_text	string	false	只读	用户修改订单时备注的信息
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 : 限价单 - market : 市价单
account	string	false	none	账户类型，spot - 现货账户，margin - 杠杆账户，cross_margin - 全仓杠杆账户，portfolio - 保证金账户统一账户只能设置 `cross_margin`
side	string	true	none	买单或者卖单
amount	string	true	none	交易数量 `type`为`limit`时，指交易货币，即需要交易的货币，如`BTC_USDT`中指`BTC`。 `type`为`market`时，根据买卖不同指代不同 - `side` : `buy` 指代计价货币，`BTC_USDT`中指`USDT` - `side` : `sell` 指代交易货币，`BTC_USDT`中指`BTC`
price	string	false	none	交易价,`type`=`limit`时必填
time_in_force	string	false	none	Time in force 策略。 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled，立即成交或者取消，只吃单不挂单 - poc: PendingOrCancelled，被动委托，只挂单不吃单 - fok: FillOrKill，全部成交或者全部取消 `type`=`market`时仅支持`ioc`和`fok`
iceberg	string	false	none	冰山下单显示的数量，不指定或传 0 都默认为普通下单。目前不支持全部冰山。
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	只读	已成交总金额
avg_deal_price	string	false	只读	平均成交价
fee	string	false	只读	成交扣除的手续费
fee_currency	string	false	只读	手续费计价单位
point_fee	string	false	只读	手续费抵扣使用的点卡数量
gt_fee	string	false	只读	手续费抵扣使用的 GT 数量
gt_maker_fee	string	false	只读	手续费maker抵扣使用的 GT 数量
gt_taker_fee	string	false	只读	手续费taker抵扣使用的 GT 数量
gt_discount	boolean	false	只读	是否开启GT抵扣
rebated_fee	string	false	只读	返还的手续费
rebated_fee_currency	string	false	只读	返还手续费计价单位
stp_id	integer	false	只读	订单所属的`STP用户组`id，同一个`STP用户组`内用户之间的订单不允许发生自成交。 1. 如果撮合时两个订单的 `stp_id` 非 `0` 且相等，则不成交，而是根据 `taker` 的 `stp_act` 执行相应策略。 2. 没有设置`STP用户组`成交的订单，`stp_id` 默认返回 `0`。
stp_act	string	false	none	Self-Trading Prevention Action,用户可以用该字段设置自定义限制自成交策略。 1. 用户在设置加入`STP用户组`后，可以通过传递 `stp_act` 来限制用户发生自成交的策略，没有传递 `stp_act` 默认按照 `cn` 的策略。 2. 用户在没有设置加入`STP用户组`时，传递 `stp_act` 参数会报错。 3. 用户没有使用 `stp_act` 发生成交的订单，`stp_act` 返回 `-`。 - cn: Cancel newest,取消新订单，保留老订单 - co: Cancel oldest,取消⽼订单，保留新订单 - cb: Cancel both,新旧订单都取消
finish_as	string	false	只读	订单结束方式，包括： - open: 等待处理 - filled: 完全成交 - cancelled: 用户撤销 - ioc: 未立即完全成交，因为 tif 设置为 ioc - stp: 订单发生自成交限制而被撤销

# 枚举值列表

属性	值
status	open
status	closed
status	cancelled
type	limit
type	market
account	spot
account	margin
account	cross_margin
account	portfolio
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	ioc
finish_as	stp

# CancelBatchOrder

{
  "currency_pair": "string",
  "id": "string",
  "account": "string"
}

需要撤销的订单信息

# 属性

名称	类型	必选	限制	描述
currency_pair	string	true	none	订单的交易对
id	string	true	none	订单 ID 或者用户自定义 ID 。如果使用自定义 ID，只能在订单创建后的 30 分钟内有效
account	string	false	none	撤销的订单如果是全仓杠杆账户订单或是统一账户apikey，该字段必须指定且设置为 `cross_margin`

# 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.0001 - 0.01 这个范围的利率。借出时可不设置该字段，由系统根据该币种最近的市场利率来设置。
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

# EstimateRate

{
  "property1": "string",
  "property2": "string"
}

预估当前小时的借贷利率，按币种进行返回

# 属性

名称	类型	必选	限制	描述
additionalProperties	string	false	none	none

# 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	订单类型，默认为限价单 - limit : 限价单 - market : 市价单
» side	string	true	none	买卖方向 - buy: 买 - sell: 卖
» price	string	true	none	挂单价格
» amount	string	true	none	交易数量 `type`为`limit`时，指交易货币，即需要交易的货币，如`BTC_USDT`中指`BTC`。 `type`为`market`时，根据买卖不同指代不同 - `side` : `buy` 指代计价货币，`BTC_USDT`中指`USDT` - `side` : `sell` 指代交易货币，`BTC_USDT`中指`BTC`
» 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	<=
type	limit
type	market
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,
  "enable_bonus": true,
  "enable_credit": true,
  "create_time": 0,
  "funding_cap_ratio": "string"
}

合约详情

# 属性

名称	类型	必选	限制	描述
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	最多挂单数量
enable_bonus	boolean	false	none	是否支持体验金
enable_credit	boolean	false	none	是否支持统一账户
create_time	number(double)	false	none	表示合约的创建时间
funding_cap_ratio	string	false	none	资金费率上限的系数。资金费率上限 = (1/市场最大杠杆 - 维持保证金率) * funding_cap_ratio

# 枚举值列表

属性	值
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",
  "update_time": 0
}

合约仓位详情

# 属性

名称	类型	必选	限制	描述
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个等级，`1` 最高，`5` 最低，特殊情况 `6` 是没有持仓或在爆仓中
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 时）
update_time	integer(int64)	false	只读	最后更新时间

# 枚举值列表

属性	值
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",
  "stp_id": 0,
  "stp_act": "co",
  "amend_text": "string",
  "biz_info": "string"
}

合约订单详情

# 属性

名称	类型	必选	限制	描述
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: 只减仓被排除的不容易成交的挂单 - stp: 订单发生自成交限制而被撤销
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
stp_id	integer	false	只读	订单所属的`STP用户组`id，同一个`STP用户组`内用户之间的订单不允许发生自成交。 1. 如果撮合时两个订单的 `stp_id` 非 `0` 且相等，则不成交，而是根据 `taker` 的 `stp_act` 执行相应策略。 2. 没有设置`STP用户组`成交的订单，`stp_id` 默认返回 `0`。
stp_act	string	false	none	Self-Trading Prevention Action,用户可以用该字段设置自定义限制自成交策略。 1. 用户在设置加入`STP用户组`后，可以通过传递 `stp_act` 来限制用户发生自成交的策略，没有传递 `stp_act` 默认按照 `cn` 的策略。 2. 用户在没有设置加入`STP用户组`时，传递 `stp_act` 参数会报错。 3. 用户没有使用 `stp_act` 发生成交的订单，`stp_act` 返回 `-`。 - cn: Cancel newest,取消新订单，保留老订单 - co: Cancel oldest,取消⽼订单，保留新订单 - cb: Cancel both,新旧订单都取消
amend_text	string	false	只读	用户修改订单时备注的信息
biz_info	string	false	只读	附加信息

# 枚举值列表

属性	值
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
finish_as	stp
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok
auto_size	close_long
auto_size	close_short
stp_act	co
stp_act	cn
stp_act	cb
stp_act	-

# 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

Last Updated: 11/24/2023, 10:31:47 AM

# Gate API v4 v4.59.0

# 访问链接

# SDK

# 关于APIv4 Key升级

# 与 APIv2 的区别

# 市商申请

# 技术支持

# Changelog

# General

# 匹配机制

# 匹配优先级

# 订单生命周期

# 数据中心

# 接口概览

# 逐仓迁移说明

# API

# HTTP 通用格式

# 时间

# 网关入出站时间

# 分页

# 限频规则

# 返回格式

# 数据类型

# 统一帐户

# 资金划转

# 现货交易

# 永续合约交易

# 请求ID

# Self-Trade Prevention(STP)

# 名词解释

# 成交策略

# 接口参数调整

# 使用场景

# 保证金账户体系

# 说明

# 保证金公式

# 资产流水类型

# 通用

# 订单

# 充提

# Startup

# 返佣

# 兑换

# C2C

# 奖励

# 账户出入金

# 点卡

# 金融

# 借贷

# 币圈

# PUSH交易

# 量化跟单

# NFT

# 异常处理

# 异常 label 列表

# 认证

# 生成 API key

# APIv4 权限

# APIv4 验签请求接口发送要求

# APIv4 签名字符串生成方式

# Request Method

# Request URL

# Query String

# HexEncode(SHA512(Request Payload))

# Timestamp

# 常见问题

# Withdrawal

# 提现

参数

返回

返回格式

# 枚举值列表

# 取消指定 ID 的提现操作

参数

返回

返回格式

# 枚举值列表

# Wallet

# 查询币种支持的链

参数

# 异常 `label` 列表