Gate API v4 v4.46.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.46.0

2023-05-08

• New feature: query spot account book in GET /spot/account_book endpoint
• New feature: query user futures trading fee in GET /futures/{settle}/fee endpoint
• Add is_internal field in GET /futures/{settle}/trades endpoint

v4.45.0

2023-04-21

• The margin loan has been migrated to the Lend & Earn. For more information, please refer to the Margin Migration Instructions
• New feature: Get interest records for the cross margin account in GET /margin/cross/interest_records endpoint.
• New feature: Add Self-Trade Prevention feature in the POST /futures/{settle}/batch_orders endpoint.
• Add futures_in、futures_out two fields in GET /margin/cross/account_book endpoint.

v4.44.0

2023-04-07

• Add ORDER_BOOK_NOT_FOUND and FAILED_RETRIEVE_ASSETS error messages.

v4.43.0

2023-03-27

• New feature: Add Self-Trade Prevention feature in the POST /spot/orders endpoint. Fore more detail, please refer to STP overview
• New feature: Get API key's ip whitelist in GET /account/detail endpoint.
• Add amend_text in PATCH /spot/orders/{order_id} endpoint.
• Add lowest_ask and highest_bid fields in GET /futures/{settle}/tickers endpoint

v4.42.0

2023-03-13

• New feature: add Lend & Earn API
• New feature: Add Self-Trade Prevention feature in the POST /futures/{settle}/orders endpoint. Fore more detail, please refer to STP overview
• Add delivery account type in POST /wallet/sub_account_transfers endpoint
• Add amend_text field in PUT /futures/{settle}/orders/{order_id} endpoint

v4.41.0

2023-03-03

• Add negative_liab, futures_pos_liab, equity, total_freeze, total_liab, portfolio_margin_total_liab, portfolio_margin_total_equity fields in GET /margin/cross/accounts endpoint

v4.40.0

2023-02-24

• New feature: List Auto-Deleveraging history endpoint Get /futures/{settle}/auto_deleverages
• Add sum field in GET /futures/{settle}/candlesticks endpoint

v4.39.0

2023-02-09

• New feature: Query a batch of user trading fee rate endpoint GET /spot/batch_fee
• Add enable_bonus、enable_credit fields in GET /futures/{settle}/contracts endpoint

v4.38.0

2023-02-04

• New feature: time range query for my futures trade endpoint GET /futures/{settle}/my_trades_timerange
• Add withdraw_order_id field in POST /withdrawals endpoint

v4.37.0

2023-01-20

• Add new rebate API endpoints.

v4.36.0

2022-12-23

• Hiding all amount is not supported any more when using iceberg in POST /spot/orders and POST /spot/batch_orders endpoints

v4.35.0

2022-12-09

• New feature: amend order endpoint /spot/orders/{order_id}
• Add avg_deal_price field in GET /spot/orders response
• Add portfolio_margin_total field in ``GET /margin/cross/accounts` response
• Support market order in POST /spot/batch_orders endpoint

v4.34.0

2022-11-25

• Support market order in POST /spot/orders endpoint

v4.33.0

2022-11-11

• New feature: Futures Premium Index endpoint GET /futures/{settle}/premium_index
• Allow to specify password and email when creating a sub-account.

v4.32.0

2022-10-28

• Improve options api document

v4.31.0

2022-10-14

• Allow to transfer futures and cross_margin funds between two sub-accounts in POST /wallet/sub_account_to_sub_account endpoint

v4.30.0

2022-09-23

• New feature: manage sub-accounts API Key
• New feature: lock and unlock sub-account endpoint
• Allow to transfer between two sub-accounts in POST /wallet/sub_account_to_sub_account endpoint

v4.29.0

2022-09-09

• New feature: create and list sub-accounts
• Add settle parameter in GET /wallet/fee endpoint
• Add refr field in option order
• The maximum number of API Keys changes to 20

v4.28.0

2022-08-12

• Add offset parameter in GET /futures/{settle}/trades
• new countdown cancel orders endpoint for spot and futures.

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

Margin Migration Instructions

Between 14:00 (UTC+8) on April 13, 2023 and 14:00 (UTC+8) on April 23, 2023, the platform will gradually migrate the assets that have not been borrowed in the lending market to the Lend & Earn through an automated system process. At the same time, assets that have already been borrowed will be cancelled for automatic lending. After the migration is complete, you can check your investment details in the Lend & Earn. During this period, borrowing funds through the lending market will be temporarily suspended. You can also manually transfer your assets from the lending market to the Lend & Earn to obtain investment returns in advance.

After the automatic migration, the old version of the borrowing and lending endpoint will be deprecated, and the new version of the endpoint can be found in the /margin/uni endpoint group. For detailed endpoint migration, please refer to the following table:"

Margin account related endpoints：

Name	Path	Deprecated	New Path
Margin account list	GET /margin/accounts	No	-
List margin account balance change history	GET /margin/account_book	No	-
Funding account list	GET /margin/funding_accounts	No	-
Update user's auto repayment setting	POST /margin/auto_repay	No	-
Querying user's automatic repayment settings	GET /margin/auto_repay	No	-
Get the max transferable amount for a specific margin currency	GET /margin/transferable	No	-

The margin lending and borrowing related APIs have been migrated to the /margin/uni API group：

Name	Old Path	Deprecated	New Path
List all supported currency pairs supported in margin trading	GET /margin/currency_pairs	Yes	GET /margin/uni/currency_pairs
Query one single margin currency pair	GET /margin/currency_pairs/{currency_pair}	Yes	GET /margin/uni/currency_pairs/{currency_pair}
Lend or borrow	POST /margin/loans	Yes	POST /margin/uni/loans
Retrieve one single loan detail	GET /margin/loans/{loan_id}	Yes	-
List all loans	GET /margin/loans	Yes	GET /margin/uni/loans
Repay a loan	POST /margin/loans/{loan_id}/repayment	Yes	POST /margin/uni/loans
List loan repayment records	GET /margin/loans/{loan_id}/repayment	Yes	GET /margin/uni/loan_records
Get the max borrowable amount for a specific margin currency	GET /margin/borrowable	Yes	GET /margin/uni/borrowable
List interest records	-	-	GET /margin/uni/interest_records

The earn related APIs have been migrated to the /earn/uni API group):

Name	Old Path	Deprecated	New Path
List all supported currency pairs supported in margin trading	GET /margin/currency_pairs	Yes	GET /earn/uni/currencies
Query one single margin currency pair	GET /margin/currency_pairs/{currency_pair}	Yes	GET /earn/uni/currencies/{currency}
Lend or borrow	POST /margin/loans	Yes	POST /earn/uni/lends
List all loans	GET /margin/loans	Yes	GET /earn/uni/lends
Order book of lending loans	GET /margin/funding_book	Yes	-
Merge multiple lending loans	POST /margin/merged_loans	Yes	-
Modify a loan	PATCH /margin/loans/{loan_id}	Yes	PATCH /earn/uni/lends
Cancel lending loan	DELETE /margin/loans/{loan_id}	Yes	POST /earn/uni/lends
List repayment records of a specific loan	GET /margin/loan_records	Yes	GET /earn/uni/lend_records
Get one single loan record	GET /margin/loan_records/{loan_record_id}	Yes	-
Modify a loan record	PATCH /margin/loan_records/{loan_record_id}	Yes	-
List interest records	-	-	GET /earn/uni/interest_records

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 multi-currency margin sharing among multi-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.

Self-Trade Prevention (STP)

Concepts

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

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

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

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

STP Strategies

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

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

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

API Parameter Adjustment

Take placing futures order as an example:

POST /futures/{settle}/orders

New request body parameter:

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

New response fields:

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

User case

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

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

T1: The STP strategy version released.

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

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

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

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

• If stp_act is co , the order placed by taker will be retained, the order status will be open, and the system will cancel the order of maker.

• If stp_act is cb, both the long and short orders will be cancelled. Orders' finish_as will be set to stp. The key response fields returned are:

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

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

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

Error Handling

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

The error response body follows a format like:

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

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

Take Python requests (opens new window) for example, error handling can be written like:

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

import requests

r = requests.get("https://api.gateio.ws/api/v4/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
ORDER_BOOK_NOT_FOUND	Insufficient liquidity
FAILED_RETRIEVE_ASSETS	Failed to retrieve account assets

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

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

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

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

TIP

Note: If the key is named with spot 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='{"withdraw_order_id":"order_123456","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='{"withdraw_order_id":"order_123456","currency":"USDT","address":"1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs","amount":"222.61","memo":"","chain":"TRX"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /withdrawals

Withdraw

Body parameter

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

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» withdraw_order_id	body	string	false	Client order id, up to 32 length and can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
» 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	true	Name of the chain used in withdrawals

Example responses

202 Response

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

Responses

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

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» id	string	Record ID
» txid	string	Hash record of the withdrawal
» withdraw_order_id	string	Client order id, up to 32 length and can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
» timestamp	string	Operation time
» amount	string	Currency amount
» currency	string	Currency name
» address	string	Withdrawal address. Required for withdrawals
» memo	string	Additional remarks with regards to the withdrawal
» status	string	Record status. - DONE: done - CANCEL: cancelled - REQUEST: requesting - MANUAL: pending manual approval - BCODE: GateCode operation - EXTPEND: pending confirm after sending - FAIL: pending confirm when fail - INVALID: invalid order - VERIFY: verifying - PROCES: processing - PEND: pending - DMOVE: required manual approval - SPLITPEND: the order is automatically split due to large amount
» chain	string	Name of the chain used in withdrawals
» 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",
    "withdraw_order_id": "order_123456",
    "currency": "USDT",
    "address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
    "txid": "128988928203223323290",
    "amount": "222.61",
    "memo": "",
    "status": "DONE",
    "chain": "TRX"
  }
]

Responses

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

Response Schema

Status Code 200

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

Enumerated Values

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

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	User ID of sub-account, you can query multiple records separated by ,. If not specified, it will return the records of all sub accounts
from	query	integer(int64)	false	Time range beginning, default to 7 days before current time
to	query	integer(int64)	false	Time range ending, default to current time
limit	query	integer	false	Maximum number of records to be returned in a single list
offset	query	integer	false	List offset, starting from 0

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

Enumerated Values

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

WARNING

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

Sub-account transfers to sub-account

Code samples

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

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

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

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

POST /wallet/sub_account_to_sub_account

Sub-account transfers to sub-account

Body parameter

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

Parameters

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

Enumerated Values

Parameter	Value
» sub_account_from_type	spot
» sub_account_from_type	futures
» sub_account_from_type	cross_margin
» sub_account_to_type	spot
» sub_account_to_type	futures
» sub_account_to_type	cross_margin

Responses

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

WARNING

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

Retrieve withdrawal status

Code samples

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

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

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

WARNING

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

Query 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	User ID of sub-account, you can query multiple records separated by ,. If not specified, it will return the records of all sub accounts

Example responses

200 Response

[
  {
    "uid": "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	User ID of sub-account, you can query multiple records separated by ,. If not specified, it will return the records of all sub accounts
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 is the balance after the user's accumulated deposit, withdraw, profit and loss (including realized profit and loss, fund, fee and referral rebate), excluding unrealized profit and loss. total = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund)
»»» 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(including bonus. Bonus can't be be withdrawn. The transfer amount needs to deduct the bonus)
»»» 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	User ID of sub-account, you can query multiple records separated by ,. If not specified, it will return the records of all sub accounts

Example responses

200 Response

[
  {
    "uid": "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
settle	query	string	false	Specify the settlement currency of the contract to get more accurate rate settings

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

settle: Specify the settlement currency of the contract to get more accurate rate settings

This field is optional. Generally, the rate settings for all settlement currencies are the same.

Enumerated Values

Parameter	Value
settle	BTC
settle	USDT
settle	USD

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

SubAccount

Sub-accounts management

Create a new sub-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 = '/sub_accounts'
query_param = ''
body='{"remark":"remark","login_name":"sub_account_for_trades"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

POST /sub_accounts

Create a new sub-account

Body parameter

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

Parameters

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

Example responses

201 Response

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

Responses

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

Response Schema

Status Code 201

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

WARNING

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

List sub-accounts

Code samples

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

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

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

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

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

GET /sub_accounts

List sub-accounts

Parameters

Name	In	Type	Required	Description
type	query	string	false	0 to list all types of sub-accounts (currently supporting cross margin accounts and sub-accounts).

Detailed descriptions

type: 0 to list all types of sub-accounts (currently supporting cross margin accounts and sub-accounts). 1 to list sub-accounts only. If no parameter is passed, only sub-accounts will be listed by default.

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

WARNING

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

Get the sub-account

Code samples

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

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

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

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

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

GET /sub_accounts/{user_id}

Get the sub-account

Parameters

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

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

WARNING

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

Create API Key of the sub-account

Code samples

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

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

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

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

POST /sub_accounts/{user_id}/keys

Create API Key of the sub-account

Body parameter

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

Parameters

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

Detailed descriptions

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

• wallet: wallet
• spot: spot/margin
• futures: perpetual contract
• delivery: delivery
• earn: earn
• options: options

Enumerated Values

Parameter	Value
»»» name	wallet
»»» name	spot
»»» name	futures
»»» name	delivery
»»» name	earn
»»» name	options

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

Enumerated Values

Property	Value
name	wallet
name	spot
name	futures
name	delivery
name	earn
name	options

WARNING

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

List all API Key of the sub-account

Code samples

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

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

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

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

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

GET /sub_accounts/{user_id}/keys

List all API Key of the sub-account

Parameters

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

Example responses

200 Response

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

Responses

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

WARNING

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

Update API key of the sub-account

Code samples

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

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

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

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

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

Update API key of the sub-account

Body parameter

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

Parameters

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

Detailed descriptions

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

• wallet: wallet
• spot: spot/margin
• futures: perpetual contract
• delivery: delivery
• earn: earn
• options: options

Enumerated Values

Parameter	Value
»»» name	wallet
»»» name	spot
»»» name	futures
»»» name	delivery
»»» name	earn
»»» name	options

Responses

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

WARNING

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

Delete API key of the sub-account

Code samples

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

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

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

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

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

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

Delete API key of the sub-account

Parameters

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

Responses

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

WARNING

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

Get the API Key of the sub-account

Code samples

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

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

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

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

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

Get the API Key of the sub-account

Parameters

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

Example responses

200 Response

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

Responses

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

WARNING

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

Lock the sub-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 = '/sub_accounts/0/lock'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers)
print(r.json())

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

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

POST /sub_accounts/{user_id}/lock

Lock the sub-account

Parameters

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

Responses

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

WARNING

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

Unlock the sub-account

Code samples

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

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

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

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

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

POST /sub_accounts/{user_id}/unlock

Unlock the sub-account

Parameters

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

Responses

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

WARNING

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

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 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 = '/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 currency pair

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(int32)	false	Maximum number of records to be returned in a single list. Default: 100, Minimum: 1, Maximum: 1000
last_id	query	string	false	Specify list staring point using the id of last record in previous list-query results
reverse	query	boolean	false	Whether the id of records to be retrieved should be less than the last_id specified. Default to false.
from	query	integer(int64)	false	Start timestamp of the query
to	query	integer(int64)	false	Time range ending, default to current time
page	query	integer	false	Page number

Detailed descriptions

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

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

No effect if last_id is not specified.

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» id	string	Trade ID
» create_time	string	Trading time
» create_time_ms	string	Trading time, with millisecond precision
» currency_pair	string	Currency pair
» side	string	Order side
» role	string	Trade role. No value in public endpoints
» amount	string	Trade amount
» price	string	Order price
» order_id	string	Related order ID. No value in public endpoints
» fee	string	Fee deducted. No value in public endpoints
» fee_currency	string	Fee currency unit. No value in public endpoints
» point_fee	string	Points used to deduct fee. No value in public endpoints
» gt_fee	string	GT used to deduct fee. No value in public endpoints
» amend_text	string	The custom data that the user remarked when amending the order

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

Query a batch of user trading fee rates

Code samples

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

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

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

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

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

GET /spot/batch_fee

Query a batch of user trading fee rates

Parameters

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

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» additionalProperties	object	none
»» user_id	integer(int64)	User ID
»» taker_fee	string	taker fee rate
»» maker_fee	string	maker fee rate
»» gt_discount	boolean	If GT deduction is enabled
»» gt_taker_fee	string	Taker fee rate if using GT deduction. It will be 0 if GT deduction is disabled
»» gt_maker_fee	string	Maker fee rate if using GT deduction. It will be 0 if GT deduction is disabled
»» loan_fee	string	Loan fee rate of margin lending
»» point_type	string	Point type. 0 - Initial version. 1 - new version since 202009
»» currency_pair	string	Currency pair

WARNING

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

List spot accounts

Code samples

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

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

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

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

GET /spot/account_book

Query account book

Record time range cannot exceed 30 days

Parameters

Name	In	Type	Required	Description
currency	query	string	false	Retrieve data of the specified 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": "margin_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: - deposit: deposit - withdraw: withdrawal - sub_account_transfer: transfer between main and sub accounts - margin_in: transfer to margin account - margin_out: transfer out of margin account - margin_funding_in: transfer to margin funding - margin_funding_out: transfer out of margin funding - cross_margin_in: transfer to cross margin account - cross_margin_out: transfer out of cross margin account - copy_trading_in: transfer to copy trading account - copy_trading_out: transfer out of copy trading account - quant_in: transfer to quant trading - quant_out: transfer out of quant trading - futures_in: transfer to futures account - futures_out: transfer out of futures account - delivery_in: transfer to delivery account - delivery_out: transfer out of delivery account - new_order: new order locked - order_fill: order fills - referral_fee: fee refund from referrals - order_fee: order fee generated from fills - interest: interest - lend: lending - redeem: lending redemption - profit: lending interest payment - flash_swap_buy: flash swap buy - flash_swap_sell: flash swap sell - unknown: unknown type

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,"stp_act":"cn"}]'
# 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,"stp_act":"cn"}]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /spot/batch_orders

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

Parameters

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

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Request is completed	[Inline]

Response Schema

Status Code 200

Name	Type	Description
» None	object	Batch order details
»» text	string	User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- prefix 3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
»» succeeded	boolean	Whether the batch of orders succeeded
»» label	string	Error label, if any, otherwise an empty string
»» message	string	Detailed error message, if any, otherwise an empty string
»» id	string	Order ID
»» create_time	string	Creation time of order
»» update_time	string	Last modification time of order
»» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
»» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
»» status	string	Order status - open: to be filled - closed: filled - cancelled: cancelled
»» currency_pair	string	Currency pair
»» type	string	Order Type - limit : Limit Order - market : Market Order
»» account	string	Account type. spot - use spot account; 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. Hiding all amount is not supported.
»» 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
»» stp_id	integer	Orders between users in the same stp_id group are not allowed to be self-traded 1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker. 2. stp_id returns 0 by default for orders that have not been set for STP group
»» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group, he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy。 2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter。 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, Cancel old orders and keep new ones - cb: Cancel both, Both old and new orders will be cancelled
»» finish_as	string	How the order was finished. - open: processing - filled: filled totally - cancelled: manually cancelled - ioc: time in force is IOC, finish immediately - stp: cancelled because self trade prevention

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
account	spot
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
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	ioc
finish_as	stp

WARNING

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

List all open orders

Code samples

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

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

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
account	spot
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
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	ioc
finish_as	stp

WARNING

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

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

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,"stp_act":"cn"}'
# 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,"stp_act":"cn"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /spot/orders

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. Self Trade Prevention

• Set stp_act to decide the strategy of self-trade prevention. For detailed usage, refer to the stp_act parameter in request body

Body parameter

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

Parameters

Name	In	Type	Required	Description
body	body	Order	true	none
» text	body	string	false	User defined information. If not empty, must follow the rules below:
» currency_pair	body	string	true	Currency pair
» type	body	string	false	Order Type
» account	body	string	false	Account type. spot - use spot account; 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	When type is limit, it refers to base currency. For instance, BTC_USDT means BTC
» price	body	string	false	Price can't be empty when type= limit
» time_in_force	body	string	false	Time in force
» iceberg	body	string	false	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported.
» auto_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:
» stp_act	body	string	false	Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies

Detailed descriptions

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

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

Besides user defined information, reserved contents are listed below, denoting how the order is created:

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

» type: Order Type

• limit : Limit Order
• market : Market Order

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

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

» time_in_force: Time in force

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

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

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

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

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

Enumerated Values

Parameter	Value
» type	limit
» type	market
» 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
» stp_act	cn
» stp_act	co
» stp_act	cb
» stp_act	-

Example responses

201 Response

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

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

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

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 can only be checked when the order is in orderbook. When the order is finished, it can be checked within 1 hour after the end of the order. After that, only order ID is accepted.

Example responses

200 Response

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

Responses

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

WARNING

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

Amend an order

Code samples

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

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

url = '/spot/orders/12345'
query_param = 'currency_pair=BTC_USDT'
body='{"amount":"1","price":"14"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PATCH', host + prefix + url + "?" + query_param, headers=headers, data=body)
print(r.json())

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

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

PATCH /spot/orders/{order_id}

Amend an order

By default, the orders of spot and margin account are updated. If you need to modify orders of the cross-margin account, you must specify account as cross_margin. For portfolio margin account, only cross_margin account is supported.

Currently, only supports modification of price or amount fields.

Regarding rate limiting: modify order and create order sharing rate limiting rules. Regarding matching priority: only modifying the amount does not affect the priority. If the price is modified, the priority will be adjusted to the last of the new price. Note: If the modified amount is less than the fill amount, the order will be cancelled.

Body parameter

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

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» amount	body	string	false	New order amount. amount and price must specify one of them
» price	body	string	false	New order price. amount and Price must specify one of them"
» amend_text	body	string	false	Custom info during amending order
order_id	path	string	true	Order ID returned, or user custom ID(i.e., text field).
currency_pair	query	string	true	Currency pair
account	query	string	false	Specify operation account. 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 can only be checked when the order is in orderbook. When the order is finished, it can be checked within 1 hour after the end of the order. After that, only order ID is accepted.

Example responses

200 Response

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

Responses

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

WARNING

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

Cancel a single order

Code samples

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

host = "https://api.gateio.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 can only be checked when the order is in orderbook. When the order is finished, it can be checked within 1 hour after the end of the order. After that, only order ID is accepted.

Example responses

200 Response

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

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

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

GET /spot/my_trades

List personal trading history

Spot 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. If you don't specify from and/or to parameters, only the last 7 days of data will be retured. The range of from and to is not alloed to exceed 30 days. Time range parameters are handled as order finish time.

Parameters

Name	In	Type	Required	Description
currency_pair	query	string	false	Retrieve results with specified currency pair
limit	query	integer	false	Maximum number of records to be returned in a single list
page	query	integer	false	Page number
order_id	query	string	false	Filter trades with specified order ID. currency_pair is also required if this field is present
account	query	string	false	Specify operation account. Default to spot 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
» amend_text	string	The custom data that the user remarked when amending the order

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

Countdown cancel 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/countdown_cancel_all'
query_param = ''
body='{"timeout":30,"currency_pair":"BTC_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

POST /spot/countdown_cancel_all

Countdown cancel orders

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

Body parameter

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

Parameters

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

Detailed descriptions

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

Example responses

200 Response

{
  "triggerTime": "1660039145000"
}

Responses

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

Response Schema

Status Code 200

triggerTime

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

WARNING

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

Create a price-triggered order

Code samples

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

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

Parameters

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

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Auto order detail	SpotPriceTriggeredOrder

WARNING

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

cancel a price-triggered order

Code samples

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

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

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

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

List all supported currency pairs supported in margin trading(Deprecated)

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(Deprecated)

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(Deprecated)

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(Deprecated)

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(Deprecated)

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(Deprecated)

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 (daily rate)
» amount	string	Borrowable amount
» days	integer	The number of days till the loan repayment's dateline

This operation does not require authentication

Lend or borrow(Deprecated)

Code samples

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

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.0001, 0.01] 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.0001, 0.01] 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(Deprecated)

Code samples

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

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(Deprecated)

Code samples

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

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(Deprecated)

Code samples

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

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&qu