Gate API v4 v4.27.0

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

Welcome to Gate.io API

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

Access URL

REST API BaseURL:

• Live trading: https://api.gateio.ws/api/v4
• Futures TestNet trading: https://fx-api-testnet.gateio.ws/api/v4
• Futures live trading alternative (futures only): https://fx-api.gateio.ws/api/v4

SDK

Available SDK:

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

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.

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

About APIv4 key improvement

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

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

Comparison with APIv2

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

The ways APIv4 and APIv2 differ are:

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

Which one to choose:

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

Application for Marketers

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

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

Provide the above content and submit to [email protected] , we will accept within 3 working days.

TIP

Vip11 and above need to open GT deduction in the personal center to enjoy the professional market rate.

Technical Support

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

• Submit Work Order Feedback
• Online Work Order Feedback
• Send your contact information and questions to [email protected] We will assign technical specialists to serve you.

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

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

DANGER

Even if you submit a problem, you should not submit the API key information to customer service or others, otherwise there will be serious asset risk. If it has been accidentally leaked, please delete the existing API and rebuild it.

Changelog

v4.27.0

2022-07-29

• Add basis_rate、basis_value fields in GET /delivery/{settle}/tickers response
• Add X-Client-Request-Id http header for tracking request
• new create a batch of futures order endpoint POST /futures/{settle}/batch_orders
• new FOK tif type for futures order

v4.26.0

2022-07-15

• Spot Price-Trigger order supports portfolio margin account
• Add GET /wallet/saved_address to list saved address
• POST /wallet/transfers returns tx_id field
• Add GET /wallet/sub_account_cross_margin_balances to query subaccount's cross_margin account
• Add status field in GET /margin/currency_pairs response

v4.25.1

2022-07-06

• New GET /spot/time endpoint which get system's time info.
• New GET /options/my_settlements endpoint which list my selttlements.
• Add change_utc0, change_utc8 fields in GET /spot/tickers endpoint

v4.25.0

2022-06-24

• Support portfolio margin account API
• Cross-margin add more fields. Please refer to endpoint document for more details.
• Add status field in GET /margin/cross/currencies endpoint, determine whether the cross currency is disabled 0-disable 1-enable
• New POST /spot/cross_liquidate_orders spot trading endpoint that close position when the cross-currency is disabled
• Add bouns and history fields in GET /futures/{settle}/accounts endpoint
• Add text、fee and point_fee fields in GET /futures/{settle}/my_trades endpoint
• Fix typo for cancel a price-triggered order endpoints
• POST /wallet/sub_account_transfers supports transferring to cross_margin

v4.24.0

2022-05-20

• Support flash swap operations with new API group /flash_swap. Spot operation permission is required.
• New wallet APIs GET /wallet/sub_account_margin_balances and GET /wallet/sub_account_futures_balances to help main account retrieving sub accounts' margin and perpetual contract balances
• New perpetual contract API GET /futures/{settle}/index_constituents/{index} to retrieve index price constituents
• Fix missing fields like order_type in FuturesPriceTriggeredOrder

v4.23.4

2022-04-25

• Add PUT /futures/{settle}/orders/{order_id} to amend perpetual futures orders
• Spot candlesticks supports 30d interval

v4.23.3

2022-04-01

1. Spot candlestick API returns base currency amount
2. Spot currency detail add chain field.
3. Add withdrawal and deposit status in GET /wallet/currency_chains response
4. Add missing cross_leverage_limit in perpetual contract's dual mode position leverage update API
5. Support more intervals in perpetual and delivery contract candlesticks

v4.23.2

2022-01-21

1. Add fee in withdrawal and deposit history
2. Add fix fee rate in spot Currency

v4.23.1

2021-12-23

1. Spot orders support new time_in_force FOK
2. New FOK_NOT_FILL error label

v4.23.0

2021-12-09

1. Add options API
2. Add detailed rate limiting rules
3. Add GET /wallet/currency_chains to retrieve chains supported by currency
4. Add additional status for deposit and withdrawal history

v4.22.4

2021-11-01

1. Data type of ctime and ftime in SpotPriceTriggeredOrder should be int64

v4.22.3

2021-10-27

1. GET /spot/trades supports time range based query using from and to.

v4.22.2

2021-09-29

1. Add more status in withdrawal or deposit record model
2. Add new write only field auto_size in FuturesOrder to support closing dual mode position.

v4.22.1

2021-09-07

1. New wallet API GET /wallet/total_balance to retrieve all user's estimate balance.
2. Add locked and risk in margin account response
3. Margin and cross margin loans support custom text input.

v4.22.0

2021-08-13

1. Delivery contract API supports BTC settled
2. Spot API GET /spot/orders and GET /spot/my_trades supports query by time range
3. Add margin and cross margin max borrowable API
4. Multiple document enhancements.

v4.21.6

2021-08-12

1. Fix incorrect address field name in GET /wallet/deposit_address

v4.21.5

2021-06-30

• GET /spot/orders, GET /spot/orders/{order_id} and GET /spot/my_trades allow empty currency_pair if operated against finished orders
• Add fixed withdrawal fee on multiple chains in GET /wallet/withdraw_status response
• Add GET /margin/transferable and GET /margin/cross/transferable to retrieve maximum transferable amount from margin and cross margin account
• Add from and to parameter to specify time range for futures position closes history API

v4.21.4

2021-06-23

• Add cross margin account change history API GET /margin/cross/account_book
• Add millisecond timestamp in GET /margin/account_book response

v4.21.3

2021-06-17

• Add order book timestamp for both spot and futures trading

v4.21.2

2021-06-07

• Futures API support cross margin leverage modification
• Add new spot cross margin API /margin/cross
• Add spot order operations using spot cross margin account
• Add unpaid interests in spot margin account query
• Add new millisecond fields create_time_ms and update_time_ms in spot orders.
• Add DELETE /withdrawals/{withdrawal_id} to cancel withdrawal operation

v4.20.1

2021-04-14

• Update document links

v4.20.0

2021-03-25

• Support spot auto orders with API group /spot/price_orders

v4.19.6

2021-03-22

• Add trading timestamp in spot currency pair

v4.19.5

2021-03-18

• Spot and Futures operations based on order ID also accept user custom ID(but only for 30 minutes since creation)

v4.19.4

2021-03-10

• /wallet/sub_account_transfers supports transferals with sub user's perpetual contract account

v4.19.3

2021-03-04

• Add margin loans auto repay API /margin/auto_repay
• Add multichain_address in /wallet/deposit_address for currencies with multiple deposit addresses
• Optimize documentation

v4.19.2

2021-03-01

• Add /wallet/fee API to retrieve trading fee. Previous /spot/fee is deprecated in favour of this one.
• Add new field chain in withdrawal operation.
• Add new field with_id in /futures/{settle}/order_book API and id field in its response
• Add new offset in API /futures/{settle}/position_close to retrieve position close history with pagination.
• Add contract value calculation. Refer to Contract model for details.
• Fix incorrect field type in futures stats API

v4.18.4

2021-01-22

• Add field create_time_ms in spot Trade model
• ETF currency pairs' ticker add net value related info

v4.18.1

2021-01-07

• Add iceberg order support for spot orders
• Fix incorrect field types in /futures/{settle}/contract_stats

v4.18.0

2020-12-21

• Add new spot API/spot/currencies and /spot/currencies/{currency} to retrieve currency info
• Add more fields, e.g., top_lsr_account, top_lsr_size, in futures ContractStat model.

v4.17.1

2020-12-16

• Increase maximum of limit in /spot/order_book to 100

v4.17.0

2020-12-15

• Add /wallet/sub_account_balances to retrieve sub accounts' balances.

v4.16.1

2020-12-10

• Fix mistaken field name dual_mode in futures position model which should be mode instead.

v4.16.0

2020-12-09

Spot

• Increase order number limit each currency pair to 10 in POST /spot/batch_orders
• Add new query parameter reverse in GET /spot/trades to trace back trading history

Futures

• Add perpetual contract dual mode position support. Use /futures/{settle}/dual_mode to set position's dual mode. For dual mode position operations, refer to /futures/{settle}/dual_comp/positions API group
• Add perpetual contract new field in_dual_mode in futures account response model; dual_mode in position response model.
• Add new perpetual contract public API /futures/{settle}/liq_orders to query liquidated orders in markets

v4.15.5

2020-11-04

• Add /futures/{settle}/contract_stats API to retrieve contract stats
• Add /margin/{currency_pair} to retrieve single margin currency pair detail

v4.15.4

2020-09-01

• Add point_type in GET /spot/fee response
• Add GET /wallet/withdraw_status API
• Add C# SDK entry

v4.15.2

2020-08-12

• Add GET /spot/fee to retrieve spot order trading fee rates

v4.15.1

2020-08-04

• Add GET /spot/open_orders to retrieve all open orders in spot trading
• Add GET /margin/account_book to retrieve margin account balance history

v4.14.1

2020-07-08

• maximum length of text field in order extends to 28(prefix excluded)

v4.14.0

2020-07-06

• New Delivery contract APIs /delivery

v4.13.1

2020-06-28

• Add GET /wallet/sub_account_transfers to list sub account transfer records

v4.13.0

2020-05-20

• APIv4 now supports withdraw API. Refer to POST /withdrawals and "Authentication" section for details.
• POST /wallet/transfers supports transferring between spot and futures account
• Wallet API supports retrieving deposits and withdrawals history
• Futures orders and personal trades retrieving now supports offset field
• Futures Contract model add new field in_delisting

v4.12.0

2020-04-08

• APIv4 Key management improved. Keys are no longer separated with different trading types. Every key can now have multiple operation permissions. Refer to "About APIv4 key improvement" for details.
• Add POST /wallet/sub_account_transfers to support transferring between main and sub account
• GET /spot/candlesticks adds query parameters from and to to support retrieving history data points

v4.11.2

2020-03-29

• Add filled_total in Order to replace fill_price (the latter is badly named)
• Add new error label POC_FILL_IMMEDIATELY

v4.11.1

2020-03-23

• Add role in GET /spot/my_trades response
• Fix missing currency account in GET /margin/funding_accounts

v4.11.0

2020-03-20

• Spot order supports GT fee discount
• Spot order time in force supports poc

v4.10.1

2020-02-24

• Add trade_status in spot currency pair

v4.10.0

2020-02-17

• Margin order creation adds new field auto_borrow(write only) to borrow the insufficient part by the system if balance is not enough
• Add new API POST /spot/cancel_batch_orders to support batch cancellation with specified order IDs
• Add new document section "Error handling" and "Which one to choose, APIv4 or APIv2?"

v4.9.1

2020-01-07

• Add fee and recent modification time in Order and BatchOrder
• Add fee in GET /spot/my_trades response

v4.9.0

2019-12-17

• last_id in GET /futures/{settle}/trades is deprecated. Use from and to to retrieve trading history

v4.8.2

2019-12-02

• Add /spot/batch_orders to support creating a bundle of spot or margin orders
• Fee rate of margin loan repayment enjoys VIP discount
• Loan add new fields fee_rate(fee rate of lending loan) and orig_id(original loan ID if loan is auto renewed)

v4.8.1

2019-11-27

• Fix missing settle in GET /futures/{settle}/positions docs and code snippet

v4.8.0

2019-11-07

• Futures API now supports settling in USDT.
• Change /futures to /futures/{settle} in ALL futures API to support futures operations in different settle currency.
• currency field in /futures/{settle}/accounts response adds new value: USDT
• Add volume_24h_base, volume_24h_quote and volume_24h_settle in /futures/{setttle}/tickers response to replace volume_24h_btc and volume_24h_usd. The latter two are still preserved for compatibility usage, but are NOT recommended for any futures operations.

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

For compatibility, GET /futures/xxx defaults to GET /futures/btc/xxx, e.g. GET /futures/accounts will be treated as GET /futures/btc/accounts

v4.7.3

2019-07-18

• Add text in /spot/orders and /futures/orders to support user defined order information

v4.6.3

2019-06-11

• Add point information in Futures account and position

v4.7.2

2019-05-29

• Change rate in Loan as non-required for lending side.

v4.7.1

2019-04-17

• Add wallet v4 API. Support transfers between spot and margin account for now.
• GET /margin/loans can sort by rate and support an optional parameter currency_pair
• Fix miscellaneous document issues

v4.6.2

2019-04-24

• Fix price-triggered futures order's docs incorrect override docs for GET /futures/orders/{order_id} and DELETE /futures/orders/{order_id}

v4.6.1

2019-04-02

• Add high_24h, low_24h and funding_rate_indicative in futures ticker

v4.6.0

2019-03-21

SDK related only

• Rename futures order related function name in SDKs to avoid duplication with spot order API in Go
• Fix query parameter not decoded while generating authentication signature

v4.5.2

2019-03-14

• currency_pair in /spot/order_book should be a required parameter
• Optimize document code samples

v4.5.1

2019-03-11

• Fix missing URL parameter description

v4.5.0

2019-03-05

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

• Add Spot v4 API to provide improved API capability
• Add Margin v4 API to provide support for margin loans and trading
• Add Futures price triggered auto order API support. Refer to /futures/price_orders for details
• Base URL of all Gate API v4 real trading changed to https://api.gateio.ws/api/v4

v1.3.0

2019-02-13

Important update

• Domain of base URLs are changed to fx-api.gateio.ws and fx-api-testnet.gateio.ws respectively, *.gateio.io is deprecated and will soon be out of service.

v1.2.1

2019-02-13

• Add volumn_24h_usd and volume_24h_btc in GET /futures/tickers response

v1.2.0

2019-01-17

• Add GET /futures/contracts/{contract} to get one single contract
• Add GET /futures/positions/{contract} to get one single position
• Add GET /futures/account_book to retrieve user account balance history
• Add config_change_time in Contract model
• fix miscellaneous document issues

v1.1.0

2019-01-08

• Add more fields to Contract, Position, FuturesOrder
• Add API GET /futures/position_close to retrieve position close history
• Add optional order_id support for API GET /futures/my_trades
• Change the status code of DELETE /futures/orders and DELETE /futures/orders/{order_id} from 204 to 200, with cancelled order details returned on success.
• Request DELETE /futures/orders/{order_id} with invalid order ID or order that has been finished will return 404 instead of ignoring the error
• POST /futures/orders now supports POC, iceberg

v1.0.0

2018-12-30

• 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
host + /api/v4/margin/*	Margin Trading	Margin account management, lending, repayment, etc
host + /api/v4/wallet/*	Wallet Management	Charge and withdrawal records, balance inquiries, fund transfers, etc.
host + /api/v4/withdrawals/*	Withdrawal	Withdrawal of digital currency

API

HTTP convention

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

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

Using limit-offset method, send request parameters like:

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

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

• 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, margin trade,etc.
	Cancel orders	5000r/s	User ID	Canceling(all) orders, etc.
Perpetual Swaps	Public endpoints	300r/s	IP	Order book, Candlesticks, trading pairs, funding rate, etc.
	Place orders	100r/s	User ID	Placing(bulk) orders, etc.
	Private endpoints	400r/s	User ID	Position,fee rate,etc.
	Cancel orders			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

Portfolio Margin Account

Since version 4.25.0, we start supporting portfolio margin account. Gate.io's Portfolio Margin Account is a new feature of Gate.io's trading system. Its main function is to break the capital isolation between cross-margin leverage account and USD cross-margin perpetual contract account inside a Classic Account and achieve the mufti-currency margin sharing among mufti-product lines. Thanks to the margin sharing, users don't need to transfer funds between the two accounts, and the profit and loss of positions among different trading products can offset each other and effectively improve the capital utilization rate. See more details in the Help Center

Before using the portfolio margin account's API key, you should create the API key on the API management page. The API key supports spot and perpetual contracts trading only.

If permissions of the API key can't be checked, ensure your cross-margin account has available balance first.

Transfer

The classic account and portfolio margin account are two different capital isolation accounts. If you want to achieve multi-currency margin sharing among multi-product lines, use the portfolio margin account please.

The funds of the portfolio margin account come from the classic account. Due to the change of funds in the classic account, the transfer of funds can only be performed using the API Key of the classic account.

The portfolio margin account is upgraded based on the cross-margin account of the original classic account, so the classic account only needs to transfer its spot funds to the cross-margin account to deposit the portfolio margin account. Similarly, withdrawals from portfolio margin account can be achieved by the classic account performing transferals from the cross margin to its spot account.

The API Key of the portfolio margin account can only perform transferals among its own multiple accounts. Due to the sharing of margin, the portfolio margin account does not need to transfer funds to its futures account (we also restrict doing so). If the futures account has PNL funds that need to be withdrawn, it must be transferred by the portfolio margin account's API key to its cross-margin account first, so that the classic account can perform withdrawals from portfolio margin account.

Spot trading

The spot trading of the portfolio margin account is almost the same as the classic account, except that cross_margin must be specified in the account parameter when placing orders. 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": "cross_margin",
  "side": "buy",
  ...
}

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

TIP

It should be noted that the portfolio margin account is upgraded from the classic account's cross-margin account. The API Key of the classic account originally supports the operation of the cross-margin account. In order not to affect the existing operations of the classic account, we still retain this function of the classic account. So whether it is the API Key of the classic account or the portfolio margin account, both can operate the same the cross margin account (note that the futures accounts are separate)

Futures trading

The API operation of the perpetual contract of the portfolio margin account is exactly the same as that of the classic account, but currently only supports USD settlement

TIP

In the futures trading, it should be noted that there is no compatibility for cross-margin accounts like using the API Key of the classic account in spot trading. Therefore, when using the API Key of the classic account for futures trading, assets are kept under classic account-futures, and when using portfolio margin account API Key for futures trading, assets are kept under portfolio margin account-futures. These two are different futures accounts. In addition, funds under classic account-spot cannot share margin with classic account-futures.

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.

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/futures/btc/contracts/BTC_USD")
try:
    r.raise_for_status()
except requests.HTTPError:
    # catch 2xx errors, parse error message in body, and do something based on `label`
    if r.json()['label'] == 'xxx':
        print(r.json())

or with Python SDK (opens new window):

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

api = FuturesApi()
try:
    api.get_futures_contract(settle='btc', contract="BTC_USD")
except ApiException as e:  # ApiException wraps whole error information, see implementation for details
    detail = json.loads(e.value.body)
    if detail['label'] == 'xxx':
        print(detail)

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
MARGIN_BALANCE_EXCEPTION	Abnormal margin account
MARGIN_TRANSFER_FAILED	Failed to transfer with margin account
TOO_MUCH_FUTURES_AVAILABLE	Futures balance exceeds max allowed
FUTURES_BALANCE_NOT_ENOUGH	Futures balance not enough
ACCOUNT_EXCEPTION	Abnormal account
SUB_ACCOUNT_TRANSFER_FAILED	Failed to transfer with sub account
ADDRESS_NOT_USED	Address never being used in web console
TOO_FAST	Withdrawing request exceeds frequency limit
WITHDRAWAL_OVER_LIMIT	Withdrawal limit exceeded
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 and margin 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
MARGIN_NOT_SUPPORTED	Request currency pair doesn't provide margin trading
MARGIN_BALANCE_NOT_ENOUGH	Margin balance is not enough
AMOUNT_TOO_LITTLE	Amount does not reach minimum required
AMOUNT_TOO_MUCH	Amount exceeds maximum allowed
REPEATED_CREATION	Repeated creation
LOAN_NOT_FOUND	Margin loan is not found
LOAN_RECORD_NOT_FOUND	Margin loan record is not found
NO_MATCHED_LOAN	No loan can match request borrow requirement
NOT_MERGEABLE	Request loans cannot be merged
NO_CHANGE	No change is made
REPAY_TOO_MUCH	Repay more than required
TOO_MANY_CURRENCY_PAIRS	Too many currency pairs in batch orders creation
TOO_MANY_ORDERS	Too many orders in one currency pair in batch orders creation
MIXED_ACCOUNT_TYPE	More than one account type is used in batch orders creation
AUTO_BORROW_TOO_MUCH	Auto borrow exceeds maximum allowed
TRADE_RESTRICTED	Trading is restricted due to high debt ratio
FOK_NOT_FILL	FOK order cannot be filled completely
INITIAL_MARGIN_TOO_LOW	User's total initial margin rate is too low
NO_MERGEABLE_ORDERS	Orders can be merged not found

• Futures related

label	Meaning
USER_NOT_FOUND	User has no futures account
CONTRACT_NO_COUNTER	No counter order found
CONTRACT_NOT_FOUND	Contract not found
RISK_LIMIT_EXCEEDED	Risk limit exceeded
INSUFFICIENT_AVAILABLE	Balance is not enough
LIQUIDATE_IMMEDIATELY	Operation may cause liquidation
LEVERAGE_TOO_HIGH	leverage too high
LEVERAGE_TOO_LOW	leverage too low
ORDER_NOT_FOUND	Order not found
ORDER_NOT_OWNED	Order not owned
ORDER_FINISHED	Order already finished
TOO_MANY_ORDERS	Too many open orders
POSITION_CROSS_MARGIN	margin updating is not allowed in cross margin
POSITION_IN_LIQUIDATION	Position is being liquidated
POSITION_IN_CLOSE	Position is closing
POSITION_EMPTY	Position is empty
REMOVE_TOO_MUCH	Changed margin exceeds allowed
RISK_LIMIT_NOT_MULTIPLE	Risk limit is not a multiple of step
RISK_LIMIT_TOO_HIGH	Risk limit too high
RISK_LIMIT_TOO_lOW	Risk limit too low
PRICE_TOO_DEVIATED	Order price deviates too much from mark price
SIZE_TOO_LARGE	Order size exceeds maximum
SIZE_TOO_SMALL	Order size does not reach minimum
PRICE_OVER_LIQUIDATION	Price to increase position can not exceeds liquidation price
PRICE_OVER_BANKRUPT	Price to decrease position cannot exceeds bankrupting price
ORDER_POC_IMMEDIATE	POC order will be finished immediately
INCREASE_POSITION	POC order will increase position
CONTRACT_IN_DELISTING	Contract is delisting, only reduce-only order or close order is allowed
POSITION_NOT_FOUND	Position not found
POSITION_DUAL_MODE	Operation forbidden in dual-mode
ORDER_PENDING	Operation forbidden with pending orders
POSITION_HOLDING	Operation forbidden with holding position
REDUCE_EXCEEDED	Reduce order would exceed position in dual-mode
NO_CHANGE	No change is made
AMEND_WITH_STOP	Amend forbidden with stop order
ORDER_FOK	Killed for FOK

• 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 5 API keys, and the permission configuration of each key is independent of each other. It is recommended to set a note name for each key to indicate its purpose.

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

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

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

TIP

Note: If the key is named with spot or futures, 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.

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

APIv4 Permissions

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

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

All GET operations are read requests, while others are write requests. Each permission group can be set to 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

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

API Signature string generation

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

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

Request Method

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

Request URL

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

Query String

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

HexEncode(SHA512(Request Payload))

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

Timestamp

Timestamp request header value.

Examples

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

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

1. List all orders

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

Signature string：

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

Explanation：

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

Signature generated

55f84ea195d6fe57ce62464daaa7c3c02fa9d1dde954e4c898289c9a2407a3d6fb3faf24deff16790d726b66ac9f74526668b13bd01029199cc4fcc522418b8a

2. Create an order

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

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

Signature string：

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

Explanation：

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

Signature generated

eae42da914a590ddf727473aff25fc87d50b64783941061f47a3fdb92742541fc4c2c14017581b4199a1418d54471c269c03a38d788d802e2c306c37636389f0

# example authentication implementation in Python

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

import time
import hashlib
import hmac
import requests
import json

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

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

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

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

FAQ

• How to retrieve POST /wallet/transfers history?

  Records of transfers generated through POST /wallet/transfers has multiple methods to be retrieved based on account, including:

  • GET /margin/account_book to retrieve transferals from or to margin account.
  • GET /futures/{settle}/account_book?type=dnw to retrieve perpetual contract account history
  • GET /delivery/{settle}/account_book?type=dnw to retrieve delivery contract account history

• How to create margin orders?

  Margin order creation has been merged into spot order APIs. In POST /spot/orders or POST /spot/batch_orders, set account to margin to create margin orders.

• Futures operation returns error USER_NOT_FOUND

  Futures account is not initialized yet. Making a deposit to your futures account will help. Note that each settle currency is associated with an independent futures account.

• Futures operation returns error CONTRACT_NOT_FOUND

  Every settle currency has its own contract list. Make sure the contract you specified is supported by the settle currency. You can query the list with

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

• 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

Withdrawal

Withdrawal operations

Withdraw

Code samples

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

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

url = '/withdrawals'
query_param = ''
body='{"currency":"USDT","address":"1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs","amount":"222.61","memo":"","chain":"TRX"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

POST /withdrawals

Withdraw

Body parameter

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

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» amount	body	string	true	Currency amount
» currency	body	string	true	Currency name
» address	body	string	false	Withdrawal address. Required for withdrawals
» memo	body	string	false	Additional remarks with regards to the withdrawal
» chain	body	string	false	Name of the chain used in withdrawals
» fee	body	string	false	Fee

Example responses

202 Response

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

Responses

Status	Meaning	Description	Schema
202	Accepted (opens new window)	Withdraw request is accepted. Refer to withdrawal records for status	Inline

Response Schema

Status Code 202

Name	Type	Description
» id	string	Record ID
» txid	string	Hash record of the withdrawal
» timestamp	string	Operation time
» amount	string	Currency amount
» currency	string	Currency name
» address	string	Withdrawal address. Required for withdrawals
» memo	string	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
» fee	string	Fee

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

Cancel withdrawal with specified ID

Code samples

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

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

url = '/withdrawals/210496'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

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

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

DELETE /withdrawals/{withdrawal_id}

Cancel withdrawal with specified ID

Parameters

Name	In	Type	Required	Description
withdrawal_id	path	string	true	none

Example responses

202 Response

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

Responses

Status	Meaning	Description	Schema
202	Accepted (opens new window)	Cancellation accepted. Refer to record status for the cancellation result	Inline

Response Schema

Status Code 202

Name	Type	Description
» id	string	Record ID
» txid	string	Hash record of the withdrawal
» timestamp	string	Operation time
» amount	string	Currency amount
» currency	string	Currency name
» address	string	Withdrawal address. Required for withdrawals
» memo	string	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
» fee	string	Fee

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

Wallet

Wallet

List chains supported for specified currency

Code samples

# coding: utf-8
import requests

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

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

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

GET /wallet/currency_chains

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

This operation does not require authentication

Generate currency deposit address

Code samples

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

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

url = '/wallet/deposit_address'
query_param = 'currency=USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

GET /wallet/deposit_address

Generate currency deposit address

Parameters

Name	In	Type	Required	Description
currency	query	string	true	Currency name

Example responses

200 Response

{
  "currency": "USDT",
  "address": "LPXtk1kWHioP62SzfqwKbYE3Z7Wt2ujYEc",
  "multichain_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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/withdrawals'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /wallet/withdrawals

Retrieve withdrawal records

Record time range cannot exceed 30 days

Parameters

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

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (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
» 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
» fee	string	Fee

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/deposits'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /wallet/deposits

Retrieve deposit records

Record time range cannot exceed 30 days

Parameters

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

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (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
» 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
» fee	string	Fee

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 trading accounts

Code samples

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

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

url = '/wallet/transfers'
query_param = ''
body='{"currency":"BTC","from":"spot","to":"margin","amount":"1","currency_pair":"BTC_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

POST /wallet/transfers

Transfer between trading accounts

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

1. spot - margin
2. spot - futures(perpetual)
3. spot - delivery
4. spot - cross margin
5. spot - options

Body parameter

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

Parameters

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

Enumerated Values

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

Example responses

200 Response

{
  "tx_id": 59636381286
}

Responses

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

Response Schema

Status Code 200

TransactionID

Name	Type	Description
» tx_id	integer(int64)	Order id

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/sub_account_transfers'
query_param = ''
body='{"currency":"BTC","sub_account":"10002","direction":"to","amount":"1","sub_account_type":"spot"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

POST /wallet/sub_account_transfers

Transfer between main and sub accounts

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

Body parameter

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

Parameters

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

Enumerated Values

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

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/sub_account_transfers'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /wallet/sub_account_transfers

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	Sub account user ID. Return records related to all sub accounts if not specified
from	query	integer(int64)	false	Time range beginning, default to 7 days before current time
to	query	integer(int64)	false	Time range ending, default to current time
limit	query	integer	false	Maximum number of records 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, futures - perpetual contract account, cross_margin - cross margin account

Enumerated Values

Property	Value
direction	to
direction	from
sub_account_type	spot
sub_account_type	futures
sub_account_type	cross_margin

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/withdraw_status'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /wallet/withdraw_status

Retrieve withdrawal status

Parameters

Name	In	Type	Required	Description
currency	query	string	false	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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/sub_account_balances'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /wallet/sub_account_balances

Retrieve sub account balances

Parameters

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

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (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 sub accounts' margin balances

Code samples

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

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

url = '/wallet/sub_account_margin_balances'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /wallet/sub_account_margin_balances

Query sub accounts' margin balances

Parameters

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

Example responses

200 Response

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

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	array	Margin account balances
»» None	object	Margin account detail. base refers to base currency, while `quotes to quote currency
»»» currency_pair	string	Currency pair
»»» locked	boolean	Whether account is locked
»»» risk	string	Current risk rate of margin account
»»» base	object	Account currency details
»»»» currency	string	Currency name
»»»» available	string	Amount suitable for margin trading.
»»»» locked	string	Locked amount, used in margin trading
»»»» borrowed	string	Borrowed amount
»»»» interest	string	Unpaid interests
»»» quote	object	Account currency details
»»»» currency	string	Currency name
»»»» available	string	Amount suitable for margin trading.
»»»» locked	string	Locked amount, used in margin trading
»»»» borrowed	string	Borrowed amount
»»»» interest	string	Unpaid interests

WARNING

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

Query sub accounts' futures account balances

Code samples

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

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

url = '/wallet/sub_account_futures_balances'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /wallet/sub_account_futures_balances

Query sub accounts' futures account balances

Parameters

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

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	Futures account balances
»» additionalProperties	object	none
»»» total	string	total = position_margin + order_margin + available
»»» unrealised_pnl	string	Unrealized PNL
»»» position_margin	string	Position margin
»»» order_margin	string	Order margin of unfinished orders
»»» available	string	The available balance for transferring or trading
»»» point	string	POINT amount
»»» currency	string	Settle currency
»»» in_dual_mode	boolean	Whether dual mode is enabled
»»» enable_credit	boolean	Whether portfolio margin account mode is enabled
»»» position_initial_margin	string	Initial margin position, applicable to the portfolio margin account model
»»» maintenance_margin	string	Maintenance margin position, applicable to the portfolio margin account model
»»» bonus	string	Perpetual Contract Bonus
»»» history	object	Statistical data
»»»» dnw	string	total amount of deposit and withdraw
»»»» pnl	string	total amount of trading profit and loss
»»»» fee	string	total amount of fee
»»»» refr	string	total amount of referrer rebates
»»»» fund	string	total amount of funding costs
»»»» point_dnw	string	total amount of point deposit and withdraw
»»»» point_fee	string	total amount of point fee
»»»» point_refr	string	total amount of referrer rebates of point fee
»»»» bonus_dnw	string	total amount of perpetual contract bonus transfer
»»»» bonus_offset	string	total amount of perpetual contract bonus deduction

WARNING

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

Query subaccount's cross_margin account info

Code samples

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

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

url = '/wallet/sub_account_cross_margin_balances'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /wallet/sub_account_cross_margin_balances

Query subaccount's cross_margin account info

Parameters

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

Example responses

200 Response

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

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	none
»» user_id	integer(int64)	User ID of the cross margin account. 0 means that the subaccount has not yet opened a cross margin account
»» locked	boolean	Whether account is locked
»» balances	object	none
»»» CrossMarginBalance	object	none
»»»» available	string	Available amount
»»»» freeze	string	Locked amount
»»»» borrowed	string	Borrowed amount
»»»» interest	string	Unpaid interests
»»» total	string	Total account value in USDT, i.e., the sum of all currencies' (available+freeze)*price*discount
»»» borrowed	string	Total borrowed value in USDT, i.e., the sum of all currencies' borrowed*price*discount
»»» borrowed_net	string	Total borrowed value in USDT * borrowed factor
»»» net	string	Total net assets in USDT
»»» leverage	string	Position leverage
»»» interest	string	Total unpaid interests in USDT, i.e., the sum of all currencies' interest*price*discount
»»» risk	string	Risk rate. When it belows 110%, liquidation will be triggered. Calculation formula: total / (borrowed+interest)
»»» total_initial_margin	string	Total initial margin
»»» total_margin_balance	string	Total margin balance
»»» total_maintenance_margin	string	Total maintenance margin
»»» total_initial_margin_rate	string	Total initial margin rate
»»» total_maintenance_margin_rate	string	Total maintenance margin rate
»»» total_available_margin	string	Total available margin

WARNING

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

Query saved address

Code samples

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

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

url = '/wallet/saved_address'
query_param = 'currency=USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

GET /wallet/saved_address

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

WARNING

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

Retrieve personal trading fee

Code samples

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

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

url = '/wallet/fee'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /wallet/fee

Retrieve personal trading fee

Parameters

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

Detailed descriptions

currency_pair: Specify a currency pair to retrieve precise fee rate

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

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (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
» loan_fee	string	Loan fee rate of margin lending
» point_type	string	Point type. 0 - Initial version. 1 - new version since 202009
» futures_taker_fee	string	Futures trading taker fee
» futures_maker_fee	string	Future trading maker fee

WARNING

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

Retrieve user's total balances

Code samples

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

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

url = '/wallet/total_balance'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /wallet/total_balance

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
• GET /margin/accounts to query margin account balance
• GET /futures/{settle}/accounts to query futures 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": {
    "cross_margin": {
      "amount": "0",
      "currency": "USDT"
    },
    "spot": {
      "currency": "USDT",
      "amount": "42264489969935775.5160259954878034182418"
    },
    "finance": {
      "amount": "662714381.70310327810191647181",
      "currency": "USDT"
    },
    "margin": {
      "amount": "1259175.664137668554329559",
      "currency": "USDT"
    },
    "quant": {
      "amount": "591702859674467879.6488202650892478553852",
      "currency": "USDT"
    },
    "futures": {
      "amount": "2384175.5606114082065",
      "currency": "USDT"
    },
    "delivery": {
      "currency": "USDT",
      "amount": "1519804.9756702"
    },
    "warrant": {
      "amount": "0",
      "currency": "USDT"
    },
    "cbbc": {
      "currency": "USDT",
      "amount": "0"
    }
  },
  "total": {
    "currency": "USDT",
    "amount": "633967350312281193.068368815439797304437"
  }
}

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 balances in different accounts - cross_margin: cross margin account - spot: spot account - finance: finance account - margin: margin account - quant: quant account - futures: futures account - delivery: delivery account - warrant: warrant account - cbbc: cbbc 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

WARNING

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

Spot

Spot trading

List all currencies' details

Code samples

# coding: utf-8
import requests

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

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

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

GET /spot/currencies

List all currencies' details

Currency has two forms:

1. Only currency name, e.g., BTC, USDT
2. <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

This operation does not require authentication

Get details of a specific currency

Code samples

# coding: utf-8
import requests

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

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

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

GET /spot/currencies/{currency}

Get 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

This operation does not require authentication

List all currency pairs supported

Code samples

# coding: utf-8
import requests

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

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

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

GET /spot/currency_pairs

List all currency pairs supported

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	All currency pairs retrieved	[CurrencyPair]

This operation does not require authentication

Get details of a specifc order

Code samples

# coding: utf-8
import requests

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

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

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

GET /spot/currency_pairs/{currency_pair}

Get details of a specifc order

Parameters

Name	In	Type	Required	Description
currency_pair	path	string	true	Currency pair

Example responses

200 Response

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

Responses

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

This operation does not require authentication

Retrieve ticker information

Code samples

# coding: utf-8
import requests

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

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

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

GET /spot/tickers

Retrieve ticker information

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

Parameters

Name	In	Type	Required	Description
currency_pair	query	string	false	Currency pair
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

This operation does not require authentication

Retrieve order book

Code samples

# coding: utf-8
import requests

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

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

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

GET /spot/order_book

Retrieve order book

Order book will be sorted by price from high to low on bids; 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

This operation does not require authentication

Retrieve market trades

Code samples

# coding: utf-8
import requests

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

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

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

GET /spot/trades

Retrieve market trades

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	false	Maximum number of records to be returned in a single list
last_id	query	string	false	Specify list staring point using the id of last record in previous list-query results
reverse	query	boolean	false	Whether 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

Enumerated Values

Property	Value
side	buy
side	sell
role	taker
role	maker

This operation does not require authentication

Market candlesticks

Code samples

# coding: utf-8
import requests

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

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

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

GET /spot/candlesticks

Market candlesticks

Maximum of 1000 points 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

This operation does not require authentication

Query user trading fee rates

Code samples

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

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

url = '/spot/fee'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /spot/fee

Query user trading fee rates

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

Parameters

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

Detailed descriptions

currency_pair: Specify a currency pair to retrieve precise fee rate

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

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (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
» loan_fee	string	Loan fee rate of margin lending
» point_type	string	Point type. 0 - Initial version. 1 - new version since 202009
» futures_taker_fee	string	Futures trading taker fee
» futures_maker_fee	string	Future trading maker fee

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /spot/accounts

List spot accounts

Parameters

Name	In	Type	Required	Description
currency	query	string	false	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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/batch_orders'
query_param = ''
body='[{"text":"t-123456","currency_pair":"ETH_BTC","type":"limit","account":"spot","side":"buy","iceberg":"0","amount":"1","price":"5.00032","time_in_force":"gtc","auto_borrow":false}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

POST /spot/batch_orders

Create a batch of orders

Batch orders requirements:

1. custom order field text is required
2. At most 4 currency pairs, maximum 10 orders each, are allowed in one request
3. No mixture of spot orders and margin orders, i.e. account must be identical for all orders

Body parameter

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

Parameters

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

Example responses

200 Response

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

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
»» account	string	Account type. spot - use spot account; margin - use margin account; cross_margin - use cross margin account
»» side	string	Order side
»» amount	string	Trade amount
»» price	string	Order price
»» time_in_force	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none
»» iceberg	string	Amount to display for the iceberg order. Null or 0 for normal orders. Set to -1 to hide the order completely
»» auto_repay	boolean	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay cannot be both set to true in one order.
»» 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

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
account	spot
account	margin
account	cross_margin
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok

WARNING

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/open_orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /spot/open_orders

List all open orders

List open orders in all currency pairs.

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

Spot and margin orders are returned by default. To list cross margin orders, account must be set to cross_margin

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 and margin account if not specified. Set to cross_margin to operate against margin account. Portfolio margin account must set to cross_margin only

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (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(.)
»»» 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
»»» account	string	Account type. spot - use spot account; margin - use margin account; cross_margin - use cross margin account. Portfolio margin account must set to cross-margin
»»» 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. Set to -1 to hide the order completely
»»» auto_repay	boolean	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay cannot be both set to true in one order.
»»» 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

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
account	spot
account	margin
account	cross_margin
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok

WARNING

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

close position when cross-currency is disabled

Code samples

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

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

url = '/spot/cross_liquidate_orders'
query_param = ''
body='{"currency_pair":"GT_USDT","amount":"12","price":"10.15","text":"t-34535"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

POST /spot/cross_liquidate_orders

close position when cross-currency is disabled

Currently, only cross-margin accounts are supported to close position when cross currencies are disabled. Maximum buy quantity = (unpaid principal and interest - currency balance - the amount of the currency in the order book) / 0.998

Body parameter

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

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» text	body	string	false	User defined information. If not empty, must follow the rules below:
» currency_pair	body	string	true	Currency pair
» amount	body	string	true	Trade amount
» price	body	string	true	Order price

Detailed descriptions

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

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

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",
  "left": "0.5",
  "filled_total": "2.50016",
  "fee": "0.005",
  "fee_currency": "ETH",
  "point_fee": "0",
  "gt_fee": "0",
  "gt_discount": false,
  "rebated_fee": "0",
  "rebated_fee_currency": "BTC"
}

Responses

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

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/orders'
query_param = ''
body='{"text":"t-123456","currency_pair":"ETH_BTC","type":"limit","account":"spot","side":"buy","iceberg":"0","amount":"1","price":"5.00032","time_in_force":"gtc","auto_borrow":false}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

POST /spot/orders

Create an order

You can place orders with spot, margin or cross margin account through setting the accountfield. It defaults to spot, which means spot account is used to place orders.

When margin account is used, i.e., account is margin, auto_borrow field can be set to true to enable the server to borrow the amount lacked using POST /margin/loans when your account's balance is not enough. Whether margin orders' fill will be used to repay margin loans automatically is determined by the auto repayment setting in your margin account, which can be updated or queried using /margin/auto_repay API.

When cross margin account is used, i.e., account is cross_margin, auto_borrow can also be enabled to achieve borrowing the insufficient amount automatically if cross account's balance is not enough. But it differs from margin account that automatic repayment is determined by order's auto_repay field and only current order's fill will be used to repay cross margin loans.

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.

Body parameter

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

Parameters

Name	In	Type	Required	Description
body	body	Order	true	none
» text	body	string	false	User defined information. If not empty, must follow the rules below:
» currency_pair	body	string	true	Currency pair
» type	body	string	false	Order type. limit - limit order
» account	body	string	false	Account type. spot - use spot account; margin - use margin account; cross_margin - use cross margin account. Portfolio margin account must set to cross-margin
» side	body	string	true	Order side
» amount	body	string	true	Trade amount
» price	body	string	true	Order price
» time_in_force	body	string	false	Time in force
» iceberg	body	string	false	Amount to display for the iceberg order. Null or 0 for normal orders. Set to -1 to hide the order completely
» auto_borrow	body	boolean	false	Used in margin or cross margin trading to allow automatic loan of insufficient amount if balance is not enough.
» auto_repay	body	boolean	false	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that:

Detailed descriptions

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

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

» time_in_force: Time in force

• 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

» auto_repay: Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that:

1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders.
2. auto_borrow and auto_repay cannot be both set to true in one order.

Enumerated Values

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

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",
  "left": "0.5",
  "filled_total": "2.50016",
  "fee": "0.005",
  "fee_currency": "ETH",
  "point_fee": "0",
  "gt_fee": "0",
  "gt_discount": false,
  "rebated_fee": "0",
  "rebated_fee_currency": "BTC"
}

Responses

Status	Meaning	Description	Schema
201	Created (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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/orders'
query_param = 'currency_pair=BTC_USDT&status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

GET /spot/orders

List orders

Spot and margin orders are returned by default. If cross margin orders are needed, account must be set to cross_margin

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 and margin account if not specified. Set to cross_margin to operate against margin account. Portfolio margin account must set to cross_margin only
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",
    "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	[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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/orders'
query_param = 'currency_pair=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

DELETE /spot/orders

Cancel all open orders in specified currency pair

If account is not set, all open orders, including spot, margin and cross margin ones, 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 types being included
• portfolio margin account：cross_margin only

Enumerated Values

Parameter	Value
side	buy
side	sell
account	spot
account	margin
account	cross_margin

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",
    "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)	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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/cancel_batch_orders'
query_param = ''
body='[{"currency_pair":"BTC_USDT","id":"123456"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

POST /spot/cancel_batch_orders

Cancel a batch of orders with an ID list

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

Body parameter

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

Parameters

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

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (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. If cancelled order is cross margin order, this field is set to cross_margin

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/orders/12345'
query_param = 'currency_pair=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

GET /spot/orders/{order_id}

Get a single order

Spot and margin orders are queried by default. If cross margin orders are needed or portfolio margin account are used, account must be set to cross_margin.

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. Default to spot and margin account if not specified. Set to cross_margin to operate against margin account. Portfolio margin account must set to cross_margin only

Detailed descriptions

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

Example responses

200 Response

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

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

Cancel a single order

Code samples

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

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

url = '/spot/orders/12345'
query_param = 'currency_pair=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

DELETE /spot/orders/{order_id}

Cancel a single order

Spot and margin orders are cancelled by default. If trying to cancel cross margin orders or portfolio margin account are used, account must be set to cross_margin

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. Default to spot and margin account if not specified. Set to cross_margin to operate against margin account. Portfolio margin account must set to cross_margin only

Detailed descriptions

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

Example responses

200 Response

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

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/my_trades'
query_param = 'currency_pair=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

GET /spot/my_trades

List personal trading history

Spot and margin trades are queried by default. If cross margin trades are needed, account must be set to cross_margin

You can also set from and(or) to to query by time range 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.
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 and margin account if not specified. Set to cross_margin to operate against margin account. Portfolio margin account must set to cross_margin only
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

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

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

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

GET /spot/time

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)

This operation does not require authentication

Create a price-triggered order

Code samples

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

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

url = '/spot/price_orders'
query_param = ''
body='{"trigger":{"price":"100","rule":">=","expiration":3600},"put":{"type":"limit","side":"buy","price":"2.15","amount":"2.00000000","account":"normal","time_in_force":"gtc"},"market":"GT_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

POST /spot/price_orders

Create a price-triggered order

Body parameter

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

Parameters

Name	In	Type	Required	Description
body	body	SpotPriceTriggeredOrder	true	none
» trigger	body	object	true	none
»» price	body	string	true	Trigger price
»» rule	body	string	true	Price trigger condition
»» expiration	body	integer	true	How 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. Portfolio margin account must set to cross_margin
»» 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. Portfolio margin account must set to cross_margin

• normal: spot trading
• margin: margin trading
• cross_margin: cross_margin 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
»» account	margin
»» account	cross_margin
»» 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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/price_orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

GET /spot/price_orders

Retrieve running auto order list

Parameters

Name	In	Type	Required	Description
status	query	string	true	Only list the orders with this status
market	query	string	false	Currency pair
account	query	string	false	Trading account type. Portfolio margin account must set to cross_margin
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
account	margin
account	cross_margin

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/price_orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

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

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

DELETE /spot/price_orders

Cancel all open orders

Parameters

Name	In	Type	Required	Description
market	query	string	false	Currency pair
account	query	string	false	Trading account type. Portfolio margin account must set to cross_margin

Enumerated Values

Parameter	Value
account	normal
account	margin
account	cross_margin

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (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 single order

Code samples

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

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

url = '/spot/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /spot/price_orders/{order_id}

Get a single order

Parameters

Name	In	Type	Required	Description
order_id	path	string	true	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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/spot/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

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

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

DELETE /spot/price_orders/{order_id}

cancel a 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

Margin

Margin API; margin trading uses spot trading API

List all supported currency pairs supported in margin trading

Code samples

# coding: utf-8
import requests

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

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

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

GET /margin/currency_pairs

List all supported currency pairs supported in margin trading

Example responses

200 Response

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

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	Currency pair
» base	string	Base currency
» quote	string	Quote currency
» leverage	integer	Leverage
» min_base_amount	string	Minimum base currency to loan, null means no limit
» min_quote_amount	string	Minimum quote currency to loan, null means no limit
» max_quote_amount	string	Maximum borrowable amount for quote currency. Base currency limit is calculated by quote maximum and market price. null means no limit
» status	integer(int32)	Currency pair status - 0: disabled - 1: enabled

This operation does not require authentication

Query one single margin currency pair

Code samples

# coding: utf-8
import requests

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

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

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

GET /margin/currency_pairs/{currency_pair}

Query one single margin currency pair

Parameters

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

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» id	string	Currency pair
» base	string	Base currency
» quote	string	Quote currency
» leverage	integer	Leverage
» min_base_amount	string	Minimum base currency to loan, null means no limit
» min_quote_amount	string	Minimum quote currency to loan, null means no limit
» max_quote_amount	string	Maximum borrowable amount for quote currency. Base currency limit is calculated by quote maximum and market price. null means no limit
» status	integer(int32)	Currency pair status - 0: disabled - 1: enabled

This operation does not require authentication

Order book of lending loans

Code samples

# coding: utf-8
import requests

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

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

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

GET /margin/funding_book

Order book of lending loans

Parameters

Name	In	Type	Required	Description
currency	query	string	true	Retrieve data of the specified currency

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» rate	string	Loan rate
» amount	string	Borrowable amount
» days	integer	The number of days till the loan repayment's dateline

This operation does not require authentication

Margin account list

Code samples

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

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

url = '/margin/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /margin/accounts

Margin account list

Parameters

Name	In	Type	Required	Description
currency_pair	query	string	false	Currency pair

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» None	object	Margin account detail. base refers to base currency, while `quotes to quote currency
»» currency_pair	string	Currency pair
»» locked	boolean	Whether account is locked
»» risk	string	Current risk rate of margin account
»» base	object	Account currency details
»»» currency	string	Currency name
»»» available	string	Amount suitable for margin trading.
»»» locked	string	Locked amount, used in margin trading
»»» borrowed	string	Borrowed amount
»»» interest	string	Unpaid interests
»» quote	object	Account currency details
»»» currency	string	Currency name
»»» available	string	Amount suitable for margin trading.
»»» locked	string	Locked amount, used in margin trading
»»» borrowed	string	Borrowed amount
»»» interest	string	Unpaid interests

WARNING

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

List margin account balance change history

Code samples

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

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

url = '/margin/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /margin/account_book

List margin account balance change history

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

Parameters

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

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» id	string	Balance change record ID
» time	string	Balance changed timestamp
» time_ms	integer(int64)	The timestamp of the change (in milliseconds)
» currency	string	Currency changed
» currency_pair	string	Account currency pair
» change	string	Amount changed. Positive value means transferring in, while negative out
» balance	string	Balance after change

WARNING

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

Funding account list

Code samples

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

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

url = '/margin/funding_accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /margin/funding_accounts

Funding account list

Parameters

Name	In	Type	Required	Description
currency	query	string	false	Retrieve data of the specified currency

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

WARNING

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

Lend or borrow

Code samples

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

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

url = '/margin/loans'
query_param = ''
body='{"side":"borrow","currency":"BTC","rate":"0.002","amount":"1.5","days":10,"auto_renew":true,"currency_pair":"ETH_BTC","fee_rate":"0.18","orig_id":"123424","text":"t-abc"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

POST /margin/loans

Lend or borrow

Body parameter

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

Parameters

Name	In	Type	Required	Description
body	body	Loan	true	none
» side	body	string	true	Loan side
» currency	body	string	true	Loan currency
» rate	body	string	false	Loan rate. Only rates in [0.0002, 0.002] are supported.
» amount	body	string	true	Loan amount
» days	body	integer	false	Loan days. Only 10 is supported for now
» auto_renew	body	boolean	false	Whether to auto renew the loan upon expiration
» currency_pair	body	string	false	Currency pair. Required if borrowing
» fee_rate	body	string	false	Loan fee rate
» orig_id	body	string	false	Original loan ID of the loan if auto-renewed, otherwise equals to id
» text	body	string	false	User defined custom ID

Detailed descriptions

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

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

Enumerated Values

Parameter	Value
» side	lend
» side	borrow

Example responses

201 Response

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

Responses

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

WARNING

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

List all loans

Code samples

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

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

url = '/margin/loans'
query_param = 'status=open&side=lend'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

GET /margin/loans

List all loans

Parameters

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

Enumerated Values

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

Example responses

200 Response

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

Responses

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

WARNING

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

Merge multiple lending loans

Code samples

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

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

url = '/margin/merged_loans'
query_param = 'currency=BTC&ids=123,234,345'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

POST /margin/merged_loans

Merge multiple lending loans

Parameters

Name	In	Type	Required	Description
currency	query	string	true	Retrieve data of the specified currency
ids	query	string	true	A comma-separated (,) list of IDs of the loans lent. Maximum of 20 IDs are allowed in a request

Example responses

201 Response

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

Responses

Status	Meaning	Description	Schema
201	Created (opens new window)	Loans merged	Loan

WARNING

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

Retrieve one single loan detail

Code samples

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

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

url = '/margin/loans/12345'
query_param = 'side=lend'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

GET /margin/loans/{loan_id}

Retrieve one single loan detail

Parameters

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

Enumerated Values

Parameter	Value
side	lend
side	borrow

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	Loan

WARNING

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

Modify a loan

Code samples

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

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

url = '/margin/loans/12345'
query_param = ''
body='{"currency":"BTC","side":"borrow","currency_pair":"BTC_USDT","auto_renew":false}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PATCH', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

PATCH /margin/loans/{loan_id}

Modify a loan

Only auto_renew modification is supported currently

Body parameter

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

Parameters

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

Enumerated Values

Parameter	Value
» side	lend
» side	borrow

Example responses

200 Response

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

Responses

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

WARNING

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

Cancel lending loan

Code samples

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

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

url = '/margin/loans/12345'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

DELETE /margin/loans/{loan_id}

Cancel lending loan

Only lent loans can be cancelled

Parameters

Name	In	Type	Required	Description
currency	query	string	true	Retrieve data of the specified currency
loan_id	path	string	true	Loan ID

Example responses

200 Response

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

Responses

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

WARNING

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

Repay a loan

Code samples

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

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

url = '/margin/loans/12345/repayment'
query_param = ''
body='{"currency_pair":"ETH_BTC","currency":"ETH","mode":"partial","amount":"100"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

POST /margin/loans/{loan_id}/repayment

Repay a loan

Body parameter

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

Parameters

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

Enumerated Values

Parameter	Value
» mode	all
» mode	partial

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Loan repaid	Loan

WARNING

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

List loan repayment records

Code samples

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

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

url = '/margin/loans/12345/repayment'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /margin/loans/{loan_id}/repayment

List loan repayment records

Parameters

Name	In	Type	Required	Description
loan_id	path	string	true	Loan ID

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

WARNING

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

List repayment records of a specific loan

Code samples

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

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

url = '/margin/loan_records'
query_param = 'loan_id=12345'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

GET /margin/loan_records

List repayment records of a specific loan

Parameters

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

Enumerated Values

Parameter	Value
status	loaned
status	finished

Example responses

200 Response

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

Responses

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

WARNING

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

Get one single loan record

Code samples

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

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

url = '/margin/loan_records/12345'
query_param = 'loan_id=12345'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

GET /margin/loan_records/{loan_record_id}

Get one single loan record

Parameters

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

Example responses

200 Response

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

Responses

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

WARNING

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

Modify a loan record

Code samples

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

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

url = '/margin/loan_records/12345'
query_param = ''
body='{"currency":"BTC","side":"borrow","currency_pair":"BTC_USDT","auto_renew":false}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PATCH', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

PATCH /margin/loan_records/{loan_record_id}

Modify a loan record

Only auto_renew modification is supported currently

Body parameter

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

Parameters

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

Enumerated Values

Parameter	Value
» side	lend
» side	borrow

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Loan record updated	LoanRecord

WARNING

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

Update user's auto repayment setting

Code samples

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

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

url = '/margin/auto_repay'
query_param = 'status=on'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

POST /margin/auto_repay

Update user's auto repayment setting

Parameters

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

Example responses

200 Response

{
  "status": "on"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Current auto repayment setting	Inline

Response Schema

Status Code 200

AutoRepaySetting

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

Enumerated Values

Property	Value
status	on
status	off

WARNING

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

Retrieve user auto repayment setting

Code samples

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

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

url = '/margin/auto_repay'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /margin/auto_repay

Retrieve user auto repayment setting

Example responses

200 Response

{
  "status": "on"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Current auto repayment setting	Inline

Response Schema

Status Code 200

AutoRepaySetting

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

Enumerated Values

Property	Value
status	on
status	off

WARNING

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

Get the max transferable amount for a specific margin currency

Code samples

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

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

url = '/margin/transferable'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

GET /margin/transferable

Get the max transferable amount for a specific margin currency

Parameters

Name	In	Type	Required	Description
currency	query	string	true	Retrieve data of the specified currency
currency_pair	query	string	false	Currency pair

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

MarginTransferable

Name	Type	Description
» currency	string	Currency detail
» currency_pair	string	Currency pair
» amount	string	Max transferable amount

WARNING

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

Get the max borrowable amount for a specific margin currency

Code samples

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

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

url = '/margin/borrowable'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

GET /margin/borrowable

Get the max borrowable amount for a specific margin currency

Parameters

Name	In	Type	Required	Description
currency	query	string	true	Retrieve data of the specified currency
currency_pair	query	string	false	Currency pair

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

MarginBorrowable

Name	Type	Description
» currency	string	Currency detail
» currency_pair	string	Currency pair
» amount	string	Max borrowable amount

WARNING

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

Currencies supported by cross margin.

Code samples

# coding: utf-8
import requests

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

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

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

GET /margin/cross/currencies

Currencies supported by cross margin.

Example responses

200 Response

[
  {
    "name": "BTC",
    "rate": "0.0002",
    "prec": "0.000001",
    "discount": "1",
    "min_borrow_amount": "0.01",
    "user_max_borrow_amount": "1000000",
    "total_max_borrow_amount": "10000000",
    "price": "63015.5214",
    "status": 1
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» name	string	Currency name
» rate	string	Loan rate
» prec	string	Currency precision
» discount	string	Currency value discount, which is used in total value calculation
» min_borrow_amount	string	Minimum currency borrow amount. Unit is currency itself
» user_max_borrow_amount	string	Maximum borrow value allowed per user, in USDT
» total_max_borrow_amount	string	Maximum borrow value allowed for this currency, in USDT
» price	string	Price change between this currency and USDT
» status	integer	status - 0 : disable - 1 : enable

This operation does not require authentication

Retrieve detail of one single currency supported by cross margin

Code samples

# coding: utf-8
import requests

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

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

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

GET /margin/cross/currencies/{currency}

Retrieve detail of one single currency supported by cross margin

Parameters

Name	In	Type	Required	Description
currency	path	string	true	Currency name

Example responses

200 Response

{
  "name": "BTC",
  "rate": "0.0002",
  "prec": "0.000001",
  "discount": "1",
  "min_borrow_amount": "0.01",
  "user_max_borrow_amount": "1000000",
  "total_max_borrow_amount": "10000000",
  "price": "63015.5214",
  "status": 1
}

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» name	string	Currency name
» rate	string	Loan rate
» prec	string	Currency precision
» discount	string	Currency value discount, which is used in total value calculation
» min_borrow_amount	string	Minimum currency borrow amount. Unit is currency itself
» user_max_borrow_amount	string	Maximum borrow value allowed per user, in USDT
» total_max_borrow_amount	string	Maximum borrow value allowed for this currency, in USDT
» price	string	Price change between this currency and USDT
» status	integer	status - 0 : disable - 1 : enable

This operation does not require authentication

Retrieve cross margin account

Code samples

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

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

url = '/margin/cross/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /margin/cross/accounts

Retrieve cross margin account

Example responses

200 Response

{
  "user_id": 10001,
  "locked": false,
  "balances": {
    "ETH": {
      "available": "0",
      "freeze": "0",
      "borrowed": "0.075393666654",
      "interest": "0.0000106807603333"
    },
    "POINT": {
      "available": "9999999999.017023138734",
      "freeze": "0",
      "borrowed": "0",
      "interest": "0"
    },
    "USDT": {
      "available": "0.00000062023",
      "freeze": "0",
      "borrowed": "0",
      "interest": "0"
    }
  },
  "total": "230.94621713",
  "borrowed": "161.66395521",
  "interest": "0.02290237",
  "risk": "1.4284",
  "total_initial_margin": "1025.0524665088",
  "total_margin_balance": "3382495.944473949183",
  "total_maintenance_margin": "205.01049330176",
  "total_initial_margin_rate": "3299.827135672679",
  "total_maintenance_margin_rate": "16499.135678363399",
  "total_available_margin": "3381470.892007440383"
}

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
» locked	boolean	Whether account is locked
» balances	object	none
»» CrossMarginBalance	object	none
»»» available	string	Available amount
»»» freeze	string	Locked amount
»»» borrowed	string	Borrowed amount
»»» interest	string	Unpaid interests
»» total	string	Total account value in USDT, i.e., the sum of all currencies' (available+freeze)*price*discount
»» borrowed	string	Total borrowed value in USDT, i.e., the sum of all currencies' borrowed*price*discount
»» interest	string	Total unpaid interests in USDT, i.e., the sum of all currencies' interest*price*discount
»» risk	string	Risk rate. When it belows 110%, liquidation will be triggered. Calculation formula: total / (borrowed+interest)
»» total_initial_margin	string	Total initial margin
»» total_margin_balance	string	Total margin balance
»» total_maintenance_margin	string	Total maintenance margin
»» total_initial_margin_rate	string	Total initial margin rate
»» total_maintenance_margin_rate	string	Total maintenance margin rate
»» total_available_margin	string	Total available margin

WARNING

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

Retrieve cross margin account change history

Code samples

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

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

url = '/margin/cross/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /margin/cross/account_book

Retrieve cross margin account change history

Record time range cannot exceed 30 days

Parameters

Name	In	Type	Required	Description
currency	query	string	false	Filter by currency
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
limit	query	integer	false	Maximum number of records to be returned in a single list
type	query	string	false	Only retrieve changes of the specified type. All types will be returned if not specified.

Example responses

200 Response

[
  {
    "id": "123456",
    "time": 1547633726123,
    "currency": "BTC",
    "change": "1.03",
    "balance": "4.59316525194",
    "type": "in"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» id	string	Balance change record ID
» time	integer(int64)	The timestamp of the change (in milliseconds)
» currency	string	Currency changed
» change	string	Amount changed. Positive value means transferring in, while negative out
» balance	string	Balance after change
» type	string	Account change type, including: - in: transferals into cross margin account - out: transferals out from cross margin account - repay: loan repayment - borrow: borrowed loan - new_order: new order locked - order_fill: order fills - referral_fee: fee refund from referrals - order_fee: order fee generated from fills - unknown: unknown type

Enumerated Values

Property	Value
type	in
type	out
type	repay
type	borrow
type	new_order
type	order_fill
type	referral_fee
type	order_fee
type	unknown

WARNING

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

Create a cross margin borrow loan

Code samples

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

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

url = '/margin/cross/loans'
query_param = ''
body='{"currency":"EOS","amount":"110.553635","text":"web"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

POST /margin/cross/loans

Create a cross margin borrow loan

Borrow amount cannot be less than currency minimum borrow amount

Body parameter

{
  "currency": "EOS",
  "amount": "110.553635",
  "text": "web"
}

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» currency	body	string	true	Currency name
» amount	body	string	true	Borrowed amount
» text	body	string	false	User defined custom ID

Example responses

200 Response

{
  "id": "17",
  "create_time": 1620381696159,
  "update_time": 1620381696159,
  "currency": "EOS",
  "amount": "110.553635",
  "text": "web",
  "status": 2,
  "repaid": "110.506649705159",
  "repaid_interest": "0.046985294841",
  "unpaid_interest": "0.0000074393366667"
}

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» id	string	Borrow loan ID
» create_time	integer(int64)	Creation timestamp, in milliseconds
» update_time	integer(int64)	Update timestamp, in milliseconds
» currency	string	Currency name
» amount	string	Borrowed amount
» text	string	User defined custom ID
» status	integer(int32)	Borrow loan status, which includes: - 1: failed to borrow - 2: borrowed but not repaid - 3: repayment complete
» repaid	string	Repaid amount
» repaid_interest	string	Repaid interest
» unpaid_interest	string	Outstanding interest yet to be paid

Enumerated Values

Property	Value
status	1
status	2
status	3

WARNING

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

List cross margin borrow history

Code samples

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

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

url = '/margin/cross/loans'
query_param = 'status=0'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

GET /margin/cross/loans

List cross margin borrow history

Sort by creation time in descending order by default. Set reverse=false to return ascending results.

Parameters

Name	In	Type	Required	Description
status	query	integer	true	Filter by status. Supported values are 2 and 3.
currency	query	string	false	Filter by currency
limit	query	integer	false	Maximum number of records to be returned in a single list
offset	query	integer	false	List offset, starting from 0
reverse	query	boolean	false	Whether to sort in descending order, which is the default. Set reverse=false to return ascending results

Example responses

200 Response

[
  {
    "id": "17",
    "create_time": 1620381696159,
    "update_time": 1620381696159,
    "currency": "EOS",
    "amount": "110.553635",
    "text": "web",
    "status": 2,
    "repaid": "110.506649705159",
    "repaid_interest": "0.046985294841",
    "unpaid_interest": "0.0000074393366667"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» id	string	Borrow loan ID
» create_time	integer(int64)	Creation timestamp, in milliseconds
» update_time	integer(int64)	Update timestamp, in milliseconds
» currency	string	Currency name
» amount	string	Borrowed amount
» text	string	User defined custom ID
» status	integer(int32)	Borrow loan status, which includes: - 1: failed to borrow - 2: borrowed but not repaid - 3: repayment complete
» repaid	string	Repaid amount
» repaid_interest	string	Repaid interest
» unpaid_interest	string	Outstanding interest yet to be paid

Enumerated Values

Property	Value
status	1
status	2
status	3

WARNING

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

Retrieve single borrow loan detail

Code samples

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

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

url = '/margin/cross/loans/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /margin/cross/loans/{loan_id}

Retrieve single borrow loan detail

Parameters

Name	In	Type	Required	Description
loan_id	path	string	true	Borrow loan ID

Example responses

200 Response

{
  "id": "17",
  "create_time": 1620381696159,
  "update_time": 1620381696159,
  "currency": "EOS",
  "amount": "110.553635",
  "text": "web",
  "status": 2,
  "repaid": "110.506649705159",
  "repaid_interest": "0.046985294841",
  "unpaid_interest": "0.0000074393366667"
}

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» id	string	Borrow loan ID
» create_time	integer(int64)	Creation timestamp, in milliseconds
» update_time	integer(int64)	Update timestamp, in milliseconds
» currency	string	Currency name
» amount	string	Borrowed amount
» text	string	User defined custom ID
» status	integer(int32)	Borrow loan status, which includes: - 1: failed to borrow - 2: borrowed but not repaid - 3: repayment complete
» repaid	string	Repaid amount
» repaid_interest	string	Repaid interest
» unpaid_interest	string	Outstanding interest yet to be paid

Enumerated Values

Property	Value
status	1
status	2
status	3

WARNING

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

When the liquidity of the currency is insufficient and the transaction risk is high, the currency will be disabled, and funds cannot be transferred.When the available balance of cross-margin is insufficient, the balance of the spot account can be used for repayment. Please ensure that the balance of the spot account is sufficient, and system uses cross-margin account for repayment first

Code samples

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

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

url = '/margin/cross/repayments'
query_param = ''
body='{"currency":"EOS","amount":"110.553635"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

POST /margin/cross/repayments

When the liquidity of the currency is insufficient and the transaction risk is high, the currency will be disabled, and funds cannot be transferred.When the available balance of cross-margin is insufficient, the balance of the spot account can be used for repayment. Please ensure that the balance of the spot account is sufficient, and system uses cross-margin account for repayment first

Body parameter

{
  "currency": "EOS",
  "amount": "110.553635"
}

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» currency	body	string	true	Repayment currency
» amount	body	string	true	Repayment amount

Example responses

200 Response

[
  {
    "id": "17",
    "create_time": 1620381696159,
    "update_time": 1620381696159,
    "currency": "EOS",
    "amount": "110.553635",
    "text": "web",
    "status": 2,
    "repaid": "110.506649705159",
    "repaid_interest": "0.046985294841",
    "unpaid_interest": "0.0000074393366667"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Loan repaid	[Inline]

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» id	string	Borrow loan ID
» create_time	integer(int64)	Creation timestamp, in milliseconds
» update_time	integer(int64)	Update timestamp, in milliseconds
» currency	string	Currency name
» amount	string	Borrowed amount
» text	string	User defined custom ID
» status	integer(int32)	Borrow loan status, which includes: - 1: failed to borrow - 2: borrowed but not repaid - 3: repayment complete
» repaid	string	Repaid amount
» repaid_interest	string	Repaid interest
» unpaid_interest	string	Outstanding interest yet to be paid

Enumerated Values

Property	Value
status	1
status	2
status	3

WARNING

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

Retrieve cross margin repayments

Code samples

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

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

url = '/margin/cross/repayments'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /margin/cross/repayments

Retrieve cross margin repayments

Sort by creation time in descending order by default. Set reverse=false to return ascending results.

Parameters

Name	In	Type	Required	Description
currency	query	string	false	none
loan_id	query	string	false	none
limit	query	integer	false	Maximum number of records to be returned in a single list
offset	query	integer	false	List offset, starting from 0
reverse	query	boolean	false	Whether to sort in descending order, which is the default. Set reverse=false to return ascending results

Example responses

200 Response

[
  {
    "id": "51",
    "create_time": 1620696347990,
    "loan_id": "30",
    "currency": "BTC",
    "principal": "5.385542",
    "interest": "0.000044879516"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» id	string	Loan record ID
» create_time	integer(int64)	Repayment time
» loan_id	string	Borrow loan ID
» currency	string	Currency name
» principal	string	Repaid principal
» interest	string	Repaid interest

WARNING

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

Get the max transferable amount for a specific cross margin currency

Code samples

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

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

url = '/margin/cross/transferable'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

GET /margin/cross/transferable

Get the max transferable amount for a specific cross margin currency

Parameters

Name	In	Type	Required	Description
currency	query	string	true	Retrieve data of the specified currency

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

CrossMarginTransferable

Name	Type	Description
» currency	string	Currency detail
» amount	string	Max transferable amount

WARNING

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

Get the max borrowable amount for a specific cross margin currency

Code samples

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

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

url = '/margin/cross/borrowable'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

GET /margin/cross/borrowable

Get the max borrowable amount for a specific cross margin currency

Parameters

Name	In	Type	Required	Description
currency	query	string	true	Retrieve data of the specified currency

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

CrossMarginBorrowable

Name	Type	Description
» currency	string	Currency detail
» amount	string	Max borrowable amount

WARNING

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

Flash_swap

Flash swap

List all supported currencies in flash swap

Code samples

# coding: utf-8
import requests

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

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

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

GET /flash_swap/currencies

List all supported currencies in flash swap

Example responses

200 Response

[
  {
    "currency": "BTC",
    "min_amount": "0.000001",
    "max_amount": "1.000000",
    "swappable": [
      "USDT",
      "GT",
      "ETH"
    ]
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» None	object	Currencies supported in flash swap
»» currency	string	Currency name
»» min_amount	string	Minimum amount required in flash swap
»» max_amount	string	Maximum amount allowed in flash swap
»» swappable	array	Currencies which can be swapped to from this currency

This operation does not require authentication

Create a flash swap order

Code samples

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

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

url = '/flash_swap/orders'
query_param = ''
body='{"preview_id":"4564564","sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT","buy_amount":"10"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/flash_swap/orders"
query_param=""
body_param='{"preview_id":"4564564","sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT","buy_amount":"10"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /flash_swap/orders

Create a flash swap order

Initiate a flash swap preview in advance because order creation requires a preview result

Body parameter

{
  "preview_id": "4564564",
  "sell_currency": "BTC",
  "sell_amount": "0.1",
  "buy_currency": "USDT",
  "buy_amount": "10"
}

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» preview_id	body	string	false	Preview result ID
» sell_currency	body	string	true	Currency to sell which can be retrieved from supported currency list API GET /flash_swap/currencies
» sell_amount	body	string	false	Amount to sell.
» buy_currency	body	string	true	Currency to buy which can be retrieved from supported currency list API GET /flash_swap/currencies
» buy_amount	body	string	false	Amount to buy.

Detailed descriptions

» sell_amount: Amount to sell. It is required to choose one parameter between sell_amount and buy_amount

» buy_amount: Amount to buy. It is required to choose one parameter between sell_amount and buy_amount

Example responses

201 Response

{
  "id": 54646,
  "create_time": 1651116876378,
  "update_time": 1651116876378,
  "user_id": 11135567,
  "sell_currency": "BTC",
  "sell_amount": "0.01",
  "buy_currency": "USDT",
  "buy_amount": "10",
  "price": "100",
  "status": 1
}

Responses

Status	Meaning	Description	Schema
201	Created (opens new window)	The flash swap order is created successfully	Inline

Response Schema

Status Code 201

Flash swap order

Name	Type	Description
» id	integer(int64)	Flash swap order ID
» create_time	integer(int64)	Creation time of order (in milliseconds)
» user_id	integer(int64)	User ID
» sell_currency	string	Currency to sell
» sell_amount	string	Amount to sell
» buy_currency	string	Currency to buy
» buy_amount	string	Amount to buy
» price	string	Price
» status	integer	Flash swap order status 1 - success 2 - failure

WARNING

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

List all flash swap orders

Code samples

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

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

url = '/flash_swap/orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /flash_swap/orders

List all flash swap orders

Parameters

Name	In	Type	Required	Description
status	query	integer	false	Flash swap order status
sell_currency	query	string	false	Currency to sell which can be retrieved from supported currency list API GET /flash_swap/currencies
buy_currency	query	string	false	Currency to buy which can be retrieved from supported currency list API GET /flash_swap/currencies
reverse	query	boolean	false	If results are sorted by id in reverse order. Default to true
limit	query	integer	false	Maximum number of records to be returned in a single list
page	query	integer	false	Page number

Detailed descriptions

status: Flash swap order status

1 - success 2 - failure

reverse: If results are sorted by id in reverse order. Default to true

• true: sort by id in descending order(recent first)
• false: sort by id in ascending order(oldest first)

Example responses

200 Response

[
  {
    "id": 54646,
    "create_time": 1651116876378,
    "update_time": 1651116876378,
    "user_id": 11135567,
    "sell_currency": "BTC",
    "sell_amount": "0.01",
    "buy_currency": "USDT",
    "buy_amount": "10",
    "price": "100",
    "status": 1
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	[Flash swap order]
» None	object	Flash swap order
»» id	integer(int64)	Flash swap order ID
»» create_time	integer(int64)	Creation time of order (in milliseconds)
»» user_id	integer(int64)	User ID
»» sell_currency	string	Currency to sell
»» sell_amount	string	Amount to sell
»» buy_currency	string	Currency to buy
»» buy_amount	string	Amount to buy
»» price	string	Price
»» status	integer	Flash swap order status 1 - success 2 - failure

WARNING

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

Get a single flash swap order's detail

Code samples

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

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

url = '/flash_swap/orders/1'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /flash_swap/orders/{order_id}

Get a single flash swap order's detail

Parameters

Name	In	Type	Required	Description
order_id	path	integer	true	Flash swap order ID

Example responses

200 Response

{
  "id": 54646,
  "create_time": 1651116876378,
  "update_time": 1651116876378,
  "user_id": 11135567,
  "sell_currency": "BTC",
  "sell_amount": "0.01",
  "buy_currency": "USDT",
  "buy_amount": "10",
  "price": "100",
  "status": 1
}

Responses

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

Response Schema

Status Code 200

Flash swap order

Name	Type	Description
» id	integer(int64)	Flash swap order ID
» create_time	integer(int64)	Creation time of order (in milliseconds)
» user_id	integer(int64)	User ID
» sell_currency	string	Currency to sell
» sell_amount	string	Amount to sell
» buy_currency	string	Currency to buy
» buy_amount	string	Amount to buy
» price	string	Price
» status	integer	Flash swap order status 1 - success 2 - failure

WARNING

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

Initiate a flash swap order preview

Code samples

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

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

url = '/flash_swap/orders/preview'
query_param = ''
body='{"preview_id":"4564564","sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT","buy_amount":"10"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/flash_swap/orders/preview"
query_param=""
body_param='{"preview_id":"4564564","sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT","buy_amount":"10"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /flash_swap/orders/preview

Initiate a flash swap order preview

Body parameter

{
  "preview_id": "4564564",
  "sell_currency": "BTC",
  "sell_amount": "0.1",
  "buy_currency": "USDT",
  "buy_amount": "10"
}

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» preview_id	body	string	false	Preview result ID
» sell_currency	body	string	true	Currency to sell which can be retrieved from supported currency list API GET /flash_swap/currencies
» sell_amount	body	string	false	Amount to sell.
» buy_currency	body	string	true	Currency to buy which can be retrieved from supported currency list API GET /flash_swap/currencies
» buy_amount	body	string	false	Amount to buy.

Detailed descriptions

» sell_amount: Amount to sell. It is required to choose one parameter between sell_amount and buy_amount

» buy_amount: Amount to buy. It is required to choose one parameter between sell_amount and buy_amount

Example responses

200 Response

{
  "preview_id": "3453434",
  "sell_currency": "BTC",
  "sell_amount": "0.1",
  "buy_currency": "USDT",
  "buy_amount": "10",
  "price": "100"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	The flash swap order successfully previewed	Inline

Response Schema

Status Code 200

Initiate a flash swap order preview

Name	Type	Description
» preview_id	string	Preview result ID
» sell_currency	string	Currency to sell which can be retrieved from supported currency list API GET /flash_swap/currencies
» sell_amount	string	Amount to sell
» buy_currency	string	Currency to buy which can be retrieved from supported currency list API GET /flash_swap/currencies
» buy_amount	string	Amount to buy
» price	string	Price

WARNING

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

Futures

Futures contract API

List all futures contracts

Code samples

# coding: utf-8
import requests

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

url = '/futures/usdt/contracts'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/futures/usdt/contracts \
  -H 'Accept: application/json'

GET /futures/{settle}/contracts

List all futures contracts

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

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

Responses

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

This operation does not require authentication

Get a single contract

Code samples

# coding: utf-8
import requests

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

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

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

GET /futures/{settle}/contracts/{contract}

Get a single contract

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Contract information	Contract

This operation does not require authentication

Futures order book

Code samples

# coding: utf-8
import requests

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

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

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

GET /futures/{settle}/order_book

Futures order book

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

Parameters

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

Enumerated Values

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

Example responses

200 Response

{
  "id": 123456,
  "current": 1623898993.123,
  "update": 1623898993.121,
  "asks": [
    {
      "p": "1.52",
      "s": 100
    },
    {
      "p": "1.53",
      "s": 40
    }
  ],
  "bids": [
    {
      "p": "1.17",
      "s": 150
    },
    {
      "p": "1.16",
      "s": 203
    }
  ]
}

Responses

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

Response Schema

Status Code 200

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

This operation does not require authentication

Futures trading history

Code samples

# coding: utf-8
import requests

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

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

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

GET /futures/{settle}/trades

Futures trading history

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	true	Futures contract
limit	query	integer	false	Maximum number of records to be returned in a single list
last_id	query	string	false	Specify the starting point for this list based on a previously retrieved id
from	query	integer(int64)	false	Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items.
to	query	integer(int64)	false	Specify end time in Unix seconds, default to current time

Detailed descriptions

last_id: Specify the starting point for this list based on a previously retrieved id

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

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

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

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	integer(int64)	Trade ID
» create_time	number(double)	Trading time
» create_time_ms	number(double)	Trading time, with milliseconds set to 3 decimal places.
» contract	string	Futures contract
» size	integer(int64)	Trading size
» price	string	Trading price

This operation does not require authentication

Get futures candlesticks

Code samples

# coding: utf-8
import requests

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

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

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

GET /futures/{settle}/candlesticks

Get futures candlesticks

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

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

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	true	Futures contract
from	query	integer(int64)	false	Start time of candlesticks, formatted in Unix timestamp in seconds.
to	query	integer(int64)	false	End time of candlesticks, formatted in Unix timestamp in seconds. Default to current time
limit	query	integer	false	Maximum recent data points to return. limit is conflicted with from and to. If either from or to is specified, request will be rejected.
interval	query	string	false	Interval time between data points. Note that 1w means natual week(Mon-Sun), while 7d means every 7d since unix 0

Detailed descriptions

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd
interval	10s
interval	30s
interval	1m
interval	5m
interval	15m
interval	30m
interval	1h
interval	2h
interval	4h
interval	6h
interval	8h
interval	12h
interval	1d
interval	7d
interval	1w
interval	30d

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

This operation does not require authentication

List futures tickers

Code samples

# coding: utf-8
import requests

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

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

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

GET /futures/{settle}/tickers

List futures tickers

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

This operation does not require authentication

Funding rate history

Code samples

# coding: utf-8
import requests

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

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

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

GET /futures/{settle}/funding_rate

Funding rate history

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

This operation does not require authentication

Futures insurance balance history

Code samples

# coding: utf-8
import requests

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

url = '/futures/usdt/insurance'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/futures/usdt/insurance \
  -H 'Accept: application/json'

GET /futures/{settle}/insurance

Futures insurance balance history

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

This operation does not require authentication

Futures stats

Code samples

# coding: utf-8
import requests

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

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

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

GET /futures/{settle}/contract_stats

Futures stats

Parameters

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

Enumerated Values

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

Example responses

200 Response

[
  {
    "time": 1603865400,
    "lsr_taker": 100,
    "lsr_account": 0.5,
    "long_liq_size": 0,
    "short_liq_size": 0,
    "open_interest": 124724,
    "short_liq_usd": 0,
    "mark_price": "8865",
    "top_lsr_size": 1.02,
    "short_liq_amount": 0,
    "long_liq_amount": 0,
    "open_interest_usd": 1511,
    "top_lsr_account": 1.5,
    "long_liq_usd": 0
  }
]

Responses

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

Response Schema

Status Code 200

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

This operation does not require authentication

Get index constituents

Code samples

# coding: utf-8
import requests

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

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

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

GET /futures/{settle}/index_constituents/{index}

Get index constituents

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
index	path	string	true	Index name

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

{
  "index": "BTC_USDT",
  "constituents": [
    {
      "exchange": "Binance",
      "symbols": [
        "BTC_USDT"
      ]
    },
    {
      "exchange": "Gate.io",
      "symbols": [
        "BTC_USDT"
      ]
    },
    {
      "exchange": "Huobi",
      "symbols": [
        "BTC_USDT"
      ]
    }
  ]
}

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» index	string	Index name
» constituents	array	Constituents
»» IndexConstituent	object	none
»»» exchange	string	Exchange
»»» symbols	array	Symbol list

This operation does not require authentication

Retrieve liquidation history

Code samples

# coding: utf-8
import requests

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

url = '/futures/usdt/liq_orders'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/futures/usdt/liq_orders \
  -H 'Accept: application/json'

GET /futures/{settle}/liq_orders

Retrieve liquidation history

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

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

[
  {
    "time": 1548654951,
    "contract": "BTC_USDT",
    "size": 600,
    "leverage": "25",
    "margin": "0.006705256878",
    "entry_price": "3536.123",
    "liq_price": "3421.54",
    "mark_price": "3420.27",
    "order_id": 317393847,
    "order_price": "3405",
    "fill_price": "3424",
    "left": 0
  }
]

Responses

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

Response Schema

Status Code 200

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

This operation does not require authentication

Query futures account

Code samples

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

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

url = '/futures/usdt/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /futures/{settle}/accounts

Query futures account

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

{
  "user": 1666,
  "currency": "USDT",
  "total": "9707.803567115145",
  "unrealised_pnl": "3371.248828",
  "position_margin": "38.712189181",
  "order_margin": "0",
  "available": "9669.091377934145",
  "point": "0",
  "bonus": "0",
  "in_dual_mode": false,
  "history": {
    "dnw": "10000",
    "pnl": "68.3685",
    "fee": "-1.645812875",
    "refr": "0",
    "fund": "-358.919120009855",
    "point_dnw": "0",
    "point_fee": "0",
    "point_refr": "0",
    "bonus_dnw": "0",
    "bonus_offset": "0"
  }
}

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» total	string	total = position_margin + order_margin + available
» unrealised_pnl	string	Unrealized PNL
» position_margin	string	Position margin
» order_margin	string	Order margin of unfinished orders
» available	string	The available balance for transferring or trading
» point	string	POINT amount
» currency	string	Settle currency
» in_dual_mode	boolean	Whether dual mode is enabled
» enable_credit	boolean	Whether portfolio margin account mode is enabled
» position_initial_margin	string	Initial margin position, applicable to the portfolio margin account model
» maintenance_margin	string	Maintenance margin position, applicable to the portfolio margin account model
» bonus	string	Perpetual Contract Bonus
» history	object	Statistical data
»» dnw	string	total amount of deposit and withdraw
»» pnl	string	total amount of trading profit and loss
»» fee	string	total amount of fee
»» refr	string	total amount of referrer rebates
»» fund	string	total amount of funding costs
»» point_dnw	string	total amount of point deposit and withdraw
»» point_fee	string	total amount of point fee
»» point_refr	string	total amount of referrer rebates of point fee
»» bonus_dnw	string	total amount of perpetual contract bonus transfer
»» bonus_offset	string	total amount of perpetual contract bonus deduction

WARNING

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

Query account book

Code samples

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

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

url = '/futures/usdt/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /futures/{settle}/account_book

Query account book

Parameters

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

Detailed descriptions

type: Changing Type:

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

Enumerated Values

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

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

Enumerated Values

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

WARNING

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

List all positions of a user

Code samples

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

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

url = '/futures/usdt/positions'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /futures/{settle}/positions

List all positions of a user

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

[
  {
    "user": 10000,
    "contract": "BTC_USDT",
    "size": -9440,
    "leverage": "0",
    "risk_limit": "100",
    "leverage_max": "100",
    "maintenance_rate": "0.005",
    "value": "2.497143098997",
    "margin": "4.431548146258",
    "entry_price": "3779.55",
    "liq_price": "99999999",
    "mark_price": "3780.32",
    "unrealised_pnl": "-0.000507486844",
    "realised_pnl": "0.045543982432",
    "history_pnl": "0",
    "last_close_pnl": "0",
    "realised_point": "0",
    "history_point": "0",
    "adl_ranking": 5,
    "pending_orders": 16,
    "close_order": {
      "id": 232323,
      "price": "3779",
      "is_liq": false
    },
    "mode": "single",
    "cross_leverage_limit": "0"
  }
]

Responses

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

WARNING

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

Get single position

Code samples

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

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

url = '/futures/usdt/positions/BTC_USDT'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /futures/{settle}/positions/{contract}

Get single position

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

{
  "user": 10000,
  "contract": "BTC_USDT",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  },
  "mode": "single",
  "cross_leverage_limit": "0"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Position information	Position

WARNING

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

Update position margin

Code samples

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

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

url = '/futures/usdt/positions/BTC_USDT/margin'
query_param = 'change=0.01'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

POST /futures/{settle}/positions/{contract}/margin

Update position margin

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

{
  "user": 10000,
  "contract": "BTC_USDT",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  },
  "mode": "single",
  "cross_leverage_limit": "0"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Position information	Position

WARNING

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

Update position leverage

Code samples

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

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

url = '/futures/usdt/positions/BTC_USDT/leverage'
query_param = 'leverage=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

POST /futures/{settle}/positions/{contract}/leverage

Update position leverage

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	path	string	true	Futures contract
leverage	query	string	true	New position leverage
cross_leverage_limit	query	string	false	Cross margin leverage(valid only when leverage is 0)

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

{
  "user": 10000,
  "contract": "BTC_USDT",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  },
  "mode": "single",
  "cross_leverage_limit": "0"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Position information	Position

WARNING

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

Update position risk limit

Code samples

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

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

url = '/futures/usdt/positions/BTC_USDT/risk_limit'
query_param = 'risk_limit=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

POST /futures/{settle}/positions/{contract}/risk_limit

Update position risk limit

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

{
  "user": 10000,
  "contract": "BTC_USDT",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  },
  "mode": "single",
  "cross_leverage_limit": "0"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Position information	Position

WARNING

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

Enable or disable dual mode

Code samples

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

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

url = '/futures/usdt/dual_mode'
query_param = 'dual_mode=true'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

POST /futures/{settle}/dual_mode

Enable or disable dual mode

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

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

{
  "user": 1666,
  "currency": "USDT",
  "total": "9707.803567115145",
  "unrealised_pnl": "3371.248828",
  "position_margin": "38.712189181",
  "order_margin": "0",
  "available": "9669.091377934145",
  "point": "0",
  "bonus": "0",
  "in_dual_mode": false,
  "history": {
    "dnw": "10000",
    "pnl": "68.3685",
    "fee": "-1.645812875",
    "refr": "0",
    "fund": "-358.919120009855",
    "point_dnw": "0",
    "point_fee": "0",
    "point_refr": "0",
    "bonus_dnw": "0",
    "bonus_offset": "0"
  }
}

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» total	string	total = position_margin + order_margin + available
» unrealised_pnl	string	Unrealized PNL
» position_margin	string	Position margin
» order_margin	string	Order margin of unfinished orders
» available	string	The available balance for transferring or trading
» point	string	POINT amount
» currency	string	Settle currency
» in_dual_mode	boolean	Whether dual mode is enabled
» enable_credit	boolean	Whether portfolio margin account mode is enabled
» position_initial_margin	string	Initial margin position, applicable to the portfolio margin account model
» maintenance_margin	string	Maintenance margin position, applicable to the portfolio margin account model
» bonus	string	Perpetual Contract Bonus
» history	object	Statistical data
»» dnw	string	total amount of deposit and withdraw
»» pnl	string	total amount of trading profit and loss
»» fee	string	total amount of fee
»» refr	string	total amount of referrer rebates
»» fund	string	total amount of funding costs
»» point_dnw	string	total amount of point deposit and withdraw
»» point_fee	string	total amount of point fee
»» point_refr	string	total amount of referrer rebates of point fee
»» bonus_dnw	string	total amount of perpetual contract bonus transfer
»» bonus_offset	string	total amount of perpetual contract bonus deduction

WARNING

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

Retrieve position detail in dual mode

Code samples

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

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

url = '/futures/usdt/dual_comp/positions/BTC_USDT'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /futures/{settle}/dual_comp/positions/{contract}

Retrieve position detail in dual mode

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

[
  {
    "user": 10000,
    "contract": "BTC_USDT",
    "size": -9440,
    "leverage": "0",
    "risk_limit": "100",
    "leverage_max": "100",
    "maintenance_rate": "0.005",
    "value": "2.497143098997",
    "margin": "4.431548146258",
    "entry_price": "3779.55",
    "liq_price": "99999999",
    "mark_price": "3780.32",
    "unrealised_pnl": "-0.000507486844",
    "realised_pnl": "0.045543982432",
    "history_pnl": "0",
    "last_close_pnl": "0",
    "realised_point": "0",
    "history_point": "0",
    "adl_ranking": 5,
    "pending_orders": 16,
    "close_order": {
      "id": 232323,
      "price": "3779",
      "is_liq": false
    },
    "mode": "single",
    "cross_leverage_limit": "0"
  }
]

Responses

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

WARNING

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

Update position margin in dual mode

Code samples

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

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

url = '/futures/usdt/dual_comp/positions/BTC_USDT/margin'
query_param = 'change=0.01&dual_side=dual_long'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

POST /futures/{settle}/dual_comp/positions/{contract}/margin

Update position margin in dual mode

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd
dual_side	dual_long
dual_side	dual_short

Example responses

200 Response

[
  {
    "user": 10000,
    "contract": "BTC_USDT",
    "size": -9440,
    "leverage": "0",
    "risk_limit": "100",
    "leverage_max": "100",
    "maintenance_rate": "0.005",
    "value": "2.497143098997",
    "margin": "4.431548146258",
    "entry_price": "3779.55",
    "liq_price": "99999999",
    "mark_price": "3780.32",
    "unrealised_pnl": "-0.000507486844",
    "realised_pnl": "0.045543982432",
    "history_pnl": "0",
    "last_close_pnl": "0",
    "realised_point": "0",
    "history_point": "0",
    "adl_ranking": 5,
    "pending_orders": 16,
    "close_order": {
      "id": 232323,
      "price": "3779",
      "is_liq": false
    },
    "mode": "single",
    "cross_leverage_limit": "0"
  }
]

Responses

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

WARNING

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

Update position leverage in dual mode

Code samples

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

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

url = '/futures/usdt/dual_comp/positions/BTC_USDT/leverage'
query_param = 'leverage=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

POST /futures/{settle}/dual_comp/positions/{contract}/leverage

Update position leverage in dual mode

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	path	string	true	Futures contract
leverage	query	string	true	New position leverage
cross_leverage_limit	query	string	false	Cross margin leverage(valid only when leverage is 0)

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

[
  {
    "user": 10000,
    "contract": "BTC_USDT",
    "size": -9440,
    "leverage": "0",
    "risk_limit": "100",
    "leverage_max": "100",
    "maintenance_rate": "0.005",
    "value": "2.497143098997",
    "margin": "4.431548146258",
    "entry_price": "3779.55",
    "liq_price": "99999999",
    "mark_price": "3780.32",
    "unrealised_pnl": "-0.000507486844",
    "realised_pnl": "0.045543982432",
    "history_pnl": "0",
    "last_close_pnl": "0",
    "realised_point": "0",
    "history_point": "0",
    "adl_ranking": 5,
    "pending_orders": 16,
    "close_order": {
      "id": 232323,
      "price": "3779",
      "is_liq": false
    },
    "mode": "single",
    "cross_leverage_limit": "0"
  }
]

Responses

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

WARNING

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

Update position risk limit in dual mode

Code samples

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

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

url = '/futures/usdt/dual_comp/positions/BTC_USDT/risk_limit'
query_param = 'risk_limit=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

POST /futures/{settle}/dual_comp/positions/{contract}/risk_limit

Update position risk limit in dual mode

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

[
  {
    "user": 10000,
    "contract": "BTC_USDT",
    "size": -9440,
    "leverage": "0",
    "risk_limit": "100",
    "leverage_max": "100",
    "maintenance_rate": "0.005",
    "value": "2.497143098997",
    "margin": "4.431548146258",
    "entry_price": "3779.55",
    "liq_price": "99999999",
    "mark_price": "3780.32",
    "unrealised_pnl": "-0.000507486844",
    "realised_pnl": "0.045543982432",
    "history_pnl": "0",
    "last_close_pnl": "0",
    "realised_point": "0",
    "history_point": "0",
    "adl_ranking": 5,
    "pending_orders": 16,
    "close_order": {
      "id": 232323,
      "price": "3779",
      "is_liq": false
    },
    "mode": "single",
    "cross_leverage_limit": "0"
  }
]

Responses

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

WARNING

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

Create a futures order

Code samples

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

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

url = '/futures/usdt/orders'
query_param = ''
body='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

POST /futures/{settle}/orders

Create a futures order

• Creating futures orders requires size, which is number of contracts instead of currency amount. You can use quanto_multiplier in contract detail response to know how much currency 1 size contract represents
• Zero-filled order cannot be retrieved 10 minutes after order cancellation. You will get a 404 not found for such orders
• Set reduce_only to true can keep the position from changing side when reducing position size
• In single position mode, to close a position, you need to set size to 0 and close to true
• In dual position mode, to close one side position, you need to set auto_size side, reduce_only to true and size to 0

Body parameter

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

Parameters

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

Detailed descriptions

» tif: Time in force

• gtc: GoodTillCancelled
• ioc: ImmediateOrCancelled, taker only
• poc: PendingOrCancelled, reduce-only
• fok: FillOrKill, fill either completely or none

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

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

• web: from web
• api: from API
• app: from mobile phones
• auto_deleveraging: from ADL
• liquidation: from liquidation
• insurance: from insurance

Enumerated Values

Parameter	Value
» tif	gtc
» tif	ioc
» tif	poc
» tif	fok
» auto_size	close_long
» auto_size	close_short
settle	btc
settle	usdt
settle	usd

Example responses

201 Response

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

Responses

Status	Meaning	Description	Schema
201	Created (opens new window)	Order details	FuturesOrder

WARNING

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

List futures orders

Code samples

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

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

url = '/futures/usdt/orders'
query_param = 'contract=BTC_USDT&status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

GET /futures/{settle}/orders

List futures orders

Zero-filled order cannot be retrieved 10 minutes after order cancellation

Parameters

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

Enumerated Values

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

Example responses

200 Response

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

Responses

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

Response Headers

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

WARNING

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

Cancel all open orders matched

Code samples

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

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

url = '/futures/usdt/orders'
query_param = 'contract=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

DELETE /futures/{settle}/orders

Cancel all open orders matched

Zero-filled order cannot be retrieved 10 minutes after order cancellation

Parameters

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

Enumerated Values

Parameter	Value
side	ask
side	bid
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	All orders matched cancelled	[FuturesOrder]

WARNING

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

Create a batch of futures orders

Code samples

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

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

url = '/futures/usdt/batch_orders'
query_param = ''
body='[{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

POST /futures/{settle}/batch_orders

Create a batch of futures orders

• Up to 10 orders per request
• If any of the order's parameters are missing or in the wrong format, all of them will not be executed, and a http status 400 error will be returned directly
• If the parameters are checked and passed, all are executed. Even if there is a business logic error in the middle (such as insufficient funds), it will not affect other execution orders
• The returned result is in array format, and the order corresponds to the orders in the request body
• In the returned result, the succeeded field of type bool indicates whether the execution was successful or not
• If the execution is successful, the normal order content is included; if the execution fails, the label field is included to indicate the cause of the error
• In the rate limiting, each order is counted individually

Body parameter

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

Parameters

Name	In	Type	Required	Description
body	body	array[object]	true	none
settle	path	string	true	Settle currency

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Request is completed	[Inline]

Response Schema

Status Code 200

Name	Type	Description
» None	object	Futures order details
»» succeeded	boolean	Whether the batch of orders succeeded
»» label	string	Error label, only exists if execution fails
»» detail	string	Error detail, only present if execution failed and details need to be given
»» id	integer(int64)	Futures order ID
»» user	integer	User ID
»» create_time	number(double)	Creation time of order
»» finish_time	number(double)	Order finished time. Not returned if order is open
»» finish_as	string	How the order was finished. - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC, finish immediately - auto_deleveraged: finished by ADL - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because of position close
»» status	string	Order status - open: waiting to be traded - finished: finished
»» contract	string	Futures contract
»» size	integer(int64)	Order size. Specify positive number to make a bid, and negative number to ask
»» iceberg	integer(int64)	Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size
»» price	string	Order price. 0 for market order with tif set as ioc
»» is_close	boolean	Is the order to close position
»» is_reduce_only	boolean	Is the order reduce-only
»» is_liq	boolean	Is the order for liquidation
»» tif	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, reduce-only - fok: FillOrKill, fill either completely or none
»» left	integer(int64)	Size left to be traded
»» fill_price	string	Fill price of the order
»» 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: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance
»» tkfr	string	Taker fee
»» mkfr	string	Maker fee
»» refu	integer	Reference user ID

Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok

WARNING

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /futures/{settle}/orders/{order_id}

Get a single order

Zero-filled order cannot be retrieved 10 minutes after order cancellation

Parameters

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

Detailed descriptions

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

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

Responses

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

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

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

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

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

Cancel a single order

Parameters

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

Detailed descriptions

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

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

Responses

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

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/orders/12345'
query_param = ''
body='{"size":100,"price":"54321"}'
# 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.ws"
prefix="/api/v4"
method="PUT"
url="/futures/usdt/orders/12345"
query_param=""
body_param='{"size":100,"price":"54321"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

PUT /futures/{settle}/orders/{order_id}

Amend an order

Body parameter

{
  "size": 100,
  "price": "54321"
}

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» size	body	integer(int64)	false	New order size, including filled part.
» price	body	string	false	New order price.
settle	path	string	true	Settle currency
order_id	path	string	true	Order ID returned, or user custom ID(i.e., text field).

Detailed descriptions

» size: New order size, including filled part.

• If new size is less than or equal to filled size, the order will be cancelled.
• Order side must be identical to the original one.
• Close order size cannot be changed.
• For reduce only orders, increasing size may leads to other reduce only orders being cancelled.
• If price is not changed, decreasing size will not change its precedence in order book, while increasing will move it to the last at current price.

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

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

Responses

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

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/my_trades'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /futures/{settle}/my_trades

List personal trading history

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd
count_total	0
count_total	1

Example responses

200 Response

[
  {
    "id": 121234231,
    "create_time": 1514764800.123,
    "contract": "BTC_USDT",
    "order_id": "21893289839",
    "size": 100,
    "price": "100.123",
    "text": "t-123456",
    "fee": "0.01",
    "point_fee": "0",
    "role": "taker"
  }
]

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	integer(int64)	Trade ID
» create_time	number(double)	Trading time
» contract	string	Futures contract
» order_id	string	Order ID related
» size	integer(int64)	Trading size
» price	string	Trading price
» role	string	Trade role. Available values are taker and maker
» text	string	User defined information
» fee	string	Fee deducted
» point_fee	string	Points used to deduct fee

Enumerated Values

Property	Value
role	taker
role	maker

Response Headers

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

WARNING

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

List position close history

Code samples

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

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

url = '/futures/usdt/position_close'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /futures/{settle}/position_close

List position close history

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

Enumerated Values

Property	Value
side	long
side	short

WARNING

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

List liquidation history

Code samples

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

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

url = '/futures/usdt/liquidates'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /futures/{settle}/liquidates

List liquidation history

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

[
  {
    "time": 1548654951,
    "contract": "BTC_USDT",
    "size": 600,
    "leverage": "25",
    "margin": "0.006705256878",
    "entry_price": "3536.123",
    "liq_price": "3421.54",
    "mark_price": "3420.27",
    "order_id": 317393847,
    "order_price": "3405",
    "fill_price": "3424",
    "left": 0
  }
]

Responses

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

Response Schema

Status Code 200

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

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/price_orders'
query_param = ''
body='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/price_orders"
query_param=""
body_param='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /futures/{settle}/price_orders

Create a price-triggered order

Body parameter

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  },
  "order_type": "close-long-order"
}

Parameters

Name	In	Type	Required	Description
body	body	FuturesPriceTriggeredOrder	true	none
» initial	body	object	true	none
»» contract	body	string	true	Futures contract
»» size	body	integer(int64)	false	Order size. Positive size means to buy, while negative one means to sell. Set to 0 to close the position
»» price	body	string	true	Order price. Set to 0 to use market price
»» close	body	boolean	false	Set to true if trying to close the position
»» tif	body	string	false	Time in force. If using market price, only ioc is supported.
»» text	body	string	false	How the order is created. Possible values are: web, api and app
»» reduce_only	body	boolean	false	Set to true to create a reduce-only order
»» auto_size	body	string	false	Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0
» trigger	body	object	true	none
»» strategy_type	body	integer	false	How the order will be triggered
»» price_type	body	integer(int32)	false	Price type. 0 - latest deal price, 1 - mark price, 2 - index price
»» price	body	string	false	Value of price on price triggered, or price gap on price gap triggered
»» rule	body	integer(int32)	false	Trigger condition type
»» expiration	body	integer	false	How long (in seconds) to wait for the condition to be triggered before cancelling the order.
» order_type	body	string	false	Take-profit/stop-loss types, which include:
settle	path	string	true	Settle currency

Detailed descriptions

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

• gtc: GoodTillCancelled
• ioc: ImmediateOrCancelled

»» strategy_type: How the order will be triggered

• 0: by price, which means the order will be triggered if price condition is satisfied
• 1: by price gap, which means the order will be triggered if gap of recent two prices of specified price_type are satisfied. Only 0 is supported currently

»» rule: Trigger condition type

• 1: calculated price based on strategy_type and price_type >= price
• 2: calculated price based on strategy_type and price_type <= price

» order_type: Take-profit/stop-loss types, which include:

• close-long-order: order take-profit/stop-loss, close long position
• close-short-order: order take-profit/stop-loss, close short position
• close-long-position: position take-profit/stop-loss, close long position
• close-short-position: position take-profit/stop-loss, close short position
• plan-close-long-position: position planned take-profit/stop-loss, close long position
• plan-close-short-position: position planned take-profit/stop-loss, close short position

The order take-profit/stop-loss can not be passed by request. These two types are read only.

Enumerated Values

Parameter	Value
»» tif	gtc
»» tif	ioc
»» strategy_type	0
»» strategy_type	1
»» price_type	0
»» price_type	1
»» price_type	2
»» rule	1
»» rule	2
settle	btc
settle	usdt
settle	usd

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

List all auto orders

Code samples

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

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

url = '/futures/usdt/price_orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

GET /futures/{settle}/price_orders

List all auto orders

Parameters

Name	In	Type	Required	Description
status	query	string	true	Only list the orders with this status
contract	query	string	false	Futures contract, return related data only if specified
limit	query	integer	false	Maximum number of records to be returned in a single list
offset	query	integer	false	List offset, starting from 0
settle	path	string	true	Settle currency

Enumerated Values

Parameter	Value
status	open
status	finished
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

[
  {
    "initial": {
      "contract": "BTC_USDT",
      "size": 100,
      "price": "5.03"
    },
    "trigger": {
      "strategy_type": 0,
      "price_type": 0,
      "price": "3000",
      "rule": 1,
      "expiration": 86400
    },
    "id": 1283293,
    "user": 1234,
    "create_time": 1514764800,
    "finish_time": 1514764900,
    "trade_id": 13566,
    "status": "finished",
    "finish_as": "cancelled",
    "reason": "",
    "order_type": "close-long-order"
  }
]

Responses

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

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/price_orders'
query_param = 'contract=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

DELETE /futures/{settle}/price_orders

Cancel all open orders

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

[
  {
    "initial": {
      "contract": "BTC_USDT",
      "size": 100,
      "price": "5.03"
    },
    "trigger": {
      "strategy_type": 0,
      "price_type": 0,
      "price": "3000",
      "rule": 1,
      "expiration": 86400
    },
    "id": 1283293,
    "user": 1234,
    "create_time": 1514764800,
    "finish_time": 1514764900,
    "trade_id": 13566,
    "status": "finished",
    "finish_as": "cancelled",
    "reason": "",
    "order_type": "close-long-order"
  }
]

Responses

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

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /futures/{settle}/price_orders/{order_id}

Get a single order

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  },
  "id": 1283293,
  "user": 1234,
  "create_time": 1514764800,
  "finish_time": 1514764900,
  "trade_id": 13566,
  "status": "finished",
  "finish_as": "cancelled",
  "reason": "",
  "order_type": "close-long-order"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Auto order detail	FuturesPriceTriggeredOrder

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

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

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

DELETE /futures/{settle}/price_orders/{order_id}

cancel a price-triggered order

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  },
  "id": 1283293,
  "user": 1234,
  "create_time": 1514764800,
  "finish_time": 1514764900,
  "trade_id": 13566,
  "status": "finished",
  "finish_as": "cancelled",
  "reason": "",
  "order_type": "close-long-order"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Auto order detail	FuturesPriceTriggeredOrder

WARNING

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

Delivery

Delivery contract API

List all futures contracts

Code samples

# coding: utf-8
import requests

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

url = '/delivery/usdt/contracts'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/contracts \
  -H 'Accept: application/json'

GET /delivery/{settle}/contracts

List all futures contracts

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

[
  {
    "name": "BTC_USDT_20200814",
    "underlying": "BTC_USDT",
    "cycle": "WEEKLY",
    "type": "direct",
    "quanto_multiplier": "0.0001",
    "mark_type": "index",
    "last_price": "9017",
    "mark_price": "9019",
    "index_price": "9005.3",
    "basis_rate": "0.185095",
    "basis_value": "13.7",
    "basis_impact_value": "100000",
    "settle_price": "0",
    "settle_price_interval": 60,
    "settle_price_duration": 1800,
    "settle_fee_rate": "0.0015",
    "expire_time": 1593763200,
    "order_price_round": "0.1",
    "mark_price_round": "0.1",
    "leverage_min": "1",
    "leverage_max": "100",
    "maintenance_rate": "1000000",
    "risk_limit_base": "140.726652109199",
    "risk_limit_step": "1000000",
    "risk_limit_max": "8000000",
    "maker_fee_rate": "-0.00025",
    "taker_fee_rate": "0.00075",
    "ref_discount_rate": "0",
    "ref_rebate_rate": "0.2",
    "order_price_deviate": "0.5",
    "order_size_min": 1,
    "order_size_max": 1000000,
    "orders_limit": 50,
    "orderbook_id": 63,
    "trade_id": 26,
    "trade_size": 435,
    "position_size": 130,
    "config_change_time": 1593158867,
    "in_delisting": false
  }
]

Responses

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

This operation does not require authentication

Get a single contract

Code samples

# coding: utf-8
import requests

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

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

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

GET /delivery/{settle}/contracts/{contract}

Get a single contract

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

{
  "name": "BTC_USDT_20200814",
  "underlying": "BTC_USDT",
  "cycle": "WEEKLY",
  "type": "direct",
  "quanto_multiplier": "0.0001",
  "mark_type": "index",
  "last_price": "9017",
  "mark_price": "9019",
  "index_price": "9005.3",
  "basis_rate": "0.185095",
  "basis_value": "13.7",
  "basis_impact_value": "100000",
  "settle_price": "0",
  "settle_price_interval": 60,
  "settle_price_duration": 1800,
  "settle_fee_rate": "0.0015",
  "expire_time": 1593763200,
  "order_price_round": "0.1",
  "mark_price_round": "0.1",
  "leverage_min": "1",
  "leverage_max": "100",
  "maintenance_rate": "1000000",
  "risk_limit_base": "140.726652109199",
  "risk_limit_step": "1000000",
  "risk_limit_max": "8000000",
  "maker_fee_rate": "-0.00025",
  "taker_fee_rate": "0.00075",
  "ref_discount_rate": "0",
  "ref_rebate_rate": "0.2",
  "order_price_deviate": "0.5",
  "order_size_min": 1,
  "order_size_max": 1000000,
  "orders_limit": 50,
  "orderbook_id": 63,
  "trade_id": 26,
  "trade_size": 435,
  "position_size": 130,
  "config_change_time": 1593158867,
  "in_delisting": false
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Contract information	DeliveryContract

This operation does not require authentication

Futures order book

Code samples

# coding: utf-8
import requests

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

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

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

GET /delivery/{settle}/order_book

Futures order book

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

Parameters

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

Enumerated Values

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

Example responses

200 Response

{
  "id": 123456,
  "current": 1623898993.123,
  "update": 1623898993.121,
  "asks": [
    {
      "p": "1.52",
      "s": 100
    },
    {
      "p": "1.53",
      "s": 40
    }
  ],
  "bids": [
    {
      "p": "1.17",
      "s": 150
    },
    {
      "p": "1.16",
      "s": 203
    }
  ]
}

Responses

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

Response Schema

Status Code 200

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

This operation does not require authentication

Futures trading history

Code samples

# coding: utf-8
import requests

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

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

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

GET /delivery/{settle}/trades

Futures trading history

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	true	Futures contract
limit	query	integer	false	Maximum number of records to be returned in a single list
last_id	query	string	false	Specify the starting point for this list based on a previously retrieved id
from	query	integer(int64)	false	Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items.
to	query	integer(int64)	false	Specify end time in Unix seconds, default to current time

Detailed descriptions

last_id: Specify the starting point for this list based on a previously retrieved id

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

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

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

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	integer(int64)	Trade ID
» create_time	number(double)	Trading time
» create_time_ms	number(double)	Trading time, with milliseconds set to 3 decimal places.
» contract	string	Futures contract
» size	integer(int64)	Trading size
» price	string	Trading price

This operation does not require authentication

Get futures candlesticks

Code samples

# coding: utf-8
import requests

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

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

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

GET /delivery/{settle}/candlesticks

Get futures candlesticks

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

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

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	true	Futures contract
from	query	integer(int64)	false	Start time of candlesticks, formatted in Unix timestamp in seconds.
to	query	integer(int64)	false	End time of candlesticks, formatted in Unix timestamp in seconds. Default to current time
limit	query	integer	false	Maximum recent data points to return. limit is conflicted with from and to. If either from or to is specified, request will be rejected.
interval	query	string	false	Interval time between data points. Note that 1w means natual week(Mon-Sun), while 7d means every 7d since unix 0

Detailed descriptions

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd
interval	10s
interval	30s
interval	1m
interval	5m
interval	15m
interval	30m
interval	1h
interval	2h
interval	4h
interval	6h
interval	8h
interval	12h
interval	1d
interval	7d
interval	1w
interval	30d

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

This operation does not require authentication

List futures tickers

Code samples

# coding: utf-8
import requests

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

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

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

GET /delivery/{settle}/tickers

List futures tickers

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

This operation does not require authentication

Futures insurance balance history

Code samples

# coding: utf-8
import requests

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

url = '/delivery/usdt/insurance'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/insurance \
  -H 'Accept: application/json'

GET /delivery/{settle}/insurance

Futures insurance balance history

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

This operation does not require authentication

Query futures account

Code samples

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

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

url = '/delivery/usdt/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /delivery/{settle}/accounts

Query futures account

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

{
  "user": 1666,
  "currency": "USDT",
  "total": "9707.803567115145",
  "unrealised_pnl": "3371.248828",
  "position_margin": "38.712189181",
  "order_margin": "0",
  "available": "9669.091377934145",
  "point": "0",
  "bonus": "0",
  "in_dual_mode": false,
  "history": {
    "dnw": "10000",
    "pnl": "68.3685",
    "fee": "-1.645812875",
    "refr": "0",
    "fund": "-358.919120009855",
    "point_dnw": "0",
    "point_fee": "0",
    "point_refr": "0",
    "bonus_dnw": "0",
    "bonus_offset": "0"
  }
}

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» total	string	total = position_margin + order_margin + available
» unrealised_pnl	string	Unrealized PNL
» position_margin	string	Position margin
» order_margin	string	Order margin of unfinished orders
» available	string	The available balance for transferring or trading
» point	string	POINT amount
» currency	string	Settle currency
» in_dual_mode	boolean	Whether dual mode is enabled
» enable_credit	boolean	Whether portfolio margin account mode is enabled
» position_initial_margin	string	Initial margin position, applicable to the portfolio margin account model
» maintenance_margin	string	Maintenance margin position, applicable to the portfolio margin account model
» bonus	string	Perpetual Contract Bonus
» history	object	Statistical data
»» dnw	string	total amount of deposit and withdraw
»» pnl	string	total amount of trading profit and loss
»» fee	string	total amount of fee
»» refr	string	total amount of referrer rebates
»» fund	string	total amount of funding costs
»» point_dnw	string	total amount of point deposit and withdraw
»» point_fee	string	total amount of point fee
»» point_refr	string	total amount of referrer rebates of point fee
»» bonus_dnw	string	total amount of perpetual contract bonus transfer
»» bonus_offset	string	total amount of perpetual contract bonus deduction

WARNING

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

Query account book

Code samples

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

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

url = '/delivery/usdt/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /delivery/{settle}/account_book

Query account book

Parameters

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

Detailed descriptions

type: Changing Type:

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

Enumerated Values

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

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

Enumerated Values

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

WARNING

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

List all positions of a user

Code samples

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

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

url = '/delivery/usdt/positions'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /delivery/{settle}/positions

List all positions of a user

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

[
  {
    "user": 10000,
    "contract": "BTC_USDT",
    "size": -9440,
    "leverage": "0",
    "risk_limit": "100",
    "leverage_max": "100",
    "maintenance_rate": "0.005",
    "value": "2.497143098997",
    "margin": "4.431548146258",
    "entry_price": "3779.55",
    "liq_price": "99999999",
    "mark_price": "3780.32",
    "unrealised_pnl": "-0.000507486844",
    "realised_pnl": "0.045543982432",
    "history_pnl": "0",
    "last_close_pnl": "0",
    "realised_point": "0",
    "history_point": "0",
    "adl_ranking": 5,
    "pending_orders": 16,
    "close_order": {
      "id": 232323,
      "price": "3779",
      "is_liq": false
    },
    "mode": "single",
    "cross_leverage_limit": "0"
  }
]

Responses

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

WARNING

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

Get single position

Code samples

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

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

url = '/delivery/usdt/positions/BTC_USDT_20200814'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

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

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

GET /delivery/{settle}/positions/{contract}

Get single position

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

{
  "user": 10000,
  "contract": "BTC_USDT",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  },
  "mode": "single",
  "cross_leverage_limit": "0"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Position information	Position

WARNING

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

Update position margin

Code samples

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

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

url = '/delivery/usdt/positions/BTC_USDT_20200814/margin'
query_param = 'change=0.01'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

POST /delivery/{settle}/positions/{contract}/margin

Update position margin

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

{
  "user": 10000,
  "contract": "BTC_USDT",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  },
  "mode": "single",
  "cross_leverage_limit": "0"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Position information	Position

WARNING

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

Update position leverage

Code samples

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

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

url = '/delivery/usdt/positions/BTC_USDT_20200814/leverage'
query_param = 'leverage=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

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

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

POST /delivery/{settle}/positions/{contract}/leverage

Update position leverage

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

{
  "user": 10000,
  "contract": "BTC_USDT",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  },
  "mode": "single",
  "cross_leverage_limit": "0"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Position information	Position

WARNING

To perform this operation, you must be authenticated by API key and secret

Update position risk limit

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/positions/BTC_USDT_20200814/risk_limit'
query_param = 'risk_limit=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/positions/BTC_USDT_20200814/risk_limit"
query_param="risk_limit=10"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /delivery/{settle}/positions/{contract}/risk_limit

Update position risk limit

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	path	string	true	Futures contract
risk_limit	query	string	true	New position risk limit

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

{
  "user": 10000,
  "contract": "BTC_USDT",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  },
  "mode": "single",
  "cross_leverage_limit": "0"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Position information	Position

WARNING

To perform this operation, you must be authenticated by API key and secret

Create a futures order

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/orders'
query_param = ''
body='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/orders"
query_param=""
body_param='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /delivery/{settle}/orders

Create a futures order

Zero-filled order cannot be retrieved 10 minutes after order cancellation

Body parameter

{
  "contract": "BTC_USDT",
  "size": 6024,
  "iceberg": 0,
  "price": "3765",
  "tif": "gtc",
  "text": "t-my-custom-id"
}

Parameters

Name	In	Type	Required	Description
body	body	FuturesOrder	true	none
» contract	body	string	true	Futures contract
» size	body	integer(int64)	true	Order size. Specify positive number to make a bid, and negative number to ask
» iceberg	body	integer(int64)	false	Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size
» price	body	string	false	Order price. 0 for market order with tif set as ioc
» close	body	boolean	false	Set as true to close the position, with size set to 0
» reduce_only	body	boolean	false	Set as true to be reduce-only order
» tif	body	string	false	Time in force
» text	body	string	false	User defined information. If not empty, must follow the rules below:
» auto_size	body	string	false	Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0
settle	path	string	true	Settle currency

Detailed descriptions

» tif: Time in force

• gtc: GoodTillCancelled
• ioc: ImmediateOrCancelled, taker only
• poc: PendingOrCancelled, reduce-only
• fok: FillOrKill, fill either completely or none

» text: User defined information. If not empty, must follow the rules below:

1. prefixed with t-
2. no longer than 28 bytes without t- prefix
3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created:

• web: from web
• api: from API
• app: from mobile phones
• auto_deleveraging: from ADL
• liquidation: from liquidation
• insurance: from insurance

Enumerated Values

Parameter	Value
» tif	gtc
» tif	ioc
» tif	poc
» tif	fok
» auto_size	close_long
» auto_size	close_short
settle	btc
settle	usdt
settle	usd

Example responses

201 Response

{
  "id": 15675394,
  "user": 100000,
  "contract": "BTC_USDT",
  "create_time": 1546569968,
  "size": 6024,
  "iceberg": 0,
  "left": 6024,
  "price": "3765",
  "fill_price": "0",
  "mkfr": "-0.00025",
  "tkfr": "0.00075",
  "tif": "gtc",
  "refu": 0,
  "is_reduce_only": false,
  "is_close": false,
  "is_liq": false,
  "text": "t-my-custom-id",
  "status": "finished",
  "finish_time": 1514764900,
  "finish_as": "cancelled"
}

Responses

Status	Meaning	Description	Schema
201	Created (opens new window)	Order details	FuturesOrder

WARNING

To perform this operation, you must be authenticated by API key and secret

List futures orders

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/orders

List futures orders

Zero-filled order cannot be retrieved 10 minutes after order cancellation

Parameters

Name	In	Type	Required	Description
contract	query	string	false	Futures contract
status	query	string	true	Only list the orders with this status
limit	query	integer	false	Maximum number of records to be returned in a single list
offset	query	integer	false	List offset, starting from 0
last_id	query	string	false	Specify list staring point using the id of last record in previous list-query results
count_total	query	integer	false	Whether to return total number matched. Default to 0(no return)
settle	path	string	true	Settle currency

Enumerated Values

Parameter	Value
status	open
status	finished
count_total	0
count_total	1
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

[
  {
    "id": 15675394,
    "user": 100000,
    "contract": "BTC_USDT",
    "create_time": 1546569968,
    "size": 6024,
    "iceberg": 0,
    "left": 6024,
    "price": "3765",
    "fill_price": "0",
    "mkfr": "-0.00025",
    "tkfr": "0.00075",
    "tif": "gtc",
    "refu": 0,
    "is_reduce_only": false,
    "is_close": false,
    "is_liq": false,
    "text": "t-my-custom-id",
    "status": "finished",
    "finish_time": 1514764900,
    "finish_as": "cancelled"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[FuturesOrder]

Response Headers

Status	Header	Type	Format	Description
200	X-Pagination-Limit	integer		Request limit specified
200	X-Pagination-Offset	integer		Request offset specified
200	X-Pagination-Total	integer		Total number matched. Only returned if count_total set to 1

WARNING

To perform this operation, you must be authenticated by API key and secret

Cancel all open orders matched

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/orders'
query_param = 'contract=BTC_USDT_20200814'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/delivery/usdt/orders"
query_param="contract=BTC_USDT_20200814"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /delivery/{settle}/orders

Cancel all open orders matched

Zero-filled order cannot be retrieved 10 minutes after order cancellation

Parameters

Name	In	Type	Required	Description
contract	query	string	true	Futures contract
side	query	string	false	All bids or asks. Both included if not specified
settle	path	string	true	Settle currency

Enumerated Values

Parameter	Value
side	ask
side	bid
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

[
  {
    "id": 15675394,
    "user": 100000,
    "contract": "BTC_USDT",
    "create_time": 1546569968,
    "size": 6024,
    "iceberg": 0,
    "left": 6024,
    "price": "3765",
    "fill_price": "0",
    "mkfr": "-0.00025",
    "tkfr": "0.00075",
    "tif": "gtc",
    "refu": 0,
    "is_reduce_only": false,
    "is_close": false,
    "is_liq": false,
    "text": "t-my-custom-id",
    "status": "finished",
    "finish_time": 1514764900,
    "finish_as": "cancelled"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	All orders matched cancelled	[FuturesOrder]

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/orders/{order_id}

Get a single order

Zero-filled order cannot be retrieved 10 minutes after order cancellation

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
order_id	path	string	true	Retrieve the data of the order with the specified ID

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

{
  "id": 15675394,
  "user": 100000,
  "contract": "BTC_USDT",
  "create_time": 1546569968,
  "size": 6024,
  "iceberg": 0,
  "left": 6024,
  "price": "3765",
  "fill_price": "0",
  "mkfr": "-0.00025",
  "tkfr": "0.00075",
  "tif": "gtc",
  "refu": 0,
  "is_reduce_only": false,
  "is_close": false,
  "is_liq": false,
  "text": "t-my-custom-id",
  "status": "finished",
  "finish_time": 1514764900,
  "finish_as": "cancelled"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Order details	FuturesOrder

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/delivery/usdt/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /delivery/{settle}/orders/{order_id}

Cancel a single order

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
order_id	path	string	true	Retrieve the data of the order with the specified ID

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

{
  "id": 15675394,
  "user": 100000,
  "contract": "BTC_USDT",
  "create_time": 1546569968,
  "size": 6024,
  "iceberg": 0,
  "left": 6024,
  "price": "3765",
  "fill_price": "0",
  "mkfr": "-0.00025",
  "tkfr": "0.00075",
  "tif": "gtc",
  "refu": 0,
  "is_reduce_only": false,
  "is_close": false,
  "is_liq": false,
  "text": "t-my-custom-id",
  "status": "finished",
  "finish_time": 1514764900,
  "finish_as": "cancelled"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Order details	FuturesOrder

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/my_trades'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/my_trades"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/my_trades

List personal trading history

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	false	Futures contract
order	query	integer(int64)	false	Futures order ID, return related data only if specified
limit	query	integer	false	Maximum number of records to be returned in a single list
offset	query	integer	false	List offset, starting from 0
last_id	query	string	false	Specify list staring point using the id of last record in previous list-query results
count_total	query	integer	false	Whether to return total number matched. Default to 0(no return)

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd
count_total	0
count_total	1

Example responses

200 Response

[
  {
    "id": 121234231,
    "create_time": 1514764800.123,
    "contract": "BTC_USDT",
    "order_id": "21893289839",
    "size": 100,
    "price": "100.123",
    "text": "t-123456",
    "fee": "0.01",
    "point_fee": "0",
    "role": "taker"
  }
]

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	integer(int64)	Trade ID
» create_time	number(double)	Trading time
» contract	string	Futures contract
» order_id	string	Order ID related
» size	integer(int64)	Trading size
» price	string	Trading price
» role	string	Trade role. Available values are taker and maker
» text	string	User defined information
» fee	string	Fee deducted
» point_fee	string	Points used to deduct fee

Enumerated Values

Property	Value
role	taker
role	maker

Response Headers

Status	Header	Type	Format	Description
200	X-Pagination-Limit	integer		Request limit specified
200	X-Pagination-Offset	integer		Request offset specified
200	X-Pagination-Total	integer		Total number matched. Only returned if count_total set to 1

WARNING

To perform this operation, you must be authenticated by API key and secret

List position close history

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/position_close'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/position_close"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/position_close

List position close history

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	false	Futures contract
limit	query	integer	false	Maximum number of records to be returned in a single list

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

[
  {
    "time": 1546487347,
    "pnl": "0.00013",
    "side": "long",
    "contract": "BTC_USDT",
    "text": "web"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» time	number(double)	Position close time
» contract	string	Futures contract
» side	string	Position side, long or short
» pnl	string	PNL
» text	string	Text of close order

Enumerated Values

Property	Value
side	long
side	short

WARNING

To perform this operation, you must be authenticated by API key and secret

List liquidation history

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/liquidates'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/liquidates"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/liquidates

List liquidation history

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	false	Futures contract
limit	query	integer	false	Maximum number of records to be returned in a single list
at	query	integer	false	Specify a liquidation timestamp

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

[
  {
    "time": 1548654951,
    "contract": "BTC_USDT",
    "size": 600,
    "leverage": "25",
    "margin": "0.006705256878",
    "entry_price": "3536.123",
    "liq_price": "3421.54",
    "mark_price": "3420.27",
    "order_id": 317393847,
    "order_price": "3405",
    "fill_price": "3424",
    "left": 0
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» time	integer(int64)	Liquidation time
» contract	string	Futures contract
» leverage	string	Position leverage. Not returned in public endpoints.
» size	integer(int64)	Position size
» margin	string	Position margin. Not returned in public endpoints.
» entry_price	string	Average entry price. Not returned in public endpoints.
» liq_price	string	Liquidation price. Not returned in public endpoints.
» mark_price	string	Mark price. Not returned in public endpoints.
» order_id	integer(int64)	Liquidation order ID. Not returned in public endpoints.
» order_price	string	Liquidation order price
» fill_price	string	Liquidation order average taker price
» left	integer(int64)	Liquidation order maker size

WARNING

To perform this operation, you must be authenticated by API key and secret

List settlement history

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/settlements'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/settlements"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/settlements

List settlement history

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	false	Futures contract
limit	query	integer	false	Maximum number of records to be returned in a single list
at	query	integer	false	Specify a settlement timestamp

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
settle	usd

Example responses

200 Response

[
  {
    "time": 1548654951,
    "contract": "BTC_USDT",
    "size": 600,
    "leverage": "25",
    "margin": "0.006705256878",
    "entry_price": "3536.123",
    "settle_price": "3421.54",
    "profit": "-6.87498",
    "fee": "0.03079386"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
» time	integer(int64)	Liquidation time
» contract	string	Futures contract
» leverage	string	Position leverage
» size	integer(int64)	Position size
» margin	string	Position margin
» entry_price	string	Average entry price
» settle_price	string	Settled price
» profit	string	Profit
» fee	string	Fee deducted

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/price_orders'
query_param = ''
body='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/price_orders"
query_param=""
body_param='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /delivery/{settle}/price_orders

Create a price-triggered order

Body parameter

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  },
  "order_type": "close-long-order"
}

Parameters

Name	In	Type	Required	Description
body	body	FuturesPriceTriggeredOrder	true	none
» initial	body	object	true	none
»» contract	body	string	true	Futures contract
»» size	body	integer(int64)	false	Order size. Positive size means to buy, while negative one means to sell. Set to 0 to close the position
»» price	body	string	true	Order price. Set to 0 to use market price
»» close	body	boolean	false	Set to true if trying to close the position
»» tif	body	string	false	Time in force. If using market price, only ioc is supported.
»» text	body	string	false	How the order is created. Possible values are: web, api and app
»» reduce_only	body	boolean	false	Set to true to create a reduce-only order
»» auto_size	body	string	false	Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0
» trigger	body	object	true	none
»» strategy_type	body	integer	false	How the order will be triggered
»» price_type	body	integer(int32)	false	Price type. 0 - latest deal price, 1 - mark price, 2 - index price
»» price	body	string	false	Value of price on price triggered, or price gap on price gap triggered
»» rule	body	integer(int32)	false	Trigger condition type
»» expiration	body	integer	false	How long (in seconds) to wait for the condition to be triggered before cancelling the order.
» order_type	body	string	false	Take-profit/stop-loss types, which include:
settle	path	string	true	Settle currency

Detailed descriptions

»» tif: Time in force. If using market price, only ioc is supported.

• gtc: GoodTillCancelled
• ioc: ImmediateOrCancelled

»» strategy_type: How the order will be triggered

• 0: by price, which means the order will be triggered if price condition is satisfied
• 1: by price gap, which means the order will be triggered if gap of recent two prices of specified price_type are satisfied. Only 0 is supported currently

»» rule: Trigger condition type

• 1: calculated price based on strategy_type and price_type >= price
• 2: calculated price based on strategy_type and price_type <= price

» order_type: Take-profit/stop-loss types, which include:

• close-long-order: order take-profit/stop-loss, close long position
• close-short-order: order take-profit/stop-loss, close short position
• close-long-position: position take-profit/stop-loss, close long position
• close-short-position: position take-profit/stop-loss, close short position
• plan-close-long-position: position planned take-profit/stop-loss, close long position
• plan-close-short-position: position planned take-profit/stop-loss, close short position

The order take-profit/stop-loss can not be passed by request. These two types are read only.

Enumerated Values

Parameter	Value
»» tif	gtc
»» tif	ioc
»» strategy_type	0
»» strategy_type	1
»» price_type	0
»» price_type	1
»» price_type	2
»» rule	1
»» rule	2
settle	usdt
settle	btc

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

List all auto orders

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/price_orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/price_orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/price_orders

List all auto orders

Parameters

Name	In	Type	Required	Description
status	query	string	true	Only list the orders with this status
contract	query	string	false	Futures contract, return related data only if specified
limit	query	integer	false	Maximum number of records to be returned in a single list
offset	query	integer	false	List offset, starting from 0
settle	path	string	true	Settle currency

Enumerated Values

Parameter	Value
status	open
status	finished
settle	usdt
settle	btc

Example responses

200 Response

[
  {
    "initial": {
      "contract": "BTC_USDT",
      "size": 100,
      "price": "5.03"
    },
    "trigger": {
      "strategy_type": 0,
      "price_type": 0,
      "price": "3000",
      "rule": 1,
      "expiration": 86400
    },
    "id": 1283293,
    "user": 1234,
    "create_time": 1514764800,
    "finish_time": 1514764900,
    "trade_id": 13566,
    "status": "finished",
    "finish_as": "cancelled",
    "reason": "",
    "order_type": "close-long-order"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[FuturesPriceTriggeredOrder]

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/price_orders'
query_param = 'contract=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/delivery/usdt/price_orders"
query_param="contract=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /delivery/{settle}/price_orders

Cancel all open orders

Parameters

Name	In	Type	Required	Description
contract	query	string	true	Futures contract
settle	path	string	true	Settle currency

Enumerated Values

Parameter	Value
settle	usdt
settle	btc

Example responses

200 Response

[
  {
    "initial": {
      "contract": "BTC_USDT",
      "size": 100,
      "price": "5.03"
    },
    "trigger": {
      "strategy_type": 0,
      "price_type": 0,
      "price": "3000",
      "rule": 1,
      "expiration": 86400
    },
    "id": 1283293,
    "user": 1234,
    "create_time": 1514764800,
    "finish_time": 1514764900,
    "trade_id": 13566,
    "status": "finished",
    "finish_as": "cancelled",
    "reason": "",
    "order_type": "close-long-order"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Batch cancellation request accepted. Query order status by listing orders	[FuturesPriceTriggeredOrder]

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /delivery/{settle}/price_orders/{order_id}

Get a single order

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
order_id	path	string	true	Retrieve the data of the order with the specified ID

Enumerated Values

Parameter	Value
settle	usdt
settle	btc

Example responses

200 Response

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  },
  "id": 1283293,
  "user": 1234,
  "create_time": 1514764800,
  "finish_time": 1514764900,
  "trade_id": 13566,
  "status": "finished",
  "finish_as": "cancelled",
  "reason": "",
  "order_type": "close-long-order"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Auto order detail	FuturesPriceTriggeredOrder

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/delivery/usdt/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/delivery/usdt/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /delivery/{settle}/price_orders/{order_id}

cancel a price-triggered order

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
order_id	path	string	true	Retrieve the data of the order with the specified ID

Enumerated Values

Parameter	Value
settle	usdt
settle	btc

Example responses

200 Response

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  },
  "id": 1283293,
  "user": 1234,
  "create_time": 1514764800,
  "finish_time": 1514764900,
  "trade_id": 13566,
  "status": "finished",
  "finish_as": "cancelled",
  "reason": "",
  "order_type": "close-long-order"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Auto order detail	FuturesPriceTriggeredOrder

WARNING

To perform this operation, you must be authenticated by API key and secret

Options

Options API

List all underlyings

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/underlyings'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/underlyings \
  -H 'Accept: application/json'

GET /options/underlyings

List all underlyings

Example responses

200 Response

[
  {
    "name": "BTC_USDT",
    "index_price": "70000"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
» name	string	Underlying name
» index_price	string	Spot index price

This operation does not require authentication

List all expiration times

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/expirations'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/expirations?underlying=BTC_USDT \
  -H 'Accept: application/json'

GET /options/expirations

List all expiration times

Parameters

Name	In	Type	Required	Description
underlying	query	string	true	Underlying

Example responses

200 Response

[
  1637913600
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List expiration times of specified underlying	[integer]

Response Schema

Status Code 200

Name	Type	Description
» None	integer(int64)	Unix timestamp of the expiration time

This operation does not require authentication

List all the contracts with specified underlying and expiration time

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/contracts'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/contracts?underlying=BTC_USDT \
  -H 'Accept: application/json'

GET /options/contracts

List all the contracts with specified underlying and expiration time

Parameters

Name	In	Type	Required	Description
underlying	query	string	true	Underlying
expiration	query	integer(int64)	false	Unix timestamp of the expiration time

Example responses

200 Response

[
  {
    "name": "BTC_USDT-20211130-65000-C",
    "tag": "WEEK",
    "create_time": 1636702700,
    "expiration_time": 1637913600,
    "is_call": true,
    "strike_price": "65000",
    "last_price": "13000",
    "mark_price": "14010",
    "orderbook_id": 9,
    "trade_id": 1,
    "trade_size": 10,
    "position_size": 10,
    "underlying": "BTC_USDT",
    "underlying_price": "70000",
    "multiplier": "0.0001",
    "order_price_round": "0.1",
    "mark_price_round": "0.1",
    "maker_fee_rate": "0.0004",
    "taker_fee_rate": "0.0004",
    "price_limit_fee_rate": "0.1",
    "ref_discount_rate": "0",
    "ref_rebate_rate": "0",
    "order_price_deviate": "0.5",
    "order_size_min": 1,
    "order_size_max": 100000,
    "orders_limit": 50
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
None	array	[Futures contract details]
» None	object	Futures contract details
»» name	string	Futures contract
»» tag	string	tag
»» create_time	number(double)	Creation time
»» expiration_time	number(double)	Expiration time
»» is_call	boolean	true means call options, while false is put options
»» multiplier	string	Multiplier used in converting from invoicing to settlement currency
»» underlying	string	Underlying
»» underlying_price	string	Underlying price
»» last_price	string	Last trading price
»» mark_price	string	Current mark price
»» index_price	string	Current index price
»» maker_fee_rate	string	Maker fee rate, where negative means rebate
»» taker_fee_rate	string	Taker fee rate
»» order_price_round	string	Minimum order price increment
»» mark_price_round	string	Minimum mark price increment
»» order_size_min	integer(int64)	Minimum order size the contract allowed
»» order_size_max	integer(int64)	Maximum order size the contract allowed
»» order_price_deviate	string	deviation between order price and current index price. If price of an order is denoted as order_price, it must meet the following condition: abs(order_price - mark_price) <= mark_price * order_price_deviate
»» ref_discount_rate	string	Referral fee rate discount
»» ref_rebate_rate	string	Referrer commission rate
»» orderbook_id	integer(int64)	Current orderbook ID
»» trade_id	integer(int64)	Current trade ID
»» trade_size	integer(int64)	Historical accumulated trade size
»» position_size	integer(int64)	Current total long position size
»» orders_limit	integer	Maximum number of open orders

This operation does not require authentication

Query specified contract detail

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/contracts/BTC_USDT-20211130-65000-C'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/contracts/BTC_USDT-20211130-65000-C \
  -H 'Accept: application/json'

GET /options/contracts/{contract}

Query specified contract detail

Parameters

Name	In	Type	Required	Description
contract	path	string	true	none

Example responses

200 Response

{
  "name": "BTC_USDT-20211130-65000-C",
  "tag": "WEEK",
  "create_time": 1636702700,
  "expiration_time": 1637913600,
  "is_call": true,
  "strike_price": "65000",
  "last_price": "13000",
  "mark_price": "14010",
  "orderbook_id": 9,
  "trade_id": 1,
  "trade_size": 10,
  "position_size": 10,
  "underlying": "BTC_USDT",
  "underlying_price": "70000",
  "multiplier": "0.0001",
  "order_price_round": "0.1",
  "mark_price_round": "0.1",
  "maker_fee_rate": "0.0004",
  "taker_fee_rate": "0.0004",
  "price_limit_fee_rate": "0.1",
  "ref_discount_rate": "0",
  "ref_rebate_rate": "0",
  "order_price_deviate": "0.5",
  "order_size_min": 1,
  "order_size_max": 100000,
  "orders_limit": 50
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Successfully retrieved	Inline

Response Schema

Status Code 200

Futures contract details

Name	Type	Description
» name	string	Futures contract
» tag	string	tag
» create_time	number(double)	Creation time
» expiration_time	number(double)	Expiration time
» is_call	boolean	true means call options, while false is put options
» multiplier	string	Multiplier used in converting from invoicing to settlement currency
» underlying	string	Underlying
» underlying_price	string	Underlying price
» last_price	string	Last trading price
» mark_price	string	Current mark price
» index_price	string	Current index price
» maker_fee_rate	string	Maker fee rate, where negative means rebate
» taker_fee_rate	string	Taker fee rate
» order_price_round	string	Minimum order price increment
» mark_price_round	string	Minimum mark price increment
» order_size_min	integer(int64)	Minimum order size the contract allowed
» order_size_max	integer(int64)	Maximum order size the contract allowed
» order_price_deviate	string	deviation between order price and current index price. If price of an order is denoted as order_price, it must meet the following condition: abs(order_price - mark_price) <= mark_price * order_price_deviate
» ref_discount_rate	string	Referral fee rate discount
» ref_rebate_rate	string	Referrer commission rate
» orderbook_id	integer(int64)	Current orderbook ID
» trade_id	integer(int64)	Current trade ID
» trade_size	integer(int64)	Historical accumulated trade size
» position_size	integer(int64)	Current total long position size
» orders_limit	integer	Maximum number of open orders

This operation does not require authentication

List settlement history

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/settlements'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/settlements?underlying=BTC_USDT \
  -H 'Accept: application/json'

GET /options/settlements

List settlement history

Parameters

Name	In	Type	Required	Description
underlying	query	string	true	Underlying
limit	query	integer	false	Maximum number of records to be returned in a single list
offset	query	integer	false	List offset, starting from 0
from	query	integer(int64)	false	Start timestamp
to	query	integer(int64)	false	End timestamp

Example responses

200 Response

[
  {
    "time": 1598839200,
    "profit": "312.35",
    "fee": "0.3284",
    "settle_price": "11687.65",
    "contract": "BTC-WEEKLY-200824-11000-P",
    "strike_price": "12000"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» time	number(double)	Last changed time of configuration
» contract	string	Contract name
» profit	string	Settlement profit per size
» fee	string	Settlement fee per size
» strike_price	string	Strike price
» settle_price	string	settlement price

This operation does not require authentication

Get specified contract's settlement

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/settlements/BTC_USDT-20211130-65000-C'
query_param = 'underlying=BTC_USDT&at=0'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/settlements/BTC_USDT-20211130-65000-C?underlying=BTC_USDT&at=0 \
  -H 'Accept: application/json'

GET /options/settlements/{contract}

Get specified contract's settlement

Parameters

Name	In	Type	Required	Description
contract	path	string	true	none
underlying	query	string	true	Underlying
at	query	integer(int64)	true	none

Example responses

200 Response

{
  "time": 1598839200,
  "profit": "312.35",
  "fee": "0.3284",
  "settle_price": "11687.65",
  "contract": "BTC-WEEKLY-200824-11000-P",
  "strike_price": "12000"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Successfully retrieved	Inline

Response Schema

Status Code 200

Name	Type	Description
» time	number(double)	Last changed time of configuration
» contract	string	Contract name
» profit	string	Settlement profit per size
» fee	string	Settlement fee per size
» strike_price	string	Strike price
» settle_price	string	settlement price

This operation does not require authentication

List my options settlements

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/my_settlements'
query_param = 'underlying=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/my_settlements"
query_param="underlying=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/my_settlements

List my options settlements

Parameters

Name	In	Type	Required	Description
underlying	query	string	true	Underlying
contract	query	string	false	Contract name
limit	query	integer	false	Maximum number of records to be returned in a single list
offset	query	integer	false	List offset, starting from 0
from	query	integer(int64)	false	Start timestamp
to	query	integer(int64)	false	End timestamp

Example responses

200 Response

[
  {
    "size": -1,
    "settle_profit": "0",
    "contract": "BTC_USDT-20220624-26000-C",
    "strike_price": "26000",
    "time": 1656057600,
    "settle_price": "20917.461281337048",
    "underlying": "BTC_USDT",
    "realised_pnl": "-0.00116042",
    "fee": "0"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
» time	number(double)	Settlement time
» underlying	string	Underlying
» contract	string	Futures contract
» strike_price	string	Strike price
» settle_price	string	settlement price
» size	integer(int64)	Size
» settle_profit	string	Settlement profit
» fee	string	Fee
» realised_pnl	string	The accumulated profit and loss of opening a position, including premium, fee, settlement profit, etc.

WARNING

To perform this operation, you must be authenticated by API key and secret

Futures order book

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/order_book'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/order_book?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /options/order_book

Futures order book

Bids will be sorted by price from high to low, while asks sorted reversely

Parameters

Name	In	Type	Required	Description
contract	query	string	true	Futures contract
interval	query	string	false	Order depth. 0 means no aggregation is applied. default to 0
limit	query	integer	false	Maximum number of order depth data in asks or bids
with_id	query	boolean	false	Whether the order book update ID will be returned. This ID increases by 1 on every order book update

Enumerated Values

Parameter	Value
interval	0
interval	0.1
interval	0.01

Example responses

200 Response

{
  "id": 123456,
  "current": 1623898993.123,
  "update": 1623898993.121,
  "asks": [
    {
      "p": "1.52",
      "s": 100
    },
    {
      "p": "1.53",
      "s": 40
    }
  ],
  "bids": [
    {
      "p": "1.17",
      "s": 150
    },
    {
      "p": "1.16",
      "s": 203
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Order book retrieved	Inline

Response Schema

Status Code 200

Name	Type	Description
» id	integer(int64)	Order Book ID. Increases by 1 on every order book change. Set with_id=true to include this field in response
» current	number(double)	Response data generation timestamp
» update	number(double)	Order book changed timestamp
» asks	array	Asks order depth
»» futures_order_book_item	object	none
»»» p	string	Price
»»» s	integer(int64)	Size
»» bids	array	Bids order depth
»»» futures_order_book_item	object	none
»»»» p	string	Price
»»»» s	integer(int64)	Size

This operation does not require authentication

List tickers of options contracts

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/tickers'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/tickers?underlying=BTC_USDT \
  -H 'Accept: application/json'

GET /options/tickers

List tickers of options contracts

Parameters

Name	In	Type	Required	Description
underlying	query	string	true	Underlying

Example responses

200 Response

[
  {
    "name": "BTC_USDT-20211130-65000-C",
    "last_price": "13000",
    "mark_price": "14010",
    "position_size": 10,
    "ask1_size": 0,
    "ask1_price": "0",
    "bid1_size": 1,
    "bid1_price": "11",
    "vega": "41.41202",
    "theta": "-120.1506",
    "rho": "6.52485",
    "gamma": "0.00004",
    "delta": "0.33505",
    "mark_iv": "0.123",
    "bid_iv": "0.023",
    "ask_iv": "0.342",
    "leverage": "13"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Successfully retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
» None	object	Options contract detail
»» name	string	Options contract name
»» last_price	string	Last trading price
»» mark_price	string	Current mark price
»» index_price	string	Current index price
»» ask1_size	integer(int64)	Best ask size
»» ask1_price	string	Best ask price
»» bid1_size	integer(int64)	Best bid size
»» bid1_price	string	Best bid price
»» position_size	integer(int64)	Current total long position size
»» mark_iv	string	Implied volatility
»» bid_iv	string	Bid side implied volatility
»» ask_iv	string	Ask side implied volatility
»» leverage	string	Current leverage. Formula: underlying_price / mark_price * delta
»» delta	string	Delta
»» gamma	string	Gamma
»» vega	string	Vega
»» theta	string	Theta
»» rho	string	Rho

This operation does not require authentication

Get underlying ticker

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/underlying/tickers/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/underlying/tickers/BTC_USDT \
  -H 'Accept: application/json'

GET /options/underlying/tickers/{underlying}

Get underlying ticker

Parameters

Name	In	Type	Required	Description
underlying	path	string	true	Underlying

Example responses

200 Response

{
  "trade_put": 33505,
  "trade_call": 123,
  "index_price": "76543.3"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Successfully retrieved	Inline

Response Schema

Status Code 200

Options underlying detail

Name	Type	Description
» trade_put	integer(int64)	Total put options trades amount in last 24h
» trade_call	integer(int64)	Total call options trades amount in last 24h
» index_price	string	Index price

This operation does not require authentication

Get futures candlesticks

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/candlesticks'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/candlesticks?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /options/candlesticks

Get futures candlesticks

Parameters

Name	In	Type	Required	Description
contract	query	string	true	Futures contract
limit	query	integer	false	Maximum number of records to be returned in a single list
from	query	integer(int64)	false	Start timestamp
to	query	integer(int64)	false	End timestamp
interval	query	string	false	Interval time between data points

Enumerated Values

Parameter	Value
interval	1m
interval	5m
interval	15m
interval	30m
interval	1h

Example responses

200 Response

[
  {
    "t": 1539852480,
    "v": 97151,
    "c": "1.032",
    "h": "1.032",
    "l": "1.032",
    "o": "1.032"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Successfully retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
None	array	[data point in every timestamp]
» None	object	data point in every timestamp
»» t	number(double)	Unix timestamp in seconds
»» v	integer(int64)	size volume. Only returned if contract is not prefixed
»» c	string	Close price
»» h	string	Highest price
»» l	string	Lowest price
»» o	string	Open price

This operation does not require authentication

Mark price candlesticks of an underlying

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/underlying/candlesticks'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/underlying/candlesticks?underlying=BTC_USDT \
  -H 'Accept: application/json'

GET /options/underlying/candlesticks

Mark price candlesticks of an underlying

Parameters

Name	In	Type	Required	Description
underlying	query	string	true	Underlying
limit	query	integer	false	Maximum number of records to be returned in a single list
from	query	integer(int64)	false	Start timestamp
to	query	integer(int64)	false	End timestamp
interval	query	string	false	Interval time between data points

Enumerated Values

Parameter	Value
interval	1m
interval	5m
interval	15m
interval	30m
interval	1h

Example responses

200 Response

[
  {
    "t": 1539852480,
    "v": 97151,
    "c": "1.032",
    "h": "1.032",
    "l": "1.032",
    "o": "1.032"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Successfully retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
None	array	[data point in every timestamp]
» None	object	data point in every timestamp
»» t	number(double)	Unix timestamp in seconds
»» v	integer(int64)	size volume. Only returned if contract is not prefixed
»» c	string	Close price
»» h	string	Highest price
»» l	string	Lowest price
»» o	string	Open price

This operation does not require authentication

Options trade history

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/trades'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/options/trades \
  -H 'Accept: application/json'

GET /options/trades

Options trade history

Parameters

Name	In	Type	Required	Description
contract	query	string	false	Contract name
type	query	string(P)	false	C is call, while P is put
limit	query	integer	false	Maximum number of records to be returned in a single list
offset	query	integer	false	List offset, starting from 0
from	query	integer(int64)	false	Start timestamp
to	query	integer(int64)	false	End timestamp

Example responses

200 Response

[
  {
    "id": 121234231,
    "create_time": 1514764800,
    "contract": "BTC_USDT",
    "size": -100,
    "price": "100.123"
  }
]

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	integer(int64)	Trade ID
» create_time	number(double)	Trading time
» create_time_ms	number(double)	Trading time, with milliseconds set to 3 decimal places.
» contract	string	Futures contract
» size	integer(int64)	Trading size
» price	string	Trading price

This operation does not require authentication

List options account

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/accounts

List options account

Example responses

200 Response

{
  "user": 666,
  "currency": "USDT",
  "short_enabled": true,
  "total": "170",
  "unrealised_pnl": "-600",
  "init_margin": "1300",
  "maint_margin": "1125",
  "order_margin": "0",
  "available": "0",
  "point": "0"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Successfully retrieved	Inline

Response Schema

Status Code 200

Name	Type	Description
» user	integer	User ID
» total	string	Total account balance
» short_enabled	boolean	If the account is allowed to short
» unrealised_pnl	string	Unrealized PNL
» init_margin	string	Initial position margin
» maint_margin	string	Position maintenance margin
» order_margin	string	Order margin of unfinished orders
» available	string	Available balance to transfer out or trade
» point	string	POINT amount
» currency	string	Settle currency

WARNING

To perform this operation, you must be authenticated by API key and secret

List account changing history

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/account_book"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/account_book

List account changing history

Parameters

Name	In	Type	Required	Description
limit	query	integer	false	Maximum number of records to be returned in a single list
offset	query	integer	false	List offset, starting from 0
from	query	integer(int64)	false	Start timestamp
to	query	integer(int64)	false	End timestamp
type	query	string	false	Changing Type:

Detailed descriptions

type: Changing Type:

• dnw: Deposit & Withdraw
• prem: Trading premium
• fee: Trading fee
• refr: Referrer rebate
• set: settlement PNL

Enumerated Values

Parameter	Value
type	dnw
type	prem
type	fee
type	refr
type	set

Example responses

200 Response

[
  {
    "time": 1636426005,
    "change": "-0.16",
    "balance": "7378.189",
    "text": "BTC_USDT-20211216-5000-P:25",
    "type": "fee"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
» time	number(double)	Change time
» change	string	Amount changed
» balance	string	Account total balance after change
» type	string	Changing Type: - dnw: Deposit & Withdraw - prem: Trading premium - fee: Trading fee - refr: Referrer rebate - point_dnw: POINT Deposit & Withdraw - point_fee: POINT Trading fee - point_refr: POINT Referrer rebate
» text	string	custom text

WARNING

To perform this operation, you must be authenticated by API key and secret

List user's positions of specified underlying

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/positions'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/positions"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/positions

List user's positions of specified underlying

Parameters

Name	In	Type	Required	Description
underlying	query	string	false	Underlying

Example responses

200 Response

[
  {
    "user": 11027586,
    "contract": "BTC_USDT-20211216-5000-P",
    "size": 10,
    "entry_price": "1234",
    "realised_pnl": "120",
    "mark_price": "6000",
    "unrealised_pnl": "-320",
    "pending_orders": 1,
    "close_order": {
      "id": 232323,
      "price": "5779",
      "is_liq": false
    }
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
None	array	[Futures position details]
» None	object	Futures position details
»» user	integer	User ID
»» contract	string	Futures contract
»» size	integer(int64)	Position size
»» entry_price	string	Entry price
»» mark_price	string	Current mark price
»» realised_pnl	string	Realized PNL
»» unrealised_pnl	string	Unrealized PNL
»» pending_orders	integer	Current open orders
»» close_order	object|null	Current close order if any, or null
»»» id	integer(int64)	Close order ID
»»» price	string	Close order price
»»» is_liq	boolean	Is the close order from liquidation

WARNING

To perform this operation, you must be authenticated by API key and secret

Get specified contract position

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/positions/BTC_USDT-20211130-65000-C'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/positions/BTC_USDT-20211130-65000-C"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/positions/{contract}

Get specified contract position

Parameters

Name	In	Type	Required	Description
contract	path	string	true	none

Example responses

200 Response

{
  "user": 11027586,
  "contract": "BTC_USDT-20211216-5000-P",
  "size": 10,
  "entry_price": "1234",
  "realised_pnl": "120",
  "mark_price": "6000",
  "unrealised_pnl": "-320",
  "pending_orders": 1,
  "close_order": {
    "id": 232323,
    "price": "5779",
    "is_liq": false
  }
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Successfully retrieved	Inline

Response Schema

Status Code 200

Futures position details

Name	Type	Description
» user	integer	User ID
» contract	string	Futures contract
» size	integer(int64)	Position size
» entry_price	string	Entry price
» mark_price	string	Current mark price
» realised_pnl	string	Realized PNL
» unrealised_pnl	string	Unrealized PNL
» pending_orders	integer	Current open orders
» close_order	object|null	Current close order if any, or null
»» id	integer(int64)	Close order ID
»» price	string	Close order price
»» is_liq	boolean	Is the close order from liquidation

WARNING

To perform this operation, you must be authenticated by API key and secret

List user's liquidation history of specified underlying

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/position_close'
query_param = 'underlying=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/position_close"
query_param="underlying=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/position_close

List user's liquidation history of specified underlying

Parameters

Name	In	Type	Required	Description
underlying	query	string	true	Underlying
contract	query	string	false	Contract name

Example responses

200 Response

[
  {
    "time": 1631764800,
    "pnl": "-42914.291",
    "settle_size": "-10001",
    "side": "short",
    "contract": "BTC_USDT-20210916-5000-C",
    "text": "settled"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
» time	number(double)	Position close time
» contract	string	Futures contract
» side	string	Position side, long or short
» pnl	string	PNL
» text	string	Text of close order
» settle_size	string	settlement size

Enumerated Values

Property	Value
side	long
side	short

WARNING

To perform this operation, you must be authenticated by API key and secret

Create an options order

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/orders'
query_param = ''
body='{"size":-1,"iceberg":0,"contract":"BTC_USDT-20210916-5000-C","text":"-","tif":"gtc","price":"100"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/options/orders"
query_param=""
body_param='{"size":-1,"iceberg":0,"contract":"BTC_USDT-20210916-5000-C","text":"-","tif":"gtc","price":"100"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /options/orders

Create an options order

Body parameter

{
  "size": -1,
  "iceberg": 0,
  "contract": "BTC_USDT-20210916-5000-C",
  "text": "-",
  "tif": "gtc",
  "price": "100"
}

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» contract	body	string	true	Contract name
» size	body	integer(int64)	true	Order size. Specify positive number to make a bid, and negative number to ask
» iceberg	body	integer(int64)	false	Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size
» price	body	string	false	Order price. 0 for market order with tif set as ioc
» close	body	boolean	false	Set as true to close the position, with size set to 0
» reduce_only	body	boolean	false	Set as true to be reduce-only order
» tif	body	string	false	Time in force
» text	body	string	false	User defined information. If not empty, must follow the rules below:

Detailed descriptions

» tif: Time in force

• gtc: GoodTillCancelled
• ioc: ImmediateOrCancelled, taker only
• poc: PendingOrCancelled, reduce-only

» text: User defined information. If not empty, must follow the rules below:

1. prefixed with t-
2. no longer than 28 bytes without t- prefix
3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created:

• web: from web
• api: from API
• app: from mobile phones
• auto_deleveraging: from ADL
• liquidation: from liquidation
• insurance: from insurance

Enumerated Values

Parameter	Value
» tif	gtc
» tif	ioc
» tif	poc

Example responses

201 Response

{
  "status": "finished",
  "size": -1,
  "id": 2,
  "iceberg": 0,
  "is_liq": false,
  "is_close": false,
  "contract": "BTC_USDT-20210916-5000-C",
  "text": "-",
  "fill_price": "100",
  "finish_as": "filled",
  "left": 0,
  "tif": "gtc",
  "is_reduce_only": false,
  "create_time": 1631763361,
  "finish_time": 1631763397,
  "price": "100"
}

Responses

Status	Meaning	Description	Schema
201	Created (opens new window)	Order detail	Inline

Response Schema

Status Code 201

Options order detail

Name	Type	Description
» id	integer(int64)	Options order ID
» user	integer	User ID
» create_time	number(double)	Creation time of order
» finish_time	number(double)	Order finished time. Not returned if order is open
» finish_as	string	How the order was finished. - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC, finish immediately - auto_deleveraged: finished by ADL - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because of position close
» status	string	Order status - open: waiting to be traded - finished: finished
» contract	string	Contract name
» size	integer(int64)	Order size. Specify positive number to make a bid, and negative number to ask
» iceberg	integer(int64)	Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size
» price	string	Order price. 0 for market order with tif set as ioc
» is_close	boolean	Is the order to close position
» is_reduce_only	boolean	Is the order reduce-only
» is_liq	boolean	Is the order for liquidation
» tif	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, reduce-only
» left	integer(int64)	Size left to be traded
» fill_price	string	Fill price of the order
» 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: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance
» tkfr	string	Taker fee
» mkfr	string	Maker fee
» refu	integer	Reference user ID

Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
status	open
status	finished
tif	gtc
tif	ioc
tif	poc

WARNING

To perform this operation, you must be authenticated by API key and secret

List futures orders

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/orders

List futures orders

Parameters

Name	In	Type	Required	Description
contract	query	string	false	Contract name
underlying	query	string	false	Underlying
status	query	string	true	Only list the orders with this status
limit	query	integer	false	Maximum number of records to be returned in a single list
offset	query	integer	false	List offset, starting from 0
from	query	integer(int64)	false	Start timestamp
to	query	integer(int64)	false	End timestamp

Enumerated Values

Parameter	Value
status	open
status	finished

Example responses

200 Response

[
  {
    "status": "finished",
    "size": -1,
    "id": 2,
    "iceberg": 0,
    "is_liq": false,
    "is_close": false,
    "contract": "BTC_USDT-20210916-5000-C",
    "text": "-",
    "fill_price": "100",
    "finish_as": "filled",
    "left": 0,
    "tif": "gtc",
    "is_reduce_only": false,
    "create_time": 1631763361,
    "finish_time": 1631763397,
    "price": "100"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
None	array	[Options order detail]
» None	object	Options order detail
»» id	integer(int64)	Options order ID
»» user	integer	User ID
»» create_time	number(double)	Creation time of order
»» finish_time	number(double)	Order finished time. Not returned if order is open
»» finish_as	string	How the order was finished. - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC, finish immediately - auto_deleveraged: finished by ADL - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because of position close
»» status	string	Order status - open: waiting to be traded - finished: finished
»» contract	string	Contract name
»» size	integer(int64)	Order size. Specify positive number to make a bid, and negative number to ask
»» iceberg	integer(int64)	Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size
»» price	string	Order price. 0 for market order with tif set as ioc
»» is_close	boolean	Is the order to close position
»» is_reduce_only	boolean	Is the order reduce-only
»» is_liq	boolean	Is the order for liquidation
»» tif	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, reduce-only
»» left	integer(int64)	Size left to be traded
»» fill_price	string	Fill price of the order
»» 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: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance
»» tkfr	string	Taker fee
»» mkfr	string	Maker fee
»» refu	integer	Reference user ID

Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
status	open
status	finished
tif	gtc
tif	ioc
tif	poc

WARNING

To perform this operation, you must be authenticated by API key and secret

Cancel all open orders matched

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/options/orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /options/orders

Cancel all open orders matched

Parameters

Name	In	Type	Required	Description
contract	query	string	false	Contract name
underlying	query	string	false	Underlying
side	query	string	false	All bids or asks. Both included if not specified

Enumerated Values

Parameter	Value
side	ask
side	bid

Example responses

200 Response

[
  {
    "status": "finished",
    "size": -1,
    "id": 2,
    "iceberg": 0,
    "is_liq": false,
    "is_close": false,
    "contract": "BTC_USDT-20210916-5000-C",
    "text": "-",
    "fill_price": "100",
    "finish_as": "filled",
    "left": 0,
    "tif": "gtc",
    "is_reduce_only": false,
    "create_time": 1631763361,
    "finish_time": 1631763397,
    "price": "100"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	All orders matched cancelled	[Inline]

Response Schema

Status Code 200

Name	Type	Description
None	array	[Options order detail]
» None	object	Options order detail
»» id	integer(int64)	Options order ID
»» user	integer	User ID
»» create_time	number(double)	Creation time of order
»» finish_time	number(double)	Order finished time. Not returned if order is open
»» finish_as	string	How the order was finished. - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC, finish immediately - auto_deleveraged: finished by ADL - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because of position close
»» status	string	Order status - open: waiting to be traded - finished: finished
»» contract	string	Contract name
»» size	integer(int64)	Order size. Specify positive number to make a bid, and negative number to ask
»» iceberg	integer(int64)	Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size
»» price	string	Order price. 0 for market order with tif set as ioc
»» is_close	boolean	Is the order to close position
»» is_reduce_only	boolean	Is the order reduce-only
»» is_liq	boolean	Is the order for liquidation
»» tif	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, reduce-only
»» left	integer(int64)	Size left to be traded
»» fill_price	string	Fill price of the order
»» 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: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance
»» tkfr	string	Taker fee
»» mkfr	string	Maker fee
»» refu	integer	Reference user ID

Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
status	open
status	finished
tif	gtc
tif	ioc
tif	poc

WARNING

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/orders/{order_id}

Get a single order

Parameters

Name	In	Type	Required	Description
order_id	path	integer(int64)	true	Order ID returned on successful order creation

Example responses

200 Response

{
  "status": "finished",
  "size": -1,
  "id": 2,
  "iceberg": 0,
  "is_liq": false,
  "is_close": false,
  "contract": "BTC_USDT-20210916-5000-C",
  "text": "-",
  "fill_price": "100",
  "finish_as": "filled",
  "left": 0,
  "tif": "gtc",
  "is_reduce_only": false,
  "create_time": 1631763361,
  "finish_time": 1631763397,
  "price": "100"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Order detail	Inline

Response Schema

Status Code 200

Options order detail

Name	Type	Description
» id	integer(int64)	Options order ID
» user	integer	User ID
» create_time	number(double)	Creation time of order
» finish_time	number(double)	Order finished time. Not returned if order is open
» finish_as	string	How the order was finished. - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC, finish immediately - auto_deleveraged: finished by ADL - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because of position close
» status	string	Order status - open: waiting to be traded - finished: finished
» contract	string	Contract name
» size	integer(int64)	Order size. Specify positive number to make a bid, and negative number to ask
» iceberg	integer(int64)	Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size
» price	string	Order price. 0 for market order with tif set as ioc
» is_close	boolean	Is the order to close position
» is_reduce_only	boolean	Is the order reduce-only
» is_liq	boolean	Is the order for liquidation
» tif	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, reduce-only
» left	integer(int64)	Size left to be traded
» fill_price	string	Fill price of the order
» 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: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance
» tkfr	string	Taker fee
» mkfr	string	Maker fee
» refu	integer	Reference user ID

Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
status	open
status	finished
tif	gtc
tif	ioc
tif	poc

WARNING

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/options/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /options/orders/{order_id}

Cancel a single order

Parameters

Name	In	Type	Required	Description
order_id	path	integer(int64)	true	Order ID returned on successful order creation

Example responses

200 Response

{
  "status": "finished",
  "size": -1,
  "id": 2,
  "iceberg": 0,
  "is_liq": false,
  "is_close": false,
  "contract": "BTC_USDT-20210916-5000-C",
  "text": "-",
  "fill_price": "100",
  "finish_as": "filled",
  "left": 0,
  "tif": "gtc",
  "is_reduce_only": false,
  "create_time": 1631763361,
  "finish_time": 1631763397,
  "price": "100"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Order detail	Inline

Response Schema

Status Code 200

Options order detail

Name	Type	Description
» id	integer(int64)	Options order ID
» user	integer	User ID
» create_time	number(double)	Creation time of order
» finish_time	number(double)	Order finished time. Not returned if order is open
» finish_as	string	How the order was finished. - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC, finish immediately - auto_deleveraged: finished by ADL - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because of position close
» status	string	Order status - open: waiting to be traded - finished: finished
» contract	string	Contract name
» size	integer(int64)	Order size. Specify positive number to make a bid, and negative number to ask
» iceberg	integer(int64)	Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size
» price	string	Order price. 0 for market order with tif set as ioc
» is_close	boolean	Is the order to close position
» is_reduce_only	boolean	Is the order reduce-only
» is_liq	boolean	Is the order for liquidation
» tif	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, reduce-only
» left	integer(int64)	Size left to be traded
» fill_price	string	Fill price of the order
» 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: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance
» tkfr	string	Taker fee
» mkfr	string	Maker fee
» refu	integer	Reference user ID

Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
status	open
status	finished
tif	gtc
tif	ioc
tif	poc

WARNING

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.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/options/my_trades'
query_param = 'underlying=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/my_trades"
query_param="underlying=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /options/my_trades

List personal trading history

Parameters

Name	In	Type	Required	Description
underlying	query	string	true	Underlying
contract	query	string	false	Contract name
limit	query	integer	false	Maximum number of records to be returned in a single list
offset	query	integer	false	List offset, starting from 0
from	query	integer(int64)	false	Start timestamp
to	query	integer(int64)	false	End timestamp

Example responses

200 Response

[
  {
    "underlying_price": "48000",
    "size": 1,
    "contract": "BTC_USDT-20210916-5000-C",
    "id": 1,
    "role": "taker",
    "create_time": 1631763397,
    "order_id": 4,
    "price": "100"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
» id	integer(int64)	Trade ID
» create_time	number(double)	Trading time
» contract	string	Futures contract
» order_id	integer	Order ID related
» size	integer(int64)	Trading size
» price	string	Trading price
» underlying_price	string	Underlying price
» role	string	Trade role. Available values are taker and maker

Enumerated Values

Property	Value
role	taker
role	maker

WARNING

To perform this operation, you must be authenticated by API key and secret

Schemas

CurrencyPair

{
  "id": "string",
  "base": "string",
  "quote": "string",
  "fee": "string",
  "min_base_amount": "string",
  "min_quote_amount": "string",
  "amount_precision": 0,
  "precision": 0,
  "trade_status": "untradable",
  "sell_start": 0,
  "buy_start": 0
}

Spot currency pair

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	Currency pair
base	string	false	none	Base currency
quote	string	false	none	Quote currency
fee	string	false	none	Trading fee
min_base_amount	string	false	none	Minimum amount of base currency to trade, null means no limit
min_quote_amount	string	false	none	Minimum amount of quote currency to trade, null means no limit
amount_precision	integer	false	none	Amount scale
precision	integer	false	none	Price scale
trade_status	string	false	none	How currency pair can be traded - untradable: cannot be bought or sold - buyable: can be bought - sellable: can be sold - tradable: can be bought or sold
sell_start	integer(int64)	false	none	Sell start unix timestamp in seconds
buy_start	integer(int64)	false	none	Buy start unix timestamp in seconds

Enumerated Values

Property	Value
trade_status	untradable
trade_status	buyable
trade_status	sellable
trade_status	tradable

Order

{
  "id": "string",
  "text": "string",
  "create_time": "string",
  "update_time": "string",
  "create_time_ms": 0,
  "update_time_ms": 0,
  "status": "open",
  "currency_pair": "string",
  "type": "limit",
  "account": "spot",
  "side": "buy",
  "amount": "string",
  "price": "string",
  "time_in_force": "gtc",
  "iceberg": "string",
  "auto_borrow": true,
  "auto_repay": true,
  "left": "string",
  "fill_price": "string",
  "filled_total": "string",
  "fee": "string",
  "fee_currency": "string",
  "point_fee": "string",
  "gt_fee": "string",
  "gt_discount": true,
  "rebated_fee": "string",
  "rebated_fee_currency": "string"
}

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(.)
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
account	string	false	none	Account type. spot - use spot account; margin - use margin account; cross_margin - use cross margin account. Portfolio margin account must set to cross-margin
side	string	true	none	Order side
amount	string	true	none	Trade amount
price	string	true	none	Order price
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
iceberg	string	false	none	Amount to display for the iceberg order. Null or 0 for normal orders. Set to -1 to hide the order completely
auto_borrow	boolean	false	write-only	Used in margin or cross margin trading to allow automatic loan of insufficient amount if balance is not enough.
auto_repay	boolean	false	none	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay cannot be both set to true in one order.
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
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_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

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
account	spot
account	margin
account	cross_margin
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok

Loan

{
  "id": "string",
  "create_time": "string",
  "expire_time": "string",
  "status": "open",
  "side": "lend",
  "currency": "string",
  "rate": "string",
  "amount": "string",
  "days": 0,
  "auto_renew": false,
  "currency_pair": "string",
  "left": "string",
  "repaid": "string",
  "paid_interest": "string",
  "unpaid_interest": "string",
  "fee_rate": "string",
  "orig_id": "string",
  "text": "string"
}

Margin loan details

Properties

Name	Type	Required	Restrictions	Description
id	string	false	read-only	Loan ID
create_time	string	false	read-only	Creation time
expire_time	string	false	read-only	Repay time of the loan. No value will be returned for lending loan
status	string	false	read-only	Loan status open - not fully loaned loaned - all loaned out for lending loan; loaned in for borrowing side finished - loan is finished, either being all repaid or cancelled by the lender auto_repaid - automatically repaid by the system
side	string	true	none	Loan side
currency	string	true	none	Loan currency
rate	string	false	none	Loan rate. Only rates in [0.0002, 0.002] are supported. Not required in lending. Market rate calculated from recent rates will be used if not set
amount	string	true	none	Loan amount
days	integer	false	none	Loan days. Only 10 is supported for now
auto_renew	boolean	false	none	Whether to auto renew the loan upon expiration
currency_pair	string	false	none	Currency pair. Required if borrowing
left	string	false	read-only	Amount not lent out yet
repaid	string	false	read-only	Repaid amount
paid_interest	string	false	read-only	Repaid interest
unpaid_interest	string	false	read-only	Outstanding interest yet to be paid
fee_rate	string	false	none	Loan fee rate
orig_id	string	false	none	Original loan ID of the loan if auto-renewed, otherwise equals to id
text	string	false	none	User defined custom ID

Enumerated Values

Property	Value
status	open
status	loaned
status	finished
status	auto_repaid
side	lend
side	borrow

LoanRecord

{
  "id": "string",
  "loan_id": "string",
  "create_time": "string",
  "expire_time": "string",
  "status": "loaned",
  "borrow_user_id": "string",
  "currency": "string",
  "rate": "string",
  "amount": "string",
  "days": 0,
  "auto_renew": false,
  "repaid": "string",
  "paid_interest": "string",
  "unpaid_interest": "string"
}

Margin loaned record details

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	Loan record ID
loan_id	string	false	none	Loan ID the record belongs to
create_time	string	false	none	Loan time
expire_time	string	false	none	Expiration time
status	string	false	none	Loan record status
borrow_user_id	string	false	none	Garbled user ID
currency	string	false	none	Loan currency
rate	string	false	none	Loan rate
amount	string	false	none	Loan amount
days	integer	false	none	Loan days
auto_renew	boolean	false	none	Whether the record will auto renew on expiration
repaid	string	false	none	Repaid amount
paid_interest	string	false	read-only	Repaid interest
unpaid_interest	string	false	read-only	Outstanding interest yet to be paid

Enumerated Values

Property	Value
status	loaned
status	finished

SpotPriceTriggeredOrder

{
  "trigger": {
    "price": "string",
    "rule": ">=",
    "expiration": 0
  },
  "put": {
    "type": "limit",
    "side": "buy",
    "price": "string",
    "amount": "string",
    "account": "normal",
    "time_in_force": "gtc"
  },
  "id": 0,
  "user": 0,
  "market": "string",
  "ctime": 0,
  "ftime": 0,
  "fired_order_id": 0,
  "status": "string",
  "reason": "string"
}

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. Portfolio margin account must set to cross_margin - normal: spot trading - margin: margin trading - cross_margin: cross_margin 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
account	margin
account	cross_margin
time_in_force	gtc
time_in_force	ioc

Contract

{
  "name": "string",
  "type": "inverse",
  "quanto_multiplier": "string",
  "leverage_min": "string",
  "leverage_max": "string",
  "maintenance_rate": "string",
  "mark_type": "internal",
  "mark_price": "string",
  "index_price": "string",
  "last_price": "string",
  "maker_fee_rate": "string",
  "taker_fee_rate": "string",
  "order_price_round": "string",
  "mark_price_round": "string",
  "funding_rate": "string",
  "funding_interval": 0,
  "funding_next_apply": 0,
  "risk_limit_base": "string",
  "risk_limit_step": "string",
  "risk_limit_max": "string",
  "order_size_min": 0,
  "order_size_max": 0,
  "order_price_deviate": "string",
  "ref_discount_rate": "string",
  "ref_rebate_rate": "string",
  "orderbook_id": 0,
  "trade_id": 0,
  "trade_size": 0,
  "position_size": 0,
  "config_change_time": 0,
  "in_delisting": true,
  "orders_limit": 0
}

*Contract detail.

USD value per contract:

• USDT settled contracts： quanto_multiplier x token price
• BTC settled contracts：quanto_multiplier x BTC price x token price*

Properties

Name	Type	Required	Restrictions	Description
name	string	false	none	Futures contract
type	string	false	none	Futures contract type
quanto_multiplier	string	false	none	Multiplier used in converting from invoicing to settlement currency
leverage_min	string	false	none	Minimum leverage
leverage_max	string	false	none	Maximum leverage
maintenance_rate	string	false	none	Maintenance rate of margin
mark_type	string	false	none	Mark price type, internal - based on internal trading, index - based on external index price
mark_price	string	false	none	Current mark price
index_price	string	false	none	Current index price
last_price	string	false	none	Last trading price
maker_fee_rate	string	false	none	Maker fee rate, where negative means rebate
taker_fee_rate	string	false	none	Taker fee rate
order_price_round	string	false	none	Minimum order price increment
mark_price_round	string	false	none	Minimum mark price increment
funding_rate	string	false	none	Current funding rate
funding_interval	integer	false	none	Funding application interval, unit in seconds
funding_next_apply	number(double)	false	none	Next funding time
risk_limit_base	string	false	none	Risk limit base
risk_limit_step	string	false	none	Step of adjusting risk limit
risk_limit_max	string	false	none	Maximum risk limit the contract allowed
order_size_min	integer(int64)	false	none	Minimum order size the contract allowed
order_size_max	integer(int64)	false	none	Maximum order size the contract allowed
order_price_deviate	string	false	none	deviation between order price and current index price. If price of an order is denoted as order_price, it must meet the following condition: abs(order_price - mark_price) <= mark_price * order_price_deviate
ref_discount_rate	string	false	none	Referral fee rate discount
ref_rebate_rate	string	false	none	Referrer commission rate
orderbook_id	integer(int64)	false	none	Current orderbook ID
trade_id	integer(int64)	false	none	Current trade ID
trade_size	integer(int64)	false	none	Historical accumulated trade size
position_size	integer(int64)	false	none	Current total long position size
config_change_time	number(double)	false	none	Last changed time of configuration
in_delisting	boolean	false	none	Contract is delisting
orders_limit	integer	false	none	Maximum number of open orders

Enumerated Values

Property	Value
type	inverse
type	direct
mark_type	internal
mark_type	index

Position

{
  "user": 0,
  "contract": "string",
  "size": 0,
  "leverage": "string",
  "risk_limit": "string",
  "leverage_max": "string",
  "maintenance_rate": "string",
  "value": "string",
  "margin": "string",
  "entry_price": "string",
  "liq_price": "string",
  "mark_price": "string",
  "initial_margin": "string",
  "maintenance_margin": "string",
  "unrealised_pnl": "string",
  "realised_pnl": "string",
  "history_pnl": "string",
  "last_close_pnl": "string",
  "realised_point": "string",
  "history_point": "string",
  "adl_ranking": 0,
  "pending_orders": 0,
  "close_order": {
    "id": 0,
    "price": "string",
    "is_liq": true
  },
  "mode": "single",
  "cross_leverage_limit": "string"
}

Futures position details

Properties

Name	Type	Required	Restrictions	Description
user	integer(int64)	false	read-only	User ID
contract	string	false	read-only	Futures contract
size	integer(int64)	false	read-only	Position size
leverage	string	false	none	Position leverage. 0 means cross margin; positive number means isolated margin
risk_limit	string	false	none	Position risk limit
leverage_max	string	false	read-only	Maximum leverage under current risk limit
maintenance_rate	string	false	read-only	Maintenance rate under current risk limit
value	string	false	read-only	Position value calculated in settlement currency
margin	string	false	none	Position margin
entry_price	string	false	read-only	Entry price
liq_price	string	false	read-only	Liquidation price
mark_price	string	false	read-only	Current mark price
initial_margin	string	false	read-only	The initial margin occupied by the position, applicable to the portfolio margin account
maintenance_margin	string	false	read-only	Maintenance margin required for the position, applicable to portfolio margin account
unrealised_pnl	string	false	read-only	Unrealized PNL
realised_pnl	string	false	read-only	Realized PNL
history_pnl	string	false	read-only	History realized PNL
last_close_pnl	string	false	read-only	PNL of last position close
realised_point	string	false	read-only	Realized POINT PNL
history_point	string	false	read-only	History realized POINT PNL
adl_ranking	integer	false	read-only	ADL ranking, ranging from 1 to 5
pending_orders	integer	false	read-only	Current open orders
close_order	object|null	false	read-only	Current close order if any, or null
» id	integer(int64)	false	none	Close order ID
» price	string	false	none	Close order price
» is_liq	boolean	false	none	Is the close order from liquidation
mode	string	false	none	Position mode, including: - single: dual mode is not enabled- dual_long: long position in dual mode- dual_short: short position in dual mode
cross_leverage_limit	string	false	none	Cross margin leverage(valid only when leverage is 0)

Enumerated Values

Property	Value
mode	single
mode	dual_long
mode	dual_short

FuturesOrder

{
  "id": 0,
  "user": 0,
  "create_time": 0,
  "finish_time": 0,
  "finish_as": "filled",
  "status": "open",
  "contract": "string",
  "size": 0,
  "iceberg": 0,
  "price": "string",
  "close": false,
  "is_close": true,
  "reduce_only": false,
  "is_reduce_only": true,
  "is_liq": true,
  "tif": "gtc",
  "left": 0,
  "fill_price": "string",
  "text": "string",
  "tkfr": "string",
  "mkfr": "string",
  "refu": 0,
  "auto_size": "close_long"
}

Futures order details

Properties

Name	Type	Required	Restrictions	Description
id	integer(int64)	false	read-only	Futures order ID
user	integer	false	read-only	User ID
create_time	number(double)	false	read-only	Creation time of order
finish_time	number(double)	false	read-only	Order finished time. Not returned if order is open
finish_as	string	false	read-only	How the order was finished. - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC, finish immediately - auto_deleveraged: finished by ADL - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because of position close
status	string	false	read-only	Order status - open: waiting to be traded - finished: finished
contract	string	true	none	Futures contract
size	integer(int64)	true	none	Order size. Specify positive number to make a bid, and negative number to ask
iceberg	integer(int64)	false	none	Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size
price	string	false	none	Order price. 0 for market order with tif set as ioc
close	boolean	false	write-only	Set as true to close the position, with size set to 0
is_close	boolean	false	read-only	Is the order to close position
reduce_only	boolean	false	write-only	Set as true to be reduce-only order
is_reduce_only	boolean	false	read-only	Is the order reduce-only
is_liq	boolean	false	read-only	Is the order for liquidation
tif	string	false	none	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, reduce-only - fok: FillOrKill, fill either completely or none
left	integer(int64)	false	read-only	Size left to be traded
fill_price	string	false	read-only	Fill price of the order
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: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance
tkfr	string	false	read-only	Taker fee
mkfr	string	false	read-only	Maker fee
refu	integer	false	read-only	Reference user ID
auto_size	string	false	write-only	Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0

Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok
auto_size	close_long
auto_size	close_short

FuturesPriceTriggeredOrder

{
  "initial": {
    "contract": "string",
    "size": 0,
    "price": "string",
    "close": false,
    "tif": "gtc",
    "text": "string",
    "reduce_only": false,
    "auto_size": "string",
    "is_reduce_only": true,
    "is_close": true
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "string",
    "rule": 1,
    "expiration": 0
  },
  "id": 0,
  "user": 0,
  "create_time": 0,
  "finish_time": 0,
  "trade_id": 0,
  "status": "open",
  "finish_as": "cancelled",
  "reason": "string",
  "order_type": "string",
  "me_order_id": "string"
}

Futures order details

Properties

Name	Type	Required	Restrictions	Description
initial	object	true	none	none
» contract	string	true	none	Futures contract
» size	integer(int64)	false	none	Order size. Positive size means to buy, while negative one means to sell. Set to 0 to close the position
» price	string	true	none	Order price. Set to 0 to use market price
» close	boolean	false	write-only	Set to true if trying to close the position
» tif	string	false	none	Time in force. If using market price, only ioc is supported. - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled
» text	string	false	none	How the order is created. Possible values are: web, api and app
» reduce_only	boolean	false	none	Set to true to create a reduce-only order
» auto_size	string	false	write-only	Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0
» is_reduce_only	boolean	false	read-only	Is the order reduce-only
» is_close	boolean	false	read-only	Is the order to close position
trigger	object	true	none	none
» strategy_type	integer	false	none	How the order will be triggered - 0: by price, which means the order will be triggered if price condition is satisfied - 1: by price gap, which means the order will be triggered if gap of recent two prices of specified price_type are satisfied. Only 0 is supported currently
» price_type	integer(int32)	false	none	Price type. 0 - latest deal price, 1 - mark price, 2 - index price
» price	string	false	none	Value of price on price triggered, or price gap on price gap triggered
» rule	integer(int32)	false	none	Trigger condition type - 1: calculated price based on strategy_type and price_type >= price - 2: calculated price based on strategy_type and price_type <= price
» expiration	integer	false	none	How long (in seconds) to wait for the condition to be triggered before cancelling the order.
id	integer(int64)	false	read-only	Auto order ID
user	integer	false	read-only	User ID
create_time	number(double)	false	read-only	Creation time
finish_time	number(double)	false	read-only	Finished time
trade_id	integer(int64)	false	read-only	ID of the newly created order on condition triggered
status	string	false	read-only	Auto order status - open: order is active - finished: order is finished - inactive: order is not active, only for close-long-order or close-short-order - invalid: order is invalid, only for close-long-order or close-short-order
finish_as	string	false	read-only	How order is finished
reason	string	false	read-only	Additional remarks on how the order was finished
order_type	string	false	none	Take-profit/stop-loss types, which include: - close-long-order: order take-profit/stop-loss, close long position - close-short-order: order take-profit/stop-loss, close short position - close-long-position: position take-profit/stop-loss, close long position - close-short-position: position take-profit/stop-loss, close short position - plan-close-long-position: position planned take-profit/stop-loss, close long position - plan-close-short-position: position planned take-profit/stop-loss, close short position The order take-profit/stop-loss can not be passed by request. These two types are read only.
me_order_id	string	false	read-only	Corresponding order ID of order take-profit/stop-loss.

Enumerated Values

Property	Value
tif	gtc
tif	ioc
strategy_type	0
strategy_type	1
price_type	0
price_type	1
price_type	2
rule	1
rule	2
status	open
status	finished
status	inactive
status	invalid
finish_as	cancelled
finish_as	succeeded
finish_as	failed
finish_as	expired

DeliveryContract

{
  "name": "string",
  "underlying": "string",
  "cycle": "WEEKLY",
  "type": "inverse",
  "quanto_multiplier": "string",
  "leverage_min": "string",
  "leverage_max": "string",
  "maintenance_rate": "string",
  "mark_type": "internal",
  "mark_price": "string",
  "index_price": "string",
  "last_price": "string",
  "maker_fee_rate": "string",
  "taker_fee_rate": "string",
  "order_price_round": "string",
  "mark_price_round": "string",
  "basis_rate": "string",
  "basis_value": "string",
  "basis_impact_value": "string",
  "settle_price": "string",
  "settle_price_interval": 0,
  "settle_price_duration": 0,
  "expire_time": 0,
  "risk_limit_base": "string",
  "risk_limit_step": "string",
  "risk_limit_max": "string",
  "order_size_min": 0,
  "order_size_max": 0,
  "order_price_deviate": "string",
  "ref_discount_rate": "string",
  "ref_rebate_rate": "string",
  "orderbook_id": 0,
  "trade_id": 0,
  "trade_size": 0,
  "position_size": 0,
  "config_change_time": 0,
  "in_delisting": true,
  "orders_limit": 0
}

Futures contract details

Properties

Name	Type	Required	Restrictions	Description
name	string	false	none	Futures contract
underlying	string	false	none	Underlying
cycle	string	false	none	Cycle type, e.g. WEEKLY, QUARTERLY
type	string	false	none	Futures contract type
quanto_multiplier	string	false	none	Multiplier used in converting from invoicing to settlement currency
leverage_min	string	false	none	Minimum leverage
leverage_max	string	false	none	Maximum leverage
maintenance_rate	string	false	none	Maintenance rate of margin
mark_type	string	false	none	Mark price type, internal - based on internal trading, index - based on external index price
mark_price	string	false	none	Current mark price
index_price	string	false	none	Current index price
last_price	string	false	none	Last trading price
maker_fee_rate	string	false	none	Maker fee rate, where negative means rebate
taker_fee_rate	string	false	none	Taker fee rate
order_price_round	string	false	none	Minimum order price increment
mark_price_round	string	false	none	Minimum mark price increment
basis_rate	string	false	none	Fair basis rate
basis_value	string	false	none	Fair basis value
basis_impact_value	string	false	none	Funding used for calculating impact bid, ask price
settle_price	string	false	none	Settle price
settle_price_interval	integer	false	none	Settle price update interval
settle_price_duration	integer	false	none	Settle price update duration in seconds
expire_time	integer(int64)	false	none	Contract expiry timestamp
risk_limit_base	string	false	none	Risk limit base
risk_limit_step	string	false	none	Step of adjusting risk limit
risk_limit_max	string	false	none	Maximum risk limit the contract allowed
order_size_min	integer(int64)	false	none	Minimum order size the contract allowed
order_size_max	integer(int64)	false	none	Maximum order size the contract allowed
order_price_deviate	string	false	none	deviation between order price and current index price. If price of an order is denoted as order_price, it must meet the following condition: abs(order_price - mark_price) <= mark_price * order_price_deviate
ref_discount_rate	string	false	none	Referral fee rate discount
ref_rebate_rate	string	false	none	Referrer commission rate
orderbook_id	integer(int64)	false	none	Current orderbook ID
trade_id	integer(int64)	false	none	Current trade ID
trade_size	integer(int64)	false	none	Historical accumulated trade size
position_size	integer(int64)	false	none	Current total long position size
config_change_time	number(double)	false	none	Last changed time of configuration
in_delisting	boolean	false	none	Contract is delisting
orders_limit	integer	false	none	Maximum number of open orders

Enumerated Values

Property	Value
cycle	WEEKLY
cycle	BI-WEEKLY
cycle	QUARTERLY
cycle	BI-QUARTERLY
type	inverse
type	direct
mark_type	internal
mark_type	index