Spot & Margin
Announcements

# Gate API v4 v4.44.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.HK API. The APIv4 interface provides spot trading, including public interfaces to query market information, as well as private interfaces that require authentication to enable automated trading based on the API.

# Access URL

REST API BaseURL:

Live trading: https://api.gatehk.com/api/v4

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

# Changelog

v4.44.0

2023-05-24

Initial release

# 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

# API

# HTTP convention

All read endpoints use GET method. They accept only request parameters. No request body will be read.
DELETE methods remove resources(like orders), but not all removing operation using DELETE, as DELETEs don't read request body either. For complex removing operations, POST method is used with parameters filled in request body.
Updating is done using POST, PUT or PATCH method. Their parameters are either in body or request parameters for different endpoints. Refer to endpoint detail for how to send the request.
All endpoints return HTTP status code 2xx on success. 401 is returned on authentication failure. Other 4xx codes mean the request is malformed. 5xx means the server encounter some critical error on processing the request. Commit issues if 5xx is met.

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

1596531048
"1596531048"
1596531048.285
"1596531048.285"

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

page-limit
limit-offset

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:

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

Using limit-offset method, send request parameters like:

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

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

X-Pagination-Limit: request limit
X-Pagination-Offset: request offset
X-Pagination-Total: total record number satisfying the request

# Frequency limit rule

Markets	Endpoints	Limits	Based On	Include
Spot	Public endpoints	900r/s	IP	Order book, Candlesticks, trading pairs, etc.
	Private endpoints	900r/s	API Key	Trading history, fee rate, etc.
	Place orders	10r/s	User ID and trading pair	Placing(bulk) orders trade,etc.
	Cancel orders	5000r/s	User ID	Canceling(all) orders, etc.
Wallet	All endpoints	200r/s	API Key	Deposit and withdrawal history, transfer etc.
Withdrawal	Withdraw	1r/3s	User ID	Withdraw

The rate limit is counted against each sub-account or main account.

WebSocket:

The message limit sent to the server: unlimited.
Number of connections per IP: ≤ 300

NOTICE:

When repeatedly violating rate limits, it depends on

the request< burst rate, the request will have a delay.
the request> burst rate, the request will be declined.

# 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

Type	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

# Spot trading

For example, if you want to place a buy order for the BTC_USDT currency pair, the order request will be similar to

POST /spot/orders

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

For other related restrictions, please refer to the document of the API endpoint directly.

# Request ID

It is allowed to set an X-Client-Request-Id header in the request, and the API will also carry this header in the response. You can use this field to locate the corresponding request that the API responds to, which is convenient for users to set the request id for tracking.

# Self-Trade Prevention (STP)

# Concepts

Self-Trade Prevention: STP will prevent any user's orders from being matched with each other.

CN: Cancel new, Cancel new orders and keep old ones.

CO: Cancel old, Cancel old orders and keep new ones.

CB: Cancel both, Both old and new orders will be cancelled.

# STP Strategies

We support three STP strategies, which are CN , CO and CB.

STP is achieved by adding users to one STP trading group. When a user in a STP group place orders, and trading could happen with existing orders of users in the same group, orders will be cancelled. The prevention strategy depends on the stp_act parameter specified when placing the order as taker. If not specified, the CN strategy will be used by default.

A user has to be added to a STP trading group before using STP. When a user does not belong to any STP trading group, and place orders with the stp_act parameter, the orders will be rejected.

# API Parameter Adjustment

Take placing spot order as an example:

POST /spot/{settle}/orders

New request body parameter:

Name	Position	Type	Required	Description
stp_act	body	string	No	STP Strategies, including: - cn - co - cb

New response fields:

Name	Type	Required	Restriction	Description
stp_act	string	No	none	STP Strategies, including： - cn - co - cb
stp_id	integer(int64)	No	readonly	The ID of the STP trading group to which user belongs.
finish_as	string	No	readonly	order finish type: - stp: The order has been canceled due to the `STP`

# User case

There are multiple accounts under Organization A, and the IDs of several accounts are 101, 102, and 103

In order to prevent self-trading of orders placed by internal accounts of the organization, the administrator created a STP trading group with group ID 100, and added accounts 101 and 102 to the STP trading group. In this case, the members in the group are [101,102].

T1: The STP strategy version released.

T2: After the organization A account 101 places a short order, there is no matching order in the market order book to match the transaction. At this time, the role of the order is maker, and the order status is open. The key response fields returned are:

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

T3: Organization A account 101/102 places a long order, and it can reach a trade with account 101’s short order. The match engine finds both two orders' stp_id are 100, so it applies the STP strategy of the taker order, which defaults to cn , and cancels the long order. Order's finish_as will be set to stp. The key response fields returned are:

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

If stp_act is co , the order placed by taker will be retained, the order status will be open, and the system will cancel the order of maker.
If stp_act is cb, both the long and short orders will be cancelled. Orders' finish_as will be set to stp. The key response fields returned are:

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

T3': If account 103 places a long order, and it can reach a trade with account 101’s short order, the transaction will be made since account 103 has not been added to account 101’s STP group. The key response fields returned are:

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

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

label: denotes error type in string format. Its value are chosen from a certain list(see below). Programs can use label to identify and catch a specific error.
message(or detail): detailed error message. A longer explanation showing why the error is generated or how to avoid it. Its purpose is helping to better understand the API. Error handling mechanism with this field is highly NOT recommended.

Take Python requests (opens new window) 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/spot/orders?currency_pair=BTC_USDT&status=finished")
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 (opens new window):

import gate_api
from gate_api.exceptions import ApiException, GateApiException
# Defining the host is optional and defaults to https://api.gateio.ws/api/v4
# See configuration.py for a list of all supported configuration parameters.
configuration = gate_api.Configuration(
  host = "https://api.gateio.ws/api/v4"
)

api_client = gate_api.ApiClient(configuration)
# Create an instance of the API class
api_instance = gate_api.SpotApi(api_client)

try:
  # List all currencies' details
  api_response = api_instance.list_currencies()
  print(api_response)
except GateApiException as ex:
  print("Gate api exception, label: %s, message: %s\n" % (ex.label, ex.message))
except ApiException as e:
  print("Exception when calling SpotApi->list_currencies: %s\n" % e)

# `label` list

Request parameter or format related

`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

Authentication related

`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

Wallet related

`label`	Meaning
SUB_ACCOUNT_NOT_FOUND	Sub account not found
SUB_ACCOUNT_LOCKED	Sub account is locked
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
API_WITHDRAW_DISABLED	API withdrawal operation is disabled temporarily
INVALID_WITHDRAW_ID	Invalid withdraw ID
INVALID_WITHDRAW_CANCEL_STATUS	Cancelling withdrawal not allowed with current status

Spot trading related

`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
AMOUNT_TOO_LITTLE	Amount does not reach minimum required
AMOUNT_TOO_MUCH	Amount exceeds maximum allowed
REPEATED_CREATION	Repeated creation
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
FOK_NOT_FILL	FOK order cannot be filled completely
NO_MERGEABLE_ORDERS	Orders can be merged not found
ORDER_BOOK_NOT_FOUND	Insufficient liquidity
FAILED_RETRIEVE_ASSETS	Failed to retrieve account assets

Server errors

`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 20 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.

TIP

Note: If the key is named with spot, then it could be the default name after APIv4 migration. For details refer to About APIv4 key improvement section

Created key can also be updated or deleted, but any modification(s) can take up to 5 minutes to take effect.

# APIv4 Permissions

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

Products	Permissions
`spot`	`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 disabled, read-only or read-write.

Please note 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

Generate APIv4 Key pairs in web console, and make sure it has the right permissions.
Set request header KEY to the key.
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.
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,
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/spot/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.

List all orders

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

Signature string：

	GET\n
	/api/v4/spot/orders\n
	currency_pair=BTC_USDT&status=finished&limit=50\n
	cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e\n
	1684372832

Explanation：

/api/v4/spot/orders: request url
currency_pair=BTC_USDT&status=finished&limit=50: keep the query string as it is in the request url
request body use empty string's hashed result
1684372832: Unix timestamp in seconds

Signature generated

328f17a80d8f88210d78c32da9904831068870d3d0ed2a4c7d90bf5ffc6658213cd89b768b411716ac300f66f73221592eae091955cec6e307c2824c71cab6b3

Create an order

	POST /api/v4/spot/orders HTTP/1.1
    {"text": "t-123456","currency_pair": "BTC_USDT","type": "limit","account": "spot","side": "buy","iceberg": "0","amount": "0.0001","price": "10000","time_in_force": "gtc","auto_borrow": false}

Signature string：


	POST\n
	/api/v4/spot/orders\n
	\n
	4022d26519fcdac68319f01f3e0b657438b9fac6c2b4fe146993c2ea1c35dd8e7005a34d53b644e8df27af5f9e6b05cd9165ea12577319b1127a5d57771ab286\n
	1684372761

Explanation：

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

Signature generated

17c69854bde32afd415515ec3b494bdaacf8b56460316f995ae2761f700e99abad138b304a153e68a4118ae645b12048dcc01046bfe7efadb818ea825c5968d8


# 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 = '/spot/orders'
    body = {
		"text": "t-123456",
		"currency_pair": "BTC_USDT",
		"type": "limit",
		"account": "spot",
		"side": "buy",
		"iceberg": "0",
		"amount": "0.0001",
		"price": "10000",
		"time_in_force": "gtc",
		"auto_borrow": False
	}
    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

Difference between sub account and main account
- Sub account API Key cannot operate transferals between main and sub account, i.e., POST /wallet/sub_account_transfers
- Sub account API Key cannot operate withdrawal, i.e., POST /withdrawals
- If sub account does not have some business permission, even if its API key has the permission, the operations will be rejected too.
I have other question(s) not covered above

Contact support for the issue. If the problem is related to one of the SDKs, you can also open an issue in the corresponding GitHub repository.

When submitting an issue, please include the following information to help identify the problem:
- User ID
  - Original request URL, request parameters and request body
  - What API key was used and where was it used, TestNet or real trading(API secret is not needed)
  - Programming language. Providing a code snippet will be better
  - Whether SDK was used. If so, which method caused the problem

# Spot

Spot trading

# List all currencies' details

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.hk"
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.hk/api/v4/spot/currencies \
  -H 'Accept: application/json'

GET /spot/currencies

List all currencies' details

Currency has two forms:

Only currency name, e.g., BTC, USDT
<currency>_<chain>, e.g., HT_ETH The latter one occurs when one currency has multiple chains. Currency detail contains a chain field whatever the form is. To retrieve all chains of one currency, you can use use all the details which has the name of the currency or name starting with <currency>_.

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	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
» fixed_rate	string	Fixed fee rate. Only for fixed rate currencies, not valid for normal currencies
» chain	string	Chain of currency

# Get details of a specific currency

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.hk"
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.hk/api/v4/spot/currencies/GT \
  -H 'Accept: application/json'

GET /spot/currencies/{currency}

Get details of a specific 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,
  "chain": "GT"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	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
» fixed_rate	string	Fixed fee rate. Only for fixed rate currencies, not valid for normal currencies
» chain	string	Chain of currency

# Retrieve ticker information

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.hk"
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.hk/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
timezone	query	string	false	Timezone

# Enumerated Values

Parameter	Value
timezone	utc0
timezone	utc8
timezone	all

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Successfully retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
» currency_pair	string	Currency pair
» last	string	Last trading price
» lowest_ask	string	Recent lowest ask
» highest_bid	string	Recent highest bid
» change_percentage	string	Change percentage in the last 24h
» change_utc0	string	utc0 timezone, the percentage change in the last 24 hours
» change_utc8	string	utc8 timezone, the percentage change in the last 24 hours
» base_volume	string	Base currency trade volume in the last 24h
» quote_volume	string	Quote currency trade volume in the last 24h
» 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 previous net value at re-balancing time
» etf_pre_timestamp	integer(int64)\|null	ETF previous re-balancing time
» etf_leverage	string\|null	ETF current leverage

# Retrieve order book

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.hk"
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.hk/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; low to high 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

{
  "id": 123456,
  "current": 1623898993123,
  "update": 1623898993121,
  "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 (opens new window)	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`
» current	integer(int64)	The timestamp of the response data being generated (in milliseconds)
» update	integer(int64)	The timestamp of when the orderbook last changed (in milliseconds)
» 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
import time
import hashlib
import hmac

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

url = '/spot/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.hk"
prefix="/api/v4"
method="GET"
url="/spot/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/trades

Retrieve market trades

You can use from and to to query by time range, or use last_id by scrolling page. The default behavior is by time range.

Scrolling query using last_id is not recommended any more. If last_id is specified, time range query parameters will be ignored.

Parameters

Name	In	Type	Required	Description
currency_pair	query	string	true	Currency pair
limit	query	integer(int32)	false	Maximum number of records to be returned in a single list. Default: 100, Minimum: 1, Maximum: 1000
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 the id of records to be retrieved should be less than the last_id specified. Default to false.
from	query	integer(int64)	false	Start timestamp of the query
to	query	integer(int64)	false	Time range ending, default to current time
page	query	integer	false	Page number

# Detailed descriptions

reverse: Whether the id of records to be retrieved should be less than the last_id specified. Default to false.

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 (opens new window)	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
» currency_pair	string	Currency pair
» side	string	Order side
» role	string	Trade role. No value in public endpoints
» 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	Points used to deduct fee. No value in public endpoints
» gt_fee	string	GT used to deduct fee. No value in public endpoints
» amend_text	string	The custom data that the user remarked when amending the order
» sequence_id	string	Represents a unique and consecutive trade ID within a single market. It is used to track and identify trades in the specific market
» text	string	User defined information. No value in public endpoints

# Enumerated Values

Property	Value
side	buy
side	sell
role	taker
role	maker

WARNING

To perform this operation, you must be authenticated by API key and secret

# Market candlesticks

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.hk"
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.hk/api/v4/spot/candlesticks?currency_pair=BTC_USDT \
  -H 'Accept: application/json'

GET /spot/candlesticks

Market candlesticks

Maximum of 1000 points can be returned in a 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 to return. `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. Note that `30d` means 1 natual month, not 30 days

# 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
interval	30d

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Successfully retrieved	[[string]]

Response Schema

Status Code 200

Name	Type	Description
» None	array	Candlestick data point detail. The array elements represent the following items respectively: - Unix timestamp in seconds - Quote currency trading volume - Close price - Highest price - Lowest price - Open price - Base currency trading amount

# Query user trading fee rates

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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",
  "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 (opens new window)	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	If 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
» point_type	string	Point type. 0 - Initial version. 1 - new version since 202009

WARNING

To perform this operation, you must be authenticated by API key and secret

# Query a batch of user trading fee rates

Code samples

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

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

url = '/spot/batch_fee'
query_param = 'currency_pairs=BTC_USDT,ETH_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.hk"
prefix="/api/v4"
method="GET"
url="/spot/batch_fee"
query_param="currency_pairs=BTC_USDT,ETH_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

GET /spot/batch_fee

Query a batch of user trading fee rates

Parameters

Name	In	Type	Required	Description
currency_pairs	query	string	true	A request can only query up to 50 currency pairs

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Successfully retrieved	Inline

Response Schema

Status Code 200

Name	Type	Description
» additionalProperties	object	none
»» user_id	integer(int64)	User ID
»» taker_fee	string	taker fee rate
»» maker_fee	string	maker fee rate
»» gt_discount	boolean	If 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
»» currency_pair	string	Currency pair

WARNING

To perform this operation, you must be authenticated by API key and secret

# List spot accounts

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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	Retrieve data of the specified currency

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	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

WARNING

To perform this operation, you must be authenticated by API key and secret

# Create a batch of orders

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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:

custom order field text is required
At most 4 currency pairs, maximum 10 orders each, are allowed in one request
No mixture of spot 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[Order]	true	none

Example responses

200 Response

[
  {
    "text": "t-123456",
    "succeeded": true,
    "label": "",
    "message": "",
    "id": "12332324",
    "create_time": "1548000000",
    "update_time": "1548000100",
    "create_time_ms": 1548000000123,
    "update_time_ms": 1548000100123,
    "currency_pair": "ETC_BTC",
    "status": "cancelled",
    "type": "limit",
    "account": "spot",
    "side": "buy",
    "amount": "1",
    "price": "5.00032",
    "time_in_force": "gtc",
    "iceberg": "0",
    "auto_borrow": false,
    "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 (opens new window)	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 the batch of orders succeeded
»» label	string	Error label, if any, otherwise an empty string
»» message	string	Detailed error message, if any, otherwise an empty string
»» id	string	Order ID
»» create_time	string	Creation time of order
»» update_time	string	Last modification time of order
»» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
»» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
»» status	string	Order status - `open`: to be filled - `closed`: filled - `cancelled`: cancelled
»» currency_pair	string	Currency pair
»» type	string	Order Type - limit : Limit Order - market : Market Order
»» account	string	Account type，spot - use spot 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 - fok: FillOrKill, fill either completely or none
»» iceberg	string	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported.
»» auto_repay	boolean	Default is disabled.
»» 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	Points 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
»» stp_id	integer	Orders between users in the same `stp_id` group are not allowed to be self-traded 1. If the `stp_id` of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the `stp_act` of the taker. 2. `stp_id` returns `0` by default for orders that have not been set for `STP group`
»» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the `STP Group`, he can pass `stp_act` to limit the user's self-trade prevetion strategy. If `stp_act` is not passed, the default is `cn` strategy。 2. When the user does not join the `STP group`, an error will be returned when passing the `stp_act` parameter。 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, Cancel old orders and keep new ones - cb: Cancel both, Both old and new orders will be cancelled
»» finish_as	string	How the order was finished. - open: processing - filled: filled totally - cancelled: manually cancelled - ioc: time in force is `IOC`, finish immediately - stp: cancelled because self trade prevention

# Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
account	spot
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	ioc
finish_as	stp

WARNING

To perform this operation, you must be authenticated by API key and secret

# List all open orders

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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.

Spot orders are returned by default.

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
account	query	string	false	Specify operation account. Default to spot account if not specified.

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",
        "auto_borrow": false,
        "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 (opens new window)	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(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4
»»» amend_text	string	The custom data that the user remarked when amending the order
»»» create_time	string	Creation time of order
»»» update_time	string	Last modification time of order
»»» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
»»» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
»»» status	string	Order status - `open`: to be filled - `closed`: filled - `cancelled`: cancelled
»»» currency_pair	string	Currency pair
»»» type	string	Order Type - limit : Limit Order - market : Market Order
»»» account	string	Account type，spot - use spot account
»»» side	string	Order side
»»» amount	string	When `type` is limit, it refers to base currency. For instance, `BTC_USDT` means `BTC` When `type` is `market`, it refers to different currency according to `side` - `side` : `buy` means quote currency, `BTC_USDT` means `USDT` - `side` : `sell` means base currency，`BTC_USDT` means `BTC`
»»» price	string	Price can't be empty when `type`= `limit`
»»» 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 - fok: FillOrKill, fill either completely or none Only `ioc` and `fok` are supported when `type`=`market`
»»» iceberg	string	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported.
»»» auto_repay	boolean	Default is disabled.
»»» 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
»»» avg_deal_price	string	Average fill price
»»» fee	string	Fee deducted
»»» fee_currency	string	Fee currency unit
»»» point_fee	string	Points used to deduct fee
»»» gt_fee	string	GT used to deduct fee
»»» gt_maker_fee	string	GT used to deduct maker fee
»»» gt_taker_fee	string	GT used to deduct taker fee
»»» gt_discount	boolean	Whether GT fee discount is used
»»» rebated_fee	string	Rebated fee
»»» rebated_fee_currency	string	Rebated fee currency unit
»»» stp_id	integer	Orders between users in the same `stp_id` group are not allowed to be self-traded 1. If the `stp_id` of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the `stp_act` of the taker. 2. `stp_id` returns `0` by default for orders that have not been set for `STP group`
»»» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the `STP Group`, he can pass `stp_act` to limit the user's self-trade prevetion strategy. If `stp_act` is not passed, the default is `cn` strategy。 2. When the user does not join the `STP group`, an error will be returned when passing the `stp_act` parameter。 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, Cancel old orders and keep new ones - cb: Cancel both, Both old and new orders will be cancelled
»»» finish_as	string	How the order was finished. - open: processing - filled: filled totally - cancelled: manually cancelled - ioc: time in force is `IOC`, finish immediately - stp: cancelled because self trade prevention

# Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
account	spot
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	ioc
finish_as	stp

WARNING

To perform this operation, you must be authenticated by API key and secret

# Create an order

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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

You can place orders with spot account through setting the account field. It defaults to spot, which means spot account is used to place orders. Automatic repayment will be triggered when the order is finished, i.e., its status is either cancelled or closed. Order status An order waiting to be filled is open, and it stays open until it is filled totally. If fully filled, order is finished and its status turns to closed.If the order is cancelled before it is totally filled, whether or not partially filled, its status is cancelled. Iceberg order iceberg field can be used to set the amount shown. Set to -1 to hide the order completely. Note that the hidden part's fee will be charged using taker's fee rate. Self Trade Prevention Set stp_act to decide the strategy of self-trade prevention. For detailed usage, refer to the stp_act parameter in request body

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
» account	body	string	false	Account type，spot - use spot account
» side	body	string	true	Order side
» amount	body	string	true	When `type` is limit, it refers to base currency. For instance, `BTC_USDT` means `BTC`
» price	body	string	false	Price can't be empty when `type`= `limit`
» 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. Hiding all amount is not supported.
» auto_repay	body	boolean	false	Default is disabled.
» stp_act	body	string	false	Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies

# Detailed descriptions

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

prefixed with t-
no longer than 28 bytes without t- prefix
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:

101: from android
102: from IOS
103: from IPAD
104: from webapp
3: from web
2: from apiv2
apiv4: from apiv4

» type: Order Type

limit : Limit Order
market : Market Order

» amount: When type is limit, it refers to base currency. For instance, BTC_USDT means BTC When type is market, it refers to different currency according to side

side : buy means quote currency, BTC_USDT means USDT
side : sell means base currency，BTC_USDT means BTC

» time_in_force: Time in force

gtc: GoodTillCancelled
ioc: ImmediateOrCancelled, taker only
poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee
fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market

» stp_act: Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies

After users join the STP Group, he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy。
When the user does not join the STP group, an error will be returned when passing the stp_act parameter。
If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-'

cn: Cancel newest, Cancel new orders and keep old ones
co: Cancel oldest, Cancel old orders and keep new ones
cb: Cancel both, Both old and new orders will be cancelled

# Enumerated Values

Parameter	Value
» type	limit
» type	market
» account	spot
» side	buy
» side	sell
» time_in_force	gtc
» time_in_force	ioc
» time_in_force	poc
» time_in_force	fok
» stp_act	cn
» stp_act	co
» stp_act	cb
» stp_act	-

Example responses

201 Response

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

Responses

Status	Meaning	Description	Schema
201	Created (opens new window)	Order created.	Order

WARNING

To perform this operation, you must be authenticated by API key and secret

# List orders

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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

Spot orders are returned by default. When status is open, i.e., listing open orders, only pagination parameters page and limit are supported and limit cannot be larger than 100. Query by side and time range parameters from and to are not supported.

When status is finished, i.e., listing finished orders, pagination parameters, time range parameters from and to, and side parameters are all supported. Time range parameters are handled as order finish time.

Parameters

Name	In	Type	Required	Description
currency_pair	query	string	true	Retrieve results with specified currency pair. It is required for open orders, but optional for finished ones.
status	query	string	true	List orders based on status
page	query	integer	false	Page number
limit	query	integer	false	Maximum number of records to be returned. If `status` is `open`, maximum of `limit` is 100
account	query	string	false	Specify operation account. Default to spot account if not specified.
from	query	integer(int64)	false	Start timestamp of the query
to	query	integer(int64)	false	Time range ending, default to current time
side	query	string	false	All bids or asks. Both included if not specified

# 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
side	buy
side	sell

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[Order]

WARNING

To perform this operation, you must be authenticated by API key and secret

# 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.hk"
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.hk"
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

If account is not set, all open orders will be cancelled. You can set account to cancel only orders within the specified account

Parameters

Name	In	Type	Required	Description
currency_pair	query	string	true	Currency pair
side	query	string	false	All bids or asks. Both included if not specified
account	query	string	false	Specify account type

# Detailed descriptions

account: Specify account type

classic account：Default to all account

# Enumerated Values

Parameter	Value
side	buy
side	sell
account	spot

Example responses

200 Response

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

Responses

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

WARNING

To perform this operation, you must be authenticated by API key and secret

# 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.hk"
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.hk"
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 (opens new window)	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
»» account	string	Empty by default.

WARNING

To perform this operation, you must be authenticated by API key and secret

# Get a single order

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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

Spot orders are queried by default.

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
account	query	string	false	Specify operation account.

# Detailed descriptions

order_id: Order ID returned, or user custom ID(i.e., text field). Operations based on custom ID can only be checked when the order is in orderbook. When the order is finished, it can be checked within 1 hour after the end of the order. After that, only order ID is accepted.

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Detail retrieved	Order

WARNING

To perform this operation, you must be authenticated by API key and secret

# Amend an order

Code samples

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

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

url = '/spot/orders/12345'
query_param = 'currency_pair=BTC_USDT'
body='{"amount":"1","price":"14"}'
# 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 + "?" + query_param, headers=headers, data=body)
print(r.json())

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

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

PATCH /spot/orders/{order_id}

Amend an order

By default, the orders of spot are updated. Currently, only supports modification of price or amount fields. Regarding rate limiting: modify order and create order sharing rate limiting rules. Regarding matching priority: only modifying the amount does not affect the priority. If the price is modified, the priority will be adjusted to the last of the new price. Note: If the modified amount is less than the fill amount, the order will be cancelled.

Body parameter

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

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» amount	body	string	false	New order amount. `amount` and `price` must specify one of them
» price	body	string	false	New order price. `amount` and `Price` must specify one of them"
» amend_text	body	string	false	Custom info during amending order
order_id	path	string	true	Order ID returned, or user custom ID(i.e., `text` field).
currency_pair	query	string	true	Currency pair
account	query	string	false	Specify operation account.

# Detailed descriptions

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Updated	Order

WARNING

To perform this operation, you must be authenticated by API key and secret

# Cancel a single order

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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

Spot is cancelled by default.

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
account	query	string	false	Specify operation account.

# Detailed descriptions

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Order cancelled	Order

WARNING

To perform this operation, you must be authenticated by API key and secret

# List personal trading history

Code samples

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

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

url = '/spot/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.hk"
prefix="/api/v4"
method="GET"
url="/spot/my_trades"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

GET /spot/my_trades

List personal trading history

Spot trades are queried by default.

Parameters

Name	In	Type	Required	Description
currency_pair	query	string	false	Retrieve results with specified currency pair
limit	query	integer	false	Maximum number of records to be returned in a single list
page	query	integer	false	Page number
order_id	query	string	false	Filter trades with specified order ID. `currency_pair` is also required if this field is present
account	query	string	false	Specify operation account,default to spot.
from	query	integer(int64)	false	Start timestamp of the query
to	query	integer(int64)	false	Time range ending, default to current time

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 (opens new window)	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
» currency_pair	string	Currency pair
» side	string	Order side
» role	string	Trade role. No value in public endpoints
» 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	Points used to deduct fee. No value in public endpoints
» gt_fee	string	GT used to deduct fee. No value in public endpoints
» amend_text	string	The custom data that the user remarked when amending the order
» sequence_id	string	Represents a unique and consecutive trade ID within a single market. It is used to track and identify trades in the specific market
» text	string	User defined information. No value in public endpoints

# Enumerated Values

Property	Value
side	buy
side	sell
role	taker
role	maker

WARNING

To perform this operation, you must be authenticated by API key and secret

# Get server current time

Code samples

# coding: utf-8
import requests

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

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


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

GET /spot/time

Get server current time

Example responses

200 Response

{
  "server_time": 1597026383085
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Successfully retrieved	Inline

Response Schema

Status Code 200

SystemTime

Name	Type	Description
» server_time	integer(int64)	Server current time(ms)

# Countdown cancel orders

Code samples

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

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

url = '/spot/countdown_cancel_all'
query_param = ''
body='{"timeout":30,"currency_pair":"BTC_USDT"}'
# 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.hk"
prefix="/api/v4"
method="POST"
url="/spot/countdown_cancel_all"
query_param=""
body_param='{"timeout":30,"currency_pair":"BTC_USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /spot/countdown_cancel_all

Countdown cancel orders

When the timeout set by the user is reached, if there is no cancel or set a new countdown, the related pending orders will be automatically cancelled. This endpoint can be called repeatedly to set a new countdown or cancel the countdown. For example, call this endpoint at 30s intervals, each countdowntimeout is set to 30s. If this endpoint is not called again within 30 seconds, all pending orders on the specified market will be automatically cancelled, if no market is specified, all market pending orders will be cancelled. If the timeout is set to 0 within 30 seconds, the countdown timer will expire and the cacnel function will be cancelled.

Body parameter

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

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» timeout	body	integer(int32)	true	Countdown time, in seconds
» currency_pair	body	string	false	Currency pair

# Detailed descriptions

» timeout: Countdown time, in seconds At least 5 seconds, 0 means cancel the countdown

Example responses

200 Response

{
  "triggerTime": "1660039145000"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Set countdown successfully	Inline

Response Schema

Status Code 200

triggerTime

Name	Type	Description
» triggerTime	integer(int64)	Timestamp of the end of the countdown, in milliseconds

WARNING

To perform this operation, you must be authenticated by API key and secret

# Create a price-triggered order

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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 long (in seconds) to wait for the condition to be triggered before cancelling the order.
» 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 account type. `
»» time_in_force	body	string	false	time_in_force
» market	body	string	true	Currency pair

# Detailed descriptions

»» rule: Price trigger condition

=: triggered when market price larger than or equal to price field
<=: triggered when market price less than or equal to price field

»» side: Order side

buy: buy side
sell: sell side

»» account: Trading account type. `

normal: spot trading

»» time_in_force: time_in_force

gtc: GoodTillCancelled
ioc: ImmediateOrCancelled, taker only

# Enumerated Values

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

Example responses

201 Response

{
  "id": 1432329
}

Responses

Status	Meaning	Description	Schema
201	Created (opens new window)	Order created	Inline

Response Schema

Status Code 201

TriggerOrderResponse

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

WARNING

To perform this operation, you must be authenticated by API key and secret

# Retrieve running auto order list

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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	Only list the orders with this status
market	query	string	false	Currency pair
account	query	string	false	Trading account type.
limit	query	integer	false	Maximum number of records to be returned in a single list
offset	query	integer	false	List offset, starting from 0

# Enumerated Values

Parameter	Value
status	open
status	finished
account	normal

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 (opens new window)	List retrieved	[SpotPriceTriggeredOrder]

WARNING

To perform this operation, you must be authenticated by API key and secret

# Cancel all open orders

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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 type.

# Enumerated Values

Parameter	Value
account	normal

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 (opens new window)	Batch cancellation request accepted. Query order status by listing orders	[SpotPriceTriggeredOrder]

WARNING

To perform this operation, you must be authenticated by API key and secret

# Get a price-triggered order

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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 price-triggered order

Parameters

Name	In	Type	Required	Description
order_id	path	string	true	Retrieve the data of the order with the specified ID

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 (opens new window)	Auto order detail	SpotPriceTriggeredOrder

WARNING

To perform this operation, you must be authenticated by API key and secret

# cancel a price-triggered order

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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 price-triggered order

Parameters

Name	In	Type	Required	Description
order_id	path	string	true	Retrieve the data of the order with the specified ID

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 (opens new window)	Auto order detail	SpotPriceTriggeredOrder

WARNING

To perform this operation, you must be authenticated by API key and secret

# Wallet

Wallet

# List chains supported for specified currency

Code samples

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

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

url = '/wallet/currency_chains'
query_param = 'currency=GT'
# 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.hk"
prefix="/api/v4"
method="GET"
url="/wallet/currency_chains"
query_param="currency=GT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

GET /wallet/currency_chains

List chains supported for specified currency

Parameters

Name	In	Type	Required	Description
currency	query	string	true	Currency name

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Successfully retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
» chain	string	Chain name
» name_cn	string	Chain name in Chinese
» name_en	string	Chain name in English
» contract_address	string	Smart contract address for the currency; if no address is available, it will be an empty string
» is_disabled	integer	If it is disabled. 0 means NOT being disabled
» is_deposit_disabled	integer	Is deposit disabled. 0 means not
» is_withdraw_disabled	integer	Is withdrawal disabled. 0 means not

WARNING

To perform this operation, you must be authenticated by API key and secret

# Generate currency deposit address

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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_addresses": [
    {
      "chain": "TRX",
      "address": "LPXtk1kWHioP62SzfqwKbYE3Z7Wt2ujYEc",
      "payment_id": "",
      "payment_name": "",
      "obtain_failed": 0
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Address successfully generated	Inline

Response Schema

Status Code 200

Name	Type	Description
» currency	string	Currency detail
» address	string	Deposit address
» multichain_addresses	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	The obtain failed status- 0: address successfully obtained- 1: failed to obtain address

WARNING

To perform this operation, you must be authenticated by API key and secret

# Retrieve withdrawal records

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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 to be returned in a single list
offset	query	integer	false	List offset, starting from 0

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	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
» withdraw_order_id	string	Client order id, up to 32 length and can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
» timestamp	string	Operation time
» amount	string	Currency amount
» currency	string	Currency name
» address	string	Withdrawal address. Required for withdrawals
» memo	string	Additional remarks with regards to the withdrawal
» status	string	Record status. - DONE: done - CANCEL: cancelled - REQUEST: requesting - MANUAL: pending manual approval - BCODE: GateCode operation - EXTPEND: pending confirm after sending - FAIL: pending confirm when fail - INVALID: invalid order - VERIFY: verifying - PROCES: processing - PEND: pending - DMOVE: required manual approval - SPLITPEND: the order is automatically split due to large amount
» chain	string	Name of the chain used in withdrawals

# Enumerated Values

Property	Value
status	DONE
status	CANCEL
status	REQUEST
status	MANUAL
status	BCODE
status	EXTPEND
status	FAIL
status	INVALID
status	VERIFY
status	PROCES
status	PEND
status	DMOVE
status	SPLITPEND

WARNING

To perform this operation, you must be authenticated by API key and secret

# Retrieve deposit records

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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 to be returned in a single list
offset	query	integer	false	List offset, starting from 0

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	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
» withdraw_order_id	string	Client order id, up to 32 length and can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
» timestamp	string	Operation time
» amount	string	Currency amount
» currency	string	Currency name
» address	string	Withdrawal address. Required for withdrawals
» memo	string	Additional remarks with regards to the withdrawal
» status	string	Record status. - DONE: done - CANCEL: cancelled - REQUEST: requesting - MANUAL: pending manual approval - BCODE: GateCode operation - EXTPEND: pending confirm after sending - FAIL: pending confirm when fail - INVALID: invalid order - VERIFY: verifying - PROCES: processing - PEND: pending - DMOVE: required manual approval - SPLITPEND: the order is automatically split due to large amount
» chain	string	Name of the chain used in withdrawals

# Enumerated Values

Property	Value
status	DONE
status	CANCEL
status	REQUEST
status	MANUAL
status	BCODE
status	EXTPEND
status	FAIL
status	INVALID
status	VERIFY
status	PROCES
status	PEND
status	DMOVE
status	SPLITPEND

WARNING

To perform this operation, you must be authenticated by API key and secret

# Transfer between main and sub accounts

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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 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

# Enumerated Values

Parameter	Value
» direction	to
» direction	from
» sub_account_type	spot

Responses

Status	Meaning	Description	Schema
204	No Content (opens new window)	Balance transferred	None

WARNING

To perform this operation, you must be authenticated by API key and secret

# Retrieve transfer records between main and sub accounts

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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

Retrieve 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	User ID of sub-account, you can query multiple records separated by `,`. If not specified, it will return the records of all sub accounts
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 to be returned in a single 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 (opens new window)	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

# Enumerated Values

Property	Value
direction	to
direction	from
sub_account_type	spot

WARNING

To perform this operation, you must be authenticated by API key and secret

# Sub-account transfers to sub-account

Code samples

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

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

url = '/wallet/sub_account_to_sub_account'
query_param = ''
body='{"currency":"usdt","sub_account_from":"10001","sub_account_from_type":"spot","sub_account_to":"10002","sub_account_to_type":"spot","amount":"1"}'
# 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.hk"
prefix="/api/v4"
method="POST"
url="/wallet/sub_account_to_sub_account"
query_param=""
body_param='{"currency":"usdt","sub_account_from":"10001","sub_account_from_type":"spot","sub_account_to":"10002","sub_account_to_type":"spot","amount":"1"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /wallet/sub_account_to_sub_account

Sub-account transfers to sub-account

Body parameter

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

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» currency	body	string	true	Transfer currency name
» sub_account_type	body	string	false	Transfer from the account. (deprecate, use `sub_account_from_type` and `sub_account_to_type` instead)
» sub_account_from	body	string	true	Transfer from the user id of the sub-account
» sub_account_from_type	body	string	true	Transfer from the account. `spot` - spot account
» sub_account_to	body	string	true	Transfer to the user id of the sub-account
» sub_account_to_type	body	string	true	Transfer to the account. `spot` - spot account
» amount	body	string	true	Transfer amount

# Enumerated Values

Parameter	Value
» sub_account_from_type	spot
» sub_account_to_type	spot

Responses

Status	Meaning	Description	Schema
204	No Content (opens new window)	Balance transferred	None

WARNING

To perform this operation, you must be authenticated by API key and secret

# Retrieve withdrawal status

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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	Retrieve data of the specified currency

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",
    "withdraw_fix_on_chains": {
      "BTC": "20",
      "ETH": "15",
      "TRX": "0",
      "EOS": "2.5"
    }
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	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
» withdraw_fix_on_chains	object	Fixed withdrawal fee on multiple chains
»» additionalProperties	string	none

WARNING

To perform this operation, you must be authenticated by API key and secret

# Retrieve sub account balances

Code samples

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

host = "https://api.gateio.hk"
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.hk"
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	User ID of sub-account, you can query multiple records separated by `,`. If not specified, it will return the records of all sub accounts

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[Inline]

Response Schema

Status Code 200

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

WARNING

To perform this operation, you must be authenticated by API key and secret

# Query saved address

Code samples

# coding: utf-8
import requests

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

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


curl -X GET https://api.gateio.hk/api/v4/wallet/saved_address?currency=USDT \
  -H 'Accept: application/json'

GET /wallet/saved_address

Query saved address

Parameters

Name	In	Type	Required	Description
currency	query	string	true	Currency
chain	query	string	false	Chain name
limit	query	string	false	Maximum number returned, 100 at most

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
» currency	string	Currency
» chain	string	Chain name
» address	string	Address
» name	string	Name
» tag	string	Tag
» verified	string	Whether to pass the verification 0-unverified, 1-verified

# Retrieve personal trading fee

Code samples

# coding: utf-8
import requests

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

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


curl -X GET https://api.gateio.hk/api/v4/wallet/fee \
  -H 'Accept: application/json'

GET /wallet/fee

Retrieve personal trading 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",
  "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 (opens new window)	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	If 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
» point_type	string	Point type. 0 - Initial version. 1 - new version since 202009

# Retrieve user's total balances

Code samples

# coding: utf-8
import requests

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

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


curl -X GET https://api.gateio.hk/api/v4/wallet/total_balance \
  -H 'Accept: application/json'

GET /wallet/total_balance

Retrieve user's total balances

This endpoint returns an approximate sum of exchanged amount from all currencies to input currency for each account.The exchange rate and account balance could have been cached for at most 1 minute. It is not recommended to use its result for any trading calculation.

For trading calculation, use the corresponding account query endpoint for each account type. For example:

GET /spot/accounts to query spot account balance

Parameters

Name	In	Type	Required	Description
currency	query	string	false	Currency unit used to calculate the balance amount. BTC, CNY, USD and USDT are allowed. USDT is the default.

Example responses

200 Response

{
  "details": {
    "spot": {
      "currency": "USDT",
      "amount": "42264489969935775.5160259954878034182418"
    }
  },
  "total": {
    "currency": "USDT",
    "amount": "633967350312281193.068368815439797304437"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Request is valid and is successfully responded	Inline

Response Schema

Status Code 200

User's balance in all accounts

Name	Type	Description
» total	object	Total balances calculated with specified currency unit
»» amount	string	Account total balance amount
»» currency	string	Currency
» details	object	Total amount of each account. - spot: spot account
»» additionalProperties	object	Total balances calculated with specified currency unit
»»» amount	string	Account total balance amount
»»» currency	string	Currency

# Enumerated Values

Property	Value
currency	BTC
currency	CNY
currency	USD
currency	USDT
currency	BTC
currency	CNY
currency	USD
currency	USDT

# SubAccount

Sub-account management

# Create a new sub-account

Code samples

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

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

url = '/sub_accounts'
query_param = ''
body='{"remark":"remark","login_name":"sub_account_for_trades"}'
# 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.hk"
prefix="/api/v4"
method="POST"
url="/sub_accounts"
query_param=""
body_param='{"remark":"remark","login_name":"sub_account_for_trades"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /sub_accounts

Create a new sub-account

Body parameter

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

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» remark	body	string	false	custom text
» login_name	body	string	true	Sub-account login name: Only letters, numbers and underscores are supported, and cannot contain other illegal characters
» password	body	string	false	The sub-account's password. (Default: the same as main account's password)
» email	body	string	false	The sub-account's email address. (Default: the same as main account's email address)
» type	body	integer(int32)	false	Type: 1-Sub-account

Example responses

201 Response

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

Responses

Status	Meaning	Description	Schema
201	Created (opens new window)	Created Successfully	Inline

Response Schema

Status Code 201

Name	Type	Description
» remark	string	custom text
» login_name	string	Sub-account login name: Only letters, numbers and underscores are supported, and cannot contain other illegal characters
» password	string	The sub-account's password. (Default: the same as main account's password)
» email	string	The sub-account's email address. (Default: the same as main account's email address)
» state	integer(int32)	State: 1-normal, 2-locked"
» type	integer(int32)	Type: 1-Sub-account
» user_id	integer(int64)	The user id of the sub-account
» create_time	integer(int64)	Created time

WARNING

To perform this operation, you must be authenticated by API key and secret

# List sub-accounts

Code samples

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

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

url = '/sub_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.hk"
prefix="/api/v4"
method="GET"
url="/sub_accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

GET /sub_accounts

List sub-accounts

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» remark	string	custom text
» login_name	string	Sub-account login name: Only letters, numbers and underscores are supported, and cannot contain other illegal characters
» password	string	The sub-account's password. (Default: the same as main account's password)
» email	string	The sub-account's email address. (Default: the same as main account's email address)
» state	integer(int32)	State: 1-normal, 2-locked"
» type	integer(int32)	Type: 1-Sub-account
» user_id	integer(int64)	The user id of the sub-account
» create_time	integer(int64)	Created time

WARNING

To perform this operation, you must be authenticated by API key and secret

# Get the sub-account

Code samples

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

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

url = '/sub_accounts/0'
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.hk"
prefix="/api/v4"
method="GET"
url="/sub_accounts/0"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

GET /sub_accounts/{user_id}

Get the sub-account

Parameters

Name	In	Type	Required	Description
user_id	path	integer(int64)	true	Sub-account user id

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Successful	Inline

Response Schema

Status Code 200

Name	Type	Description
» remark	string	custom text
» login_name	string	Sub-account login name: Only letters, numbers and underscores are supported, and cannot contain other illegal characters
» password	string	The sub-account's password. (Default: the same as main account's password)
» email	string	The sub-account's email address. (Default: the same as main account's email address)
» state	integer(int32)	State: 1-normal, 2-locked"
» type	integer(int32)	Type: 1-Sub-account
» user_id	integer(int64)	The user id of the sub-account
» create_time	integer(int64)	Created time

WARNING

To perform this operation, you must be authenticated by API key and secret

# Create API Key of the sub-account

Code samples

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

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

url = '/sub_accounts/0/keys'
query_param = ''
body='{"name":"spot","perms":[{"name":"spot","read_only":false},{"name":"wallet","read_only":false}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
# 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.hk"
prefix="/api/v4"
method="POST"
url="/sub_accounts/0/keys"
query_param=""
body_param='{"name":"spot","perms":[{"name":"spot","read_only":false},{"name":"wallet","read_only":false}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /sub_accounts/{user_id}/keys

Create API Key of the sub-account

Body parameter

{
  "name": "spot",
  "perms": [
    {
      "name": "spot",
      "read_only": false
    },
    {
      "name": "wallet",
      "read_only": false
    }
  ],
  "ip_whitelist": [
    "127.0.0.1",
    "127.0.0.2"
  ]
}

Parameters

Name	In	Type	Required	Description
user_id	path	integer(int64)	true	Sub-account user id
body	body	SubAccountKey	true	none
» name	body	string	false	API key name
» perms	body	array	false	none
»» ApiV4KeyPerm	body	object	false	none
»»» name	body	string	false	Permission name (all permissions will be removed if no value is passed)
»»» read_only	body	boolean	false	read only
»» ip_whitelist	body	array	false	ip white list (list will be removed if no value is passed)

# Detailed descriptions

»»» name: Permission name (all permissions will be removed if no value is passed)

wallet: wallet
spot: spot

# Enumerated Values

Parameter	Value
»»» name	wallet
»»» name	spot

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Created Successfully	Inline

Response Schema

Status Code 200

Name	Type	Description
» user_id	string	User ID
» name	string	API key name
» perms	array	none
»» ApiV4KeyPerm	object	none
»»» name	string	Permission name (all permissions will be removed if no value is passed) - wallet: wallet - spot: spot
»»» read_only	boolean	read only
»» ip_whitelist	array	ip white list (list will be removed if no value is passed)
»» key	string	API Key
»» state	integer(int32)	State 1 - normal 2 - locked 3 - frozen
»» created_at	string	Creation time
»» updated_at	string	Last update time

# Enumerated Values

Property	Value
name	wallet
name	spot

WARNING

To perform this operation, you must be authenticated by API key and secret

# List all API Key of the sub-account

Code samples

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

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

url = '/sub_accounts/0/keys'
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.hk"
prefix="/api/v4"
method="GET"
url="/sub_accounts/0/keys"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

GET /sub_accounts/{user_id}/keys

List all API Key of the sub-account

Parameters

Name	In	Type	Required	Description
user_id	path	integer	true	Sub-account user id

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[SubAccountKey]

WARNING

To perform this operation, you must be authenticated by API key and secret

# Update API key of the sub-account

Code samples

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

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

url = '/sub_accounts/0/keys/string'
query_param = ''
body='{"name":"spot","perms":[{"name":"spot","read_only":false},{"name":"wallet","read_only":false}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PUT', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.hk"
prefix="/api/v4"
method="PUT"
url="/sub_accounts/0/keys/string"
query_param=""
body_param='{"name":"spot","perms":[{"name":"spot","read_only":false},{"name":"wallet","read_only":false}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

PUT /sub_accounts/{user_id}/keys/{key}

Update API key of the sub-account

Body parameter

{
  "name": "spot",
  "perms": [
    {
      "name": "spot",
      "read_only": false
    },
    {
      "name": "wallet",
      "read_only": false
    }
  ],
  "ip_whitelist": [
    "127.0.0.1",
    "127.0.0.2"
  ]
}

Parameters

Name	In	Type	Required	Description
user_id	path	integer	true	Sub-account user id
key	path	string	true	The API Key of the sub-account
body	body	SubAccountKey	true	none
» name	body	string	false	API key name
» perms	body	array	false	none
»» ApiV4KeyPerm	body	object	false	none
»»» name	body	string	false	Permission name (all permissions will be removed if no value is passed)
»»» read_only	body	boolean	false	read only
»» ip_whitelist	body	array	false	ip white list (list will be removed if no value is passed)

# Detailed descriptions

»»» name: Permission name (all permissions will be removed if no value is passed)

wallet: wallet
spot: spot

# Enumerated Values

Parameter	Value
»»» name	wallet
»»» name	spot

Responses

Status	Meaning	Description	Schema
204	No Content (opens new window)	Updated	None

WARNING

To perform this operation, you must be authenticated by API key and secret

# Delete API key of the sub-account

Code samples

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

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

url = '/sub_accounts/0/keys/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.hk"
prefix="/api/v4"
method="DELETE"
url="/sub_accounts/0/keys/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

DELETE /sub_accounts/{user_id}/keys/{key}

Delete API key of the sub-account

Parameters

Name	In	Type	Required	Description
user_id	path	integer	true	Sub-account user id
key	path	string	true	The API Key of the sub-account

Responses

Status	Meaning	Description	Schema
204	No Content (opens new window)	Delete successfully	None

WARNING

To perform this operation, you must be authenticated by API key and secret

# Get the API Key of the sub-account

Code samples

# coding: utf-8
import requests

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

url = '/sub_accounts/0/keys/string'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())


curl -X GET https://api.gateio.hk/api/v4/sub_accounts/0/keys/string \
  -H 'Accept: application/json'

GET /sub_accounts/{user_id}/keys/{key}

Get the API Key of the sub-account

Parameters

Name	In	Type	Required	Description
user_id	path	integer	true	Sub-account user id
key	path	string	true	The API Key of the sub-account

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Successful	SubAccountKey

# Lock the sub-account

Code samples

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

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

url = '/sub_accounts/0/lock'
query_param = ''
# 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, headers=headers)
print(r.json())

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

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

POST /sub_accounts/{user_id}/lock

Lock the sub-account

Parameters

Name	In	Type	Required	Description
user_id	path	integer(int64)	true	The user id of the sub-account

Responses

Status	Meaning	Description	Schema
204	No Content (opens new window)	Lock successfully	None

WARNING

To perform this operation, you must be authenticated by API key and secret

# Unlock the sub-account

Code samples

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

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

url = '/sub_accounts/0/unlock'
query_param = ''
# 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, headers=headers)
print(r.json())

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

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

POST /sub_accounts/{user_id}/unlock

Unlock the sub-account

Parameters

Name	In	Type	Required	Description
user_id	path	integer(int64)	true	The user id of the sub-account

Responses

Status	Meaning	Description	Schema
204	No Content (opens new window)	Unlock successfully	None

WARNING

To perform this operation, you must be authenticated by API key and secret

# Schemas

# SubAccountKey

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

# Properties

Name	Type	Required	Restrictions	Description
user_id	string	false	read-only	User ID
name	string	false	none	API key name
perms	array	false	none	none
» ApiV4KeyPerm	object	false	none	none
»» name	string	false	none	Permission name (all permissions will be removed if no value is passed) - wallet: wallet - spot: spot
»» read_only	boolean	false	none	read only
» ip_whitelist	array	false	none	ip white list (list will be removed if no value is passed)
» key	string	false	read-only	API Key
» state	integer(int32)	false	read-only	State 1 - normal 2 - locked 3 - frozen
» created_at	string	false	read-only	Creation time
» updated_at	string	false	read-only	Last update time

# Enumerated Values

Property	Value
name	wallet
name	spot

# Order

{
  "id": "string",
  "text": "string",
  "amend_text": "string",
  "create_time": "string",
  "update_time": "string",
  "create_time_ms": 0,
  "update_time_ms": 0,
  "status": "open",
  "currency_pair": "string",
  "type": "limit",
  "account": "spot",
  "side": "buy",
  "amount": "string",
  "price": "string",
  "time_in_force": "gtc",
  "iceberg": "string",
  "auto_repay": true,
  "left": "string",
  "fill_price": "string",
  "filled_total": "string",
  "avg_deal_price": "string",
  "fee": "string",
  "fee_currency": "string",
  "point_fee": "string",
  "gt_fee": "string",
  "gt_maker_fee": "string",
  "gt_taker_fee": "string",
  "gt_discount": true,
  "rebated_fee": "string",
  "rebated_fee_currency": "string",
  "stp_id": 0,
  "stp_act": "cn",
  "finish_as": "open"
}

Spot order details

# Properties

Name	Type	Required	Restrictions	Description
id	string	false	read-only	Order ID
text	string	false	none	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: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4
amend_text	string	false	read-only	The custom data that the user remarked when amending the order
create_time	string	false	read-only	Creation time of order
update_time	string	false	read-only	Last modification time of order
create_time_ms	integer(int64)	false	read-only	Creation time of order (in milliseconds)
update_time_ms	integer(int64)	false	read-only	Last modification time of order (in milliseconds)
status	string	false	read-only	Order status - `open`: to be filled - `closed`: filled - `cancelled`: cancelled
currency_pair	string	true	none	Currency pair
type	string	false	none	Order Type - limit : Limit Order - market : Market Order
account	string	false	none	Account type，spot - use spot account
side	string	true	none	Order side
amount	string	true	none	When `type` is limit, it refers to base currency. For instance, `BTC_USDT` means `BTC` When `type` is `market`, it refers to different currency according to `side` - `side` : `buy` means quote currency, `BTC_USDT` means `USDT` - `side` : `sell` means base currency，`BTC_USDT` means `BTC`
price	string	false	none	Price can't be empty when `type`= `limit`
time_in_force	string	false	none	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only `ioc` and `fok` are supported when `type`=`market`
iceberg	string	false	none	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported.
auto_repay	boolean	false	none	Default is disabled.
left	string	false	read-only	Amount left to fill
fill_price	string	false	read-only	Total filled in quote currency. Deprecated in favor of `filled_total`
filled_total	string	false	read-only	Total filled in quote currency
avg_deal_price	string	false	read-only	Average fill price
fee	string	false	read-only	Fee deducted
fee_currency	string	false	read-only	Fee currency unit
point_fee	string	false	read-only	Points used to deduct fee
gt_fee	string	false	read-only	GT used to deduct fee
gt_maker_fee	string	false	read-only	GT used to deduct maker fee
gt_taker_fee	string	false	read-only	GT used to deduct taker fee
gt_discount	boolean	false	read-only	Whether GT fee discount is used
rebated_fee	string	false	read-only	Rebated fee
rebated_fee_currency	string	false	read-only	Rebated fee currency unit
stp_id	integer	false	read-only	Orders between users in the same `stp_id` group are not allowed to be self-traded 1. If the `stp_id` of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the `stp_act` of the taker. 2. `stp_id` returns `0` by default for orders that have not been set for `STP group`
stp_act	string	false	none	Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the `STP Group`, he can pass `stp_act` to limit the user's self-trade prevetion strategy. If `stp_act` is not passed, the default is `cn` strategy。 2. When the user does not join the `STP group`, an error will be returned when passing the `stp_act` parameter。 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, Cancel old orders and keep new ones - cb: Cancel both, Both old and new orders will be cancelled
finish_as	string	false	read-only	How the order was finished. - open: processing - filled: filled totally - cancelled: manually cancelled - ioc: time in force is `IOC`, finish immediately - stp: cancelled because self trade prevention

# Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
account	spot
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	ioc
finish_as	stp

# SpotPriceTriggeredOrder

{
  "trigger": {
    "price": "string",
    "rule": ">=",
    "expiration": 0
  },
  "put": {
    "type": "limit",
    "side": "buy",
    "price": "string",
    "amount": "string",
    "account": "normal",
    "time_in_force": "gtc"
  },
  "id": 0,
  "user": 0,
  "market": "string",
  "ctime": 0,
  "ftime": 0,
  "fired_order_id": 0,
  "status": "string",
  "reason": "string"
}

Spot order detail

# Properties

Name	Type	Required	Restrictions	Description
trigger	object	true	none	none
» price	string	true	none	Trigger price
» rule	string	true	none	Price trigger condition - >=: triggered when market price larger than or equal to `price` field - <=: triggered when market price less than or equal to `price` field
» expiration	integer	true	none	How long (in seconds) to wait for the condition to be triggered before cancelling the order.
put	object	true	none	none
» type	string	false	none	Order type, default to `limit`
» side	string	true	none	Order side - buy: buy side - sell: sell side
» price	string	true	none	Order price
» amount	string	true	none	Order amount
» account	string	true	none	Trading account type. ` - normal: spot trading
» time_in_force	string	false	none	time_in_force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only
id	integer(int64)	false	read-only	Auto order ID
user	integer	false	read-only	User ID
market	string	true	none	Currency pair
ctime	integer(int64)	false	read-only	Creation time
ftime	integer(int64)	false	read-only	Finished time
fired_order_id	integer(int64)	false	read-only	ID of the newly created order on condition triggered
status	string	false	read-only	Status - open: open - cancelled: being manually cancelled - finish: successfully executed - failed: failed to execute - expired - expired
reason	string	false	read-only	Additional remarks on how the order was finished

# Enumerated Values

Property	Value
rule	>=
rule	<=
side	buy
side	sell
account	normal
time_in_force	gtc
time_in_force	ioc

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

# Gate API v4 v4.44.0

# Access URL

# SDK

# Changelog

# General

# Matching mechanism

# Matching priority

# Order life cycle

# Data Center

# API Overview

# API

# HTTP convention

# Time

# Pagination

# Frequency limit rule

# Return Format

# Data Type

# Spot trading

# Request ID

# Self-Trade Prevention (STP)

# Concepts

# STP Strategies

# API Parameter Adjustment

# User case

# Error Handling

# label list

# Authentication

# Generate API key

# APIv4 Permissions

# APIv4 signed request requirements

# API Signature string generation

# Request Method

# Request URL

# Query String

# HexEncode(SHA512(Request Payload))

# Timestamp

# FAQ

# Spot

# List all currencies' details

Responses

Response Schema

# Get details of a specific currency

Parameters

Responses

Response Schema

# Retrieve ticker information

Parameters

# Enumerated Values

Responses

Response Schema

# Retrieve order book

Parameters

Responses

Response Schema

# Retrieve market trades

Parameters

# Detailed descriptions

Responses

Response Schema

# Enumerated Values

# Market candlesticks

Parameters

# Detailed descriptions

# Enumerated Values

Responses

Response Schema

# Query user trading fee rates

Parameters

# Detailed descriptions

Responses

Response Schema

# Query a batch of user trading fee rates

Parameters

Responses

Response Schema

# List spot accounts

Parameters

Responses

Response Schema

# Create a batch of orders

# `label` list

# Cancel all `open` orders in specified currency pair