NAV Navbar
Python Shell

Gate API v4 v4.20.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Welcome to Gate.io API

APIv4 provides spot, margin and futures trading operations. There are public APIs to retrieve the real-time market statistics, and private APIs which needs authentication to trade on user's behalf.

Access URL：

REST API BaseURL:

WebSocket API BaseURL：

New spot WebSocket wss://api.gateio.ws/ws/v4/

Old spot WebSocket:

WebSocket Documents

Spot trading

Perpetual Contract

Delivery Contract

SDK

Available SDK:

Besides API examples, some SDK provides an additional demo application. The demo application is a relatively complete example demonstrating how to use the SDK. It can be built and run separately. Refer to corresponding repository for details.

About APIv4 key improvement

Previously(before April 2020) futures APIv4 key are separated from spot one, but this is no longer the case anymore. You can create multiple keys with each key having multiple permissions now. e.g. you can create one key with spot read/write and futures read/write permission which can be used in both spot and futures trading.

History API keys will not be affected by this improvement. Previous spot key and futures key are now one key with only spot permissions enabled, another only futures permission enabled. You can reconfigure their permissions after migration.

Comparison with APIv2

APIv4 is a standalone brand-new HTTP REST API, currently used in parallel with APIv2. APIv4 provides complete trading operations, with more highly secured authentication method. What's more, APIv4 specification is written following OpenAPI Specification. SDKs and documents are all generated from the same spec, which ensures consistency between documents and implementation.

The ways APIv4 and APIv2 differ are:

  1. Their API keys are separated from each other. Once logged into the web console, v2 API keys are generated on "APIKeys" page, while v4 "APIv4Keys" page.
  2. APIv2 supports only spot trading, while v4 supports all trading operations in spot, margin and futures.

Which one to choose:

  1. If margin or futures trading are needed, choose APIv4.
  2. If only spot trading or wallet operation is required, choose on your own.

Application for Marketers

In order to further improve the platform's opening depth and trading liquidity, we will recruit institutional market makers in an open and transparent way, and provide a professional market maker's service rate scheme for professional institutional market makers according to their contribution to the platform's liquidity.

  1. Provide Gateio UID
  2. Provide other transaction volume screenshot or VIP level
  3. Brief introduction of market making method and scale

Provide the above content and submit to business@gateio.me , we will accept within 3 working days.

Technical Support

If you have any questions or suggestions during the use, you can contact us in any of the following ways:

If you encounter API errors, it is recommended that you sort out the following content, so that we can quickly analyze the problem for you:

  1. Problem Description
  2. Gateio UID
  3. Request URI and parameters
  4. Error Code
  5. Responses

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

Spot

Futures

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

To use USDT futures, just replace /futures with /futures/usdt, e.g. use GET /futures/usdt/accounts to retrieve futures accounts settled in USDT, while GET /futures/btc/accounts returns accounts in BTC.

For compatibility, GET /futures/xxx defaults to GET /futures/btc/xxx, e.g. GET /futures/accounts will be treated as 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 related only

v4.5.2

2019-03-14

v4.5.1

2019-03-11

v4.5.0

2019-03-05

To avoid version confusion, all versions in APIv4 (documents and SDKs are both included) will start with 4 from now on

v1.3.0

2019-02-13

Important update

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

Matching mechanism

Matching priority

Gate.io Order matching follows Price Priority > Time priority principle.

Suppose that the order book is as follows：

Order Order time Ask/Selling price
A 10:00 100
B 10:00 102
C 10:01 100

If the current price of 10:02 pays 102, the final transaction order is: A, C, B

Order life cycle

A valid order sent to the matching engine is immediately confirmed and executed with existing orders, with the executing result sent back to the client.

If an order is fully executed, then it is closed. If any part of the order is not executed immediately, orders with TimeInForce set to IOC will be cancelled, while others will be appended to the price list, waiting for subsequent filling or being cancelled.

Data Center

Gate.io data center is located in AWS Japan's ap-northeast-1 region.

API Overview

API Classification Category Links Overview
host + /api/v4/spot/* Spot Trading Including currency status, market information, order, transaction records and other functions
host + /api/v4/margin/* Margin Trading Margin account management, lending, repayment, etc
host + /api/v4/wallet/* Wallet Management Charge and withdrawal records, balance inquiries, fund transfers, etc.
host + /api/v4/withdrawals/* Withdrawal Withdrawal of digital currency

API

HTTP convention

Time

All time related fields are unix timestamp in seconds if no extra note, but they may differ in formats(int64, number or string). Possible values like the following may be returned:

The best way to handle time fields is parsing them as a number with decimal places. If higher precision is not needed, you can safely cast them to integer(or long). Our SDKs listed above has already taken proper deserialization to handle them

Pagination

Pagination is achieved using one of the following method

In both method, limit limits the maximum number of records returned in one request. If no additional explanation, it defaults to 100 if not provided and its maximum value is limited to 1000.

page starts from 1, mimicking common paging used in web pages. To iterate the whole list, use the same limit and increment page by 1 until the records' length is shorter than the limit

offset starts from 0, behaving like common DB search. To iterate the whole list, increment offset by limit until the records' length is shorter than the limit.

For example, if the total number of orders is 201. Using page-limit method, send request parameters like the following:

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

Using limit-offset method, send request parameters like:

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

Some endpoints may return additional pagination metadata. If present, they are sent back through the response header. Take GET /futures/{settle}/orders as an example, following headers will be returned

Frequency limit rule

Withdraw:

Spot:

Futures:

Return Format

All API responses are in JSON format, and users need to transform and extract data by themselves.

The HTTP status code 2XX will be returned when all operations are successful. 401 indicates that there is a problem with the certification. Other 4xx status codes indicate that the request is invalid. If it is a 5xx error, the server has encountered an unknown serious error when processing the request. Please give feedback as soon as possible。

Return Status

Status Code Description
200/201 Request succeeded
202 Request accepted by the server, but processing is not done yet
204 Request succeeded, but the server doesn't return body
400 Invalid request
401 Authentication failed
404 Not Found
5xx Server Error

Data Type

Status Code Description
string String type, in double quotation marks. Price and amount are also formatted in string format
integer 32-bit integer，Mainly related to status codes, size, times, etc.
integer(int64) 64-bit integer，Mainly involves ID and higher precision timestamp
float Floating point number. Some time and stat fields use float.
object Object，Contains a child object{}
array List，Includes multiple groups of content
boolean true is true，false is false

Error Handling

For all abnormal requests, APIv4 will return non-2xx status code, with a response body in JSON format to explain the error.

The error response body follows a format like:

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

Take Python requests for example, error handling can be written like:

Following examples only deal with business-related errors. Network timeout or other common errors need to be handled separately:

import requests
r = requests.get("https://api.gateio.ws/api/v4/futures/btc/contracts/BTC_USD")
try:
    r.raise_for_status()
except requests.HTTPError:
    # catch 2xx errors, parse error message in body, and do something based on `label`
    if r.json()['label'] == 'xxx':
        print(r.json())

or with 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 wraps whole error information, see implementation for details
    detail = json.loads(e.value.body)
    if detail['label'] == 'xxx':
        print(detail)

label list

label Meaning
INVALID_PARAM_VALUE Invalid parameter value
INVALID_PROTOCOL Invalid parameter value
INVALID_ARGUMENT Invalid argument
INVALID_REQUEST_BODY Invalid request body
MISSING_REQUIRED_PARAM Missing required parameter
BAD_REQUEST Invalid request
INVALID_CONTENT_TYPE Invalid Content-Type header
NOT_ACCEPTABLE Invalid Accept- Header
METHOD_NOT_ALLOWED Request method is not allowed
NOT_FOUND Request URL not exists
label Meaning
INVALID_CREDENTIALS Invalid credentials provided
INVALID_KEY Invalid API Key
IP_FORBIDDEN Request IP not in whitelist
READ_ONLY API key is read-only
INVALID_SIGNATURE Invalid signature
MISSING_REQUIRED_HEADER Missing required authentication header
REQUEST_EXPIRED Request Timestamp is far from the server time
ACCOUNT_LOCKED Account is locked
FORBIDDEN Account has no permission to request operation
label Meaning
SUB_ACCOUNT_NOT_FOUND Sub account not found
SUB_ACCOUNT_LOCKED Sub account is locked
MARGIN_BALANCE_EXCEPTION Abnormal margin account
MARGIN_TRANSFER_FAILED Failed to transfer with margin account
TOO_MUCH_FUTURES_AVAILABLE Futures balance exceeds max allowed
FUTURES_BALANCE_NOT_ENOUGH Futures balance not enough
ACCOUNT_EXCEPTION Abnormal account
SUB_ACCOUNT_TRANSFER_FAILED Failed to transfer with sub account
ADDRESS_NOT_USED Address never being used in web console
TOO_FAST Withdrawing request exceeds frequency limit
WITHDRAWAL_OVER_LIMIT Withdrawal limit exceeded
label Meaning
INVALID_PRECISION Invalid precision
INVALID_CURRENCY Invalid currency
INVALID_CURRENCY_PAIR Invalid currency pair
POC_FILL_IMMEDIATELY Order would match and take immediately so it's cancelled
ORDER_NOT_FOUND Order not found
ORDER_CLOSED Order already closed
ORDER_CANCELLED Order already cancelled
QUANTITY_NOT_ENOUGH Amount is not enough
BALANCE_NOT_ENOUGH Balance is not enough
MARGIN_NOT_SUPPORTED Request currency pair doesn't provide margin trading
MARGIN_BALANCE_NOT_ENOUGH Margin balance is not enough
AMOUNT_TOO_LITTLE Amount does not reach minimum required
AMOUNT_TOO_MUCH Amount exceeds maximum allowed
REPEATED_CREATION Repeated creation
LOAN_NOT_FOUND Margin loan is not found
LOAN_RECORD_NOT_FOUND Margin loan record is not found
NO_MATCHED_LOAN No loan can match request borrow requirement
NOT_MERGEABLE Request loans cannot be merged
NO_CHANGE No change is made
REPAY_TOO_MUCH Repay more than required
TOO_MANY_CURRENCY_PAIRS Too many currency pairs in batch orders creation
TOO_MANY_ORDERS Too many orders in one currency pair in batch orders creation
MIXED_ACCOUNT_TYPE More than one account type is used in batch orders creation
AUTO_BORROW_TOO_MUCH Auto borrow exceeds maximum allowed
TRADE_RESTRICTED Trading is restricted due to high debt ratio
label Meaning
USER_NOT_FOUND User has no futures account
CONTRACT_NO_COUNTER No counter order found
CONTRACT_NOT_FOUND Contract not found
RISK_LIMIT_EXCEEDED Risk limit exceeded
INSUFFICIENT_AVAILABLE Balance is not enough
LIQUIDATE_IMMEDIATELY Operation may cause liquidation
LEVERAGE_TOO_HIGH leverage too high
LEVERAGE_TOO_LOW leverage too low
ORDER_NOT_FOUND Order not found
ORDER_NOT_OWNED Order not owned
ORDER_FINISHED Order already finished
TOO_MANY_ORDERS Too many open orders
POSITION_CROSS_MARGIN margin updating is not allowed in cross margin
POSITION_IN_LIQUIDATION Position is being liquidated
POSITION_IN_CLOSE Position is closing
POSITION_EMPTY Position is empty
REMOVE_TOO_MUCH Changed margin exceeds allowed
RISK_LIMIT_NOT_MULTIPLE Risk limit is not a multiple of step
RISK_LIMIT_TOO_HIGH Risk limit too high
RISK_LIMIT_TOO_lOW Risk limit too low
PRICE_TOO_DEVIATED Order price deviates too much from mark price
SIZE_TOO_LARGE Order size exceeds maximum
SIZE_TOO_SMALL Order size does not reach minimum
PRICE_OVER_LIQUIDATION Price to increase position can not exceeds liquidation price
PRICE_OVER_BANKRUPT Price to decrease position cannot exceeds bankrupting price
ORDER_POC_IMMEDIATE POC order will be finished immediately
INCREASE_POSITION POC order will increase position
CONTRACT_IN_DELISTING Contract is delisting, only reduce-only order or close order is allowed
label Meaning
INTERNAL Internal server error
SERVER_ERROR Internal server error
TOO_BUSY Server is too busy at the moment

Authentication

Generate API key

Before calling the private API interface, the API key of the account needs to be generated to verify the identity. You can log in on the website and generate it in [account management] - > [APIv4 keys], or click here to generate API keys.

Each account can create 5 API keys, and the permission configuration of each key is independent of each other. It is recommended to set a note name for each key to indicate its purpose.

Key Access Key
Secret Key The key used for signature authentication encryption

Besides, you can attach an IP whitelist, which requires the server only accept requests from specified IPs. Each key can have at most 20 IPs formatted in IPv4(not supporting IP range though). If IP whitelist is not set, the server will skip client IP validation.

Each user can create at most 5 keys with separate permissions. It is recommended to set a name for key denoting how the key will be used.

Created key can also be updated or deleted, but any modification could take effect in at most 5 minutes.

One more thing to notice that futures TestNet trading is a separate environment from futures real trading. Real trading API keys cannot be used in TestNet. If you want to test futures API with TestNet, you need to log into the console to generate TestNet API keys(in "Futures TestNet APIKeys" tab on "APIv4Keys" page). Making futures requests are identical between real and TestNet trading, with the only exceptions are different base URLs and different API keys.

APIv4 Permissions

When creating a Key, you can configure whether to enable spot, margin, contract, wallet, or withdrawal permissions for the Key, and whether to enable read-write or read-only permissions.

Products Permissions
spot/margin Read-only query orders Read-write query orders & place orders
perpetual contract Read-only query orders Read-write query orders & place orders
delivery contract Read-only query orders Read-write query orders & place orders
wallet Read-only Query for withdrawal transfer records Read-write Query for account records & fund transfers
withdrawal Read-only Query cash withdrawal records Read-write Query cash withdrawal records & withdrawals

All GET operations are read requests, while others are write requests. Each permission group can be set to either disabled, read-only or read-write.

One thing to notice that even though withdrawal API has only one operation(i.e., POST /withdrawals), for general concern, it is still separated from wallet API into a standalone permission group, while withdrawal history retrieving API stays inside wallet operations(i.e., GET /wallet/withdrawals).

APIv4 signed request requirements

  1. Generate APIv4 Key pairs in web console, and make sure it has the right permissions.
  2. Set request header KEY to the key.
  3. Set request header Timestamp to current time formatted in Unix time in seconds. Pay attention that the gap between its value and current time cannot exceed 60 seconds.
  4. Set request header SIGN to encrypted request signature. Refer to next section for how signature string is generated. Signature generation method is HexEncode(HMAC_SHA512(secret, signature_string)), i.e., the hexadecimal digest output of HMAC-SHA512 with APIv4 secret as secret and signature string as message,
  5. Make sure request client's IP is in your APIv4 Key's IP whitelist.

API Signature string generation

In APIv4, signature string is concatenated as the following way:

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

Request Method

Request method in UPPERCASE, e.g. POST, GET

Request URL

Request url. Protocol, host and port are not included, e.g. /api/v4/futures/orders

Query String

Request query string without URL encode. query parameters order should be the same as how they are concatenated in the request URL, e.g. status=finished&limit=50. Use empty string("") if no query parameters.

HexEncode(SHA512(Request Payload))

Hash the request body with SHA512 and output its Hex encoded form. If no request body, use empty string's hashed result, i.e. cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e

Timestamp

Timestamp request header value.

Examples

Note: all example signature string are broken into multiple lines for displaying purpose only. Only the \n character in signature string is reserved in reality.

Suppose the key we used is key, while the secret is secret.

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

Signature string：

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

Explanation：

  • /api/v4/futures/orders: request url
  • contract=BTC_USD&status=finished&limit=50: keep the query string as it is in the request url
  • request body use empty string's hashed result
  • 1541993715: Unix timestamp in seconds

Signature generated

55f84ea195d6fe57ce62464daaa7c3c02fa9d1dde954e4c898289c9a2407a3d6fb3faf24deff16790d726b66ac9f74526668b13bd01029199cc4fcc522418b8a

  1. Create an order
    POST /api/v4/futures/orders HTTP/1.1

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

Signature string：

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

Explanation：

  • request query string is empty, use plain empty string
  • use the hashed result of the json-string-formatted request body

Signature generated

eae42da914a590ddf727473aff25fc87d50b64783941061f47a3fdb92742541fc4c2c14017581b4199a1418d54471c269c03a38d788d802e2c306c37636389f0


# example authentication implementation in Python

"""
Python SDK is recommended as it has already implemented the authentication process for every API:
"""

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)

FAQ

Withdrawal

Withdrawal operations

Withdraw

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"}'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Withdraw

Body parameter

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

Parameters

Name In Type Required Description
body body object true none
» amount body string true Currency amount
» currency body string true Currency name
» address body string false Withdrawal address. Required for withdrawals
» memo body string false Extra withdrawal memo
» chain body string false Name of the chain used in withdrawals

Example responses

202 Response

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

Responses

Status Meaning Description Schema
202 Accepted Withdraw request is accepted. Refer to withdrawal records for status Inline

Response Schema

Status Code 202

Name Type Description
» id string Record ID
» txid string Hash record of the withdrawal
» timestamp string Operation time
» amount string Currency amount
» currency string Currency name
» address string Withdrawal address. Required for withdrawals
» memo string Extra withdrawal memo
» status string Record status.

- DONE: done
- CANCEL: cancelled
- REQUEST: requesting
- MANUAL: waiting for manual approval
- BCODE: GateCode operation
» chain string Name of the chain used in withdrawals

Enumerated Values

Property Value
status DONE
status CANCEL
status REQUEST
status MANUAL
status BCODE

Wallet

Wallet

Generate currency deposit address

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Generate currency deposit address

Parameters

Name In Type Required Description
currency query string true Currency name

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Address successfully generated Inline

Response Schema

Status Code 200

Name Type Description
» currency string Currency detail
» address string Deposit address
» multichain_address array none
»» MultiChainAddressItem object none
»»» chain string Name of the chain
»»» address string Deposit address
»»» payment_id string Notes that some currencies required(e.g., Tag, Memo) when depositing
»»» payment_name string Note type, Tag or Memo
»»» obtain_failed integer Whether address is obtained. 0 means success. 1 is failure, which needs retries

Retrieve withdrawal records

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

Retrieve withdrawal records

Record time range cannot exceed 30 days

Parameters

Name In Type Required Description
currency query string false Filter by currency. Return all currency records if not specified
from query integer(int64) false Time range beginning, default to 7 days before current time
to query integer(int64) false Time range ending, default to current time
limit query integer false Maximum number of records returned in one list
offset query integer false List offset, starting from 0

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» id string Record ID
» txid string Hash record of the withdrawal
» timestamp string Operation time
» amount string Currency amount
» currency string Currency name
» address string Withdrawal address. Required for withdrawals
» memo string Extra withdrawal memo
» status string Record status.

- DONE: done
- CANCEL: cancelled
- REQUEST: requesting
- MANUAL: waiting for manual approval
- BCODE: GateCode operation
» chain string Name of the chain used in withdrawals

Enumerated Values

Property Value
status DONE
status CANCEL
status REQUEST
status MANUAL
status BCODE

Retrieve deposit records

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

Retrieve deposit records

Record time range cannot exceed 30 days

Parameters

Name In Type Required Description
currency query string false Filter by currency. Return all currency records if not specified
from query integer(int64) false Time range beginning, default to 7 days before current time
to query integer(int64) false Time range ending, default to current time
limit query integer false Maximum number of records returned in one list
offset query integer false List offset, starting from 0

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» id string Record ID
» txid string Hash record of the withdrawal
» timestamp string Operation time
» amount string Currency amount
» currency string Currency name
» address string Withdrawal address. Required for withdrawals
» memo string Extra withdrawal memo
» status string Record status.

- DONE: done
- CANCEL: cancelled
- REQUEST: requesting
- MANUAL: waiting for manual approval
- BCODE: GateCode operation
» chain string Name of the chain used in withdrawals

Enumerated Values

Property Value
status DONE
status CANCEL
status REQUEST
status MANUAL
status BCODE

Transfer between trading accounts

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"}'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Transfer between trading accounts

Transfer between different accounts. Currently support transfers between the following:

  1. spot - margin
  2. spot - futures(perpetual)
  3. spot - delivery

Body parameter

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

Parameters

Name In Type Required Description
body body object true none
» currency body string true Transfer currency. For futures account, currency can be set to POINT or settle currency
» from body string true Account transferred from
» to body string true Account transferred to
» amount body string true Transfer amount
» currency_pair body string false Margin currency pair. Required if transfer from or to margin account
» settle body string false Futures settle currency. Required if currency is POINT

Enumerated Values

Parameter Value
» from spot
» from margin
» from futures
» from delivery
» to spot
» to margin
» to futures
» to delivery

Responses

Status Meaning Description Schema
204 No Content Balance transferred None

Transfer between main and sub accounts

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"}'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Transfer between main and sub accounts

Support transferring with sub user's spot or futures account. Note that only main user's spot account is used no matter which sub user's account is operated.

Body parameter

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

Parameters

Name In Type Required Description
body body object true none
» currency body string true Transfer currency name
» sub_account body string true Sub account user ID
» direction body string true Transfer direction. to - transfer into sub account; from - transfer out from sub account
» amount body string true Transfer amount
» sub_account_type body string false Target sub user's account. spot - spot account, futures - perpetual contract account

Enumerated Values

Parameter Value
» direction to
» direction from
» sub_account_type spot
» sub_account_type futures

Responses

Status Meaning Description Schema
204 No Content Balance transferred None

Transfer records between main and sub accounts

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

Transfer records between main and sub accounts

Record time range cannot exceed 30 days

Note: only records after 2020-04-10 can be retrieved

Parameters

Name In Type Required Description
sub_uid query string false Sub account user ID. Return records related to all sub accounts if not specified
from query integer(int64) false Time range beginning, default to 7 days before current time
to query integer(int64) false Time range ending, default to current time
limit query integer false Maximum number of records returned in one list
offset query integer false List offset, starting from 0

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» currency string Transfer currency name
» sub_account string Sub account user ID
» direction string Transfer direction. to - transfer into sub account; from - transfer out from sub account
» amount string Transfer amount
» uid string Main account user ID
» timest string Transfer timestamp
» source string Where the operation is initiated from
» sub_account_type string Target sub user's account. spot - spot account, futures - perpetual contract account

Enumerated Values

Property Value
direction to
direction from
sub_account_type spot
sub_account_type futures

Retrieve withdrawal status

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

Retrieve withdrawal status

Parameters

Name In Type Required Description
currency query string false Retrieved specified currency related data

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
» currency string Currency
» name string Currency name
» name_cn string Currency Chinese name
» deposit string Deposits fee
» withdraw_percent string Withdrawal fee rate percentage
» withdraw_fix string Fixed withdrawal fee
» withdraw_day_limit string Daily allowed withdrawal amount
» withdraw_amount_mini string Minimum withdrawal amount
» withdraw_day_limit_remain string Daily withdrawal amount left
» withdraw_eachtime_limit string Maximum amount for each withdrawal

Retrieve sub account balances

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

Retrieve sub account balances

Parameters

Name In Type Required Description
sub_uid query string false Sub account user ID. Return records related to all sub accounts if not specified

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
» uid string User ID
» available object Available balances of currencies
»» additionalProperties string none

Retrieve personal trading fee

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

Retrieve personal trading fee

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved Inline

Response Schema

Status Code 200

Name Type Description
» user_id integer(int64) User ID
» taker_fee string taker fee rate
» maker_fee string maker fee rate
» gt_discount boolean Is GT deduction is enabled
» gt_taker_fee string Taker fee rate if using GT deduction. It will be 0 if GT deduction is disabled
» gt_maker_fee string Maker fee rate if using GT deduction. It will be 0 if GT deduction is disabled
» loan_fee string Loan fee rate of margin lending
» point_type string Point type. 0 - Initial version. 1 - new version since 202009
» futures_taker_fee string Futures trading taker fee
» futures_maker_fee string Future trading maker fee

Spot

Spot trading

List all currencies' detail

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

List all currencies' detail

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» currency string Currency name
» delisted boolean Whether currency is de-listed
» withdraw_disabled boolean Whether currency's withdrawal is disabled
» withdraw_delayed boolean Whether currency's withdrawal is delayed
» deposit_disabled boolean Whether currency's deposit is disabled
» trade_disabled boolean Whether currency's trading is disabled

Get detail of one particular currency

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}

Get detail of one particular currency

Parameters

Name In Type Required Description
currency path string true Currency name

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved Inline

Response Schema

Status Code 200

Name Type Description
» currency string Currency name
» delisted boolean Whether currency is de-listed
» withdraw_disabled boolean Whether currency's withdrawal is disabled
» withdraw_delayed boolean Whether currency's withdrawal is delayed
» deposit_disabled boolean Whether currency's deposit is disabled
» trade_disabled boolean Whether currency's trading is disabled

List all currency pairs supported

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

List all currency pairs supported

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK All currency pairs retrieved [CurrencyPair]

Get detail of one single order

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}

Get detail of one single order

Parameters

Name In Type Required Description
currency_pair path string true Currency pair

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved CurrencyPair

Retrieve ticker information

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

Retrieve ticker information

Return only related data if currency_pair is specified; otherwise return all of them

Parameters

Name In Type Required Description
currency_pair query string false Currency pair

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
» currency_pair string Currency pair
» last string Last trading price
» lowest_ask string Lowest ask
» highest_bid string Highest bid
» change_percentage string Change percentage.
» base_volume string Base currency trade volume
» quote_volume string Quote currency trade volume
» high_24h string Highest price in 24h
» low_24h string Lowest price in 24h
» etf_net_value string ETF net value
» etf_pre_net_value string\ null
» etf_pre_timestamp integer(int64)\ null
» etf_leverage string\ null

Retrieve order book

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

Retrieve order book

Order book will be sorted by price from high to low on bids; reversed on asks

Parameters

Name In Type Required Description
currency_pair query string true Currency pair
interval query string false Order depth. 0 means no aggregation is applied. default to 0
limit query integer false Maximum number of order depth data in asks or bids
with_id query boolean false Return order book ID

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved Inline

Response Schema

Status Code 200

Name Type Description
» id integer(int64) Order book ID, which is updated whenever the order book is changed. Valid only when with_id is set to true
» asks array Asks order depth
»» None array price and amount
» bids array Bids order depth
»» None array price and amount

Retrieve market trades

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

Retrieve market trades

Parameters

Name In Type Required Description
currency_pair query string true Currency pair
limit query integer false Maximum number of records returned in one list
last_id query string false Specify list staring point using the id of last record in previous list-query results
reverse query boolean false Whether to retrieve records whose IDs are smaller than last_id's. Default to larger ones.

Detailed descriptions

reverse: Whether to retrieve records whose IDs are smaller than last_id's. Default to larger ones.

When last_id is specified. Set reverse to true to trace back trading history; false to retrieve latest tradings.

No effect if last_id is not specified.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» id string Trade ID
» create_time string Trading time
» create_time_ms string Trading time, with millisecond precision
» side string Order side
» role string Trade role
» amount string Trade amount
» price string Order price
» order_id string Related order ID. No value in public endpoints
» fee string Fee deducted. No value in public endpoints
» fee_currency string Fee currency unit. No value in public endpoints
» point_fee string Point used to deduct fee
» gt_fee string GT used to deduct fee

Enumerated Values

Property Value
side buy
side sell
role taker
role maker

Market candlesticks

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

Market candlesticks

Maximum of 1000 points are returned in one query. Be sure not to exceed the limit when specifying from, to and interval

Parameters

Name In Type Required Description
currency_pair query string true Currency pair
limit query integer false Maximum recent data points returned. limit is conflicted with from and to. If either from or to is specified, request will be rejected.
from query integer(int64) false Start time of candlesticks, formatted in Unix timestamp in seconds.
to query integer(int64) false End time of candlesticks, formatted in Unix timestamp in seconds. Default to current time
interval query string false Interval time between data points

Detailed descriptions

from: Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified

Enumerated Values

Parameter Value
interval 10s
interval 1m
interval 5m
interval 15m
interval 30m
interval 1h
interval 4h
interval 8h
interval 1d
interval 7d

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved [[string]]

Response Schema

Status Code 200

Name Type Description
» None array Candlestick data point detail. Meaning from left to right:

- Unix timestamp in seconds
- Trading volume
- Close price
- Highest price
- Lowest price
- Open price

Query user trading fee rates

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

Query user trading fee rates

This API is deprecated in favour of new fee retrieving API /wallet/fee.

Parameters

Name In Type Required Description
currency_pair query string false Specify a currency pair to retrieve precise fee rate

Detailed descriptions

currency_pair: Specify a currency pair to retrieve precise fee rate

This field is optional. In most cases, the fee rate is identical among all currency pairs

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved Inline

Response Schema

Status Code 200

Name Type Description
» user_id integer(int64) User ID
» taker_fee string taker fee rate
» maker_fee string maker fee rate
» gt_discount boolean Is GT deduction is enabled
» gt_taker_fee string Taker fee rate if using GT deduction. It will be 0 if GT deduction is disabled
» gt_maker_fee string Maker fee rate if using GT deduction. It will be 0 if GT deduction is disabled
» loan_fee string Loan fee rate of margin lending
» point_type string Point type. 0 - Initial version. 1 - new version since 202009
» futures_taker_fee string Futures trading taker fee
» futures_maker_fee string Future trading maker fee

List spot accounts

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

List spot accounts

Parameters

Name In Type Required Description
currency query string false Retrieved specified currency related data

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
» currency string Currency detail
» available string Available amount
» locked string Locked amount, used in trading

Create a batch of orders

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}]'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Create a batch of orders

Batch orders requirements:

  1. custom order field text is required
  2. At most 4 currency pairs, maximum 10 orders each, are allowed in one request
  3. No mixture of spot orders and margin orders, i.e. account must be identical for all 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
  }
]

Parameters

Name In Type Required Description
body body array[object] true none

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Request is completed [Inline]

Response Schema

Status Code 200

Name Type Description
» None object Batch order details
»» text string User defined information. If not empty, must follow the rules below:

1. prefixed with t-
2. no longer than 28 bytes without t- prefix
3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
»» succeeded boolean Whether order succeeds
»» label string Error label, empty string if order succeeds
»» message string Detailed error message, empty string if order succeeds
»» id string Order ID
»» create_time string Order creation time
»» update_time string Order last modification time
»» status string Order status

- open: to be filled
- closed: filled
- cancelled: cancelled
»» currency_pair string Currency pair
»» type string Order type. limit - limit order
»» account string Account type. spot - use spot account; margin - use margin account
»» side string Order side
»» amount string Trade amount
»» price string Order price
»» time_in_force string Time in force

- gtc: GoodTillCancelled
- ioc: ImmediateOrCancelled, taker only
- poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee
»» iceberg string Amount to display for the iceberg order. Null or 0 for normal orders. Set to -1 to hide the amount totally
»» left string Amount left to fill
»» fill_price string Total filled in quote currency. Deprecated in favor of filled_total
»» filled_total string Total filled in quote currency
»» fee string Fee deducted
»» fee_currency string Fee currency unit
»» point_fee string Point used to deduct fee
»» gt_fee string GT used to deduct fee
»» gt_discount boolean Whether GT fee discount is used
»» rebated_fee string Rebated fee
»» rebated_fee_currency string Rebated fee currency unit

Enumerated Values

Property Value
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

List all open orders

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

List all open orders

List open orders in all currency pairs.

Note that pagination parameters affect record number in each currency pair's open order list. No pagination is applied to the number of currency pairs returned. All currency pairs with open orders will be returned

Parameters

Name In Type Required Description
page query integer false Page number
limit query integer false Maximum number of records returned in one page in each currency pair

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
» currency_pair string Currency pair
» total integer Total open orders in this currency pair
» orders array none
»» None object Spot order details
»»» id string Order ID
»»» text string User defined information. If not empty, must follow the rules below:

1. prefixed with t-
2. no longer than 28 bytes without t- prefix
3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
»»» create_time string Order creation time
»»» update_time string Order last modification time
»»» status string Order status

- open: to be filled
- closed: filled
- cancelled: cancelled
»»» currency_pair string Currency pair
»»» type string Order type. limit - limit order
»»» account string Account type. spot - use spot account; margin - use margin account
»»» side string Order side
»»» amount string Trade amount
»»» price string Order price
»»» time_in_force string Time in force

- gtc: GoodTillCancelled
- ioc: ImmediateOrCancelled, taker only
- poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee
»»» iceberg string Amount to display for the iceberg order. Null or 0 for normal orders. Set to -1 to hide the amount totally
»»» left string Amount left to fill
»»» fill_price string Total filled in quote currency. Deprecated in favor of filled_total
»»» filled_total string Total filled in quote currency
»»» fee string Fee deducted
»»» fee_currency string Fee currency unit
»»» point_fee string Point used to deduct fee
»»» gt_fee string GT used to deduct fee
»»» gt_discount boolean Whether GT fee discount is used
»»» rebated_fee string Rebated fee
»»» rebated_fee_currency string Rebated fee currency unit

Enumerated Values

Property Value
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

Create an 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 = ''
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}'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Create an order

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
}

Parameters

Name In Type Required Description
body body Order true none
» text body string false User defined information. If not empty, must follow the rules below:
» currency_pair body string true Currency pair
» type body string false Order type. limit - limit order
» account body string false Account type. spot - use spot account; margin - use margin account
» side body string true Order side
» amount body string true Trade amount
» price body string true Order price
» time_in_force body string false Time in force
» iceberg body string false Amount to display for the iceberg order. Null or 0 for normal orders. Set to -1 to hide the amount totally
» auto_borrow body boolean false Used in margin trading(i.e. account is margin) to allow automatic loan of insufficient part if balance is not enough.

Detailed descriptions

» text: User defined information. If not empty, must follow the rules below:

  1. prefixed with t-
  2. no longer than 28 bytes without t- prefix
  3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)

» time_in_force: Time in force

Enumerated Values

Parameter Value
» type limit
» account spot
» account margin
» side buy
» side sell
» time_in_force gtc
» time_in_force ioc
» time_in_force poc

Example responses

201 Response

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

Responses

Status Meaning Description Schema
201 Created Order created. Order

List orders

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

List orders

Parameters

Name In Type Required Description
currency_pair query string true Currency pair
status query string true List orders based on status
page query integer false Page number
limit query integer false Maximum number of records returned. If status is open, maximum of limit is 100

Detailed descriptions

status: List orders based on status

open - order is waiting to be filled finished - order has been filled or cancelled

Enumerated Values

Parameter Value
status open
status finished

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Order]

Cancel all open orders in specified currency pair

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Cancel all open orders in specified currency pair

Parameters

Name In Type Required Description
currency_pair query string true Currency pair
side query string false All bids or asks. Both included in not specified
account query string false Specify account type. Default to all account types being included

Enumerated Values

Parameter Value
side buy
side sell
account spot
account margin

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Batch cancellation request accepted. Query order status by listing orders [Order]

Cancel a batch of orders with an ID list

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"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Cancel a batch of orders with an ID list

Multiple currency pairs can be specified, but maximum 20 orders are allowed per request

Body parameter

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

Parameters

Name In Type Required Description
body body array[object] true none

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Batch cancellation completed [Inline]

Response Schema

Status Code 200

Name Type Description
» CancelOrderResult object Order cancellation result
»» currency_pair string Order currency pair
»» id string Order ID
»» succeeded boolean Whether cancellation succeeded
»» label string Error label when failed to cancel the order; emtpy if succeeded
»» message string Error message when failed to cancel the order; empty if succeeded

Get a single 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'
# for `gen_sign` implementation, refer to section `Authentication` above
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}

Get a single order

Parameters

Name In Type Required Description
order_id path string true Order ID returned, or user custom ID(i.e., text field).
currency_pair query string true Currency pair

Detailed descriptions

order_id: Order ID returned, or user custom ID(i.e., text field). Operations based on custom ID are accepted only in the first 30 minutes after order creation.After that, only order ID is accepted.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Detail retrieved Order

Cancel a single 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'
# for `gen_sign` implementation, refer to section `Authentication` above
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}

Cancel a single order

Parameters

Name In Type Required Description
order_id path string true Order ID returned, or user custom ID(i.e., text field).
currency_pair query string true Currency pair

Detailed descriptions

order_id: Order ID returned, or user custom ID(i.e., text field). Operations based on custom ID are accepted only in the first 30 minutes after order creation.After that, only order ID is accepted.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Order cancelled Order

List personal trading history

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

List personal trading history

Parameters

Name In Type Required Description
currency_pair query string true Currency pair
limit query integer false Maximum number of records returned in one list
page query integer false Page number
order_id query string false List all trades of specified order

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» id string Trade ID
» create_time string Trading time
» create_time_ms string Trading time, with millisecond precision
» side string Order side
» role string Trade role
» amount string Trade amount
» price string Order price
» order_id string Related order ID. No value in public endpoints
» fee string Fee deducted. No value in public endpoints
» fee_currency string Fee currency unit. No value in public endpoints
» point_fee string Point used to deduct fee
» gt_fee string GT used to deduct fee

Enumerated Values

Property Value
side buy
side sell
role taker
role maker

Create a price-triggered 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/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"}'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Create a price-triggered order

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

Parameters

Name In Type Required Description
body body SpotPriceTriggeredOrder true none
» trigger body object true none
»» price body string true Trigger price
»» rule body string true Price trigger condition
»» expiration body integer true How many seconds will the order wait for the condition being triggered. Order will be cancelled on timed out
» put body object true none
»» type body string false Order type, default to limit
»» side body string true Order side
»» price body string true Order price
»» amount body string true Order amount
»» account body string true Trading type
»» time_in_force body string false time_in_force
» market body string true Currency pair

Detailed descriptions

»» rule: Price trigger condition

»» side: Order side

»» account: Trading type

»» time_in_force: time_in_force

Enumerated Values

Parameter Value
»» rule >=
»» rule <=
»» side buy
»» side sell
»» account normal
»» account margin
»» time_in_force gtc
»» time_in_force ioc

Example responses

201 Response

{
  "id": 1432329
}

Responses

Status Meaning Description Schema
201 Created Order created Inline

Response Schema

Status Code 201

TriggerOrderResponse

Name Type Description
» id integer(int64) Auto order ID

Retrieve running auto order list

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Retrieve running auto order list

Parameters

Name In Type Required Description
status query string true List orders based on status
market query string false Currency pair
account query string false Trading account
limit query integer false Maximum number of records returned in one list
offset query integer false List offset, starting from 0

Enumerated Values

Parameter Value
status open
status finished
account normal
account margin

Example responses

200 Response

[
  {
    "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": ""
  }
]

Responses

Status Meaning Description Schema
200 OK List retrieved [SpotPriceTriggeredOrder]

Cancel all open orders

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

Cancel all open orders

Parameters

Name In Type Required Description
market query string false Currency pair
account query string false Trading account

Enumerated Values

Parameter Value
account normal
account margin

Example responses

200 Response

[
  {
    "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": ""
  }
]

Responses

Status Meaning Description Schema
200 OK Batch cancellation request accepted. Query order status by listing orders [SpotPriceTriggeredOrder]

Get a single 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/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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}

Get a single order

Parameters

Name In Type Required Description
order_id path string true ID returned on order successfully being created

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Auto order detail SpotPriceTriggeredOrder

Cancel a single 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/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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}

Cancel a single order

Parameters

Name In Type Required Description
order_id path string true ID returned on order successfully being created

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Auto order detail SpotPriceTriggeredOrder

Margin

Margin API; margin trading uses spot trading API

List all supported currency pairs supported in margin trading

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

List all supported currency pairs supported in margin trading

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» id string Currency pair
» base string Base currency
» quote string Quote currency
» leverage integer Leverage
» min_base_amount string Minimum base currency to loan, null means no limit
» min_quote_amount string Minimum quote currency to loan, null means no limit
» max_quote_amount string Maximum borrowable amount for quote currency. Base currency limit is calculated by quote maximum and market price. null means no limit

Query one single margin currency pair

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}

Query one single margin currency pair

Parameters

Name In Type Required Description
currency_pair path string true Margin currency pair

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved Inline

Response Schema

Status Code 200

Name Type Description
» id string Currency pair
» base string Base currency
» quote string Quote currency
» leverage integer Leverage
» min_base_amount string Minimum base currency to loan, null means no limit
» min_quote_amount string Minimum quote currency to loan, null means no limit
» max_quote_amount string Maximum borrowable amount for quote currency. Base currency limit is calculated by quote maximum and market price. null means no limit

Order book of lending loans

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

Order book of lending loans

Parameters

Name In Type Required Description
currency query string true Retrieved specified currency related data

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Order book retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
» rate string Loan rate
» amount string Borrowable amount
» days integer How long the loan should be repaid

Margin account list

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

Margin account list

Parameters

Name In Type Required Description
currency_pair query string false Currency pair

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
» None object Margin account detail. base refers to base currency, while `quotes to quote currency
»» currency_pair string Currency pair
»» base object Account currency detail
»»» currency string Currency name
»»» available string Amount suitable for margin trading.
»»» locked string Locked amount, used in margin trading
»»» borrowed string Borrowed amount
»» quote object Account currency detail
»»» currency string Currency name
»»» available string Amount suitable for margin trading.
»»» locked string Locked amount, used in margin trading
»»» borrowed string Borrowed amount

List margin account balance change history

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

List margin account balance change history

Only transferring from or to margin account are provided for now. Time range allows 30 days at most

Parameters

Name In Type Required Description
currency query string false List records related to specified currency only. If specified, currency_pair is also required.
currency_pair query string false List records related to specified currency pair. Used in combination with currency. Ignored if currency is not provided
from query integer(int64) false Time range beginning, default to 7 days before current time
to query integer(int64) false Time range ending, default to current time
page query integer false Page number
limit query integer false Maximum number of records returned in one list

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
» id string Balance change record ID
» time string Balance changed timestamp
» currency string Currency changed
» currency_pair string Account currency pair
» change string Amount changed. Positive value means transferring in, while negative out
» balance string Balance after change

Funding account list

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

Funding account list

Parameters

Name In Type Required Description
currency query string false Retrieved specified currency related data

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
» currency string Currency name
» available string Available assets to lend, which is identical to spot account available
» locked string Locked amount. i.e. amount in open loans
» lent string Amount that is loaned but not repaid
» total_lent string Amount used for lending. total_lent = lent + locked

Lend or borrow

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"}'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Lend or borrow

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

Parameters

Name In Type Required Description
body body Loan true none
» side body string true Loan side
» currency body string true Loan currency
» rate body string false Loan rate. Only rates in [0.0002, 0.002] are supported.
» amount body string true Loan amount
» days body integer true Loan days
» auto_renew body boolean false Auto renew the loan on expiration
» currency_pair body string false Currency pair. Required for borrowing side
» fee_rate body string false Loan fee rate
» orig_id body string false Original loan ID if the loan is auto-renewed. Equal to id if not

Detailed descriptions

» rate: Loan rate. Only rates in [0.0002, 0.002] are supported.

Not required in lending. Market rate calculated from recent rates will be used if not set

Enumerated Values

Parameter Value
» side lend
» side borrow

Example responses

201 Response

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

Responses

Status Meaning Description Schema
201 Created Loan created Loan

List all loans

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

List all loans

Parameters

Name In Type Required Description
status query string true Loan status
side query string true Lend or borrow
currency query string false Retrieved specified currency related data
currency_pair query string false Currency pair
sort_by query string false Specify which field is used to sort. create_time or rate is supported. Default to create_time
reverse_sort query boolean false Whether to sort in descending order. Default to true
page query integer false Page number
limit query integer false Maximum number of records returned in one list

Enumerated Values

Parameter Value
status open
status loaned
status finished
status auto_repaid
side lend
side borrow
sort_by create_time
sort_by rate

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Loan]

Merge multiple lending loans

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Merge multiple lending loans

Parameters

Name In Type Required Description
currency query string true Retrieved specified currency related data
ids query string true Lending loan ID list separated by ,. Maximum of 20 IDs are allowed in one request

Example responses

201 Response

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

Responses

Status Meaning Description Schema
201 Created Loans merged Loan

Retrieve one single loan detail

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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}

Retrieve one single loan detail

Parameters

Name In Type Required Description
side query string true Lend or borrow
loan_id path string true Loan ID

Enumerated Values

Parameter Value
side lend
side borrow

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved Loan

Modify a 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}'
# for `gen_sign` implementation, refer to section `Authentication` above
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}

Modify a loan

Only auto_renew modification is supported currently

Body parameter

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

Parameters

Name In Type Required Description
body body object true none
» currency body string true Loan currency
» side body string true Loan side. Possible values are lend and borrow. For LoanRecord patching, only lend is supported
» auto_renew body boolean true Auto renew
» currency_pair body string false Currency pair. Required for borrowing side
» loan_id body string false Loan ID. Required for LoanRecord patching
loan_id path string true Loan ID

Enumerated Values

Parameter Value
» side lend
» side borrow

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Updated Loan

Cancel lending 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'
# for `gen_sign` implementation, refer to section `Authentication` above
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}

Cancel lending loan

Only lending loans can be cancelled

Parameters

Name In Type Required Description
currency query string true Retrieved specified currency related data
loan_id path string true Loan ID

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Order cancelled Loan

Repay a 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"}'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Repay a loan

Body parameter

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

Parameters

Name In Type Required Description
body body object true none
» currency_pair body string true Currency pair
» currency body string true Loan currency
» mode body string true Repay mode. all - repay all; partial - repay only some portion
» amount body string false Repay amount. Required in partial mode
loan_id path string true Loan ID

Enumerated Values

Parameter Value
» mode all
» mode partial

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Loan repaid Loan

List loan repayment records

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

List loan repayment records

Parameters

Name In Type Required Description
loan_id path string true Loan ID

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
» id string Loan record ID
» create_time string Repayment time
» principal string Repaid principal
» interest string Repaid interest

List repayment records of specified 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/loan_records'
query_param = 'loan_id=12345'
# for `gen_sign` implementation, refer to section `Authentication` above
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

List repayment records of specified loan

Parameters

Name In Type Required Description
loan_id query string true Loan ID
status query string false Loan record status
page query integer false Page number
limit query integer false Maximum number of records returned in one list

Enumerated Values

Parameter Value
status loaned
status finished

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [LoanRecord]

Get one single loan record

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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}

Get one single loan record

Parameters

Name In Type Required Description
loan_id query string true Loan ID
loan_record_id path string true Loan record ID

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Detail retrieved LoanRecord

Modify a loan record

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}'
# for `gen_sign` implementation, refer to section `Authentication` above
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}

Modify a loan record

Only auto_renew modification is supported currently

Body parameter

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

Parameters

Name In Type Required Description
body body object true none
» currency body string true Loan currency
» side body string true Loan side. Possible values are lend and borrow. For LoanRecord patching, only lend is supported
» auto_renew body boolean true Auto renew
» currency_pair body string false Currency pair. Required for borrowing side
» loan_id body string false Loan ID. Required for LoanRecord patching
loan_record_id path string true Loan record ID

Enumerated Values

Parameter Value
» side lend
» side borrow

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Loan record updated LoanRecord

Update user's auto repayment setting

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Update user's auto repayment setting

Parameters

Name In Type Required Description
status query string true New auto repayment status. on - enabled, off - disabled

Example responses

200 Response

{
  "status": "on"
}

Responses

Status Meaning Description Schema
200 OK Current auto repayment setting Inline

Response Schema

Status Code 200

AutoRepaySetting

Name Type Description
» status string Auto repayment status. on - enabled, off - disabled

Enumerated Values

Property Value
status true
status false

Retrieve user auto repayment setting

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

Retrieve user auto repayment setting

Example responses

200 Response

{
  "status": "on"
}

Responses

Status Meaning Description Schema
200 OK Current auto repayment setting Inline

Response Schema

Status Code 200

AutoRepaySetting

Name Type Description
» status string Auto repayment status. on - enabled, off - disabled

Enumerated Values

Property Value
status true
status false

Futures

永续合约

List all futures contracts

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

List all futures contracts

Parameters

Name In Type Required Description
settle path string true Settle currency

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Contract]

Get a single 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}

Get a single contract

Parameters

Name In Type Required Description
settle path string true Settle currency
contract path string true Futures contract

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Contract information Contract

Futures order book

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

Futures order book

Bids will be sorted by price from high to low, while asks sorted reversely

Parameters

Name In Type Required Description
settle path string true Settle currency
contract query string true Futures contract
interval query string false Order depth. 0 means no aggregation is applied. default to 0
limit query integer false Maximum number of order depth data in asks or bids
with_id query boolean false Whether order book update ID would be returned. This ID increments by 1 on every order book update

Enumerated Values

Parameter Value
settle btc
settle usdt
interval 0
interval 0.1
interval 0.01

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Order book retrieved Inline

Response Schema

Status Code 200

Name Type Description
» id integer(int64) Order Book ID. Increase by 1 on every order book change. Set with_id=true to include this field in response
» asks array Asks order depth
»» futures_order_book_item object none
»»» p string Price
»»» s integer(int64) Size
»» bids array Bids order depth
»»» futures_order_book_item object none
»»»» p string Price
»»»» s integer(int64) Size

Futures trading history

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

Futures trading history

Parameters

Name In Type Required Description
settle path string true Settle currency
contract query string true Futures contract
limit query integer false Maximum number of records returned in one list
last_id query string false Specify list staring point using the id of last record in previous list-query results
from query integer(int64) false Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items.
to query integer(int64) false Specify end time in Unix seconds, default to current time

Detailed descriptions

last_id: Specify list staring point using the id of last record in previous list-query results

This parameter is deprecated. Use from and to instead to limit time range

from: Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items. If items between from and to are more than limit, only limit number will be returned.

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» id integer(int64) Trade ID
» create_time number(double) Trading time
» create_time_ms number(double) Trading time, with milliseconds set to 3 decimal places.
» contract string Futures contract
» size integer(int64) Trading size
» price string Trading price

Get futures candlesticks

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

Get futures candlesticks

Return specified contract candlesticks. If prefix contract with mark_, the contract's mark price candlesticks are returned; if prefix with index_, index price candlesticks will be returned.

Maximum of 2000 points are returned in one query. Be sure not to exceed the limit when specifying from, to and interval

Parameters

Name In Type Required Description
settle path string true Settle currency
contract query string true Futures contract
from query integer(int64) false Start time of candlesticks, formatted in Unix timestamp in seconds.
to query integer(int64) false End time of candlesticks, formatted in Unix timestamp in seconds. Default to current time
limit query integer false Maximum recent data points returned. limit is conflicted with from and to. If either from or to is specified, request will be rejected.
interval query string false Interval time between data points

Detailed descriptions

from: Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified

Enumerated Values

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

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array [data point in every timestamp]
» None object data point in every timestamp
»» t number(double) Unix timestamp in seconds
»» v integer(int64) size volume. Only returned if contract is not prefixed
»» c string Close price
»» h string Highest price
»» l string Lowest price
»» o string Open price

List futures tickers

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

List futures tickers

Parameters

Name In Type Required Description
settle path string true Settle currency
contract query string false Futures contract, return related data only if specified

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» contract string Futures contract
» last string Last trading price
» change_percentage string Change percentage.
» total_size string Contract total size
» low_24h string Lowest trading price in recent 24h
» high_24h string Highest trading price in recent 24h
» volume_24h string Trade size in recent 24h
» volume_24h_btc string Trade volumes in recent 24h in BTC(deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead)
» volume_24h_usd string Trade volumes in recent 24h in USD(deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead)
» volume_24h_base string Trade volume in recent 24h, in base currency
» volume_24h_quote string Trade volume in recent 24h, in quote currency
» volume_24h_settle string Trade volume in recent 24h, in settle currency
» mark_price string Recent mark price
» funding_rate string Funding rate
» funding_rate_indicative string Indicative Funding rate in next period
» index_price string Index price
» quanto_base_rate string Exchange rate of base currency and settlement currency in Quanto contract. Not existed in contract of other types

Funding rate history

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

Funding rate history

Parameters

Name In Type Required Description
settle path string true Settle currency
contract query string true Futures contract
limit query integer false Maximum number of records returned in one list

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK History retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
» t integer(int64) Unix timestamp in seconds
» r string Funding rate

Futures insurance balance history

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

Futures insurance balance history

Parameters

Name In Type Required Description
settle path string true Settle currency
limit query integer false Maximum number of records returned in one list

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» t integer(int64) Unix timestamp in seconds
» b string Insurance balance

Futures stats

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

Futures stats

Parameters

Name In Type Required Description
settle path string true Settle currency
contract query string true Futures contract
from query integer(int64) false Start timestamp
interval query string false none
limit query integer false none

Enumerated Values

Parameter Value
settle btc
settle usdt
interval 5m
interval 15m
interval 30m
interval 1h
interval 4h
interval 1d

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
» time integer(int64) Stat timestamp
» lsr_taker number Long/short account number ratio
» lsr_account number Long/short taker size ratio
» long_liq_size integer(int64) Long liquidation size
» long_liq_amount number(double) Long liquidation amount(base currency)
» long_liq_usd number(double) Long liquidation volume(quote currency)
» short_liq_size integer(int64) Short liquidation size
» short_liq_amount number(double) Short liquidation amount(base currency)
» short_liq_usd number(double) Short liquidation volume(quote currency)
» open_interest integer(int64) Open interest size
» open_interest_usd number(double) Open interest volume(quote currency)
» top_lsr_account number(double) Top trader long/short account ratio
» top_lsr_size number(double) Top trader long/short position ratio

Retrieve liquidation history

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

Retrieve liquidation history

Interval between from and to cannot exceeds 3600. Some private fields will not be returned in public endpoints. Refer to field description for detail.

Parameters

Name In Type Required Description
settle path string true Settle currency
contract query string false Futures contract, return related data only if specified
from query integer(int64) false Start timestamp
to query integer(int64) false End timestamp
limit query integer false Maximum number of records returned in one list

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» time integer(int64) Liquidation time
» contract string Futures contract
» leverage string Position leverage. Not returned in public endpoints.
» size integer(int64) Position size
» margin string Position margin. Not returned in public endpoints.
» entry_price string Average entry price. Not returned in public endpoints.
» liq_price string Liquidation price. Not returned in public endpoints.
» mark_price string Mark price. Not returned in public endpoints.
» order_id integer(int64) Liquidation order ID. Not returned in public endpoints.
» order_price string Liquidation order price
» fill_price string Liquidation order average taker price
» left integer(int64) Liquidation order maker size

Query futures account

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

Query futures account

Parameters

Name In Type Required Description
settle path string true Settle currency

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved Inline

Response Schema

Status Code 200

Name Type Description
» total string Total assets, total = position_margin + order_margin + available
» unrealised_pnl string Unrealized PNL
» position_margin string Position margin
» order_margin string Order margin of unfinished orders
» available string Available balance to transfer out or trade
» point string POINT amount
» currency string Settle currency
» in_dual_mode boolean Whether dual mode is enabled

Query account book

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

Query account book

Parameters

Name In Type Required Description
settle path string true Settle currency
limit query integer false Maximum number of records returned in one list
from query integer(int64) false Start timestamp
to query integer(int64) false End timestamp
type query string false Changing Type:

Detailed descriptions

type: Changing Type: - dnw: Deposit & Withdraw - pnl: Profit & Loss by reducing position - fee: Trading fee - refr: Referrer rebate - fund: Funding - point_dnw: POINT Deposit & Withdraw - point_fee: POINT Trading fee - point_refr: POINT Referrer rebate

Enumerated Values

Parameter Value
settle btc
settle usdt
type dnw
type pnl
type fee
type refr
type fund
type point_dnw
type point_fee
type point_refr

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» time number(double) Change time
» change string Change amount
» balance string Balance after change
» type string Changing Type:
- dnw: Deposit & Withdraw
- pnl: Profit & Loss by reducing position
- fee: Trading fee
- refr: Referrer rebate
- fund: Funding
- point_dnw: POINT Deposit & Withdraw
- point_fee: POINT Trading fee
- point_refr: POINT Referrer rebate
» text string Comment

Enumerated Values

Property Value
type dnw
type pnl
type fee
type refr
type fund
type point_dnw
type point_fee
type point_refr

List all positions of a user

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

List all positions of a user

Parameters

Name In Type Required Description
settle path string true Settle currency

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Position]

Get single 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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}

Get single position

Parameters

Name In Type Required Description
settle path string true Settle currency
contract path string true Futures contract

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Position information Position

Update position margin

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Update position margin

Parameters

Name In Type Required Description
settle path string true Settle currency
contract path string true Futures contract
change query string true Margin change. Use positive number to increase margin, negative number otherwise.

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Position information Position

Update position leverage

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Update position leverage

Parameters

Name In Type Required Description
settle path string true Settle currency
contract path string true Futures contract
leverage query string true New position leverage

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Position information Position

Update position risk limit

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Update position risk limit

Parameters

Name In Type Required Description
settle path string true Settle currency
contract path string true Futures contract
risk_limit query string true New position risk limit

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Position information Position

Enable or disable dual mode

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Enable or disable dual mode

Before setting dual mode, make sure all positions are closed and no orders are open

Parameters

Name In Type Required Description
settle path string true Settle currency
dual_mode query boolean true Whether to enable dual mode

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Updated Inline

Response Schema

Status Code 200

Name Type Description
» total string Total assets, total = position_margin + order_margin + available
» unrealised_pnl string Unrealized PNL
» position_margin string Position margin
» order_margin string Order margin of unfinished orders
» available string Available balance to transfer out or trade
» point string POINT amount
» currency string Settle currency
» in_dual_mode boolean Whether dual mode is enabled

Retrieve position detail in dual mode

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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}

Retrieve position detail in dual mode

Parameters

Name In Type Required Description
settle path string true Settle currency
contract path string true Futures contract

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved [Position]

Update position margin in dual mode

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Update position margin in dual mode

Parameters

Name In Type Required Description
settle path string true Settle currency
contract path string true Futures contract
change query string true Margin change. Use positive number to increase margin, negative number otherwise.

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved [Position]

Update position leverage in dual mode

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Update position leverage in dual mode

Parameters

Name In Type Required Description
settle path string true Settle currency
contract path string true Futures contract
leverage query string true New position leverage

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved [Position]

Update position risk limit in dual mode

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Update position risk limit in dual mode

Parameters

Name In Type Required Description
settle path string true Settle currency
contract path string true Futures contract
risk_limit query string true New position risk limit

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved [Position]

Create a futures 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 = '/futures/usdt/orders'
query_param = ''
body='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Create a futures order

Zero-fill order cannot be retrieved 60 seconds after cancellation

Body parameter

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

Parameters

Name In Type Required Description
body body FuturesOrder true none
» contract body string true Futures contract
» size body integer(int64) true Order size. Specify positive number to make a bid, and negative number to ask
» iceberg body integer(int64) false Display size for iceberg order. 0 for non-iceberg. Note that you would pay the taker fee for the hidden size
» price body string false Order price. 0 for market order with tif set as ioc
» close body boolean false Set as true to close the position, with size set to 0
» reduce_only body boolean false Set as true to be reduce-only order
» tif body string false Time in force
» text body string false User defined information. If not empty, must follow the rules below:
settle path string true Settle currency

Detailed descriptions

» tif: Time in force

» text: User defined information. If not empty, must follow the rules below:

  1. prefixed with t-
  2. no longer than 28 bytes without t- prefix
  3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created:

Enumerated Values

Parameter Value
» tif gtc
» tif ioc
» tif poc
settle btc
settle usdt

Example responses

201 Response

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

Responses

Status Meaning Description Schema
201 Created Order details FuturesOrder

List futures orders

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

List futures orders

Zero-fill order cannot be retrieved 60 seconds after cancellation

Parameters

Name In Type Required Description
contract query string true Futures contract
status query string true List orders based on status
limit query integer false Maximum number of records returned in one list
offset query integer false List offset, starting from 0
last_id query string false Specify list staring point using the id of last record in previous list-query results
count_total query integer false Whether to return total number matched. Default to 0(no return)
settle path string true Settle currency

Enumerated Values

Parameter Value
status open
status finished
count_total 0
count_total 1
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [FuturesOrder]

Response Headers

Status Header Type Format Description
200 X-Pagination-Limit integer Request limit specified
200 X-Pagination-Offset integer Request offset specified
200 X-Pagination-Total integer Total number matched. Only returned on count_total set to 1

Cancel all open orders matched

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Cancel all open orders matched

Zero-fill order cannot be retrieved 60 seconds after cancellation

Parameters

Name In Type Required Description
contract query string true Futures contract
side query string false All bids or asks. Both included in not specified
settle path string true Settle currency

Enumerated Values

Parameter Value
side ask
side bid
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK All orders matched cancelled [FuturesOrder]

Get a single 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 = '/futures/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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}

Get a single order

Zero-fill order cannot be retrieved 60 seconds after cancellation

Parameters

Name In Type Required Description
settle path string true Settle currency
order_id path string true Order ID returned, or user custom ID(i.e., text field).

Detailed descriptions

order_id: Order ID returned, or user custom ID(i.e., text field). Operations based on custom ID are accepted only in the first 30 minutes after order creation.After that, only order ID is accepted.

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Order details FuturesOrder

Cancel a single 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 = '/futures/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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}

Cancel a single order

Parameters

Name In Type Required Description
settle path string true Settle currency
order_id path string true Order ID returned, or user custom ID(i.e., text field).

Detailed descriptions

order_id: Order ID returned, or user custom ID(i.e., text field). Operations based on custom ID are accepted only in the first 30 minutes after order creation.After that, only order ID is accepted.

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Order details FuturesOrder

List personal trading history

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

List personal trading history

Parameters

Name In Type Required Description
settle path string true Settle currency
contract query string false Futures contract, return related data only if specified
order query integer(int64) false Futures order ID, return related data only if specified
limit query integer false Maximum number of records returned in one list
offset query integer false List offset, starting from 0
last_id query string false Specify list staring point using the id of last record in previous list-query results
count_total query integer false Whether to return total number matched. Default to 0(no return)

Enumerated Values

Parameter Value
settle btc
settle usdt
count_total 0
count_total 1

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» id integer(int64) Trade ID
» create_time number(double) Trading time
» contract string Futures contract
» order_id string Order ID related
» size integer(int64) Trading size
» price string Trading price
» role string Trade role. Available values are taker and maker

Enumerated Values

Property Value
role taker
role maker

Response Headers

Status Header Type Format Description
200 X-Pagination-Limit integer Request limit specified
200 X-Pagination-Offset integer Request offset specified
200 X-Pagination-Total integer Total number matched. Only returned on count_total set to 1

List position close history

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

List position close history

Parameters

Name In Type Required Description
settle path string true Settle currency
contract query string false Futures contract, return related data only if specified
limit query integer false Maximum number of records returned in one list
offset query integer false List offset, starting from 0

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» time number(double) Position close time
» contract string Futures contract
» side string Position side, long or short
» pnl string PNL
» text string Text of close order

Enumerated Values

Property Value
side long
side short

List liquidation history

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

List liquidation history

Parameters

Name In Type Required Description
settle path string true Settle currency
contract query string false Futures contract, return related data only if specified
limit query integer false Maximum number of records returned in one list
at query integer false Specify a liquidation timestamp

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» time integer(int64) Liquidation time
» contract string Futures contract
» leverage string Position leverage. Not returned in public endpoints.
» size integer(int64) Position size
» margin string Position margin. Not returned in public endpoints.
» entry_price string Average entry price. Not returned in public endpoints.
» liq_price string Liquidation price. Not returned in public endpoints.
» mark_price string Mark price. Not returned in public endpoints.
» order_id integer(int64) Liquidation order ID. Not returned in public endpoints.
» order_price string Liquidation order price
» fill_price string Liquidation order average taker price
» left integer(int64) Liquidation order maker size

Create a price-triggered 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 = '/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}}'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Create a price-triggered order

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

Parameters

Name In Type Required Description
body body FuturesPriceTriggeredOrder true none
» initial body object true none
»» contract body string true Futures contract
»» size body integer(int64) false Order size. Positive size means to buy, while negative one means to sell. Set to 0 to close the position
»» price body string true Order price. Set to 0 to use market price
»» close body boolean false Set to true if trying to close the position
»» tif body string false Time in force. If using market price, only ioc is supported.
»» text body string false How the order is created. Possible values are: web, api and app
»» reduce_only body boolean false Set to true to create an reduce-only order
» trigger body object true none
»» strategy_type body integer false How the order will be triggered
»» price_type body integer false Price type. 0 - latest deal price, 1 - mark price, 2 - index price
»» price body string false Value of price on price triggered, or price gap on price gap triggered
»» rule body integer false Trigger condition type
»» expiration body integer false How many seconds will the order wait for the condition being triggered. Order will be cancelled on timed out
settle path string true Settle currency

Detailed descriptions

»» tif: Time in force. If using market price, only ioc is supported.

»» strategy_type: How the order will be triggered

»» rule: Trigger condition type

Enumerated Values

Parameter Value
»» 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

Example responses

201 Response

{
  "id": 1432329
}

Responses

Status Meaning Description Schema
201 Created Order created Inline

Response Schema

Status Code 201

TriggerOrderResponse

Name Type Description
» id integer(int64) Auto order ID

List all auto orders

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

List all auto orders

Parameters

Name In Type Required Description
status query string true List orders based on status
contract query string false Futures contract, return related data only if specified
limit query integer false Maximum number of records returned in one list
offset query integer false List offset, starting from 0
settle path string true Settle currency

Enumerated Values

Parameter Value
status open
status finished
settle btc
settle usdt

Example responses

200 Response

[
  {
    "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": ""
  }
]

Responses

Status Meaning Description Schema
200 OK List retrieved [FuturesPriceTriggeredOrder]

Cancel all open orders

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Cancel all open orders

Parameters

Name In Type Required Description
contract query string true Futures contract
settle path string true Settle currency

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

[
  {
    "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": ""
  }
]

Responses

Status Meaning Description Schema
200 OK Batch cancellation request accepted. Query order status by listing orders [FuturesPriceTriggeredOrder]

Get a single 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 = '/futures/usdt/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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}

Get a single order

Parameters

Name In Type Required Description
settle path string true Settle currency
order_id path string true ID returned on order successfully being created

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Auto order detail FuturesPriceTriggeredOrder

Cancel a single 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 = '/futures/usdt/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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}

Cancel a single order

Parameters

Name In Type Required Description
settle path string true Settle currency
order_id path string true ID returned on order successfully being created

Enumerated Values

Parameter Value
settle btc
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Auto order detail FuturesPriceTriggeredOrder

Delivery

Delivery contract

List all futures contracts

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

List all futures contracts

Parameters

Name In Type Required Description
settle path string true Settle currency

Enumerated Values

Parameter Value
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [DeliveryContract]

Get a single 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 = '/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}

Get a single contract

Parameters

Name In Type Required Description
settle path string true Settle currency
contract path string true Futures contract

Enumerated Values

Parameter Value
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Contract information DeliveryContract

Futures order book

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

Futures order book

Bids will be sorted by price from high to low, while asks sorted reversely

Parameters

Name In Type Required Description
settle path string true Settle currency
contract query string true Futures contract
interval query string false Order depth. 0 means no aggregation is applied. default to 0
limit query integer false Maximum number of order depth data in asks or bids
with_id query boolean false Whether order book update ID would be returned. This ID increments by 1 on every order book update

Enumerated Values

Parameter Value
settle usdt
interval 0
interval 0.1
interval 0.01

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Order book retrieved Inline

Response Schema

Status Code 200

Name Type Description
» id integer(int64) Order Book ID. Increase by 1 on every order book change. Set with_id=true to include this field in response
» asks array Asks order depth
»» futures_order_book_item object none
»»» p string Price
»»» s integer(int64) Size
»» bids array Bids order depth
»»» futures_order_book_item object none
»»»» p string Price
»»»» s integer(int64) Size

Futures trading history

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

Futures trading history

Parameters

Name In Type Required Description
settle path string true Settle currency
contract query string true Futures contract
limit query integer false Maximum number of records returned in one list
last_id query string false Specify list staring point using the id of last record in previous list-query results
from query integer(int64) false Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items.
to query integer(int64) false Specify end time in Unix seconds, default to current time

Detailed descriptions

last_id: Specify list staring point using the id of last record in previous list-query results

This parameter is deprecated. Use from and to instead to limit time range

from: Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items. If items between from and to are more than limit, only limit number will be returned.

Enumerated Values

Parameter Value
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» id integer(int64) Trade ID
» create_time number(double) Trading time
» create_time_ms number(double) Trading time, with milliseconds set to 3 decimal places.
» contract string Futures contract
» size integer(int64) Trading size
» price string Trading price

Get futures candlesticks

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

Get futures candlesticks

Return specified contract candlesticks. If prefix contract with mark_, the contract's mark price candlesticks are returned; if prefix with index_, index price candlesticks will be returned.

Maximum of 2000 points are returned in one query. Be sure not to exceed the limit when specifying from, to and interval

Parameters

Name In Type Required Description
settle path string true Settle currency
contract query string true Futures contract
from query integer(int64) false Start time of candlesticks, formatted in Unix timestamp in seconds.
to query integer(int64) false End time of candlesticks, formatted in Unix timestamp in seconds. Default to current time
limit query integer false Maximum recent data points returned. limit is conflicted with from and to. If either from or to is specified, request will be rejected.
interval query string false Interval time between data points

Detailed descriptions

from: Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified

Enumerated Values

Parameter Value
settle usdt
interval 10s
interval 1m
interval 5m
interval 15m
interval 30m
interval 1h
interval 4h
interval 8h
interval 1d
interval 7d

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array [data point in every timestamp]
» None object data point in every timestamp
»» t number(double) Unix timestamp in seconds
»» v integer(int64) size volume. Only returned if contract is not prefixed
»» c string Close price
»» h string Highest price
»» l string Lowest price
»» o string Open price

List futures tickers

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

List futures tickers

Parameters

Name In Type Required Description
settle path string true Settle currency
contract query string false Futures contract

Enumerated Values

Parameter Value
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» contract string Futures contract
» last string Last trading price
» change_percentage string Change percentage.
» total_size string Contract total size
» low_24h string Lowest trading price in recent 24h
» high_24h string Highest trading price in recent 24h
» volume_24h string Trade size in recent 24h
» volume_24h_btc string Trade volumes in recent 24h in BTC(deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead)
» volume_24h_usd string Trade volumes in recent 24h in USD(deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead)
» volume_24h_base string Trade volume in recent 24h, in base currency
» volume_24h_quote string Trade volume in recent 24h, in quote currency
» volume_24h_settle string Trade volume in recent 24h, in settle currency
» mark_price string Recent mark price
» funding_rate string Funding rate
» funding_rate_indicative string Indicative Funding rate in next period
» index_price string Index price
» quanto_base_rate string Exchange rate of base currency and settlement currency in Quanto contract. Not existed in contract of other types

Futures insurance balance history

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

Futures insurance balance history

Parameters

Name In Type Required Description
settle path string true Settle currency
limit query integer false Maximum number of records returned in one list

Enumerated Values

Parameter Value
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Successfully retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» t integer(int64) Unix timestamp in seconds
» b string Insurance balance

Query futures account

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

Query futures account

Parameters

Name In Type Required Description
settle path string true Settle currency

Enumerated Values

Parameter Value
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved Inline

Response Schema

Status Code 200

Name Type Description
» total string Total assets, total = position_margin + order_margin + available
» unrealised_pnl string Unrealized PNL
» position_margin string Position margin
» order_margin string Order margin of unfinished orders
» available string Available balance to transfer out or trade
» point string POINT amount
» currency string Settle currency
» in_dual_mode boolean Whether dual mode is enabled

Query account book

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

Query account book

Parameters

Name In Type Required Description
settle path string true Settle currency
limit query integer false Maximum number of records returned in one list
from query integer(int64) false Start timestamp
to query integer(int64) false End timestamp
type query string false Changing Type:

Detailed descriptions

type: Changing Type: - dnw: Deposit & Withdraw - pnl: Profit & Loss by reducing position - fee: Trading fee - refr: Referrer rebate - fund: Funding - point_dnw: POINT Deposit & Withdraw - point_fee: POINT Trading fee - point_refr: POINT Referrer rebate

Enumerated Values

Parameter Value
settle usdt
type dnw
type pnl
type fee
type refr
type fund
type point_dnw
type point_fee
type point_refr

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Inline]

Response Schema

Status Code 200

Name Type Description
None array none
» time number(double) Change time
» change string Change amount
» balance string Balance after change
» type string Changing Type:
- dnw: Deposit & Withdraw
- pnl: Profit & Loss by reducing position
- fee: Trading fee
- refr: Referrer rebate
- fund: Funding
- point_dnw: POINT Deposit & Withdraw
- point_fee: POINT Trading fee
- point_refr: POINT Referrer rebate
» text string Comment

Enumerated Values

Property Value
type dnw
type pnl
type fee
type refr
type fund
type point_dnw
type point_fee
type point_refr

List all positions of a user

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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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

List all positions of a user

Parameters

Name In Type Required Description
settle path string true Settle currency

Enumerated Values

Parameter Value
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [Position]

Get single 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
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}

Get single position

Parameters

Name In Type Required Description
settle path string true Settle currency
contract path string true Futures contract

Enumerated Values

Parameter Value
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Position information Position

Update position margin

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Update position margin

Parameters

Name In Type Required Description
settle path string true Settle currency
contract path string true Futures contract
change query string true Margin change. Use positive number to increase margin, negative number otherwise.

Enumerated Values

Parameter Value
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Position information Position

Update position leverage

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Update position leverage

Parameters

Name In Type Required Description
settle path string true Settle currency
contract path string true Futures contract
leverage query string true New position leverage

Enumerated Values

Parameter Value
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Position information Position

Update position risk limit

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Update position risk limit

Parameters

Name In Type Required Description
settle path string true Settle currency
contract path string true Futures contract
risk_limit query string true New position risk limit

Enumerated Values

Parameter Value
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Position information Position

Create a futures 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 = '/delivery/usdt/orders'
query_param = ''
body='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Create a futures order

Zero-fill order cannot be retrieved 60 seconds after cancellation

Body parameter

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

Parameters

Name In Type Required Description
body body FuturesOrder true none
» contract body string true Futures contract
» size body integer(int64) true Order size. Specify positive number to make a bid, and negative number to ask
» iceberg body integer(int64) false Display size for iceberg order. 0 for non-iceberg. Note that you would pay the taker fee for the hidden size
» price body string false Order price. 0 for market order with tif set as ioc
» close body boolean false Set as true to close the position, with size set to 0
» reduce_only body boolean false Set as true to be reduce-only order
» tif body string false Time in force
» text body string false User defined information. If not empty, must follow the rules below:
settle path string true Settle currency

Detailed descriptions

» tif: Time in force

» text: User defined information. If not empty, must follow the rules below:

  1. prefixed with t-
  2. no longer than 28 bytes without t- prefix
  3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created:

Enumerated Values

Parameter Value
» tif gtc
» tif ioc
» tif poc
settle usdt

Example responses

201 Response

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

Responses

Status Meaning Description Schema
201 Created Order details FuturesOrder

List futures orders

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

List futures orders

Zero-fill order cannot be retrieved 60 seconds after cancellation

Parameters

Name In Type Required Description
contract query string false Futures contract
status query string true List orders based on status
limit query integer false Maximum number of records returned in one list
offset query integer false List offset, starting from 0
last_id query string false Specify list staring point using the id of last record in previous list-query results
count_total query integer false Whether to return total number matched. Default to 0(no return)
settle path string true Settle currency

Enumerated Values

Parameter Value
status open
status finished
count_total 0
count_total 1
settle usdt

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK List retrieved [FuturesOrder]

Response Headers

Status Header Type Format Description
200 X-Pagination-Limit integer Request limit specified
200 X-Pagination-Offset integer Request offset specified
200 X-Pagination-Total integer Total number matched. Only returned on count_total set to 1

Cancel all open orders matched

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'
# for `gen_sign` implementation, refer to section `Authentication` above
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

Cancel all open orders matched

Zero-fill order cannot be retrieved 60 seconds after cancellation

Parameters

Name In Type Required Description
contract query string true Futures contract
side query string false All bids or asks. Both included in not specified
settle path string true Settle currency

Enumerated Values

Parameter Value
side ask
side bid
settle usdt

Example responses

200 Response

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