NAV Navbar
Python Shell

Gate API v4 v4.20.0

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

欢迎使用 Gate.io API

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

访问链接

REST API BaseURL:

WebSocket API BaseURL:

现货 WebSocket 新版:wss://api.gateio.ws/ws/v4/

现货 WebSocket 旧版

WebSocket 文档

现货交易

永续合约

交割合约

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 标准 书写,SDK 和文档通过同一套 API 标准生成,确保文档和程序的完整一致。

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

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

如何选择:

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

市商申请

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

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

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

技术支持

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

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

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

Changelog

v4.20.0

2020-03-25

v4.19.6

2020-03-22

v4.19.5

2020-03-18

v4.19.4

2020-03-10

v4.19.3

2021-03-04

v4.19.2

2021-03-01

v4.18.4

2021-01-22

v4.18.1

2021-01-07

v4.18.0

2020-12-21

v4.17.1

2020-12-16

v4.17.0

2020-12-15

v4.16.1

2020-12-10

v4.16.0

2020-12-09

现货

合约

v4.15.5

2020-11-04

v4.15.4

2020-09-01

v4.15.2

2020-08-12

v4.15.1

2020-08-04

v4.14.1

2020-07-08

v4.14.0

2020-07-06

v4.13.1

2020-06-28

v4.13.0

2020-05-20

v4.12.0

2020-04-08

v4.11.2

2020-03-29

v4.11.1

2020-03-23

v4.11.0

2020-03-20

v4.10.1

2020-02-24

v4.10.0

2020-02-17

v4.9.1

2020-01-07

v4.9.0

2019-12-17

v4.8.2

2019-12-02

v4.8.1

2019-11-27

v4.8.0

2019-11-07

/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

v4.6.3

2019-06-11

v4.7.2

2019-05-29

v4.7.1

2019-04-17

v4.6.2

2019-04-24

v4.6.1

2019-04-02

v4.6.0

2019-03-21

只影响 SDK

v4.5.2

2019-03-14

v4.5.1

2019-03-11

v4.5.0

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

2019-03-05

v1.3.0

2019-02-13

重要更新

v1.2.1

2019-02-13

v1.2.0

2019-01-17

v1.1.0

2019-01-08

v1.0.0

2018-12-30

General

匹配机制

匹配优先级

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

假设订单簿情况如下:

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

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

订单生命周期

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

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

数据中心

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

接口概览

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

API

HTTP 通用格式

时间

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

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

分页

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

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

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

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

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

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

如果使用 limit-offset 方法,则是:

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

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

限频规则

提现:

现货:

合约:

返回格式

所有的接口返回都是 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 为假

异常处理

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

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

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

以 Python requests 为例,异常的处理流程可以参考如下所示:

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

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 为示例:

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 账户无权执行该操作
label 含义
SUB_ACCOUNT_NOT_FOUND 子账户不存在
SUB_ACCOUNT_LOCKED 子账号被冻结
MARGIN_BALANCE_EXCEPTION 杠杆账户异常
MARGIN_TRANSFER_FAILED 杠杆资金划转失败
TOO_MUCH_FUTURES_AVAILABLE 合约账户总资产达到上限
FUTURES_BALANCE_NOT_ENOUGH 合约账户余额不足
ACCOUNT_EXCEPTION 账户异常
SUB_ACCOUNT_TRANSFER_FAILED 子账户资金划转失败
ADDRESS_NOT_USED 指定的钱包地址未在网页执行过划转
TOO_FAST 提现频率过快
WITHDRAWAL_OVER_LIMIT 超出提现额度
label 含义
INVALID_PRECISION 无效的精度
INVALID_CURRENCY 无效的币种信息
INVALID_CURRENCY_PAIR 无效的交易对
POC_FILL_IMMEDIATELY 被动委托会立即成交
ORDER_NOT_FOUND 订单不存在
ORDER_CLOSED 订单已结束
ORDER_CANCELLED 订单已撤销
QUANTITY_NOT_ENOUGH 数量不足
BALANCE_NOT_ENOUGH 余额不足
MARGIN_NOT_SUPPORTED 该交易对不支持杠杆交易
MARGIN_BALANCE_NOT_ENOUGH 杠杆账户余额不足
AMOUNT_TOO_LITTLE 数额小于最低值
AMOUNT_TOO_MUCH 数额过大
REPEATED_CREATION 重复创建
LOAN_NOT_FOUND 借贷订单不存在
LOAN_RECORD_NOT_FOUND 借贷记录不存在
NO_MATCHED_LOAN 没有借贷记录能满足借入需求
NOT_MERGEABLE 借贷单不可合并
NO_CHANGE 修改的参数与当前状态无区别
REPAY_TOO_MUCH 还款数额超出借款数额
TOO_MANY_CURRENCY_PAIRS 批量下单指定了过多交易对
TOO_MANY_ORDERS 批量下单的单个交易对下单数过多
MIXED_ACCOUNT_TYPE 批量下单中使用了多个账户类型
AUTO_BORROW_TOO_MUCH 自动借入超出最多可借
TRADE_RESTRICTED 高负债率导致交易操作被限制
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 当前合约市场处于下线过渡期,只允许创建只减仓委托或者平仓委托
label 含义
INTERNAL 内部错误
SERVER_ERROR 内部错误
TOO_BUSY 服务当前忙

认证

生成 API key

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

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

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

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

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

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

APIv4 权限

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

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

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

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

APIv4 验签请求接口发送要求

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

APIv4 签名字符串生成方式

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

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

Request Method

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

Request URL

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

Query String

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

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

HexEncode(SHA512(Request Payload))

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

Timestamp

设置在请求头部 Timestamp 里的值

示例

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

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

  1. 查询所有合约订单
    GET /api/v4/futures/orders?contract=BTC_USD&status=finished&limit=50 HTTP/1.1

签名字符串:

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

说明

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

签名结果

55f84ea195d6fe57ce62464daaa7c3c02fa9d1dde954e4c898289c9a2407a3d6fb3faf24deff16790d726b66ac9f74526668b13bd01029199cc4fcc522418b8a

  1. 创建合约委托
    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)

常见问题

Withdrawal

提现接口

提现

Code samples

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

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

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

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

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

POST /withdrawals

提现

Body parameter

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

参数

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

返回示例

202 返回

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

返回

状态码 含义 描述 格式
202 Accepted 提现请求已受理,处理结果查看该提现记录状态 Inline

返回格式

状态码 202

名称 类型 描述
» id string 交易记录 ID
» txid string 区块转账哈希记录
» timestamp string 操作时间
» amount string 币的数量
» currency string 币种名称
» address string 提现地址。提现操作必填
» memo string 转账memo等备注信息
» status string 交易状态

- DONE: 完成
- CANCEL: 已取消
- REQUEST: 请求中
- MANUAL: 待人工审核
- BCODE: 充值码操作
» chain string 提现的链名称

枚举值列表

属性
status DONE
status CANCEL
status REQUEST
status MANUAL
status BCODE

Wallet

钱包接口

获取币种充值地址

Code samples

# coding: utf-8
import 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_address": [
    {
      "chain": "TRX",
      "address": "LPXtk1kWHioP62SzfqwKbYE3Z7Wt2ujYEc",
      "payment_id": "",
      "payment_name": "",
      "obtain_failed": 0
    }
  ]
}

返回

状态码 含义 描述 格式
200 OK 地址获取成功 Inline

返回格式

状态码 200

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

获取提现记录

Code samples

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

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

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

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

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

GET /wallet/withdrawals

获取提现记录

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

参数

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

返回示例

200 返回

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

返回

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

返回格式

状态码 200

名称 类型 描述
None array
» id string 交易记录 ID
» txid string 区块转账哈希记录
» timestamp string 操作时间
» amount string 币的数量
» currency string 币种名称
» address string 提现地址。提现操作必填
» memo string 转账memo等备注信息
» status string 交易状态

- DONE: 完成
- CANCEL: 已取消
- REQUEST: 请求中
- MANUAL: 待人工审核
- BCODE: 充值码操作
» chain string 提现的链名称

枚举值列表

属性
status DONE
status CANCEL
status REQUEST
status MANUAL
status BCODE

获取充值记录

Code samples

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

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

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

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

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

GET /wallet/deposits

获取充值记录

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

参数

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

返回示例

200 返回

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

返回

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

返回格式

状态码 200

名称 类型 描述
None array
» id string 交易记录 ID
» txid string 区块转账哈希记录
» timestamp string 操作时间
» amount string 币的数量
» currency string 币种名称
» address string 提现地址。提现操作必填
» memo string 转账memo等备注信息
» status string 交易状态

- DONE: 完成
- CANCEL: 已取消
- REQUEST: 请求中
- MANUAL: 待人工审核
- BCODE: 充值码操作
» chain string 提现的链名称

枚举值列表

属性
status DONE
status CANCEL
status REQUEST
status MANUAL
status BCODE

交易账户互转

Code samples

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

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

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

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

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

POST /wallet/transfers

交易账户互转

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

  1. 现货账户 - 杠杆账户
  2. 现货账户 - 永续合约账户
  3. 现货账户 - 交割合约账户

Body parameter

{
  "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 合约结算币种。 currency 设置为 POINT 时必填

枚举值列表

参数
» from spot
» from margin
» from futures
» from delivery
» to spot
» to margin
» to futures
» to delivery

返回

状态码 含义 描述 格式
204 No Content 转账操作成功

主子账号互转

Code samples

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

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

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

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

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

POST /wallet/sub_account_transfers

主子账号互转

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

Body parameter

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

参数

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

枚举值列表

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

返回

状态码 含义 描述 格式
204 No Content 转账操作成功

主子账号划转记录

Code samples

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

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

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

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

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

GET /wallet/sub_account_transfers

主子账号划转记录

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

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

参数

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

返回示例

200 返回

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

返回

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

返回格式

状态码 200

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

枚举值列表

属性
direction to
direction from
sub_account_type spot
sub_account_type futures

查询提现状态

Code samples

# coding: utf-8
import 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"
  }
]

返回

状态码 含义 描述 格式
200 OK 列表获取成功 [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 单次最多提现额度

查询子账号余额信息

Code samples

# coding: utf-8
import 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 列表获取成功 [Inline]

返回格式

状态码 200

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

查询个人交易费率

Code samples

# coding: utf-8
import 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

查询个人交易费率

返回示例

200 返回

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

返回

状态码 含义 描述 格式
200 OK 查询成功 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 费率

Spot

现货交易

查询所有币种信息

Code samples

# 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

查询所有币种信息

返回示例

200 返回

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

返回

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

返回格式

状态码 200

名称 类型 描述
None array
» currency string 币种名称
» delisted boolean 是否下架
» withdraw_disabled boolean 是否暂停提现
» withdraw_delayed boolean 提现是否存在延迟
» deposit_disabled boolean 是否暂停充值
» trade_disabled boolean 是否暂停交易

查询单个币种信息

Code samples

# 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
}

返回

状态码 含义 描述 格式
200 OK 查询成功 Inline

返回格式

状态码 200

名称 类型 描述
» currency string 币种名称
» delisted boolean 是否下架
» withdraw_disabled boolean 是否暂停提现
» withdraw_delayed boolean 提现是否存在延迟
» deposit_disabled boolean 是否暂停充值
» trade_disabled boolean 是否暂停交易

查询支持的所有交易对

Code samples

# coding: utf-8
import requests

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

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


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

GET /spot/currency_pairs

查询支持的所有交易对

返回示例

200 返回

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

返回

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

查询单个交易对详情

Code samples

# coding: utf-8
import requests

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

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


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

GET /spot/currency_pairs/{currency_pair}

查询单个交易对详情

参数

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

返回示例

200 返回

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

返回

状态码 含义 描述 格式
200 OK 成功查询 CurrencyPair

获取交易对 ticker 信息

Code samples

# 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 交易对

返回示例

200 返回

[
  {
    "currency_pair": "BTC3L_USDT",
    "last": "2.46140352",
    "lowest_ask": "2.477",
    "highest_bid": "2.4606821",
    "change_percentage": "-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 成功查询 [Inline]

返回格式

状态码 200

名称 类型 描述
» currency_pair string 交易对
» last string 最新成交价
» lowest_ask string 卖方最低价
» highest_bid string 买方最高价
» change_percentage string 涨跌百分比,跌用负数标识,如 -7.45
» base_volume string 交易货币成交量
» quote_volume string 计价货币成交量
» high_24h string 24小时最高价
» low_24h string 24小时最低价
» etf_net_value string ETF 净值
» etf_pre_net_value string\ null
» etf_pre_timestamp integer(int64)\ null
» etf_leverage string\ null

获取市场深度信息

Code samples

# 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 返回

{
  "asks": [
    [
      "1.52",
      "1.151"
    ],
    [
      "1.53",
      "1.218"
    ]
  ],
  "bids": [
    [
      "1.17",
      "201.863"
    ],
    [
      "1.16",
      "725.464"
    ]
  ]
}

返回

状态码 含义 描述 格式
200 OK 成功查询 Inline

返回格式

状态码 200

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

查询市场成交记录

Code samples

# 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

查询市场成交记录

参数

名称 位置 类型 必选 描述
currency_pair 请求参数 string 交易对
limit 请求参数 integer 列表返回的最大数量
last_id 请求参数 string 以上个列表的最后一条记录的 ID 作为下个列表的起点
reverse 请求参数 boolean 是否获取小于 last_id 的数据,默认返回大于 last_id 的记录。

详细描述

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

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

last_id 未设置时,该字段无效。

返回示例

200 返回

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

返回

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

返回格式

状态码 200

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

枚举值列表

属性
side buy
side sell
role taker
role maker

市场 K 线图

Code samples

# coding: utf-8
import requests

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

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


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

GET /spot/candlesticks

市场 K 线图

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

参数

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

详细描述

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

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

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

枚举值列表

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

返回示例

200 返回

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

返回

状态码 含义 描述 格式
200 OK 成功查询 [[string]]

返回格式

状态码 200

名称 类型 描述
» None array 每个时间粒度的 K 线数据,从左到右依次为:

- 秒(s)精度的 Unix 时间戳
- 交易量
- 收盘价
- 最高价
- 最低价
- 开盘价

查询账户费率

Code samples

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

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

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

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

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

GET /spot/fee

查询账户费率

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

参数

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

详细描述

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

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

返回示例

200 返回

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

返回

状态码 含义 描述 格式
200 OK 查询成功 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 费率

获取现货交易账户列表

Code samples

# coding: utf-8
import 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 列表查询成功 [Inline]

返回格式

状态码 200

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

批量下单

Code samples

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

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

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

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

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

POST /spot/batch_orders

批量下单

批量下单要求:

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

Body parameter

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

参数

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

返回示例

200 返回

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

返回

状态码 含义 描述 格式
200 OK 请求执行完成 [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 订单最新修改时间
»» status string 订单状态。

- open: 等待处理
- closed: 全部成交
- cancelled: 订单撤销
»» currency_pair string 交易货币对
»» type string 订单类型,limit - 限价单
»» account string 账户类型,spot - 现货账户,margin - 杠杆账户
»» side string 买单或者卖单
»» amount string 交易数量
»» price string 交易价
»» time_in_force string Time in force 策略。

- gtc: GoodTillCancelled
- ioc: ImmediateOrCancelled,立即成交或者取消,只吃单不挂单
- poc: PendingOrCancelled,被动委托,只挂单不吃单
»» iceberg string 冰山下单显示的数量,不指定或传 0 都默认为普通下单。如果需要全部冰山,设置为 -1
»» left string 交易货币未成交数量
»» fill_price string 已成交的计价币种总额,该字段废弃,建议使用相同意义的 filled_total
»» filled_total string 已成交总金额
»» fee string 成交扣除的手续费
»» fee_currency string 手续费计价单位
»» point_fee string 手续费抵扣使用的点卡数量
»» gt_fee string 手续费抵扣使用的 GT 数量
»» gt_discount boolean 是否开启GT抵扣
»» rebated_fee string 返还的手续费
»» rebated_fee_currency string 返还手续费计价单位

枚举值列表

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

查询所有挂单

Code samples

# coding: utf-8
import 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

查询所有挂单

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

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

参数

名称 位置 类型 必选 描述
page 请求参数 integer 列表页数
limit 请求参数 integer 每个交易对每页最多返回的数量

返回示例

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 列表查询成功 [Inline]

返回格式

状态码 200

名称 类型 描述
» currency_pair string 交易对
» total integer 该交易对当前挂单总数
» orders array
»» None object 现货单详情
»»» id string 订单 ID
»»» text string 订单自定义信息,用户可以用该字段设置自定义 ID,用户自定义字段必须满足以下条件:

1. 必须以 t- 开头
2. 不计算 t- ,长度不能超过 28 字节
3. 输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.)
»»» create_time string 订单创建时间
»»» update_time string 订单最新修改时间
»»» status string 订单状态。

- open: 等待处理
- closed: 全部成交
- cancelled: 订单撤销
»»» currency_pair string 交易货币对
»»» type string 订单类型,limit - 限价单
»»» account string 账户类型,spot - 现货账户,margin - 杠杆账户
»»» side string 买单或者卖单
»»» amount string 交易数量
»»» price string 交易价
»»» time_in_force string Time in force 策略。

- gtc: GoodTillCancelled
- ioc: ImmediateOrCancelled,立即成交或者取消,只吃单不挂单
- poc: PendingOrCancelled,被动委托,只挂单不吃单
»»» iceberg string 冰山下单显示的数量,不指定或传 0 都默认为普通下单。如果需要全部冰山,设置为 -1
»»» left string 交易货币未成交数量
»»» fill_price string 已成交的计价币种总额,该字段废弃,建议使用相同意义的 filled_total
»»» filled_total string 已成交总金额
»»» fee string 成交扣除的手续费
»»» fee_currency string 手续费计价单位
»»» point_fee string 手续费抵扣使用的点卡数量
»»» gt_fee string 手续费抵扣使用的 GT 数量
»»» gt_discount boolean 是否开启GT抵扣
»»» rebated_fee string 返还的手续费
»»» rebated_fee_currency string 返还手续费计价单位

枚举值列表

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

下单

Code samples

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

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

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

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

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

POST /spot/orders

下单

Body parameter

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

参数

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

详细描述

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

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

» time_in_force: Time in force 策略。

枚举值列表

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

返回示例

201 返回

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

返回

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

查询订单列表

Code samples

# coding: utf-8
import 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

查询订单列表

参数

名称 位置 类型 必选 描述
currency_pair 请求参数 string 交易对
status 请求参数 string 基于状态查询订单列表
page 请求参数 integer 列表页数
limit 请求参数 integer 列表返回的最大数量,如果 status 设置为 openlimit 最大允许 100

详细描述

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

open - 挂单中 finished - 已结束

枚举值列表

参数
status open
status finished

返回示例

200 返回

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

返回

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

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

Code samples

# coding: utf-8
import 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 的订单

参数

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

枚举值列表

参数
side buy
side sell
account spot
account margin

返回示例

200 返回

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

返回

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

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

Code samples

# coding: utf-8
import 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 条记录

Body parameter

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

参数

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

返回示例

200 返回

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

返回

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

返回格式

状态码 200

名称 类型 描述
» CancelOrderResult object 订单撤销结果
»» currency_pair string 订单的交易对
»» id string 订单 ID
»» succeeded boolean 是否撤销成功
»» label string 撤销失败时的错误标识,成功时为空
»» message string 撤销失败时的错误描述,成功时为空

查询单个订单详情

Code samples

# coding: utf-8
import 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}

查询单个订单详情

参数

名称 位置 类型 必选 描述
order_id URL string 成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID(即 text 字段)。
currency_pair 请求参数 string 交易对

详细描述

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

返回示例

200 返回

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

返回

状态码 含义 描述 格式
200 OK 详情查询成功 Order

撤销单个订单

Code samples

# coding: utf-8
import 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}

撤销单个订单

参数

名称 位置 类型 必选 描述
order_id URL string 成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID(即 text 字段)。
currency_pair 请求参数 string 交易对

详细描述

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

返回示例

200 返回

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

返回

状态码 含义 描述 格式
200 OK 订单撤销成功 Order

查询个人成交记录

Code samples

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

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

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

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

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

GET /spot/my_trades

查询个人成交记录

参数

名称 位置 类型 必选 描述
currency_pair 请求参数 string 交易对
limit 请求参数 integer 列表返回的最大数量
page 请求参数 integer 列表页数
order_id 请求参数 string 指定查询订单 ID 为 order_id 的成交记录

返回示例

200 返回

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

返回

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

返回格式

状态码 200

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

枚举值列表

属性
side buy
side sell
role taker
role maker

创建价格触发订单

Code samples

# coding: utf-8
import 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

创建价格触发订单

Body parameter

{
  "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 交易账户类型
»» time_in_force body string time_in_force
» market body string 市场

详细描述

»» rule: 价格条件类型

»» side: 买卖方向

»» account: 交易账户类型

»» time_in_force: time_in_force

枚举值列表

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

返回示例

201 返回

{
  "id": 1432329
}

返回

状态码 含义 描述 格式
201 Created 成功下单 Inline

返回格式

状态码 201

TriggerOrderResponse

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

查询进行中自动订单列表

Code samples

# coding: utf-8
import 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 交易账户类型
limit 请求参数 integer 列表返回的最大数量
offset 请求参数 integer 列表返回的偏移量,从 0 开始

枚举值列表

参数
status open
status finished
account normal
account 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 列表查询成功 [SpotPriceTriggeredOrder]

批量取消自动订单

Code samples

# coding: utf-8
import 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 交易账户类型

枚举值列表

参数
account normal
account 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 批量撤销请求接收并处理,是否成功根据订单列表来决定 [SpotPriceTriggeredOrder]

查询单个订单详情

Code samples

# coding: utf-8
import 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 自动订单详情 SpotPriceTriggeredOrder

撤销单个订单

Code samples

# coding: utf-8
import 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 自动订单详情 SpotPriceTriggeredOrder

Margin

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

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

Code samples

# 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"
  }
]

返回

状态码 含义 描述 格式
200 OK 列表成功查询 [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 表示无限制

查询单个杠杆交易对

Code samples

# 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"
}

返回

状态码 含义 描述 格式
200 OK 查询成功 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 表示无限制

借出市场的深度

Code samples

# 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 深度查询成功 [Inline]

返回格式

状态码 200

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

杠杆账户列表

Code samples

# coding: utf-8
import 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",
    "base": {
      "currency": "ETH",
      "available": "30.1",
      "locked": "0",
      "borrowed": "10.1"
    },
    "quote": {
      "currency": "BTC",
      "available": "10",
      "locked": "0",
      "borrowed": "1.5"
    }
  }
]

返回

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

返回格式

状态码 200

名称 类型 描述
» None object 某交易对的杠杆账户信息,base 对应交易货币的账户信息,quote 对应计价货币的账户信息
»» currency_pair string 交易对
»» base object 货币账户信息
»»» currency string 货币名称
»»» available string 可用于杠杆交易的额度,available = 保证金 + borrowed
»»» locked string 冻结资金,如已经放在杠杆市场里挂单交易的数额
»»» borrowed string 借入资金
»» quote object 货币账户信息
»»» currency string 货币名称
»»» available string 可用于杠杆交易的额度,available = 保证金 + borrowed
»»» locked string 冻结资金,如已经放在杠杆市场里挂单交易的数额
»»» borrowed string 借入资金

查询杠杆账户变动历史

Code samples

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

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

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

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

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

GET /margin/account_book

查询杠杆账户变动历史

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

参数

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

返回示例

200 返回

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

返回

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

返回格式

状态码 200

名称 类型 描述
» id string 账户变更记录 ID
» time string 账户变更时间戳
» currency string 变更币种
» currency_pair string 账户交易对
» change string 变更金额,正数表示转入,负数表示转出
» balance string 变更后账户余额

理财账户列表

Code samples

# coding: utf-8
import 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 列表查询成功 [Inline]

返回格式

状态码 200

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

借入或借出

Code samples

# coding: utf-8
import 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"}'
# `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"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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

借入或借出

Body parameter

{
  "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"
}

参数

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

详细描述

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

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

枚举值列表

参数
» side lend
» side borrow

返回示例

201 返回

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

返回

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

查询借贷订单列表

Code samples

# coding: utf-8
import 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_timerate ,默认是 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"
  }
]

返回

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

合并多个借贷订单

Code samples

# coding: utf-8
import 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"
}

返回

状态码 含义 描述 格式
201 Created 订单合并成功 Loan

查询借贷订单详情

Code samples

# coding: utf-8
import 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"
}

返回

状态码 含义 描述 格式
200 OK 订单查询成功 Loan

修改借贷订单

Code samples

# coding: utf-8
import 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 字段,即订单是否自动续借

Body parameter

{
  "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"
}

返回

状态码 含义 描述 格式
200 OK 修改成功 Loan

撤销借出贷款订单

Code samples

# coding: utf-8
import 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"
}

返回

状态码 含义 描述 格式
200 OK 订单撤销成功 Loan

归还借贷

Code samples

# coding: utf-8
import 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

归还借贷

Body parameter

{
  "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"
}

返回

状态码 含义 描述 格式
200 OK 还款成功 Loan

查询借贷归还记录

Code samples

# coding: utf-8
import 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 列表查询成功 [Inline]

返回格式

状态码 200

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

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

Code samples

# coding: utf-8
import 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 列表查询成功 [LoanRecord]

查看单个借出记录

Code samples

# coding: utf-8
import 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 详情查询成功 LoanRecord

修改单个借出记录

Code samples

# coding: utf-8
import 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 的修改,即调整该借出记录是否自动续借

Body parameter

{
  "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 记录修改成功 LoanRecord

修改用户自动还款设置

Code samples

# coding: utf-8
import 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=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="/margin/auto_repay"
query_param="status=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 /margin/auto_repay

修改用户自动还款设置

参数

名称 位置 类型 必选 描述
status 请求参数 string 是否开启自动还款,on - 开启, off - 关闭

返回示例

200 返回

{
  "status": "on"
}

返回

状态码 含义 描述 格式
200 OK 用户当前自动还款设置 Inline

返回格式

状态码 200

AutoRepaySetting

名称 类型 描述
» status string 自动还款状态, on - 开启,off - 关闭

枚举值列表

属性
status true
status false

查询用户自动还款设置

Code samples

# coding: utf-8
import 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 用户当前自动还款设置 Inline

返回格式

状态码 200

AutoRepaySetting

名称 类型 描述
» status string 自动还款状态, on - 开启,off - 关闭

枚举值列表

属性
status true
status false

Futures

永续合约

查询所有的合约信息

Code samples

# 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

返回示例

200 返回

[
  {
    "name": "BTC_USDT",
    "type": "direct",
    "quanto_multiplier": "0.0001",
    "ref_discount_rate": "0",
    "order_price_deviate": "0.5",
    "maintenance_rate": "0.005",
    "mark_type": "index",
    "last_price": "38026",
    "mark_price": "37985.6",
    "index_price": "37954.92",
    "funding_rate_indicative": "0.000219",
    "mark_price_round": "0.01",
    "funding_offset": 0,
    "in_delisting": false,
    "risk_limit_base": "1000000",
    "interest_rate": "0.0003",
    "order_price_round": "0.1",
    "order_size_min": 1,
    "ref_rebate_rate": "0.2",
    "funding_interval": 28800,
    "risk_limit_step": "1000000",
    "leverage_min": "1",
    "leverage_max": "100",
    "risk_limit_max": "8000000",
    "maker_fee_rate": "-0.00025",
    "taker_fee_rate": "0.00075",
    "funding_rate": "0.002053",
    "order_size_max": 1000000,
    "funding_next_apply": 1610035200,
    "short_users": 977,
    "config_change_time": 1609899548,
    "trade_size": 28530850594,
    "position_size": 5223816,
    "long_users": 455,
    "funding_impact_value": "60000",
    "orders_limit": 50,
    "trade_id": 10851092,
    "orderbook_id": 2129638396
  }
]

返回

状态码 含义 描述 格式
200 OK 列表查询成功 [Contract]

查询单个合约信息

Code samples

# 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

返回示例

200 返回

{
  "name": "BTC_USDT",
  "type": "direct",
  "quanto_multiplier": "0.0001",
  "ref_discount_rate": "0",
  "order_price_deviate": "0.5",
  "maintenance_rate": "0.005",
  "mark_type": "index",
  "last_price": "38026",
  "mark_price": "37985.6",
  "index_price": "37954.92",
  "funding_rate_indicative": "0.000219",
  "mark_price_round": "0.01",
  "funding_offset": 0,
  "in_delisting": false,
  "risk_limit_base": "1000000",
  "interest_rate": "0.0003",
  "order_price_round": "0.1",
  "order_size_min": 1,
  "ref_rebate_rate": "0.2",
  "funding_interval": 28800,
  "risk_limit_step": "1000000",
  "leverage_min": "1",
  "leverage_max": "100",
  "risk_limit_max": "8000000",
  "maker_fee_rate": "-0.00025",
  "taker_fee_rate": "0.00075",
  "funding_rate": "0.002053",
  "order_size_max": 1000000,
  "funding_next_apply": 1610035200,
  "short_users": 977,
  "config_change_time": 1609899548,
  "trade_size": 28530850594,
  "position_size": 5223816,
  "long_users": 455,
  "funding_impact_value": "60000",
  "orders_limit": 50,
  "trade_id": 10851092,
  "orderbook_id": 2129638396
}

返回

状态码 含义 描述 格式
200 OK 合约信息 Contract

查询合约市场深度信息

Code samples

# 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
interval 0
interval 0.1
interval 0.01

返回示例

200 返回

{
  "asks": [
    {
      "p": "1.52",
      "s": 100
    },
    {
      "p": "1.53",
      "s": 40
    }
  ],
  "bids": [
    {
      "p": "1.17",
      "s": 150
    },
    {
      "p": "1.16",
      "s": 203
    }
  ]
}

返回

状态码 含义 描述 格式
200 OK 深度查询成功 Inline

返回格式

状态码 200

名称 类型 描述
» id integer(int64) 深度更新 ID,深度每发生一次变化,该 ID 加 1,只有设置 with_id=true 时才返回
» asks array 卖方深度列表
»» futures_order_book_item object
»»» p string 价格
»»» s integer(int64) 数量
»» bids array 买方深度列表
»»» futures_order_book_item object
»»»» p string 价格
»»»» s integer(int64) 数量

合约市场成交记录

Code samples

# coding: utf-8
import requests

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

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


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

GET /futures/{settle}/trades

合约市场成交记录

参数

名称 位置 类型 必选 描述
settle URL string 结算货币
contract 请求参数 string 合约标识
limit 请求参数 integer 列表返回的最大数量
last_id 请求参数 string 以上个列表的最后一条记录的 ID 作为下个列表的起点。
from 请求参数 integer(int64) 指定起始时间,时间格式为秒(s)精度的 Unix 时间戳。 不指定则按照 to 和 limit 来限定返回的数量。
to 请求参数 integer(int64) 指定结束时间,不指定则默认当前时间,时间格式为秒(s)精度的 Unix 时间戳

详细描述

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

该字段不再继续支持,新的请求请使用 fromto 字段来限定时间范围

from: 指定起始时间,时间格式为秒(s)精度的 Unix 时间戳。 不指定则按照 to 和 limit 来限定返回的数量。 如果 from 和 to 指定的时间范围内的数量超过 limit,只返回 limit 数量

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

枚举值列表

参数
settle btc
settle usdt

返回示例

200 返回

[
  {
    "id": 121234231,
    "create_time": 1514764800,
    "contract": "BTC_USDT",
    "size": -100,
    "price": "100.123"
  }
]

返回

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

返回格式

状态码 200

名称 类型 描述
None array
» id integer(int64) 成交记录 ID
» create_time number(double) 成交时间
» create_time_ms number(double) 成交时间,保留 3 位小数的毫秒精度
» contract string 合约标识
» size integer(int64) 成交数量
» price string 成交价格

合约市场 K 线图

Code samples

# coding: utf-8
import requests

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

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


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

GET /futures/{settle}/candlesticks

合约市场 K 线图

如果 contract 字段在合约标识前增加了 mark_ 前缀则返回标记价格数据(如mark_BTC_USD), 如果增加了 index_ 则返回指数价格的数据(如index_BTC_USD)

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

参数

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

详细描述

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

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

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

枚举值列表

参数
settle btc
settle usdt
interval 10s
interval 1m
interval 5m
interval 15m
interval 30m
interval 1h
interval 4h
interval 8h
interval 1d
interval 7d

返回示例

200 返回

[
  {
    "t": 1539852480,
    "v": 97151,
    "c": "1.032",
    "h": "1.032",
    "l": "1.032",
    "o": "1.032"
  }
]

返回

状态码 含义 描述 格式
200 OK 成功查询 [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 开盘价

获取所有合约交易行情统计

Code samples

# 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

返回示例

200 返回

[
  {
    "contract": "BTC_USDT",
    "last": "6432",
    "low_24h": "6278",
    "high_24h": "6790",
    "change_percentage": "4.43",
    "total_size": "32323904",
    "volume_24h": "184040233284",
    "volume_24h_btc": "28613220",
    "volume_24h_usd": "184040233284",
    "volume_24h_base": "28613220",
    "volume_24h_quote": "184040233284",
    "volume_24h_settle": "28613220",
    "mark_price": "6534",
    "funding_rate": "0.0001",
    "funding_rate_indicative": "0.0001",
    "index_price": "6531"
  }
]

返回

状态码 含义 描述 格式
200 OK 查询成功 [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 双币种合约中,基础货币和结算货币的汇率。其他类型合约中此字段不存在。

合约市场历史资金费率

Code samples

# 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

返回示例

200 返回

[
  {
    "t": 1543968000,
    "r": "0.000157"
  }
]

返回

状态码 含义 描述 格式
200 OK 历史查询成功 [Inline]

返回格式

状态码 200

名称 类型 描述
» t integer(int64) 秒 s 精度的 Unix 时间戳
» r string 资金费率

合约市场保险基金历史

Code samples

# 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

返回示例

200 返回

[
  {
    "t": 1543968000,
    "b": "83.0031"
  }
]

返回

状态码 含义 描述 格式
200 OK 查询成功 [Inline]

返回格式

状态码 200

名称 类型 描述
None array
» t integer(int64) 秒 s 精度的 Unix 时间戳
» b string 保险基金余额

合约统计信息

Code samples

# 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
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 列表查询成功 [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) 大户多空持仓比

查询强平委托历史

Code samples

# 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

查询强平委托历史

fromto 的时间间隔最大为 3600。部分私有字段公共接口不会返回,具体参照字段描述

参数

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

枚举值列表

参数
settle btc
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 列表查询成功 [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) 强平委托挂单大小

获取合约账号

Code samples

# coding: utf-8
import 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

返回示例

200 返回

{
  "total": "4.4516",
  "unrealised_pnl": "0",
  "available": "4.98",
  "order_margin": "0.1",
  "position_margin": "5.1",
  "point": "10000",
  "currency": "BTC",
  "in_dual_mode": false
}

返回

状态码 含义 描述 格式
200 OK 列表查询成功 Inline

返回格式

状态码 200

名称 类型 描述
» total string 账户总资产, total = position_margin + order_margin + available
» unrealised_pnl string 未实现盈亏
» position_margin string 头寸保证金
» order_margin string 未完成订单的保证金
» available string 可用的转出或交易的额度
» point string 点卡数额
» currency string 结算币种
» in_dual_mode boolean 是否为双向持仓模式

查询合约账户变更历史

Code samples

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

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

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

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

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

GET /futures/{settle}/account_book

查询合约账户变更历史

参数

名称 位置 类型 必选 描述
settle URL string 结算货币
limit 请求参数 integer 列表返回的最大数量
from 请求参数 integer(int64) 起始时间戳
to 请求参数 integer(int64) 终止时间戳
type 请求参数 string 变更类型:

详细描述

type: 变更类型:

枚举值列表

参数
settle btc
settle usdt
type dnw
type pnl
type fee
type refr
type fund
type point_dnw
type point_fee
type point_refr

返回示例

200 返回

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

返回

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

返回格式

状态码 200

名称 类型 描述
None array
» time number(double) 时间
» change string 变更金额
» balance string 变更后账户余额
» type string 变更类型:

- dnw: 转入转出
- pnl: 减仓盈亏
- fee: 交易手续费
- refr: 推荐人返佣
- fund: 资金费用
- point_dnw: 点卡转入转出
- point_fee: 点卡交易手续费
- point_refr: 点卡推荐人返佣
» text string 注释

枚举值列表

属性
type dnw
type pnl
type fee
type refr
type fund
type point_dnw
type point_fee
type point_refr

获取用户头寸列表

Code samples

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

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

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

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

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

GET /futures/{settle}/positions

获取用户头寸列表

参数

名称 位置 类型 必选 描述
settle URL string 结算货币

枚举值列表

参数
settle btc
settle usdt

返回示例

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"
  }
]

返回

状态码 含义 描述 格式
200 OK 列表查询成功 [Position]

获取单个头寸信息

Code samples

# coding: utf-8
import 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

返回示例

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"
}

返回

状态码 含义 描述 格式
200 OK 头寸信息 Position

更新头寸保证金

Code samples

# coding: utf-8
import 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

返回示例

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"
}

返回

状态码 含义 描述 格式
200 OK 头寸信息 Position

更新头寸杠杆

Code samples

# coding: utf-8
import 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 新的杠杆倍数

枚举值列表

参数
settle btc
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"
}

返回

状态码 含义 描述 格式
200 OK 头寸信息 Position

更新头寸风险限额

Code samples

# coding: utf-8
import 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

返回示例

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"
}

返回

状态码 含义 描述 格式
200 OK 头寸信息 Position

设置持仓模式

Code samples

# coding: utf-8
import 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

返回示例

200 返回

{
  "total": "4.4516",
  "unrealised_pnl": "0",
  "available": "4.98",
  "order_margin": "0.1",
  "position_margin": "5.1",
  "point": "10000",
  "currency": "BTC",
  "in_dual_mode": false
}

返回

状态码 含义 描述 格式
200 OK 修改成功 Inline

返回格式

状态码 200

名称 类型 描述
» total string 账户总资产, total = position_margin + order_margin + available
» unrealised_pnl string 未实现盈亏
» position_margin string 头寸保证金
» order_margin string 未完成订单的保证金
» available string 可用的转出或交易的额度
» point string 点卡数额
» currency string 结算币种
» in_dual_mode boolean 是否为双向持仓模式

获取双仓模式下的持仓信息

Code samples

# coding: utf-8
import 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

返回示例

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"
  }
]

返回

状态码 含义 描述 格式
200 OK 查询成功 [Position]

更新双仓模式下的保证金

Code samples

# coding: utf-8
import 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'
# `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"
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 保证金变化数额,正数增加,负数减少

枚举值列表

参数
settle btc
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"
  }
]

返回

状态码 含义 描述 格式
200 OK 查询成功 [Position]

更新双仓模式下的杠杆

Code samples

# coding: utf-8
import 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 新的杠杆倍数

枚举值列表

参数
settle btc
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"
  }
]

返回

状态码 含义 描述 格式
200 OK 查询成功 [Position]

更新双仓模式下的风险限额

Code samples

# coding: utf-8
import 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

返回示例

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"
  }
]

返回

状态码 含义 描述 格式
200 OK 查询成功 [Position]

合约交易下单

Code samples

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

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

url = '/futures/usdt/orders'
query_param = ''
body='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/orders"
query_param=""
body_param='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /futures/{settle}/orders

合约交易下单

0 成交的订单在撤单 60s 之后无法获取

Body parameter

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

参数

名称 位置 类型 必选 描述
body body FuturesOrder
» contract body string 合约标识
» size body integer(int64) 必选。交易数量,正数为买入,负数为卖出。平仓委托则设置为0。
» iceberg body integer(int64) 冰山委托显示数量。0为完全不隐藏。注意,隐藏部分成交按照taker收取手续费。
» price body string 委托价。价格为0并且tifioc,代表市价委托。
» close body boolean 设置为 true 的时候执行平仓操作,并且size应设置为0
» reduce_only body boolean 设置为 true 的时候,为只减仓委托
» tif body string Time in force 策略,市价单当前只支持 ioc 模式
» text body string 订单自定义信息,用户可以用该字段设置自定义 ID,用户自定义字段必须满足以下条件:
settle URL string 结算货币

详细描述

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

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

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

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

枚举值列表

参数
» tif gtc
» tif ioc
» tif poc
settle btc
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"
}

返回

状态码 含义 描述 格式
201 Created 订单详情 FuturesOrder

查询合约订单列表

Code samples

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

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

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

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

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

GET /futures/{settle}/orders

查询合约订单列表

0 成交的订单在撤单 60s 之后无法获取

参数

名称 位置 类型 必选 描述
contract 请求参数 string 合约标识
status 请求参数 string 基于状态查询订单列表
limit 请求参数 integer 列表返回的最大数量
offset 请求参数 integer 列表返回的偏移量,从 0 开始
last_id 请求参数 string 以上个列表的最后一条记录的 ID 作为下个列表的起点
count_total 请求参数 integer 是否需要返回列表总数,默认为 0 不返回
settle URL string 结算货币

枚举值列表

参数
status open
status finished
count_total 0
count_total 1
settle btc
settle usdt

返回示例

200 返回

[
  {
    "id": 15675394,
    "user": 100000,
    "contract": "BTC_USDT",
    "create_time": 1546569968,
    "size": 6024,
    "iceberg": 0,
    "left": 6024,
    "price": "3765",
    "fill_price": "0",
    "mkfr": "-0.00025",
    "tkfr": "0.00075",
    "tif": "gtc",
    "refu": 0,
    "is_reduce_only": false,
    "is_close": false,
    "is_liq": false,
    "text": "t-my-custom-id",
    "status": "finished",
    "finish_time": 1514764900,
    "finish_as": "cancelled"
  }
]

返回

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

返回头部

状态码 头部 类型 格式 描述
200 X-Pagination-Limit integer 分页时指定的 limit
200 X-Pagination-Offset integer 分页时指定的 offset
200 X-Pagination-Total integer 满足条件的列表总数,只有设置 count_total 为 1 时才返回

批量取消状态为 open 的订单

Code samples

# coding: utf-8
import 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 成交的订单在撤单 60s 之后无法获取

参数

名称 位置 类型 必选 描述
contract 请求参数 string 合约标识
side 请求参数 string 指定全部买单或全部卖单,不指定则两者都包括
settle URL string 结算货币

枚举值列表

参数
side ask
side bid
settle btc
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"
  }
]

返回

状态码 含义 描述 格式
200 OK 批量撤销成功 [FuturesOrder]

查询单个订单详情

Code samples

# coding: utf-8
import 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 成交的订单在撤单 60s 之后无法获取

参数

名称 位置 类型 必选 描述
settle URL string 结算货币
order_id URL string 成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID(即 text 字段)。

详细描述

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

枚举值列表

参数
settle btc
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"
}

返回

状态码 含义 描述 格式
200 OK 订单详情 FuturesOrder

撤销单个订单

Code samples

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

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

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

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

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

DELETE /futures/{settle}/orders/{order_id}

撤销单个订单

参数

名称 位置 类型 必选 描述
settle URL string 结算货币
order_id URL string 成功创建订单时返回的订单 ID 或者用户创建时指定的自定义 ID(即 text 字段)。

详细描述

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

枚举值列表

参数
settle btc
settle usdt

返回示例

200 返回

{
  "id": 15675394,
  "user": 100000,
  "contract": "BTC_USDT",
  "create_time": 1546569968,
  "size": 6024,
  "iceberg": 0,
  "left": 6024,
  "price": "3765",
  "fill_price": "0",
  "mkfr": "-0.00025",
  "tkfr": "0.00075",
  "tif": "gtc",
  "refu": 0,
  "is_reduce_only": false,
  "is_close": false,
  "is_liq": false,
  "text": "t-my-custom-id",
  "status": "finished",
  "finish_time": 1514764900,
  "finish_as": "cancelled"
}

返回

状态码 含义 描述 格式
200 OK 订单详情 FuturesOrder

查询个人成交记录

Code samples

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

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

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

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

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

GET /futures/{settle}/my_trades

查询个人成交记录

参数

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

枚举值列表

参数
settle btc
settle usdt
count_total 0
count_total 1

返回示例

200 返回

[
  {
    "id": 121234231,
    "create_time": 1514764800,
    "create_time_ms": 1514764800.123,
    "contract": "BTC_USDT",
    "order_id": "21893289839",
    "size": 100,
    "price": "100.123",
    "role": "taker"
  }
]

返回

状态码 含义 描述 格式
200 OK 列表查询成功 [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 - 做单

枚举值列表

属性
role taker
role maker

返回头部

状态码 头部 类型 格式 描述
200 X-Pagination-Limit integer 分页时指定的 limit
200 X-Pagination-Offset integer 分页时指定的 offset
200 X-Pagination-Total integer 满足条件的列表总数,只有设置 count_total 为 1 时才返回

查询平仓历史

Code samples

# coding: utf-8
import 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 开始

枚举值列表

参数
settle btc
settle usdt

返回示例

200 返回

[
  {
    "time": 1546487347,
    "pnl": "0.00013",
    "side": "long",
    "contract": "BTC_USDT",
    "text": "web"
  }
]

返回

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

返回格式

状态码 200

名称 类型 描述
None array
» time number(double) 平仓时间
» contract string 合约标识
» side string 多空方向

- long: 做多
- short: 做空
» pnl string 盈亏
» text string 平仓委托的来源,具体取值参见order.text字段

枚举值列表

属性
side long
side short

查询强制平仓历史

Code samples

# coding: utf-8
import 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

返回示例

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 列表查询成功 [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) 强平委托挂单大小

创建价格触发订单

Code samples

# coding: utf-8
import 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","close":false,"tif":"gtc","text":"web"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400}}'
# `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","close":false,"tif":"gtc","text":"web"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400}}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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

创建价格触发订单

Body parameter

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03",
    "close": false,
    "tif": "gtc",
    "text": "web"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  }
}

参数

名称 位置 类型 必选 描述
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 的时候执行自动减仓操作
» trigger body object
»» strategy_type body integer 触发策略
»» price_type body integer 参考价格类型。 0 - 最新成交价,1 - 标记价格,2 - 指数价格
»» price body string 价格触发时为价格,价差触发时为价差
»» rule body integer 价格条件类型
»» expiration body integer 最长等待触发时间,超时则取消该订单,单位是秒 s
settle URL string 结算货币

详细描述

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

»» text: 订单的来源,包括:

»» strategy_type: 触发策略

»» rule: 价格条件类型

枚举值列表

参数
»» 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

返回示例

201 返回

{
  "id": 1432329
}

返回

状态码 含义 描述 格式
201 Created 成功下单 Inline

返回格式

状态码 201

TriggerOrderResponse

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

查询自动订单列表

Code samples

# coding: utf-8
import 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

返回示例

200 返回

[
  {
    "initial": {
      "contract": "BTC_USDT",
      "size": 100,
      "price": "5.03",
      "tif": "gtc",
      "text": "web"
    },
    "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": ""
  }
]

返回

状态码 含义 描述 格式
200 OK 列表查询成功 [FuturesPriceTriggeredOrder]

批量取消自动订单

Code samples

# coding: utf-8
import 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

返回示例

200 返回

[
  {
    "initial": {
      "contract": "BTC_USDT",
      "size": 100,
      "price": "5.03",
      "tif": "gtc",
      "text": "web"
    },
    "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": ""
  }
]

返回

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

查询单个订单详情

Code samples

# coding: utf-8
import 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

返回示例

200 返回

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03",
    "tif": "gtc",
    "text": "web"
  },
  "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": ""
}

返回

状态码 含义 描述 格式
200 OK 自动订单详情 FuturesPriceTriggeredOrder

撤销单个订单

Code samples

# coding: utf-8
import 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

返回示例

200 返回

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03",
    "tif": "gtc",
    "text": "web"
  },
  "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": ""
}

返回

状态码 含义 描述 格式
200 OK 自动订单详情 FuturesPriceTriggeredOrder

Delivery

交割合约

查询所有的合约信息

Code samples

# 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 列表查询成功 [DeliveryContract]

查询单个合约信息

Code samples

# 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 合约信息 DeliveryContract

查询合约市场深度信息

Code samples

# 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 返回

{
  "asks": [
    {
      "p": "1.52",
      "s": 100
    },
    {
      "p": "1.53",
      "s": 40
    }
  ],
  "bids": [
    {
      "p": "1.17",
      "s": 150
    },
    {
      "p": "1.16",
      "s": 203
    }
  ]
}

返回

状态码 含义 描述 格式
200 OK 深度查询成功 Inline

返回格式

状态码 200

名称 类型 描述
» id integer(int64) 深度更新 ID,深度每发生一次变化,该 ID 加 1,只有设置 with_id=true 时才返回
» asks array 卖方深度列表
»» futures_order_book_item object
»»» p string 价格
»»» s integer(int64) 数量
»» bids array 买方深度列表
»»» futures_order_book_item object
»»»» p string 价格
»»»» s integer(int64) 数量

合约市场成交记录

Code samples

# 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 作为下个列表的起点。

该字段不再继续支持,新的请求请使用 fromto 字段来限定时间范围

from: 指定起始时间,时间格式为秒(s)精度的 Unix 时间戳。 不指定则按照 to 和 limit 来限定返回的数量。 如果 from 和 to 指定的时间范围内的数量超过 limit,只返回 limit 数量

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

枚举值列表

参数
settle usdt

返回示例

200 返回

[
  {
    "id": 121234231,
    "create_time": 1514764800,
    "contract": "BTC_USDT",
    "size": -100,
    "price": "100.123"
  }
]

返回

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

返回格式

状态码 200

名称 类型 描述
None array
» id integer(int64) 成交记录 ID
» create_time number(double) 成交时间
» create_time_ms number(double) 成交时间,保留 3 位小数的毫秒精度
» contract string 合约标识
» size integer(int64) 成交数量
» price string 成交价格

合约市场 K 线图

Code samples

# coding: utf-8
import requests

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

url = '/delivery/usdt/candlesticks'
query_param = 'contract=BTC_USDT_20200814'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())


curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/candlesticks?contract=BTC_USDT_20200814 \
  -H 'Accept: application/json'

GET /delivery/{settle}/candlesticks

合约市场 K 线图

如果 contract 字段在合约标识前增加了 mark_ 前缀则返回标记价格数据(如mark_BTC_USD), 如果增加了 index_ 则返回指数价格的数据(如index_BTC_USD)

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

参数

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

详细描述

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

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

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

枚举值列表

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

返回示例

200 返回

[
  {
    "t": 1539852480,
    "v": 97151,
    "c": "1.032",
    "h": "1.032",
    "l": "1.032",
    "o": "1.032"
  }
]

返回

状态码 含义 描述 格式
200 OK 成功查询 [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 开盘价

获取所有合约交易行情统计

Code samples

# 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"
  }
]

返回

状态码 含义 描述 格式
200 OK 查询成功 [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 双币种合约中,基础货币和结算货币的汇率。其他类型合约中此字段不存在。

合约市场保险基金历史

Code samples

# 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 查询成功 [Inline]

返回格式

状态码 200

名称 类型 描述
None array
» t integer(int64) 秒 s 精度的 Unix 时间戳
» b string 保险基金余额

获取合约账号

Code samples

# coding: utf-8
import 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 返回

{
  "total": "4.4516",
  "unrealised_pnl": "0",
  "available": "4.98",
  "order_margin": "0.1",
  "position_margin": "5.1",
  "point": "10000",
  "currency": "BTC",
  "in_dual_mode": false
}

返回

状态码 含义 描述 格式
200 OK 列表查询成功 Inline

返回格式

状态码 200

名称 类型 描述
» total string 账户总资产, total = position_margin + order_margin + available
» unrealised_pnl string 未实现盈亏
» position_margin string 头寸保证金
» order_margin string 未完成订单的保证金
» available string 可用的转出或交易的额度
» point string 点卡数额
» currency string 结算币种
» in_dual_mode boolean 是否为双向持仓模式

查询合约账户变更历史

Code samples

# coding: utf-8
import 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: 变更类型:

枚举值列表

参数
settle usdt
type dnw
type pnl
type fee
type refr
type fund
type point_dnw
type point_fee
type point_refr

返回示例

200 返回

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

返回

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

返回格式

状态码 200

名称 类型 描述
None array
» time number(double) 时间
» change string 变更金额
» balance string 变更后账户余额
» type string 变更类型:

- dnw: 转入转出
- pnl: 减仓盈亏
- fee: 交易手续费
- refr: 推荐人返佣
- fund: 资金费用
- point_dnw: 点卡转入转出
- point_fee: 点卡交易手续费
- point_refr: 点卡推荐人返佣
» text string 注释

枚举值列表

属性
type dnw
type pnl
type fee
type refr
type fund
type point_dnw
type point_fee
type point_refr

获取用户头寸列表

Code samples

# coding: utf-8
import 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"
  }
]

返回

状态码 含义 描述 格式
200 OK 列表查询成功 [Position]

获取单个头寸信息

Code samples

# coding: utf-8
import 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"
}

返回

状态码 含义 描述 格式
200 OK 头寸信息 Position

更新头寸保证金

Code samples

# coding: utf-8
import 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"
}

返回

状态码 含义 描述 格式
200 OK 头寸信息 Position

更新头寸杠杆

Code samples

# coding: utf-8
import 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"
}

返回

状态码 含义 描述 格式
200 OK 头寸信息 Position

更新头寸风险限额

Code samples

# coding: utf-8
import 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"
}

返回

状态码 含义 描述 格式
200 OK 头寸信息 Position

合约交易下单

Code samples

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

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

url = '/delivery/usdt/orders'
query_param = ''
body='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}'
# `gen_sign` 的实现参考认证一章
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/orders"
query_param=""
body_param='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /delivery/{settle}/orders

合约交易下单

0 成交的订单在撤单 60s 之后无法获取

Body parameter

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

参数

名称 位置 类型 必选 描述
body body FuturesOrder
» contract body string 合约标识
» size body integer(int64) 必选。交易数量,正数为买入,负数为卖出。平仓委托则设置为0。
» iceberg body integer(int64) 冰山委托显示数量。0为完全不隐藏。注意,隐藏部分成交按照taker收取手续费。
» price body string 委托价。价格为0并且tifioc,代表市价委托。
» close body boolean 设置为 true 的时候执行平仓操作,并且size应设置为0
» reduce_only body boolean 设置为 true 的时候,为只减仓委托
» tif body string Time in force 策略,市价单当前只支持 ioc 模式
» text body string 订单自定义信息,用户可以用该字段设置自定义 ID,用户自定义字段必须满足以下条件:
settle URL string 结算货币

详细描述

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

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

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

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

枚举值列表

参数
» tif gtc
» tif ioc
» tif poc
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"
}

返回

状态码 含义 描述 格式
201 Created 订单详情 FuturesOrder

查询合约订单列表

Code samples

# coding: utf-8
import 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 成交的订单在撤单 60s 之后无法获取

参数

名称 位置 类型 必选 描述
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"
  }
]

返回

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

返回头部

状态码 头部 类型 格式 描述
200 X-Pagination-Limit integer 分页时指定的 limit
200 X-Pagination-Offset integer 分页时指定的 offset
200 X-Pagination-Total integer 满足条件的列表总数,只有设置 count_total 为 1 时才返回

批量取消状态为 open 的订单

Code samples

# coding: utf-8
import 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 成交的订单在撤单 60s 之后无法获取

参数

名称 位置 类型 必选 描述
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"
  }
]

返回

状态码 含义 描述 格式
200 OK 批量撤销成功 [FuturesOrder]

查询单个订单详情

Code samples

# coding: utf-8
import 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 成交的订单在撤单 60s 之后无法获取

参数

名称 位置 类型 必选 描述
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"
}

返回

状态码 含义 描述 格式
200 OK 订单详情 FuturesOrder

撤销单个订单

Code samples

# coding: utf-8
import 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