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.
REST API BaseURL:
https://api.gateio.ws/api/v4https://fx-api-testnet.gateio.ws/api/v4https://fx-api.gateio.ws/api/v4Available SDK:
Besides API examples, some SDK provides an additional demo application. The demo application is a relatively complete example demonstrating how to use the SDK. It can be built and run separately. Refer to corresponding repository for details.
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.
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:
Which one to choose:
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.
Provide the above content and submit to mm@gate.io , 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.
If you have any questions or suggestions during the use, you can contact us in any of the following ways:
If you encounter API errors, it is recommended that you sort out the following content, so that we can quickly analyze the problem for you:
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.
v4.85.0
2024-11-11
x-gate-exptime field in POST /futures/{settle}/orders、POST /spot/batch_order header.cross_order_margin、cross_initial_margin、cross_maintenance_margin、cross_unrealised_pnl、cross_available、isolated_position_margin field in POST /futures/{settle}/dual_mode response.v4.84.0
2024-11-04
GET /loan/multi_collateral/current_rate endpoint, Query the current interest rate of the currencylowest_size、highest_size field in GET /spot/tickers responseamount field in POST /earn/dual/orders request bodyv4.83.0
2024-10-28
GET /unified/leverage/user_currency_config endpoint, Query the maximum and minimum leverage multiples
that users can set for a currencyGET /unified/leverage/user_currency_setting endpoint, Get the user's currency leveragePOST /unified/leverage/user_currency_setting endpoint, Set the currency leverage ratioid field in GET /futures/{settle}/account_book responseleverage field in GET /unified/currency_discount_tiers responsev4.82.0
2024-10-14
GET /account/rate_limit endpoint, Get user flow limit information. For details, please refer
to Trade Ratio Rate LimitingGET /account/detail 接口, 返回值增加 copy_trading_role 字段v4.81.0
2024-09-30
POST /options/countdown_cancel_all endpoint, Countdown to cancel ordermessage field in GET /wallet/push responselowest_size、highest_size in GET /futures/{settle}/tickers responsefrom、to in GET /futures/{settle}/funding_rate queryis_max field in POST /earn/dual/orders responsev4.80.0
2024-09-09
GET /options/mmp endpoint, MMP QueryPOST /options/mmp endpoint, MMP SettingsPOST /options/mmp/reset endpoint, MMP Resetblock_number field in GET /wallet/withdrawals responsev4.79.0
2024-09-02
from、to field in GET /unified/interest_records queryoptions field in GET /unified/unified_mode responseoptions field in PUT /unified/unified_mode request bodyv4.78.0
2024-08-19
GET /wallet/push endpoint, Get RecordsPOST /withdrawals/push endpoint, Transfer between spot main accounts. Both parties cannot be
sub-accounts.GET /futures/{settle}/batch_amend_orders endpoint, Batch modify orders with specified IDsclose_size field in GET /futures/{settle}/my_trades responsetx_id field in POST /wallet/transfers responsev4.77.0
2024-08-05
GET /sub_accounts/unified_mode endpoint，Get sub-account modefrom、to field in GET /rebate/broker/commission_history queryfrom、to field in GET /rebate/broker/transaction_history queryv4.76.0
2024-07-22
GET /rebate/partner/sub_list endpoint，Partner subordinate listpage、limit field in GET /flash_swap/currency_pairs queryorder_id、currency_pair、account field in PATCH /spot/orders/{order_id}order_id、currency_pair、account field in DELETE /spot/orders/{order_id}v4.75.1
2024-07-08
GET /delivery/{settle}/risk_limit_tiers endpoint，querying risk limit levelsGET /rebate/partner/transaction_history endpoint，partners to get the transaction history of
recommended usersborrow_type field in GET /unified/loan_records responseaccum_size field in GET /futures/{settle}/position_close responsev4.75.0
2024-06-24
GET /account/debit_fee endpoint，query GT deduction configuration.POST /account/debit_fee endpoint, to enable or disable GT deduction for the current account.v4.74.1
2024-06-11
v4.74.0
2024-05-29
GET /unified/loan_margin_tiers endpoint, list loan margin tiersv4.73.0
2024-05-27
is_all parameter in POST /wallet/small_balance endpointtext field in POST /spot/cancel_batch_orders responsefunding、funding_version、use_funding field in GET /unified/accounts responsev4.72.0
2024-05-13
last_access field in GET /sub_accounts/{user_id}/keys responsecontract field in GET /futures/{settle}/risk_limit_tiers responsev4.71.0
2024-04-23
page parameter in GET /wallet/saved_address endpointGET /api/v4/rebate/user/info endpoint, retrieve user rebate informationPOST /unified/portfolio_calculator endpoint, portfolio margin calculatorGET /unified/risk_units endpoint, retrieve user risk unitPUT /unified/unified_mode endpoint, set unified account modeGET /unified/unified_mode endpoint, retrieve unified account modev4.70.0
2024-04-08
pnl_pnl、pnl_fund、pnl_fee field in GET /futures/{settle}/positions responsepnl_pnl、pnl_fund、pnl_fee field in GET /futures/{settle}/position_close responsev4.69.0
2024-03-25
text field in POST /delivery/{settle}/price_orders responsev4.68.0
2024-03-18
GET /unified/currency_discount_tiers endpoint, list currency discount tierstype parameter in GET /unified/loans endpointtype parameter in GET /unified/interest_records endpointv4.67.0
2024-03-11
filled_amount field in POST /spot/orders,POST /spot/batch_orders response10r/10s to 1r/3s(No modification to the original rate limiting behavior)v4.66.1
2024-02-19
GET /wallet/small_balance endpoint, list small balance.GET /wallet/small_balance_history endpoint, list small balance history.GET /unified/estimate_rate endpoint, get unified estimate rate.v4.65.0
2024-01-29
debit_fee field in GET /spot/batch_fee responseuser_id parameter in DELETE /account/stp_groups/{stp_id}/users endpointACK, RESULT, FULL. For details, please refer
to SPOT APIv4.64.0
2024-01-22
order_type parameter in GET /loan/multi_collateral/orders endpointorder_type,fixed_type,fixed_rate,expire_time,auto_renew,auto_repay field
in GET /loan/multi_collateral/orders responsebefore_ltv,after_ltv field in GET /loan/multi_collateral/repay responseGET /loan/multi_collateral/fixed_rate endpoint, query multi-collateral fix rate.unrealised_pnl,borrowed field in GET /wallet/total_balance responsev4.63.0
2024-01-15
decimal field in GET /wallet/currency_chains responseGET /futures/{settle}/risk_limit_tiers endpoint, list risk limit tiers.v4.62.0
2024-01-02
POST /futures/{settle}/batch_cancel_orders endpoint, users have the ability to batch cancel orders./loan/multi_collateral/**)v4.61.0
2023-12-18
GET /rebate/broker/commission_history
and GET /rebate/broker/commission_history endpointsv4.60.0
2023-12-01
/portfoli/* endpoints are deprecated./earn/**)trade_id field in GET /futures/{settle}/account_book responsev4.59.0
2023-11-22
funding_cap_ratio field in GET /futures/{settle}/contracts responsecontract field in GET /delivery/{settle}/account_book responsewithdraw_percent_on_chains field in GET /wallet/withdraw_status responseleverage field in GET /portfolio/accounts responsev4.58.0
2023-11-03
loanable field in GET /margin/cross/currencies responsebiz_info field in GET /futures/{settle}/orders/{order_id} responsetier field in GET /account/detail responsemax_base_amount、max_quote_amount field in GET /spot/currency_pairs responsev4.57.0
2023-10-20
POST /spot/orders endpointPUT /earn/uni/interest_reinvest endpoint, users have the option to enable or disable interest
reinvestment.POST /spot/amend_batch_orders endpoint, users have the ability to batch modify orders.sequence_id field in GET /spot/trades responsetext field in GET /spot/account_book responsetext field in GET /spot/my_trades responseGET /portfolio/spot/orders、 GET /portfolio/spot/orders、GET /portfolio/spot/orders/{order_id}、DELETE /portfolio/spot/orders/{order_id}
and PATCH /portfolio/spot/orders/{order_id} have been deprecated. We will remove the endpoints by the end of October
2023. Please use /spot/orders instead.v4.56.0
2023-09-25
repayment_type field in GET /margin/cross/repayments and GET /portfolio/loan_records endpoints.holding in GET /futures/{settle}/positions endpointrole in GET /futures/{settle}/my_trades_timerange endpointside and pnl in GET /futures/{settle}/position_close endpointv4.55.0
2023-09-12
POST /portfolio/account_mode endpoint, allow to change the mode.v4.54.0
2023-08-28
contract_address field in GET /wallet/currency_chains endpoint.GET /portfolio/spot/currency_pairs and GET /portfolio/spot/currency_pairs/{currency_pair} endpoints, list
portfolio spot's currency pairs.v4.53.0
2023-08-14
DELETE /account/stp_groups/{stp_id}/users endpointv4.52.0
2023-08-07
v4.51.0
2023-07-29
mode field in GET /account/detail edpoint.v4.50.0
2023-07-14
GET /flash_swap/currency_pairs, list all flash swap currency pairv4.49.0
2023-07-03
GET /futures/{settle}/orders API endpoint, the request field contract has been modified to be optional
instead of mandatory.v4.48.0
2023-06-16
client_order_id fields in GET /wallet/sub_account_transfers edpoint.v4.47.0
2023-05-23
GET /margin/uni/estimate_rate
and GET /margin/cross/estimate_rate endpoints.GET /futures/{settle}/orders_timerange endpointunderlying、underlying_price、mark_iv、delta、gamma、vega、theta fields
in GET /options/positions/{contract} endpoint.v4.46.0
2023-05-08
GET /spot/account_book endpointGET /futures/{settle}/fee endpointis_internal field in GET /futures/{settle}/trades endpointv4.45.0
2023-04-21
Lend & Earn. For more information, please refer to
the Margin Migration InstructionsGET /margin/cross/interest_records endpoint.Self-Trade Prevention feature in the POST /futures/{settle}/batch_orders endpoint.futures_in、futures_out two fields in GET /margin/cross/account_book endpoint.v4.44.0
2023-04-07
ORDER_BOOK_NOT_FOUND and FAILED_RETRIEVE_ASSETS error messages.v4.43.0
2023-03-27
Self-Trade Prevention feature in the POST /spot/orders endpoint. Fore more detail, please refer
to STP overviewGET /account/detail endpoint.amend_text in PATCH /spot/orders/{order_id} endpoint.lowest_ask and highest_bid fields in GET /futures/{settle}/tickers endpointv4.42.0
2023-03-13
Lend & Earn APISelf-Trade Prevention feature in the POST /futures/{settle}/orders endpoint. Fore more detail,
please refer to STP overviewdelivery account type in POST /wallet/sub_account_transfers endpointamend_text field in PUT /futures/{settle}/orders/{order_id} endpointv4.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
Get /futures/{settle}/auto_deleveragessum field in GET /futures/{settle}/candlesticks endpointv4.39.0
2023-02-09
GET /spot/batch_feeenable_bonus、enable_credit fields in GET /futures/{settle}/contracts endpointv4.38.0
2023-02-04
GET /futures/{settle}/my_trades_timerangewithdraw_order_id field in POST /withdrawals endpointv4.37.0
2023-01-20
v4.36.0
2022-12-23
iceberg in POST /spot/orders and POST /spot/batch_orders
endpointsv4.35.0
2022-12-09
/spot/orders/{order_id}avg_deal_price field in GET /spot/orders responseportfolio_margin_total field in ``GET /margin/cross/accounts` responsePOST /spot/batch_orders endpointv4.34.0
2022-11-25
POST /spot/orders endpointv4.33.0
2022-11-11
GET /futures/{settle}/premium_indexv4.32.0
2022-10-28
v4.31.0
2022-10-14
POST /wallet/sub_account_to_sub_account
endpointv4.30.0
2022-09-23
POST /wallet/sub_account_to_sub_account endpointv4.29.0
2022-09-09
settle parameter in GET /wallet/fee endpointrefr field in option orderv4.28.0
2022-08-12
offset parameter in GET /futures/{settle}/tradesv4.27.0
2022-07-29
basis_rate、basis_value fields in GET /delivery/{settle}/tickers responseX-Client-Request-Id http header for tracking requestPOST /futures/{settle}/batch_ordersFOK tif type for futures orderv4.26.0
2022-07-15
GET /wallet/saved_address to list saved addressPOST /wallet/transfers returns tx_id fieldGET /wallet/sub_account_cross_margin_balances to query subaccount's cross_margin accountstatus field in GET /margin/currency_pairs responsev4.25.1
2022-07-06
GET /spot/time endpoint which get system's time info.GET /options/my_settlements endpoint which list my selttlements.change_utc0, change_utc8 fields in GET /spot/tickers endpointv4.25.0
2022-06-24
status field in GET /margin/cross/currencies endpoint, determine whether the cross
currency is disabled 0-disable 1-enablePOST /spot/cross_liquidate_orders spot trading endpoint that close position when the
cross-currency is disabledbouns and history fields in GET /futures/{settle}/accounts endpointtext、fee and point_fee fields in GET /futures/{settle}/my_trades endpointcancel a price-triggered order endpointsPOST /wallet/sub_account_transfers supports transferring to cross_marginv4.24.0
2022-05-20
/flash_swap. Spot operation permission is
required.GET /wallet/sub_account_margin_balances
and GET /wallet/sub_account_futures_balances to help main account retrieving sub accounts'
margin and perpetual contract balancesGET /futures/{settle}/index_constituents/{index} to retrieve index
price constituentsorder_type in FuturesPriceTriggeredOrderv4.23.4
2022-04-25
PUT /futures/{settle}/orders/{order_id} to amend perpetual futures orders30d intervalv4.23.3
2022-04-01
chain field.GET /wallet/currency_chains responsecross_leverage_limit in perpetual contract's dual mode position leverage update APIv4.23.2
2022-01-21
fee in withdrawal and deposit historyCurrencyv4.23.1
2021-12-23
time_in_force FOKFOK_NOT_FILL error labelv4.23.0
2021-12-09
GET /wallet/currency_chains to retrieve chains supported by currencyv4.22.4
2021-11-01
ctime and ftime in SpotPriceTriggeredOrder should be int64v4.22.3
2021-10-27
GET /spot/trades supports time range based query using from and to.v4.22.2
2021-09-29
auto_size in FuturesOrder to support closing dual mode position.v4.22.1
2021-09-07
GET /wallet/total_balance to retrieve all user's estimate balance.locked and risk in margin account responsev4.22.0
2021-08-13
GET /spot/orders and GET /spot/my_trades supports query by time rangev4.21.6
2021-08-12
GET /wallet/deposit_addressv4.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 ordersGET /wallet/withdraw_status responseGET /margin/transferable and GET /margin/cross/transferable to retrieve
maximum transferable amount from margin and cross margin accountfrom and to parameter to specify time range for futures position closes history APIv4.21.4
2021-06-23
GET /margin/cross/account_bookGET /margin/account_book responsev4.21.3
2021-06-17
v4.21.2
2021-06-07
/margin/crosscreate_time_ms and update_time_ms in spot orders.DELETE /withdrawals/{withdrawal_id} to cancel withdrawal operationv4.20.1
2021-04-14
v4.20.0
2021-03-25
/spot/price_ordersv4.19.6
2021-03-22
v4.19.5
2021-03-18
v4.19.4
2021-03-10
/wallet/sub_account_transfers supports transferals with sub user's perpetual contract accountv4.19.3
2021-03-04
/margin/auto_repaymultichain_address in /wallet/deposit_address for currencies with multiple deposit
addressesv4.19.2
2021-03-01
/wallet/fee API to retrieve trading fee. Previous /spot/fee is deprecated in favour of
this one.chain in withdrawal operation.with_id in /futures/{settle}/order_book API and id field in its responseoffset in API /futures/{settle}/position_close to retrieve position close history with
pagination.Contract model for details.v4.18.4
2021-01-22
create_time_ms in spot Trade modelv4.18.1
2021-01-07
/futures/{settle}/contract_statsv4.18.0
2020-12-21
/spot/currencies and /spot/currencies/{currency} to retrieve currency infotop_lsr_account, top_lsr_size, in futures ContractStat model.v4.17.1
2020-12-16
limit in /spot/order_book to 100v4.17.0
2020-12-15
/wallet/sub_account_balances to retrieve sub accounts' balances.v4.16.1
2020-12-10
dual_mode in futures position model which should be mode instead.v4.16.0
2020-12-09
Spot
POST /spot/batch_ordersreverse in GET /spot/trades to trace back trading historyFutures
/futures/{settle}/dual_mode to set
position's dual mode. For dual mode position operations, refer
to /futures/{settle}/dual_comp/positions API groupin_dual_mode in futures account response model;
dual_mode in position response model./futures/{settle}/liq_orders to query liquidated orders in
marketsv4.15.5
2020-11-04
/futures/{settle}/contract_stats API to retrieve contract stats/margin/{currency_pair} to retrieve single margin currency pair detailv4.15.4
2020-09-01
point_type in GET /spot/fee responseGET /wallet/withdraw_status APIv4.15.2
2020-08-12
GET /spot/fee to retrieve spot order trading fee ratesv4.15.1
2020-08-04
GET /spot/open_orders to retrieve all open orders in spot tradingGET /margin/account_book to retrieve margin account balance historyv4.14.1
2020-07-08
text field in order extends to 28(prefix excluded)v4.14.0
2020-07-06
/deliveryv4.13.1
2020-06-28
GET /wallet/sub_account_transfers to list sub account transfer recordsv4.13.0
2020-05-20
POST /withdrawals and "Authentication"
section for details.POST /wallet/transfers supports transferring between spot and futures accountoffset fieldContract model add new field in_delistingv4.12.0
2020-04-08
POST /wallet/sub_account_transfers to support transferring between main and sub accountGET /spot/candlesticks adds query parameters from and to to support retrieving history data
pointsv4.11.2
2020-03-29
filled_total in Order to replace fill_price (the latter is badly named)POC_FILL_IMMEDIATELYv4.11.1
2020-03-23
role in GET /spot/my_trades responseGET /margin/funding_accountsv4.11.0
2020-03-20
pocv4.10.1
2020-02-24
trade_status in spot currency pairv4.10.0
2020-02-17
auto_borrow(write only) to borrow
the insufficient part by the system if balance is not enoughPOST /spot/cancel_batch_orders to support batch cancellation
with specified order IDsv4.9.1
2020-01-07
Order and BatchOrderGET /spot/my_trades responsev4.9.0
2019-12-17
last_id in GET /futures/{settle}/trades is deprecated. Use from and to to retrieve trading
historyv4.8.2
2019-12-02
/spot/batch_orders to support creating a bundle of spot or margin ordersLoan 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
settle in GET /futures/{settle}/positions docs and code snippetv4.8.0
2019-11-07
/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: USDTvolume_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
text in /spot/orders and /futures/orders to support user defined order informationv4.6.3
2019-06-11
v4.7.2
2019-05-29
rate in Loan as non-required for lending side.v4.7.1
2019-04-17
GET /margin/loans can sort by rate and support an optional parameter currency_pairv4.6.2
2019-04-24
GET /futures/orders/{order_id} and DELETE /futures/orders/{order_id}v4.6.1
2019-04-02
high_24h, low_24h and funding_rate_indicative in futures tickerv4.6.0
2019-03-21
SDK related only
v4.5.2
2019-03-14
currency_pair in /spot/order_book should be a required parameterv4.5.1
2019-03-11
v4.5.0
2019-03-05
To avoid version confusion, all versions in APIv4 (documents and SDKs are both included) will start
with 4 from now on
/futures/price_orders for detailshttps://api.gateio.ws/api/v4v1.3.0
2019-02-13
Important update
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
volumn_24h_usd and volume_24h_btc in GET /futures/tickers responsev1.2.0
2019-01-17
GET /futures/contracts/{contract} to get one single contractGET /futures/positions/{contract} to get one single positionGET /futures/account_book to retrieve user account balance historyconfig_change_time in Contract modelv1.1.0
2019-01-08
Contract, Position, FuturesOrderGET /futures/position_close to retrieve position close historyorder_id support for API GET /futures/my_tradesDELETE /futures/orders and DELETE /futures/orders/{order_id} from
204 to 200,
with cancelled order details returned on success.DELETE /futures/orders/{order_id} with invalid order ID or order
that has been finished will return 404 instead of ignoring the errorPOST /futures/orders now supports POC, icebergv1.0.0
2018-12-30
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
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.
Gate.io data center is located in AWS Japan's ap-northeast-1 region.
| 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 |
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 |
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.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.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.All time related fields are unix timestamp in seconds if no extra note, but they may differ in formats(int64, number or string). Possible values like the following may be returned:
The best way to handle time fields is parsing them as a number with decimal places. If higher precision is not needed, you can safely cast them to integer(or long). Our SDKs listed above has already taken proper deserialization to handle them
In every API request, the response header will always include the following fields:
X-In-Time: The timestamp when the API gateway receives a request, in Unix timestamp format, measured in microseconds.
X-Out-Time: The timestamp when the API gateway returns a response, in Unix timestamp format, measured in microseconds.
For example:
X-In-Time: 1695715091540163
X-Out-Time: 1695715091551905
Pagination is achieved using one of the following method
page-limitlimit-offsetIn both method, limit limits the maximum number of records returned in one request. If no
additional explanation, it defaults to 100 if not provided and its maximum value is limited
to 1000.
page starts from 1, mimicking common paging used in web pages. To iterate the whole list, use
the same limit and increment page by 1 until the records' length is shorter than the
limit
offset starts from 0, behaving like common DB search. To iterate the whole list, increment
offset by limit until the records' length is shorter than the limit.
For example, if the total number of orders is 201. Using page-limit method, send request parameters like the following:
page=1&limit=100page=2&limit=100page=3&limit=100Using limit-offset method, send request parameters like:
limit=100&offset=0limit=100&offset=100limit=100&offset=200Some 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 limitX-Pagination-Offset: request offsetX-Pagination-Total: total record number satisfying the request| Markets | Endpoints | Limits | Based On | Include |
|---|---|---|---|---|
| All public endpoints | Public endpoints | 200r/10s per endpoint | IP | Orderbook, Candlestick, Ticker, etc. |
| Wallet | Private endpoints |
Withdrawal(POST /withdrawals) : 1r/3s Transfer between trading accounts (POST /wallet/transfers) 80r/10s Transfer between main and sub accounts (POST /wallet/sub_account_transfers) 80r/10s Transfer from a sub-account to another sub-account (POST /wallet/sub_account_to_sub_account) 80r/10s Retrieve user's total balances (GET /wallet/total_balance) 80r/10s Retrieve sub account balances (GET /wallet/sub_account_balances) 80r/10s Query sub accounts' margin balances (GET /wallet/sub_account_margin_balances) 80r/10s Query sub accounts' futures account balances (GET /wallet/sub_account_futures_balances) 80r/10s Query subaccount's cross_margin account info(GET /wallet/sub_account_cross_margin_balances) 80r/10s The Others: 200r/10s per endpoint | UID |
Withdrawal. Query personal account balance. Query subaccount balance. |
| Spot | Private endpoints |
The rate limit for batch/single order placement and amend an order are total of 10r/s (UID+Market) The rate limit for batch/single order cancellation is total of 200r/s The Others: 200r/10s per endpoint | UID |
Spot order placement and cancellation. Trade history and fee rates. |
| Perpetual Futures | Private endpoints |
After 2024-11-07 (UTC+8), please refer to [Trade Ratio Rate Limiting](#trade-ratio-rate-limiting) The rate limit for batch/single order placement and amend an order are total of 100r/s The maximum rate limit for the order cancellation (bulk/single) is 200r/s The Others: 200r/10s per endpoint | UID |
Futures order placement and cancellation Trade history and fee rates |
| Delivery | Private endpoints |
The maximum rate limit for the order placement (bulk/single) is 500r/10s The maximum rate limit for the order cancellation (bulk/single) is 500r/10s The Others: 200r/10s per endpoint | UID |
Order placement and cancellation |
| Options | Private endpoints |
The maximum rate limit for the order placement (bulk/single) is 200r/s The maximum rate limit for the order cancellation (bulk/single) is 200r/s The Others: 200r/10s per endpoint | UID |
Order placement and cancellation |
| Subaccount | Private endpoints | 80r/10s per endpoint | UID |
Create a sub-account. Retrieve the list of sub-accounts. Disable or enable API key for a sub-account. |
| Unified | Private endpoints | Borrow or repay 15/10s | UID |
Borrow or repay(POST /unified/loans) |
| Other Private endpoints | Private endpoints | 150r/10s per endpoint | UID | Earning, collateral etc |
The rate limit is counted against each sub-account or main account.
Rate Limit
Each request to the API response header will contain the following fields:：
WebSocket:
In order to enhance trading efficiency, we have decided to implement more favorable sub-account rate limits for clients with a higher fill ratio. This assessment will be based on trading data from the past seven days and will be calculated daily at 00:00 UTC. Please note that this rule applies only to clients at VIP level 14 and above.
To facilitate a more refined management of the impact of different trading products on the fill ratio, we have introduced the concept of the symbol multiplier. This multiplier allows us to adjust the influence of each product on the overall trading volume based on its characteristics. For products with a multiplier of less than 1, they typically involve smaller contract sizes and therefore require more trading orders to achieve the same trading volume. Generally, all trading products come with a default multiplier; however, certain products are assigned independent multipliers based on their specific characteristics. For detailed information regarding the multipliers of relevant products, please refer to the provided table.
| Product Typee | Based On | Independnet Symbol Multiplier | Default Symbol Multiplier |
|---|---|---|---|
| USDT-Margined Perpetural Futures | Contract Symbol |
1 Contract Symbol: BTC-USDT ETH-USDT | 0.4 |
| Spot | Currency Pairst |
1 Currency Pairs: BTC-USDT ETH-USDT | 0.4 |
Please note: The spot trading rate limits will not be launched this time.
We will assess the behavior patterns of makers and takers based on market fluctuations and design the trading volume weight ratios accordingly. Additionally, we will regularly evaluate these weights and make synchronized adjustments when necessary.
Current weight of the maker trading volume: 100%, current weight of the taker trading volume: 90%.
The system will take a snapshot of the data at 00:00 UTC daily and, based on this information, will select the higher value between the fill ratio of the sub-account and the overall fill ratio of the main account to determine the future trading rate limit for the sub-account. For exchange brokers, the system will only consider the fill ratio of their sub-accounts. It is important to note that the main account is also considered a "sub-account."
| Contract Frequency Limitation Rules | ||
|---|---|---|
| Tier | Ratio | Rate Limit (uid) |
| Tier 1 | [0,1) | 100r/s |
| Tier 2 | [1,3) | 150r/s |
| Tier 3 | [3,5) | 200r/s |
| Tier 4 | [5,10) | 250r/s |
| Tier 5 | [10,20) | 300r/s |
| Tier 6 | [20,50) | 350r/s |
| Tier 7 | >= 50 | 400r/s |
Please stay tuned for the rate limits for spot trading.
Assuming the client has three accounts, with the symbol multipliers for trading perpetual contract products BTC-USDT and SOL-USDT being 1 and 0.4, respectively.
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 |
| 429 | Too many requests |
| 5xx | Server error |
| 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 |
TIP
The Portfolio Margin Account is no longer maintained, please refer to the new version of the Unified 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.
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.
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)
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.
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 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.
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.
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 |
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"
}
Once a user upgrades their account to the unified account, they can utilize the assets from their spot account as collateral for trading. The assets in the account, denominated in various currencies, will be adjusted based on their liquidity and converted to USD for consistent calculation of the account's assets and position value.
The maximum borrowing limit for margin trading represents the maximum amount that a user can borrow for a given trading market. The platform calculates the user's maximum borrowing limit based on factors such as available margin and platform risk control rules. Once the margin trading generates automatic borrowing, the platform immediately starts accruing interest on the borrowed digital assets.
Currently, the ability to switch to cross_margin orusdt_futures mode is available. In the future, we will gradually introduce support for various combination margin accounts, including Futures, Delivery, Options and more. Stay tuned for further updates.
Please refer to the documentation for unified API. Once you have upgraded your account, you will be able to make use of these endpoints.
Related endpoint can be found in the Unified Account API doc. After enabling the Unified Account, you can proceed to call them. For more detailed information, please refer to here
API KEY or update the permissions of an existing API KEY, checking the unified permissionAPI KEY to call the POST /api/v4/unified/account_mode endpoint, or upgrade from the WEB page to the Unified Account/api/v4/spot/** API for spot-related operations (ordering, modifying orders, querying orders), with the account=unified option/api/v4/futures/** API for perpetual futures-related operations (ordering, modifying orders, querying orders)/api/v4/unified/** API for Unified Account-related operations (account querying, loan querying)The spot trading in the Unified Account is consistent with that in the classical account. In order operations, specify account=unified, or specify account=spot and the system will automatically handle the order as a unified account order when detecting the account as a unified account. For example, to place a buy order for the BTC_USDT currency pair, the order creation request would be similar to
POST /spot/orders
{
"currency_pair": "BTC_USDT",
"account": "unified",
"side": "buy",
...
}
For other related restrictions, please refer to the document of the API endpoint directly.
| Name | Cross Margin |
|---|---|
| portfolio_margin_total_equity | Account Equity = ∑(Equity * Index Price） |
| total_margin_balance | Account Margin Balance = ∑(Positive Equity x Index Price x Adjustment Factor) + ∑(Negative Equity x Index Price) - Haircut Loss |
| total_initial_margin_rate | Account Initial Margin Level = Account Margin Balance / Account Initial Margin |
| total_maintenance_margin_rate | Account Maintenance Margin Level = Account Margin Balance / Account Maintenance Margin |
| total_initial_margin | Account Initial Margin = Total Liabilities x Spot Initial Margin Rate |
| total_maintenance_margin | Account Maintenance Margin = Total Liabilities x Spot Maintenance Margin Rate |
| equity | Equity = Coin Balance - Borrowed |
| available | Available Balance = Principal + Borrowed |
| freeze | Occupied = Assets Occupied by Spot Open Orders |
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 listlabel | Meaning |
|---|---|
| INVALID_PARAM_VALUE | Invalid parameter value |
| INVALID_PROTOCOL | Invalid parameter value |
| INVALID_ARGUMENT | Invalid argument |
| INVALID_REQUEST_BODY | Invalid request body |
| MISSING_REQUIRED_PARAM | Missing required parameter |
| BAD_REQUEST | Invalid request |
| INVALID_CONTENT_TYPE | Invalid Content-Type header |
| NOT_ACCEPTABLE | Invalid Accept- Header |
| METHOD_NOT_ALLOWED | Request method is not allowed |
| NOT_FOUND | Request URL not exists |
label | Meaning |
|---|---|
| INVALID_CREDENTIALS | Invalid credentials provided |
| INVALID_KEY | Invalid API Key |
| IP_FORBIDDEN | Request IP not in whitelist |
| READ_ONLY | API key is read-only |
| INVALID_SIGNATURE | Invalid signature |
| MISSING_REQUIRED_HEADER | Missing required authentication header |
| REQUEST_EXPIRED | Request Timestamp is far from the server time |
| ACCOUNT_LOCKED | Account is locked |
| FORBIDDEN | Account has no permission to request operation |
label | Meaning |
|---|---|
| SUB_ACCOUNT_NOT_FOUND | Sub account not found |
| SUB_ACCOUNT_LOCKED | Sub account is locked |
| MARGIN_BALANCE_EXCEPTION | Abnormal margin account |
| MARGIN_TRANSFER_FAILED | Failed to transfer with margin account |
| TOO_MUCH_FUTURES_AVAILABLE | Futures balance exceeds max allowed |
| FUTURES_BALANCE_NOT_ENOUGH | Futures balance not enough |
| ACCOUNT_EXCEPTION | Abnormal account |
| SUB_ACCOUNT_TRANSFER_FAILED | Failed to transfer with sub account |
| ADDRESS_NOT_USED | Address never being used in web console |
| TOO_FAST | Withdrawing request exceeds frequency limit |
| WITHDRAWAL_OVER_LIMIT | Withdrawal limit exceeded |
| 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 |
| DUPLICATE_REQUEST | Duplicate request |
| ORDER_EXISTS | Order already exists, do not resubmit |
| INVALID_CLIENT_ORDER_ID | The client_order_id is invalid |
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 |
| CANCEL_FAIL | Order cancel failed |
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 |
label | Meaning |
|---|---|
| COL_NOT_ENOUGH | Collateral balance not enough |
| COL_TOO_MUCH | Exceed collateral currency quota |
| INIT_LTV_TOO_HIGH | Init ltv too high |
| REDEEMED_LTV_TOO_HIGH | Ltv too high after redeem |
| BORROWABLE_NOT_ENOUGH | Left borrowable not enough |
| ORDER_TOO_MANY_TOTAL | Exceed platform order count one day |
| ORDER_TOO_MANY_DAILY | Exceed single user order count one day |
| ORDER_TOO_MANY_USER | Exceed single user order count total |
| ORDER_NOT_EXIST | Order id not exist |
| ORDER_FINISHED | Order id finished |
| ORDER_NO_PAY | Order unpaid amount is zero |
| ORDER_EXIST | Order exist |
| ORDER_HISTORY_EXIST | Order history exist |
| ORDER_REPAYING | Order is repaying |
| ORDER_LIQUIDATING | Order is liquidating |
| BORROW_TOO_LITTLE | Less than currency min borrow amount |
| BORROW_TOO_LARGE | Greater than total max borrow amount quantity |
| REPAY_AMOUNT_INVALID | Repay request amount invalid |
| REPAY_GREATER_THAN_AVAILABLE | Repay greater than available |
| POOL_BALANCE_NOT_ENOUGH | Pool balance not enough |
| CURRENCY_SETTLING | Currency settlement in progress |
| RISK_REJECT | Risk reject, please try again later |
| LOAN_FAILED | Loan failed, you can borrow again |
label | Meaning |
|---|---|
| USER_LIAB | User has liab |
| USER_PENDING_ORDERS | User has pending orders |
| MODE_SET | already set portfolio_margin mode |
label | 含义 |
|---|---|
| ERR_BALANCE_NOT_ENOUGH | balance not enough |
| ERR_PRODUCT_SELL_OUT | Target quota reached |
| ERR_PRODUCT_BUY | The project is not yet open for purchase |
| ERR_CREATE_ORDER | Put order fail |
| ERR_QUOTA_LOWER_LIMIT | Not meeting the minimum order amount |
| ERR_QUOTA_SUPERIOR_LIMIT | The maximum order limit has been reached |
| ERR_ORDER_NUMBER_LIMIT | The maximum order quantity has been reached |
| ERR_PRODUCT_CLOSE | Project closed |
| COPIES_NOT_ENOUGH | Not enough shares available to subscribe |
| COPIES_TOO_SMALL | Investment share is too small |
| COPIES_TOO_BIG | The number of investment shares exceeds the upper limit |
| TOTAL_AMOUNT_24 | The total amount of pledge and redemption within 24 hours exceeds the limit |
| TOTAL_BUYCOUNT_24 | Pledge and redemption times exceeding the limit within 24 hours |
| REDEEM_24_LIMIT | Redemption are allowed 24 hours after the last staking |
label | Meaning |
|---|---|
| INTERNAL | Internal server error |
| SERVER_ERROR | Internal server error |
| TOO_BUSY | Server is too busy at the moment |
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.
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).
KEY to the key.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.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,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 in UPPERCASE, e.g. POST, GET
Request url. Protocol, host and port are not included, e.g. /api/v4/futures/orders
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.
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 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.
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 urlcontract=BTC_USD&status=finished&limit=50: keep the query string as it is in the request url1541993715: Unix timestamp in secondsSignature generated
55f84ea195d6fe57ce62464daaa7c3c02fa9d1dde954e4c898289c9a2407a3d6fb3faf24deff16790d726b66ac9f74526668b13bd01029199cc4fcc522418b8a
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：
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)
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 historyGET /delivery/{settle}/account_book?type=dnw to retrieve delivery contract account historyHow 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
POST /wallet/sub_account_transfersPOST /withdrawalsI 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:
Withdrawal operations
Code samples
# coding: utf-8
import 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
Withdrawals to Gate addresses do not incur transaction fees.
Body parameter
{
"withdraw_order_id": "order_123456",
"currency": "USDT",
"address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
"amount": "222.61",
"memo": "",
"chain": "TRX"
}
| 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"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 202 | Accepted (opens new window) | Withdraw request is accepted. Refer to withdrawal records for status | Inline |
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 |
| 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
Code samples
# coding: utf-8
import 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/push'
query_param = ''
body='{"receive_uid":12233,"currency":"USDT","amount":"1.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="/withdrawals/push"
query_param=""
body_param='{"receive_uid":12233,"currency":"USDT","amount":"1.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 /withdrawals/push
UID transfer
Transfers between main spot accounts are allowed; however, both parties cannot be sub-accounts
Body parameter
{
"receive_uid": 12233,
"currency": "USDT",
"amount": "1.1"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » receive_uid | body | integer(int64) | true | Recipient UID |
| » currency | body | string | true | Currency name |
| » amount | body | string | true | Transfer amount |
Example responses
200 Response
{
"id": 111
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | The request has been accepted. Check the withdrawal record status for the processing result. | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Order ID |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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
| 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"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 202 | Accepted (opens new window) | Cancellation accepted. Refer to record status for the cancellation result | Inline |
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 |
| 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
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Currency name |
Example responses
200 Response
[
{
"chain": "ETH",
"name_cn": "以太坊ERC20",
"name_en": "ETH/ERC20",
"contract_address": "",
"is_disabled": 0,
"is_deposit_disabled": 0,
"is_withdraw_disabled": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » chain | string | Chain name |
| » name_cn | string | Chain name in Chinese |
| » name_en | string | Chain name in English |
| » contract_address | string | Smart contract address for the currency; if no address is available, it will be an empty string |
| » is_disabled | integer(int32) | If it is disabled. 0 means NOT being disabled |
| » is_deposit_disabled | integer(int32) | Is deposit disabled. 0 means not |
| » is_withdraw_disabled | integer(int32) | Is withdrawal disabled. 0 means not |
| » decimal | string | Withdrawal precision |
Code samples
# coding: utf-8
import 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
| 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
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Address successfully generated | Inline |
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
Code samples
# coding: utf-8
import 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
| 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",
"block_number": "41575382",
"amount": "222.61",
"fee": "0.01",
"memo": "",
"status": "DONE",
"chain": "TRX"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | string | Record ID |
| » txid | string | Hash record of the withdrawal |
| » block_number | string | 区块编号 |
| » 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 |
| » fee | string | fee |
| » currency | string | Currency name |
| » address | string | Withdrawal address. Required for withdrawals |
| » memo | string | Additional remarks with regards to the withdrawal |
| » status | string | 交易状态 - DONE: 完成 (block_number > 0 才算真的上链完成) - CANCEL: 已取消 - REQUEST: 请求中 - MANUAL: 待人工审核 - BCODE: 充值码操作 - EXTPEND: 已经发送等待确认 - FAIL: 链上失败等待确认 - INVALID: 无效订单 - VERIFY: 验证中 - PROCES: 处理中 - PEND: 处理中 - DMOVE: 待人工审核 - SPLITPEND: cny提现大于5w,自动分单 |
| » chain | string | Name of the chain used in withdrawals |
| 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
Code samples
# coding: utf-8
import 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
| 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 | The maximum number of entries returned in the list is limited to 500 transactions. |
| 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"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
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 |
| 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
Code samples
# coding: utf-8
import 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","settle":""}'
# 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","settle":""}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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:
Body parameter
{
"currency": "BTC",
"from": "spot",
"to": "margin",
"amount": "1",
"currency_pair": "BTC_USDT",
"settle": ""
}
| 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 |
| Parameter | Value |
|---|---|
| » from | spot |
| » from | margin |
| » from | futures |
| » from | delivery |
| » from | options |
| » to | spot |
| » to | margin |
| » to | futures |
| » to | delivery |
| » to | options |
Example responses
200 Response
{
"tx_id": 59636381286
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Balance transferred | Inline |
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
Code samples
# coding: utf-8
import 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='{"client_order_id":"da3ce7a088c8b0372b741419c7829033","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='{"client_order_id":"da3ce7a088c8b0372b741419c7829033","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
{
"client_order_id": "da3ce7a088c8b0372b741419c7829033",
"currency": "BTC",
"sub_account": "10002",
"direction": "to",
"amount": "1",
"sub_account_type": "spot"
}
| 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 |
| » client_order_id | body | string | false | The custom ID provided by the customer serves as a safeguard against duplicate transfers. It can be a combination of letters (case-sensitive), numbers, hyphens '-', and underscores '_', with a length ranging from 1 to 64 characters. |
| » sub_account_type | body | string | false | Target sub user's account. spot - spot account, futures - perpetual contract account, delivery - delivery account |
Example responses
200 Response
{
"tx_id": 59636381286
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Balance transferred | Inline |
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
Code samples
# coding: utf-8
import 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
| 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",
"client_order_id": "da3ce7a088c8b0372b741419c7829033",
"currency": "BTC",
"sub_account": "10002",
"direction": "to",
"amount": "1",
"sub_account_type": "spot"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
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 |
| » client_order_id | string | The custom ID provided by the customer serves as a safeguard against duplicate transfers. It can be a combination of letters (case-sensitive), numbers, hyphens '-', and underscores '_', with a length ranging from 1 to 64 characters. |
| » 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, delivery - delivery account |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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
It is possible to perform balance transfers between two sub-accounts under the same main account. You can use either the API Key of the main account or the API Key of the sub-account to initiate the transfer.
Body parameter
{
"currency": "usdt",
"sub_account_from": "10001",
"sub_account_from_type": "spot",
"sub_account_to": "10002",
"sub_account_to_type": "spot",
"amount": "1"
}
| 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 | The sub-account's outgoing trading account, spot - spot account, futures - perpetual contract account, delivery - delivery contract account. |
| » sub_account_to | body | string | true | Transfer to the user id of the sub-account |
| » sub_account_to_type | body | string | true | The sub-account's incoming trading account, spot - spot account, futures - perpetual contract account, delivery - delivery contract account |
| » amount | body | string | true | Transfer amount |
Example responses
200 Response
{
"tx_id": 59636381286
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Balance transferred | Inline |
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
Code samples
# coding: utf-8
import 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
| 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"
},
"withdraw_percent_on_chains": {
"ETH": "0%",
"GTEVM": "0%"
}
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
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 |
| » withdraw_percent_on_chains | object | Percentage withdrawal fee on multiple chains |
| »» additionalProperties | string | none |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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
| 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"
}
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
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
Code samples
# coding: utf-8
import 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
| 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"
}
}
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
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
Code samples
# coding: utf-8
import 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
| 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"
}
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
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 | The maintenance deposit occupied by the position is suitable for the new classic account margin model and unified account model |
| »»» bonus | string | Perpetual Contract Bonus |
| »»» enable_evolved_classic | boolean | Classic account margin mode, true-new mode, false-old mode |
| »»» cross_order_margin | string | Full -warehouse hanging order deposit, suitable for the new classic account margin model |
| »»» cross_initial_margin | string | The initial security deposit of the full warehouse is suitable for the new classic account margin model |
| »»» cross_maintenance_margin | string | Maintain deposit in full warehouse, suitable for new classic account margin models |
| »»» cross_unrealised_pnl | string | The full warehouse does not achieve profit and loss, suitable for the new classic account margin model |
| »»» cross_available | string | Full warehouse available amount, suitable for the new classic account margin model |
| »»» isolated_position_margin | string | Ware -position margin, suitable for the new classic account margin model |
| »»» 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
Code samples
# coding: utf-8
import 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
| 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"
}
}
}
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
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
Code samples
# coding: utf-8
import 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
| 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 |
| page | query | integer | false | Page number |
Example responses
200 Response
[
{
"currency": "usdt",
"chain": "TRX",
"address": "TWYirLzw2RARB2jfeFcfRPmeuU3rC7rakT",
"name": "gate",
"tag": "",
"verified": "1"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
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
Code samples
# coding: utf-8
import 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
| 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 |
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.
| 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",
"delivery_taker_fee": "0.00016",
"delivery_maker_fee": "-0.00015",
"debit_fee": 3
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
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 |
| » delivery_taker_fee | string | Delivery trading taker fee |
| » delivery_maker_fee | string | Delivery trading maker fee |
| » debit_fee | integer | Deduction types for rates, 1 - GT deduction, 2 - Point card deduction, 3 - VIP rates |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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 balanceGET /margin/accounts to query margin account balanceGET /futures/{settle}/accounts to query futures account balance| 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",
"borrowed": "0.00"
},
"quant": {
"amount": "591702859674467879.6488202650892478553852",
"currency": "USDT"
},
"futures": {
"amount": "2384175.5606114082065",
"currency": "USDT",
"unrealised_pnl": "0.00"
},
"delivery": {
"currency": "USDT",
"amount": "1519804.9756702",
"unrealised_pnl": "0.00"
},
"warrant": {
"amount": "0",
"currency": "USDT"
},
"cbbc": {
"currency": "USDT",
"amount": "0"
}
},
"total": {
"currency": "USDT",
"amount": "633967350312281193.068368815439797304437",
"unrealised_pnl": "0.00",
"borrowed": "0.00"
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request is valid and is successfully responded | Inline |
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 |
| »» unrealised_pnl | string | Unrealised_pnl, this field will only appear in futures, options, delivery, and total accounts |
| »» borrowed | string | Borrowed，this field will only appear in margin and cross_margin accounts |
| » 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 |
| »»» unrealised_pnl | string | Unrealised_pnl, this field will only appear in futures, options, delivery, and total accounts |
| »»» borrowed | string | Borrowed，this field will only appear in margin and cross_margin accounts |
| 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
Code samples
# coding: utf-8
import 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/small_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/small_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/small_balance
List small balance
Example responses
200 Response
[
[
{
"currency": "FLOKI",
"available_balance": "182.29400000",
"estimated_as_btc": "0.00000012",
"convertible_to_gt": "0.001080"
},
{
"currency": "MBLK",
"available_balance": "0.91723337",
"estimated_as_btc": "0.00000102",
"convertible_to_gt": "0.009188"
}
]
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Convert Small Balance |
| »» currency | string | Currency |
| »» available_balance | string | Available balance |
| »» estimated_as_btc | string | Estimated as BTC |
| »» convertible_to_gt | string | Estimated conversion to GT |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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/small_balance'
query_param = ''
body='{"currency":["FLOKI","MBLK"],"is_all":true}'
# 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/small_balance"
query_param=""
body_param='{"currency":["FLOKI","MBLK"],"is_all":true}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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/small_balance
Convert small balance
Body parameter
{
"currency": [
"FLOKI",
"MBLK"
],
"is_all": true
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | array | false | Currency |
| » is_all | body | boolean | false | Whether to exchange all |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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/small_balance_history'
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/small_balance_history"
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/small_balance_history
List small balance history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Currency |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100 |
Example responses
200 Response
[
[
{
"id": "28583810",
"create_time": 1706670777,
"currency": "FLOKI",
"amount": "182.29400000",
"gt_amount": "0.001079"
}
]
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Convert Small Balance |
| »» id | string | Order ID |
| »» currency | string | Currency |
| »» amount | string | amount |
| »» gt_amount | string | GT amount |
| »» create_time | integer(int64) | Exchange time (in seconds) |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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/push'
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/push"
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/push
Retrieve the UID transfer history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | query | integer(int32) | false | Order ID |
| from | query | integer(int32) | false | The start time of the query record. If not specified, it defaults to 7 days forward from the current time, in seconds Unix timestamp |
| to | query | integer(int32) | false | The end time of the query record. If not specified, the default is the current time, which is a Unix timestamp in seconds. |
| limit | query | integer(int32) | false | The maximum number of items returned in the list, the default value is 100 |
| offset | query | integer(int32) | false | List offset, starting from 0 |
Example responses
200 Response
[
{
"id": 111,
"push_uid": 1132,
"receive_uid": 12324,
"currency": "BTC",
"amount": "1.2",
"status": "PENDING",
"create_time": 1706670777,
"message": "The other party has not completed KYC,There is a security risk in your account, please contact customer service"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Order ID |
| » push_uid | integer(int64) | Initiator User ID |
| » receive_uid | integer(int64) | Recipient User ID |
| » currency | string | Currency name |
| » amount | string | Transfer amount |
| » create_time | integer(int64) | Creation time |
| » status | string | Withdrawal Status - CREATING: Creating - PENDING: Waiting for receiving(Please contact the other party to accept the transfer on the Gate official website) - CANCELLING: Cancelling - CANCELLED: Revoked - REFUSING: Rejection - REFUSED: Rejected - RECEIVING: Receiving - RECEIVED: Success |
| » message | string | PENDING Reason Tips |
WARNING
To perform this operation, you must be authenticated by API key and secret
Sub-accounts management
Code samples
# coding: utf-8
import 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"
}
| 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) |
| body | string | false | The sub-account's email address. (Default: the same as main account's email address) |
Example responses
201 Response
{
"remark": "remark",
"login_name": "sub_account_for_trades",
"user_id": 10001,
"state": 1,
"create_time": 168888888
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Created Successfully | Inline |
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) |
| 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
Code samples
# coding: utf-8
import 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
| 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). |
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
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
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) |
| 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
Code samples
# coding: utf-8
import 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
| 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
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successful | Inline |
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) |
| 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
Code samples
# coding: utf-8
import 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='{"mode":1,"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='{"mode":1,"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
{
"mode": 1,
"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"
]
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer(int64) | true | Sub-account user id |
| body | body | SubAccountKey | true | none |
| » mode | body | integer(int32) | false | Mode: 1 - classic 2 - portfolio account |
| » name | body | string | false | API key name |
| » perms | body | array | 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) |
»» name: Permission name (all permissions will be removed if no value is passed)
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"
],
"mode": 1,
"secret": "cddcc6e5e78060e013860bdbe5e737830b96821c027664586fb38b411808f4fd",
"key": "eb8815bf99d7bb5f8ad6497bdc4774a8",
"created_at": 1663683330,
"updated_at": 1663683330
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Created Successfully | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » user_id | string | User ID |
| » mode | integer(int32) | Mode: 1 - classic 2 - portfolio account |
| » name | string | API key name |
| » perms | array | 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 - custody: custody - options: options - account: Account - unified: unified - loan: Loan - margin: margin - unified: unified - copy: copy - pilot：pilot |
| »» 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 | integer(int64) | Creation time |
| » updated_at | integer(int64) | Last update time |
| » last_access | integer(int64) | Last access time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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
| 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
}
],
"mode": 1,
"ip_whitelist": [
"127.0.0.1",
"127.0.0.2"
],
"key": "75c3264105b74693d8cb5c7f1a8e2420",
"created_at": 1663642892,
"last_access": 1663642892,
"update_at": 1663642892
}
]
| 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
Code samples
# coding: utf-8
import 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='{"mode":1,"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='{"mode":1,"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
{
"mode": 1,
"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"
]
}
| 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 |
| » mode | body | integer(int32) | false | Mode: 1 - classic 2 - portfolio account |
| » name | body | string | false | API key name |
| » perms | body | array | 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) |
»» name: Permission name (all permissions will be removed if no value is passed)
| 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
Code samples
# coding: utf-8
import 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
| 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 |
| 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
Code samples
# coding: utf-8
import 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
| 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
}
],
"mode": 1,
"ip_whitelist": [
"127.0.0.1",
"127.0.0.2"
],
"key": "75c3264105b74693d8cb5c7f1a8e2420",
"created_at": 1663642892,
"last_access": 1663642892,
"update_at": 1663642892
}
| 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
Code samples
# coding: utf-8
import 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer(int64) | true | The user id of the sub-account |
| 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
Code samples
# coding: utf-8
import 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer(int64) | true | The user id of the sub-account |
| 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
Code samples
# coding: utf-8
import 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/unified_mode'
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/unified_mode"
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/unified_mode
Get sub-account mode
Unified account mode：
classic: Classic account modemulti_currency: Multi-currency margin modeportfolio: Portfolio margin modeExample responses
200 Response
[
{
"user_id": 110285555,
"is_unified": true,
"mode": "multi_currency"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » user_id | integer(int64) | User ID |
| » is_unified | boolean | Is it a unified account? |
| » mode | string | Unified account mode： - classic: Classic account mode- multi_currency: Multi-currency margin mode- portfolio: Portfolio margin mode |
WARNING
To perform this operation, you must be authenticated by API key and secret
Unified 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 = '/unified/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="/unified/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 /unified/accounts
Get unified account information
The assets of each currency in the account will be adjusted according to their liquidity, defined by corresponding adjustment coefficients, and then uniformly converted to USD to calculate the total asset value and position value of the account.
You can refer to the Formula in the documentation
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Retrieve data of the specified currency |
Example responses
200 Response
{
"user_id": 10001,
"locked": false,
"balances": {
"ETH": {
"available": "0",
"freeze": "0",
"borrowed": "0.075393666654",
"negative_liab": "0",
"futures_pos_liab": "0",
"equity": "1016.1",
"total_freeze": "0",
"total_liab": "0",
"spot_in_use": "1.111"
},
"POINT": {
"available": "9999999999.017023138734",
"freeze": "0",
"borrowed": "0",
"negative_liab": "0",
"futures_pos_liab": "0",
"equity": "12016.1",
"total_freeze": "0",
"total_liab": "0",
"spot_in_use": "12"
},
"USDT": {
"available": "0.00000062023",
"freeze": "0",
"borrowed": "0",
"negative_liab": "0",
"futures_pos_liab": "0",
"equity": "16.1",
"total_freeze": "0",
"total_liab": "0",
"spot_in_use": "12"
}
},
"total": "230.94621713",
"borrowed": "161.66395521",
"total_initial_margin": "1025.0524665088",
"total_margin_balance": "3382495.944473949183",
"total_maintenance_margin": "205.01049330176",
"total_initial_margin_rate": "3299.827135672679",
"total_maintenance_margin_rate": "16499.135678363399",
"total_available_margin": "3381470.892007440383",
"unified_account_total": "3381470.892007440383",
"unified_account_total_liab": "0",
"unified_account_total_equity": "100016.1",
"leverage": "2",
"spot_order_loss": "12",
"spot_hedge": false
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » user_id | integer(int64) | User ID |
| » refresh_time | integer(int64) | Time of the most recent refresh |
| » locked | boolean | Whether account is locked |
| » balances | object | none |
| »» UnifiedBalance | object | none |
| »»» available | string | Available amount |
| »»» freeze | string | Locked amount |
| »»» borrowed | string | Borrowed amount |
| »»» negative_liab | string | Negative Liabilities |
| »»» futures_pos_liab | string | Contract opening position borrowing currency (abandoned, to be offline field) |
| »»» equity | string | Equity |
| »»» total_freeze | string | Total occupancy (discarded, to be offline field) |
| »»» total_liab | string | Total liabilities |
| »»» spot_in_use | string | Spot hedging utilization |
| »»» funding | string | Quantity of funding |
| »»» funding_version | string | Funding version |
| »» total | string | Total account assets converted to USD, i.e. the sum of (available + freeze) * price in all currencies (deprecated, to be deprecated, replaced by unified_account_total) |
| »» borrowed | string | The total borrowed amount in USD, calculated as the sum of the product of borrowed * price for all currencies (excluding points cards). |
| »» 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 |
| »» unified_account_total | string | Total amount of the portfolio margin account |
| »» unified_account_total_liab | string | Total liabilities of the portfolio margin account |
| »» unified_account_total_equity | string | Total equity of the portfolio margin account |
| »» leverage | string | Leverage |
| »» spot_order_loss | string | Total order loss, in USDT |
| »» spot_hedge | boolean | Spot hedging status, true - enabled, false - not enabled. |
| »» use_funding | boolean | Whether to use funds as margin |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/account_mode'
query_param = ''
body='{"mode":"cross_margin","enabled":true}'
# 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="/unified/account_mode"
query_param=""
body_param='{"mode":"cross_margin","enabled":true}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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 /unified/account_mode
Set unified account mode (deprecated)
Body parameter
{
"mode": "cross_margin",
"enabled": true
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » mode | body | string | true | Portfolio mode |
| » enabled | body | boolean | true | Is it enabled? |
» mode: Portfolio mode
Example responses
200 Response
{
"cross_margin": true,
"usdt_futures": true
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » additionalProperties | boolean | none |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/account_mode'
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="/unified/account_mode"
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 /unified/account_mode
Inquire about unified account mode (deprecated)
cross_margin - Spot full-margin trading, usdt_futures - USDT perpetual futures
Example responses
200 Response
{
"cross_margin": true,
"usdt_futures": true
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » additionalProperties | boolean | none |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/borrowable'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/unified/borrowable"
query_param="currency=BTC"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /unified/borrowable
Query about the maximum borrowing for the unified account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Retrieve data of the specified currency |
Example responses
200 Response
{
"currency": "ETH",
"amount": "10000"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
UnifiedBorrowable
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency detail |
| » amount | string | Max borrowable amount |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/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="/unified/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 /unified/transferable
Query about the maximum transferable for the unified account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Retrieve data of the specified currency |
Example responses
200 Response
{
"currency": "ETH",
"amount": "10000"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
UnifiedTransferable
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency detail |
| » amount | string | The maximum amount that can be transferred out |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/loans'
query_param = ''
body='{"currency":"BTC","amount":"0.1","type":"borrow","repaid_all":false,"text":"t-test"}'
# 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="/unified/loans"
query_param=""
body_param='{"currency":"BTC","amount":"0.1","type":"borrow","repaid_all":false,"text":"t-test"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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 /unified/loans
Borrow or repay
When borrowing, it is essential to ensure that the borrowed amount is not below the minimum borrowing threshold for the specific cryptocurrency and does not exceed the maximum borrowing limit set by the platform and the user.
The interest on the loan will be automatically deducted from the account at regular intervals. It is the user's responsibility to manage the repayment of the borrowed amount.
For repayment, the option to repay the entire borrowed amount is available by setting the parameter repaid_all=true
Body parameter
{
"currency": "BTC",
"amount": "0.1",
"type": "borrow",
"repaid_all": false,
"text": "t-test"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Currency |
| » type | body | string | true | type: borrow - borrow, repay - repay |
| » amount | body | string | true | The amount of lending or repaying |
| » repaid_all | body | boolean | false | Full repayment is solely for repayment operations. When set to 'true,' it overrides the 'amount,' allowing for direct full repayment. |
| » text | body | string | false | User defined custom ID |
| Parameter | Value |
|---|---|
| » type | borrow |
| » type | repay |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Operated successfully | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/loans'
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="/unified/loans"
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 /unified/loans
List loans
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Retrieve data of the specified currency |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100 |
| type | query | string | false | Loan type, platform - platform, margin - margin |
Example responses
200 Response
[
{
"currency": "USDT",
"currency_pari": "GT_USDT",
"amount": "1",
"type": "margin",
"change_time": 1673247054000,
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Loan] |
| » None | object | Loan |
| »» currency | string | Currency |
| »» currency_pair | string | Currency pair |
| »» amount | string | amount |
| »» type | string | Loan type, platform - platform, margin - margin |
| »» create_time | integer(int64) | Created time |
| »» update_time | integer(int64) | Updated time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/loan_records'
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="/unified/loan_records"
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 /unified/loan_records
Get load records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| type | query | string | false | The types of lending records, borrow - indicates the action of borrowing funds, repay - indicates the action of repaying the borrowed funds |
| currency | query | string | false | Retrieve data of the specified currency |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100 |
Example responses
200 Response
[
{
"id": 16442,
"type": "borrow",
"margin_mode": "cross",
"currency_pair": "AE_USDT",
"currency": "USDT",
"amount": "1000",
"create_time": 1673247054000,
"repayment_type": "auto_repay"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Loan records |
| »» id | integer(int64) | id |
| »» type | string | type: borrow - borrow, repay - repay |
| »» repayment_type | string | Repayment type: none - no repayment type, manual_repay - manual repayment, auto_repay - automatic repayment, cancel_auto_repay - automatic repayment after cancellation |
| »» borrow_type | string | Loan type, returned when querying loan records. manual_borrow - Manual repayment , auto_borrow - Automatic repayment |
| »» currency_pair | string | Currency pair |
| »» currency | string | Currency |
| »» amount | string | The amount of lending or repaying |
| »» create_time | integer(int64) | Created time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/interest_records'
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="/unified/interest_records"
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 /unified/interest_records
List interest records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Retrieve data of the specified currency |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100 |
| from | query | integer(int64) | false | Start timestamp of the query |
| to | query | integer(int64) | false | Time range ending, default to current time |
| type | query | string | false | Loan type, platform loan - platform, leverage loan - margin, if not passed, defaults to margin |
Example responses
200 Response
[
{
"status": 1,
"currency_pair": "BTC_USDT",
"currency": "USDT",
"actual_rate": "0.00000236",
"interest": "0.00006136",
"type": "platform",
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Interest record] |
| » None | object | Interest record |
| »» currency | string | Currency name |
| »» currency_pair | string | Currency pair |
| »» actual_rate | string | Actual rate |
| »» interest | string | Interest |
| »» status | integer | Status: 0 - fail, 1 - success |
| »» type | string | Type, platform - platform，margin - margin |
| »» create_time | integer(int64) | Created time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/risk_units'
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="/unified/risk_units"
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 /unified/risk_units
Retrieve user risk unit details, only valid in portfolio margin mode
Example responses
200 Response
{
"user_id": 0,
"spot_hedge": true,
"risk_units": [
{
"symbol": "BTC",
"spot_in_use": "-13500.000001223",
"maintain_margin": "2334.002",
"initial_margin": "2334.002",
"delta": "0.22",
"gamma": "0.42",
"theta": "0.29",
"vega": "0.22"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » user_id | integer(int64) | User ID |
| » spot_hedge | boolean | Spot hedging status, true - enabled, false - not enabled. |
| » risk_units | array | Risk unit |
| »» RiskUnits | object | none |
| »»» symbol | string | Risk unit flag |
| »»» spot_in_use | string | Spot hedging utilization |
| »»» maintain_margin | string | Maintenance margin for risk unit |
| »»» initial_margin | string | Initial margin for risk unit |
| »»» delta | string | Total Delta of risk unit |
| »»» gamma | string | Total Gamma of risk unit |
| »»» theta | string | Total Theta of risk unit |
| »»» vega | string | Total Vega of risk unit |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/unified_mode'
query_param = ''
body='{"mode":"portfolio","settings":{"spot_hedge":true,"usdt_futures":true,"options":true}}'
# 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="/unified/unified_mode"
query_param=""
body_param='{"mode":"portfolio","settings":{"spot_hedge":true,"usdt_futures":true,"options":true}}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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 /unified/unified_mode
Set mode of the unified account
Switching between different account modes requires only passing the parameters n\corresponding to the target account mode. It also supports opening or closing configuration switches for the corresponding account mode when switching- When enabling classic account mode,mode=classic
PUT /unified/unified_mode
{
"mode": "classic"
}
PUT /unified/unified_mode
{
"mode": "multi_currency",
"settings": {
"usdt_futures": true
}
}
PUT /unified/unified_mode
{
"mode": "portfolio",
"settings": {
"spot_hedge": true
}
}
Body parameter
{
"mode": "portfolio",
"settings": {
"spot_hedge": true,
"usdt_futures": true,
"options": true
}
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » mode | body | string | true | Unified account mode: |
| » settings | body | object | false | none |
| »» usdt_futures | body | boolean | false | USDT contract switch. If not transmitted, the current switch value is used. If not transmitted for the first time, the default value is off. |
| »» spot_hedge | body | boolean | false | Spot hedging switch. If not transmitted, the current switch value is used. If not transmitted for the first time, the default value is off. |
| »» use_funding | body | boolean | false | When the mode is set to combined margin mode, will funds be used as margin |
| »» options | body | boolean | false | Option switch. If not transmitted, the current switch value is used. If not transmitted for the first time, the default value is off. |
» mode: Unified account mode:
classic: Classic account modemulti_currency: Multi-currency margin modeportfolio: Portfolio margin mode| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Success | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/unified_mode'
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="/unified/unified_mode"
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 /unified/unified_mode
Query mode of the unified account
Unified account mode：
classic: Classic account modemulti_currency: Multi-currency margin modeportfolio: Portfolio margin modeExample responses
200 Response
{
"mode": "portfolio",
"settings": {
"spot_hedge": true,
"usdt_futures": true,
"options": true
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » mode | string | Unified account mode: - classic: Classic account mode- multi_currency: Multi-currency margin mode- portfolio: Portfolio margin mode |
| » settings | object | none |
| »» usdt_futures | boolean | USDT contract switch. If not transmitted, the current switch value is used. If not transmitted for the first time, the default value is off. |
| »» spot_hedge | boolean | Spot hedging switch. If not transmitted, the current switch value is used. If not transmitted for the first time, the default value is off. |
| »» use_funding | boolean | When the mode is set to combined margin mode, will funds be used as margin |
| »» options | boolean | Option switch. If not transmitted, the current switch value is used. If not transmitted for the first time, the default value is off. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/estimate_rate'
query_param = 'currencies=BTC,GT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/unified/estimate_rate"
query_param="currencies=BTC,GT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /unified/estimate_rate
Get unified estimate rate
Due to fluctuations in lending depth, hourly interest rates may vary, and thus, I cannot provide exact rates. When a currency is not supported, the interest rate returned will be an empty string.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currencies | query | array[string] | true | Specify the currency names for querying in an array, separated by commas, with a maximum of 10 currencies. |
Example responses
200 Response
{
"BTC": "0.000002",
"GT": "0.000001",
"ETH": ""
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
Estimate the current hourly lending rates, categorized by currency
| Name | Type | Description |
|---|---|---|
| » additionalProperties | string | none |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/currency_discount_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/unified/currency_discount_tiers \
-H 'Accept: application/json'
GET /unified/currency_discount_tiers
List currency discount tiers
Example responses
200 Response
[
[
{
"currency": "USDT",
"discount_tiers": [
{
"tier": "1",
"discount": "1",
"lower_limit": "0",
"leverage": "10",
"upper_limit": "+"
}
]
},
{
"currency": "USDC",
"discount_tiers": [
{
"tier": "1",
"discount": "1",
"lower_limit": "0",
"leverage": "10",
"upper_limit": "10000000"
},
{
"tier": "2",
"discount": "0.98",
"lower_limit": "10000000",
"leverage": "10",
"upper_limit": "15000000"
},
{
"tier": "3",
"discount": "0.95",
"lower_limit": "15000000",
"leverage": "10",
"upper_limit": "20000000"
},
{
"tier": "4",
"discount": "0.925",
"lower_limit": "20000000",
"leverage": "10",
"upper_limit": "50000000"
},
{
"tier": "5",
"discount": "0.9",
"lower_limit": "50000000",
"leverage": "10",
"upper_limit": "100000000"
},
{
"tier": "6",
"discount": "0",
"lower_limit": "100000000",
"leverage": "10",
"upper_limit": "+"
}
]
},
{
"currency": "BTC",
"discount_tiers": [
{
"tier": "1",
"discount": "0.98",
"lower_limit": "0",
"leverage": "10",
"upper_limit": "1000"
},
{
"tier": "2",
"discount": "0.95",
"lower_limit": "1000",
"leverage": "10",
"upper_limit": "10000"
},
{
"tier": "3",
"discount": "0.9",
"lower_limit": "10000",
"leverage": "10",
"upper_limit": "50000"
},
{
"tier": "4",
"discount": "0.85",
"lower_limit": "50000",
"leverage": "10",
"upper_limit": "+"
}
]
},
{
"currency": "ETH",
"discount_tiers": [
{
"tier": "1",
"discount": "0.98",
"lower_limit": "0",
"leverage": "10",
"upper_limit": "1000"
},
{
"tier": "2",
"discount": "0.95",
"lower_limit": "1000",
"leverage": "10",
"upper_limit": "10000"
},
{
"tier": "3",
"discount": "0.9",
"lower_limit": "10000",
"leverage": "10",
"upper_limit": "50000"
},
{
"tier": "4",
"discount": "0.85",
"lower_limit": "50000",
"leverage": "10",
"upper_limit": "+"
}
]
}
]
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Currency discount tiers |
| »» currency | string | Currency name |
| »» discount_tiers | array | Tiered discount |
| »»» tier | string | Tier |
| »»» discount | string | Discount |
| »»» lower_limit | string | Lower limit |
| »»» upper_limit | string | Upper limit,＋ indicates positive infinity |
| »»» leverage | string | Position leverage |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/loan_margin_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/unified/loan_margin_tiers \
-H 'Accept: application/json'
GET /unified/loan_margin_tiers
List loan margin tiers
Example responses
200 Response
[
{
"currency": "USDT",
"margin_tiers": [
{
"tier": "1",
"margin_rate": "0.02",
"lower_limit": "200000",
"upper_limit": "400000",
"leverage": "3"
}
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Unified margin tiers |
| »» currency | string | Currency name |
| »» margin_tiers | array | Margin tiers |
| »»» MarginTiers | object | none |
| »»»» tier | string | Tier |
| »»»» margin_rate | string | Discount |
| »»»» lower_limit | string | Lower limit |
| »»»» upper_limit | string | Upper limit, "" indicates greater than (the last tier) |
| »»»» leverage | string | Position leverage |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/portfolio_calculator'
query_param = ''
body='{"spot_balances":[{"currency":"BTC","equity":"-1","freeze":"10"}],"spot_orders":[{"currency_pairs":"BTC_USDT","order_price":"344","size":"100","left":"100","type":"sell"}],"futures_positions":[{"contract":"BTC_USDT","size":"100"}],"futures_orders":[{"contract":"BTC_USDT","size":"10","left":"8"}],"options_positions":[{"options_name":"BTC_USDT-20240329-32000-C","size":"10"}],"options_orders":[{"options_name":"BTC_USDT-20240329-32000-C","size":"100","left":"80"}],"spot_hedge":false}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST https://api.gateio.ws/api/v4/unified/portfolio_calculator \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /unified/portfolio_calculator
Portfolio margin calculator
Portfolio Margin Calculator When inputting a simulated position portfolio, each position includes the position name and quantity held, supporting markets within the range of BTC and ETH perpetual contracts, options, and spot markets. When inputting simulated orders, each order includes the market identifier, order price, and order quantity, supporting markets within the range of BTC and ETH perpetual contracts, options, and spot markets. Market orders are not included.
Body parameter
{
"spot_balances": [
{
"currency": "BTC",
"equity": "-1",
"freeze": "10"
}
],
"spot_orders": [
{
"currency_pairs": "BTC_USDT",
"order_price": "344",
"size": "100",
"left": "100",
"type": "sell"
}
],
"futures_positions": [
{
"contract": "BTC_USDT",
"size": "100"
}
],
"futures_orders": [
{
"contract": "BTC_USDT",
"size": "10",
"left": "8"
}
],
"options_positions": [
{
"options_name": "BTC_USDT-20240329-32000-C",
"size": "10"
}
],
"options_orders": [
{
"options_name": "BTC_USDT-20240329-32000-C",
"size": "100",
"left": "80"
}
],
"spot_hedge": false
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » spot_balances | body | array | false | Spot |
| »» None | body | object | false | Spot |
| »»» currency | body | string | true | Currency name |
| »»» equity | body | string | true | Currency equity, where equity = balance - borrowed, represents the net delta exposure |
| »» spot_orders | body | array | false | Spot orders |
| »»» None | body | object | false | Spot orders |
| »»»» currency_pairs | body | string | true | Currency pair |
| »»»» order_price | body | string | true | Price |
| »»»» count | body | string | false | Initial order quantity for spot trading pairs, not involved in actual calculation. |
| »»»» left | body | string | true | Unfilled quantity, involved in actual calculation. |
| »»»» type | body | string | true | Order type, sell - sell order, buy - buy order. |
| »»» futures_positions | body | array | false | Futures positions |
| »»»» None | body | object | false | Futures positions |
| »»»»» contract | body | string | true | Futures name, currently only supports perpetual futures for BTC and ETH with USDT. |
| »»»»» size | body | string | true | Position size, measured in contract units. |
| »»»» futures_orders | body | array | false | Futures order |
| »»»»» None | body | object | false | Futures order |
| »»»»»» contract | body | string | true | Futures name, currently only supports perpetual futures for BTC and ETH with USDT. |
| »»»»»» size | body | string | true | Futures quantity, representing the initial order quantity, not involved in actual settlement. |
| »»»»»» left | body | string | true | Unfilled contract quantity, involved in actual calculation |
| »»»»» options_positions | body | array | false | Options positions |
| »»»»»» None | body | object | false | Options positions |
| »»»»»»» options_name | body | string | true | Option name, currently only supports options for BTC and ETH with USDT. |
| »»»»»»» size | body | string | true | Position size, measured in contract units. |
| »»»»»» options_orders | body | array | false | Option orders |
| »»»»»»» None | body | object | false | Option orders |
| »»»»»»»» options_name | body | string | true | Option name, currently only supports options for BTC and ETH with USDT. |
| »»»»»»»» size | body | string | true | Initial order quantity, not involved in actual calculation |
| »»»»»»»» left | body | string | true | Unfilled contract quantity, involved in actual calculation |
| »»»»»»» spot_hedge | body | boolean | false | Whether to enable spot hedging. |
»»» equity: Currency equity, where equity = balance - borrowed, represents the net delta exposure of your spot positions, which can be negative. Currently only supports three currencies: BTC, ETH.
»»»» count: Initial order quantity for spot trading pairs, not involved in actual calculation. Currently only supports three currencies: BTC, ETH.
Example responses
200 Response
{
"maintain_margin_total": "0.000000000000",
"initial_margin_total": "0.000000000000",
"calculate_time": "1709014486",
"risk_unit": [
{
"symbol": "BTC",
"margin_result": [
{
"type": "original_position",
"profit_loss_ranges": [
{
"price_percentage": "-0.200000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "-0.160000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "-0.120000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "-0.080000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "-0.040000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.000000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.040000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.080000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.120000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.160000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.200000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
}
],
"max_loss": {
"price_percentage": "-0.200000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
"mr1": "0.000000000000",
"mr2": "0.000000000000",
"mr3": "0.000000000000",
"mr4": "0.000000000000"
}
],
"maintain_margin": "0.000000000000",
"initial_margin": "0.000000000000"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
The output of the portfolio margin calculator.
| Name | Type | Description |
|---|---|---|
| » maintain_margin_total | string | Total maintenance margin, including only the portfolio margin calculation results for positions in the risk unit, excluding borrowed margin. If borrowing exists, conventional borrowing margin requirements will still apply. |
| » initial_margin_total | string | Total initial margin, calculated as the maximum of the following three combinations: position, position + positive delta orders, position + negative delta orders. |
| » calculate_time | integer(int64) | Calculate time |
| » risk_unit | array | Risk unit |
| »» None | object | Risk unit |
| »»» symbol | string | Risk unit name |
| »»» spot_in_use | string | Spot usage |
| »»» maintain_margin | string | Maintenance margin |
| »»» initial_margin | string | Initial margin |
| »»» margin_result | array | Margin result |
| »»»» None | object | Margin result |
| »»»»» type | string | Position combination typeoriginal_position - Original positionlong_delta_original_position - Positive delta + Original positionshort_delta_original_position - Negative delta + Original position |
| »»»»» profit_loss_ranges | array | The results of 33 pressure scenarios for MR1 |
| »»»»»» None | object | Profit and loss range |
| »»»»»»» price_percentage | string | Percentage change in price |
| »»»»»»» implied_volatility_percentage | string | Percentage change in implied volatility |
| »»»»»»» profit_loss | string | PNL |
| »»»»»» max_loss | object | Profit and loss range |
| »»»»»»» price_percentage | string | Percentage change in price |
| »»»»»»» implied_volatility_percentage | string | Percentage change in implied volatility |
| »»»»»»» profit_loss | string | PNL |
| »»»»»» mr1 | string | Stress testing |
| »»»»»» mr2 | string | Basis spread risk |
| »»»»»» mr3 | string | Volatility spread risk |
| »»»»»» mr4 | string | Option short risk |
| »»»»» delta | string | Total Delta of risk unit |
| »»»»» gamma | string | Total Gamma of risk unit |
| »»»»» theta | string | Total Theta of risk unit |
| »»»»» vega | string | Total Vega of risk unit |
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/leverage/user_currency_config'
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="/unified/leverage/user_currency_config"
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 /unified/leverage/user_currency_config
The maximum and minimum leverage multiples that users can set for a currency type are:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Currency |
Example responses
200 Response
{
"current_leverage": "2",
"min_leverage": "0",
"max_leverage": "0",
"debit": "0",
"available_margin": "0",
"borrowable": "0",
"except_leverage_borrowable": "0"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » current_leverage | string | Current leverage ratio |
| » min_leverage | string | Minimum adjustable leverage ratio |
| » max_leverage | string | Maximum adjustable leverage ratio |
| » debit | string | Current liabilities |
| » available_margin | string | Available Margin |
| » borrowable | string | The current leverage you can choose is |
| » except_leverage_borrowable | string | The maximum amount of margin that can be borrowed and the maximum amount of Yubibao that can be borrowed, whichever is smaller |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/leverage/user_currency_setting'
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="/unified/leverage/user_currency_setting"
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 /unified/leverage/user_currency_setting
Get the user's currency leverage. If currency is not passed, query all currencies.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Currency |
Example responses
200 Response
{
"currency": "BTC",
"leverage": "3"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency name |
| » leverage | string | multiple |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/leverage/user_currency_setting'
query_param = ''
body='{"currency":"BTC","leverage":"3"}'
# 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="/unified/leverage/user_currency_setting"
query_param=""
body_param='{"currency":"BTC","leverage":"3"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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 /unified/leverage/user_currency_setting
Set the currency leverage ratio
Body parameter
{
"currency": "BTC",
"leverage": "3"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | false | none |
| » currency | body | string | false | Currency name |
| » leverage | body | string | false | multiple |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Success | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Spot trading
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/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:
<currency>_<chain>, e.g., HT_ETHThe 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"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
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 |
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
| 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"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
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 |
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",
"max_base_amount": "10000",
"max_quote_amount": "10000000",
"amount_precision": 3,
"precision": 6,
"trade_status": "tradable",
"sell_start": 1516378650,
"buy_start": 1516378650
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | All currency pairs retrieved | [CurrencyPair] |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/currency_pairs/ETH_BTC'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/spot/currency_pairs/ETH_BTC \
-H 'Accept: application/json'
GET /spot/currency_pairs/{currency_pair}
Get details of a specifc currency pair
| 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",
"max_base_amount": "10000",
"max_quote_amount": "10000000",
"amount_precision": 3,
"precision": 6,
"trade_status": "tradable",
"sell_start": 1516378650,
"buy_start": 1516378650
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | CurrencyPair |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Currency pair |
| timezone | query | string | false | Timezone |
| 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"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency_pair | string | Currency pair |
| » last | string | Last trading price |
| » lowest_ask | string | Recent lowest ask |
| » lowest_size | string | The latest seller's lowest price quantity; does not exist for batch query; exists for single query, and is empty if there is no data |
| » highest_bid | string | Recent highest bid |
| » highest_size | string | The latest buyer's highest price quantity; does not exist for batch query; exists for single query, and is empty if there is no data |
| » 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 |
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
| 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"
]
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
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 |
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, The query range is the last 30 days.
Scrolling query using last_id is not recommended any more. If last_id is specified, time range query parameters will be ignored.
| 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(int32) | false | Page number |
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",
"sequence_id": "588018",
"text": "t-test"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | string | Trade ID |
| » create_time | string | Trading time |
| » create_time_ms | string | Trading time, with millisecond precision |
| » currency_pair | string | Currency pair |
| » side | string | Order side |
| » role | string | Trade role. No value in public endpoints |
| » amount | string | Trade amount |
| » price | string | Order price |
| » order_id | string | Related order ID. No value in public endpoints |
| » fee | string | Fee deducted. No value in public endpoints |
| » fee_currency | string | Fee currency unit. No value in public endpoints |
| » point_fee | string | Points used to deduct fee. No value in public endpoints |
| » gt_fee | string | GT used to deduct fee. No value in public endpoints |
| » amend_text | string | The custom data that the user remarked when amending the order |
| » sequence_id | string | Represents a unique and consecutive trade ID within a single market. It is used to track and identify trades in the specific market |
| » text | string | User defined information. No value in public endpoints |
| Property | Value |
|---|---|
| side | buy |
| side | sell |
| role | taker |
| role | maker |
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
| 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. Default toto - 100 * interval if not specified |
| 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 |
| 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",
"true"
]
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [[string]] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | array | K-line data for each time granularity, arranged from left to right: - Unix timestamp with second precision - Trading volume in quote currency - Closing price - Highest price - Lowest price - Opening price - Trading volume in base currency - Whether the window is closed; true indicates the end of this segment of candlestick chart data, false indicates that this segment of candlestick chart data is not yet complete |
Code samples
# coding: utf-8
import 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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Specify a currency pair to retrieve precise fee rate |
currency_pair: Specify a currency pair to retrieve precise fee rate
This field is optional. In most cases, the fee rate is identical among all currency pairs
Example responses
200 Response
{
"user_id": 10001,
"taker_fee": "0.002",
"maker_fee": "0.002",
"gt_discount": false,
"gt_taker_fee": "0",
"gt_maker_fee": "0",
"loan_fee": "0.18",
"point_type": "1",
"currency_pair": "BTC_USDT",
"debit_fee": 3
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
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 |
| » currency_pair | string | Currency pair |
| » debit_fee | integer | Deduction types for rates, 1 - GT deduction, 2 - Point card deduction, 3 - VIP rates |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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
| 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",
"debit_fee": 3
},
"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",
"debit_fee": 3
},
"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",
"debit_fee": 3
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
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 |
| »» debit_fee | integer | Deduction types for rates, 1 - GT deduction, 2 - Point card deduction, 3 - VIP rates |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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
| 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",
"update_id": 98
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency detail |
| » available | string | Available amount |
| » locked | string | Locked amount, used in trading |
| » update_id | integer | Version number |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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
| 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(int32) | 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",
"text": "3815099"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
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 book type. Please refer to account book type for more detail |
| » text | string | Additional information |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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-abc123","currency_pair":"BTC_USDT","type":"limit","account":"unified","side":"buy","amount":"0.001","price":"65000","time_in_force":"gtc","iceberg":"0"}]'
# 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-abc123","currency_pair":"BTC_USDT","type":"limit","account":"unified","side":"buy","amount":"0.001","price":"65000","time_in_force":"gtc","iceberg":"0"}]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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:
text is requiredaccount must be identical for all ordersBody parameter
[
{
"text": "t-abc123",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0"
}
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | integer(int64) | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | array[Order] | true | none |
Example responses
200 Response
[
{
"order_id": "12332324",
"amend_text": "t-123456",
"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_amount": "1.242",
"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
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request is completed | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Batch order details] |
| » None | object | Batch order details |
| »» order_id | string | Order ID |
| »» amend_text | string | The custom data that the user remarked when amending the order |
| »» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. 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, unified - unified 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 can be both set to true in one order. |
| »» left | string | Amount left to fill |
| »» filled_amount | string | Amount traded 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_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-traded1. 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 |
| Property | Value |
|---|---|
| status | open |
| status | closed |
| status | cancelled |
| type | limit |
| type | market |
| account | spot |
| account | margin |
| account | cross_margin |
| account | unified |
| 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
Code samples
# coding: utf-8
import 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,portfolio and margin orders are returned by default. To list cross margin orders, account must be set to cross_margin
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer(int32) | 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 ,portfolio 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"
}
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency_pair | string | Currency pair |
| » total | integer | The total number of pending orders for this trading pair on the current page |
| » 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- prefix3. 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 types， spot - spot account, margin - margin account, unified - unified account, cross_margin - cross margin account. Portfolio margin accounts can only be 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 can be both set to true in one order. |
| »»» left | string | Amount left to fill |
| »»» filled_amount | string | Amount traded 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-traded1. 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 | Order completion statuses include: - open: Awaiting processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled due to liquidation - small: Order quantity too small - depth_not_enough: Cancelled due to insufficient market depth - trader_not_enough: Cancelled due to insufficient counterparty - ioc: Not immediately filled because tif is set to ioc - poc: Not met the order strategy because tif is set to poc - fok: Not fully filled immediately because tif is set to fok - stp: Cancelled due to self-trade prevention - unknown: Unknown |
| Property | Value |
|---|---|
| status | open |
| status | closed |
| status | cancelled |
| type | limit |
| type | market |
| 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 | liquidate_cancelled |
| finish_as | depth_not_enough |
| finish_as | trader_not_enough |
| finish_as | small |
| finish_as | ioc |
| finish_as | poc |
| finish_as | fok |
| finish_as | stp |
| finish_as | unknown |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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"
}
| 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 |
| » action_mode | body | string | false | Processing Mode: |
» text: User defined information. If not empty, must follow the rules below:
t-t- prefix» action_mode: Processing Mode:
Different fields are returned when placing an order based on action_mode. This field is only valid during the request, and it is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)
Example responses
201 Response
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
| 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
Code samples
# coding: utf-8
import 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-abc123","currency_pair":"BTC_USDT","type":"limit","account":"unified","side":"buy","amount":"0.001","price":"65000","time_in_force":"gtc","iceberg":"0"}'
# 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-abc123","currency_pair":"BTC_USDT","type":"limit","account":"unified","side":"buy","amount":"0.001","price":"65000","time_in_force":"gtc","iceberg":"0"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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, portfolio, margin or cross margin account through setting the accountfield. It defaults to spot, which means spot account is used to place orders. If the user is using unified account, it defaults to the unified account.
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
stp_act to decide the strategy of self-trade prevention. For detailed usage, refer to the stp_act parameter in request bodyBody parameter
{
"text": "t-abc123",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | integer(int64) | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| 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 types， spot - spot account, margin - margin account, unified - unified account, cross_margin - cross margin account. Portfolio margin accounts can only be 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 |
| » action_mode | body | string | false | Processing Mode: |
» text: User defined information. If not empty, must follow the rules below:
t-t- prefixBesides user defined information, reserved contents are listed below, denoting how the order is created:
» type: Order Type
» 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 USDTside : sell means base currency，BTC_USDT means BTC» time_in_force: Time in force
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:
auto_borrow and auto_repay can 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
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。STP group, an error will be returned when passing the stp_act parameter。» action_mode: Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)
| Parameter | Value |
|---|---|
| » type | limit |
| » type | market |
| » 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
ACK response body example
{
"id": "12332324",
"text": "t-123456",
"amend_text": "test2"
}
RESULT response body example
{
"id": "12332324",
"text": "t-123456",
"create_time": "1548000000",
"update_time": "1548000100",
"create_time_ms": 1548000000123,
"update_time_ms": 1548000100123,
"currency_pair": "ETH_BTC",
"status": "cancelled",
"type": "limit",
"account": "spot",
"side": "buy",
"iceberg": "0",
"amount": "1",
"price": "5.00032",
"time_in_force": "gtc",
"auto_borrow": false,
"left": "0.5",
"filled_total": "2.50016",
"avg_deal_price": "5.00032",
"stp_act": "cn",
"finish_as": "stp",
"stp_id": 10240
}
FULL response body example
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
| 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
Code samples
# coding: utf-8
import 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, portfolio 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.
| 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(int32) | 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 ,portfolio 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 |
status: List orders based on status
open - order is waiting to be filled
finished - order has been filled or cancelled
Example responses
200 Response
[
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
]
| 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
open orders in specified currency pairCode samples
# coding: utf-8
import 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 = ''
# 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/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/orders
Cancel all open orders in specified currency pair
If account is not set, all open orders, including spot, portfolio, margin and cross margin ones, will be cancelled.
If currency_pair is not specified, all pending orders for trading pairs will be cancelled.
You can set account to cancel only orders within the specified account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Currency pair |
| side | query | string | false | All bids or asks. Both included if not specified |
| account | query | string | false | Specify account type: |
| action_mode | query | string | false | Processing Mode |
| x-gate-exptime | header | integer(int64) | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
account: Specify account type:
unifiedcross_marginaction_mode: Processing Mode
When placing an order, different fields are returned based on the action_mode
Example responses
200 Response
[
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"succeeded": true,
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation request accepted. Query order status by listing orders | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » 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- prefix3. 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 |
| »» 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 |
| »» 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 types， spot - spot account, margin - margin account, unified - unified account, cross_margin - cross margin account. Portfolio margin accounts can only be 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 can be both set to true in one order. |
| »» left | string | Amount left to fill |
| »» filled_amount | string | Amount traded 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-traded1. 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 |
| Property | Value |
|---|---|
| status | open |
| status | closed |
| status | cancelled |
| type | limit |
| type | market |
| 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
Code samples
# coding: utf-8
import 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"
}
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | integer(int64) | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | array[CancelBatchOrder] | true | none |
Example responses
200 Response
[
{
"currency_pair": "BTC_USDT",
"id": "123456",
"text": "123456",
"succeeded": true,
"label": null,
"message": null
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation completed | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » CancelOrderResult | object | Order cancellation result |
| »» currency_pair | string | Order currency pair |
| »» id | string | Order ID |
| »» text | string | Custom order information |
| »» 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
Code samples
# coding: utf-8
import 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, portfolio 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.
| 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 | Specify the transaction pair to query. If you are querying pending order records, this field is required. If you are querying traded records, this field can be left blank. |
| account | query | string | false | Specify operation account. Default to spot ,portfolio and margin account if not specified. Set to cross_margin to operate against margin account. Portfolio margin account must set to cross_margin only |
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": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
| 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
Code samples
# coding: utf-8
import 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 = ''
body='{"currency_pair":"BTC_USDT","account":"spot","amount":"1"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PATCH', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="PATCH"
url="/spot/orders/12345"
query_param=""
body_param='{"currency_pair":"BTC_USDT","account":"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"
PATCH /spot/orders/{order_id}
Amend an order
By default, the orders of spot, portfolio 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, both request body and query support currency_pair and account parameter passing, but request body has higher priority
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 reducing the quantity without modifying the priority of matching, altering the price or increasing the quantity will adjust the priority to the new price at the end Note: If the modified amount is less than the fill amount, the order will be cancelled.
Body parameter
{
"currency_pair": "BTC_USDT",
"account": "spot",
"amount": "1"
}
| 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 | false | Currency pair |
| account | query | string | false | Specify operation account. Default to spot ,portfolio and margin account if not specified. Set to cross_margin to operate against margin account. Portfolio margin account must set to cross_margin only |
| x-gate-exptime | header | integer(int64) | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | object | true | none |
| » currency_pair | body | string | false | Currency pair |
| » account | body | string | false | 指定查询账户。 |
| » 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 |
| » action_mode | body | string | false | Processing Mode: |
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.
» action_mode: Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)
Example responses
200 Response
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
| 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
Code samples
# coding: utf-8
import 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,portfolio 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
| 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 ,portfolio and margin account if not specified. Set to cross_margin to operate against margin account. Portfolio margin account must set to cross_margin only |
| action_mode | query | string | false | Processing Mode |
| x-gate-exptime | header | integer(int64) | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
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.
action_mode: Processing Mode
When placing an order, different fields are returned based on the action_mode
Example responses
200 Response
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
| 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
Code samples
# coding: utf-8
import 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,portfolio 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.
| 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. Default: 100, Minimum: 1, Maximum: 1000 |
| page | query | integer(int32) | 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 ,portfolio 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",
"sequence_id": "588018",
"text": "t-test"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | string | Trade ID |
| » create_time | string | Trading time |
| » create_time_ms | string | Trading time, with millisecond precision |
| » currency_pair | string | Currency pair |
| » side | string | Order side |
| » role | string | Trade role. No value in public endpoints |
| » amount | string | Trade amount |
| » price | string | Order price |
| » order_id | string | Related order ID. No value in public endpoints |
| » fee | string | Fee deducted. No value in public endpoints |
| » fee_currency | string | Fee currency unit. No value in public endpoints |
| » point_fee | string | Points used to deduct fee. No value in public endpoints |
| » gt_fee | string | GT used to deduct fee. No value in public endpoints |
| » amend_text | string | The custom data that the user remarked when amending the order |
| » sequence_id | string | Represents a unique and consecutive trade ID within a single market. It is used to track and identify trades in the specific market |
| » text | string | User defined information. No value in public endpoints |
| Property | Value |
|---|---|
| side | buy |
| side | sell |
| role | taker |
| role | maker |
WARNING
To perform this operation, you must be authenticated by API key and secret
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
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
SystemTime
| Name | Type | Description |
|---|---|---|
| » server_time | integer(int64) | Server current time(ms) |
Code samples
# coding: utf-8
import 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"
}
| 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 |
» timeout: Countdown time, in seconds At least 5 seconds, 0 means cancel the countdown
Example responses
200 Response
{
"triggerTime": "1660039145000"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Set countdown successfully | Inline |
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
Code samples
# coding: utf-8
import 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/amend_batch_orders'
query_param = ''
body='[{"order_id":"121212","currency_pair":"BTC_USDT","account":"spot","amount":"1","amend_text":"test"}]'
# 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/amend_batch_orders"
query_param=""
body_param='[{"order_id":"121212","currency_pair":"BTC_USDT","account":"spot","amount":"1","amend_text":"test"}]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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/amend_batch_orders
Batch modification of orders
Default modification of orders for spot, portfolio, and margin accounts. To modify orders for a cross margin account, the account parameter must be specified as cross_margin.
For portfolio margin accounts, the account parameter can only be specified as cross_margin.
Currently, only modifications to price or quantity (choose one) are supported.
When modifying unfinished orders, a maximum of 5 orders can be batch-modified in one request. The request parameters should be passed in an array format.
During batch modification, if one order modification fails, the modification process will continue with the next order. After execution, the response will include corresponding failure information for the failed orders.
The sequence of calling for batch order modification should be consistent with the order in the order list. The response content order for batch order modification will also be consistent with the order in the order list.
Body parameter
[
{
"order_id": "121212",
"currency_pair": "BTC_USDT",
"account": "spot",
"amount": "1",
"amend_text": "test"
}
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | integer(int64) | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | array[BatchAmendItem] | true | none |
Example responses
200 Response
[
{
"order_id": "12332324",
"amend_text": "t-123456",
"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_amount": "1.242",
"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
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order modification executed successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Batch order details] |
| » None | object | Batch order details |
| »» order_id | string | Order ID |
| »» amend_text | string | The custom data that the user remarked when amending the order |
| »» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. 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, unified - unified 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 can be both set to true in one order. |
| »» left | string | Amount left to fill |
| »» filled_amount | string | Amount traded 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_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-traded1. 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 |
| Property | Value |
|---|---|
| status | open |
| status | closed |
| status | cancelled |
| type | limit |
| type | market |
| account | spot |
| account | margin |
| account | cross_margin |
| account | unified |
| 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
Code samples
# coding: utf-8
import 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","text":"api"},"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","text":"api"},"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",
"text": "api"
},
"market": "GT_USDT"
}
| 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 | When type is limit, it refers to base currency. For instance, BTC_USDT means BTC |
| »» account | body | string | true | Trading account type. Portfolio margin account must set to cross_margin |
| »» time_in_force | body | string | false | time_in_force |
| »» text | body | string | false | The source of the order, including: |
| » market | body | string | true | Currency pair |
»» rule: Price trigger condition
=: triggered when market price larger than or equal to
pricefield
price field»» type: Order type，default to limit
»» side: Order side
»» 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 USDTside : sell means base currency，BTC_USDT means BTC»» account: Trading account type. Portfolio margin account must set to cross_margin
»» time_in_force: time_in_force
»» text: The source of the order, including:
| Parameter | Value |
|---|---|
| »» rule | >= |
| »» rule | <= |
| »» type | limit |
| »» type | market |
| »» 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
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order created | Inline |
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
Code samples
# coding: utf-8
import 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
| 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 |
| 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",
"text": "api"
},
"id": 1283293,
"user": 1234,
"market": "GT_USDT",
"ctime": 1616397800,
"ftime": 1616397801,
"fired_order_id": 0,
"status": "",
"reason": ""
}
]
| 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
Code samples
# coding: utf-8
import 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
| 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 |
| 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",
"text": "api"
},
"id": 1283293,
"user": 1234,
"market": "GT_USDT",
"ctime": 1616397800,
"ftime": 1616397801,
"fired_order_id": 0,
"status": "",
"reason": ""
}
]
| 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
Code samples
# coding: utf-8
import 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
| 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",
"text": "api"
},
"id": 1283293,
"user": 1234,
"market": "GT_USDT",
"ctime": 1616397800,
"ftime": 1616397801,
"fired_order_id": 0,
"status": "",
"reason": ""
}
| 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
Code samples
# coding: utf-8
import 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
| 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",
"text": "api"
},
"id": 1283293,
"user": 1234,
"market": "GT_USDT",
"ctime": 1616397800,
"ftime": 1616397801,
"fired_order_id": 0,
"status": "",
"reason": ""
}
| 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 API; margin trading uses spot trading API
Code samples
# coding: utf-8
import 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
| 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"
}
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
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
Code samples
# coding: utf-8
import 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
| 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 |
| type | query | string | false | Only retrieve changes of the specified type. All types will be returned if not specified. |
| from | query | integer(int64) | false | Start timestamp of the query |
| to | query | integer(int64) | false | Time range ending, default to current time |
| page | query | integer(int32) | 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"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
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 |
| » type | string | Account book type. Please refer to account book type for more detail |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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
| 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"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
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
Code samples
# coding: utf-8
import 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| status | query | string | true | New auto repayment status. on - enabled, off - disabled |
Example responses
200 Response
{
"status": "on"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Current auto repayment setting | Inline |
Status Code 200
AutoRepaySetting
| Name | Type | Description |
|---|---|---|
| » status | string | Auto repayment status. on - enabled, off - disabled |
| Property | Value |
|---|---|
| status | on |
| status | off |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Current auto repayment setting | Inline |
Status Code 200
AutoRepaySetting
| Name | Type | Description |
|---|---|---|
| » status | string | Auto repayment status. on - enabled, off - disabled |
| Property | Value |
|---|---|
| status | on |
| status | off |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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
| 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"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
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
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
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
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 |
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)
| 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
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
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 |
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)
| 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
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order book retrieved | [Inline] |
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 |
Code samples
# coding: utf-8
import 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"
}
| 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 |
» 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
| 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"
}
| 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
Code samples
# coding: utf-8
import 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)
| 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(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| 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"
}
]
| 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
Code samples
# coding: utf-8
import 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)
| 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"
}
| 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
Code samples
# coding: utf-8
import 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)
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| side | query | string | true | Lend or borrow |
| loan_id | path | string | true | Loan ID |
| Parameter | Value |
|---|---|
| side | lend |
| side | borrow |
Example responses
200 Response
{
"id": "123435",
"create_time": "1548000000",
"expire_time": "1548100000",
"side": "borrow",
"status": "loaned",
"currency": "BTC",
"rate": "0.002",
"amount": "1.5",
"days": 10,
"auto_renew": true,
"currency_pair": "ETH_BTC",
"left": "0",
"repaid": "0",
"paid_interest": "0",
"unpaid_interest": "0",
"fee_rate": "0.18",
"orig_id": "123424",
"text": "t-abc"
}
| 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
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/loans/12345'
query_param = ''
body='{"currency":"BTC","side":"borrow","currency_pair":"BTC_USDT","auto_renew":false}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PATCH', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="PATCH"
url="/margin/loans/12345"
query_param=""
body_param='{"currency":"BTC","side":"borrow","currency_pair":"BTC_USDT","auto_renew":false}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
PATCH /margin/loans/{loan_id}
Modify a loan(Deprecated)
Only auto_renew modification is supported currently
Body parameter
{
"currency": "BTC",
"side": "borrow",
"currency_pair": "BTC_USDT",
"auto_renew": false
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Loan currency |
| » side | body | string | true | Loan side. Possible values are lend and borrow. For LoanRecord patching, only lend is supported |
| » auto_renew | body | boolean | true | Auto renew |
| » currency_pair | body | string | false | Currency pair. Required if borrowing |
| » loan_id | body | string | false | Loan ID. Required for LoanRecord patching |
| loan_id | path | string | true | Loan ID |
| Parameter | Value |
|---|---|
| » side | lend |
| » side | borrow |
Example responses
200 Response
{
"id": "123435",
"create_time": "1548000000",
"expire_time": "1548100000",
"side": "borrow",
"status": "loaned",
"currency": "BTC",
"rate": "0.002",
"amount": "1.5",
"days": 10,
"auto_renew": true,
"currency_pair": "ETH_BTC",
"left": "0",
"repaid": "0",
"paid_interest": "0",
"unpaid_interest": "0",
"fee_rate": "0.18",
"orig_id": "123424",
"text": "t-abc"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Updated | Loan |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/loans/12345'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/margin/loans/12345"
query_param="currency=BTC"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /margin/loans/{loan_id}
Cancel lending loan(Deprecated)
Only lent loans can be cancelled
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Retrieve data of the specified currency |
| loan_id | path | string | true | Loan ID |
Example responses
200 Response
{
"id": "123435",
"create_time": "1548000000",
"expire_time": "1548100000",
"side": "borrow",
"status": "loaned",
"currency": "BTC",
"rate": "0.002",
"amount": "1.5",
"days": 10,
"auto_renew": true,
"currency_pair": "ETH_BTC",
"left": "0",
"repaid": "0",
"paid_interest": "0",
"unpaid_interest": "0",
"fee_rate": "0.18",
"orig_id": "123424",
"text": "t-abc"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order cancelled | Loan |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/loans/12345/repayment'
query_param = ''
body='{"currency_pair":"ETH_BTC","currency":"ETH","mode":"partial","amount":"100"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/margin/loans/12345/repayment"
query_param=""
body_param='{"currency_pair":"ETH_BTC","currency":"ETH","mode":"partial","amount":"100"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /margin/loans/{loan_id}/repayment
Repay a loan(Deprecated)
Body parameter
{
"currency_pair": "ETH_BTC",
"currency": "ETH",
"mode": "partial",
"amount": "100"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency_pair | body | string | true | Currency pair |
| » currency | body | string | true | Loan currency |
| » mode | body | string | true | Repay mode. all - repay all; partial - repay only some portion |
| » amount | body | string | false | Repay amount. Required in partial mode |
| loan_id | path | string | true | Loan ID |
| Parameter | Value |
|---|---|
| » mode | all |
| » mode | partial |
Example responses
200 Response
{
"id": "123435",
"create_time": "1548000000",
"expire_time": "1548100000",
"side": "borrow",
"status": "loaned",
"currency": "BTC",
"rate": "0.002",
"amount": "1.5",
"days": 10,
"auto_renew": true,
"currency_pair": "ETH_BTC",
"left": "0",
"repaid": "0",
"paid_interest": "0",
"unpaid_interest": "0",
"fee_rate": "0.18",
"orig_id": "123424",
"text": "t-abc"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Loan repaid | Loan |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/loans/12345/repayment'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/loans/12345/repayment"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/loans/{loan_id}/repayment
List loan repayment records(Deprecated)
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| loan_id | path | string | true | Loan ID |
Example responses
200 Response
[
{
"id": "12342323",
"create_time": "1578000000",
"principal": "100",
"interest": "2"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | string | Loan record ID |
| » create_time | string | Repayment time |
| » principal | string | Repaid principal |
| » interest | string | Repaid interest |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/loan_records'
query_param = 'loan_id=12345'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/loan_records"
query_param="loan_id=12345"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/loan_records
List repayment records of a specific loan(Deprecated)
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| loan_id | query | string | true | Loan ID |
| status | query | string | false | Loan record status |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| Parameter | Value |
|---|---|
| status | loaned |
| status | finished |
Example responses
200 Response
[
{
"id": "122342323",
"loan_id": "12840282",
"create_time": "1548000000",
"expire_time": "1548100000",
"status": "loaned",
"borrow_user_id": "******12",
"currency": "BTC",
"rate": "0.002",
"amount": "1.5",
"days": 10,
"auto_renew": false,
"repaid": "0",
"paid_interest": "0",
"unpaid_interest": "0"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [LoanRecord] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/loan_records/12345'
query_param = 'loan_id=12345'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/loan_records/12345"
query_param="loan_id=12345"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/loan_records/{loan_record_id}
Get one single loan record(Deprecated)
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| loan_id | query | string | true | Loan ID |
| loan_record_id | path | string | true | Loan record ID |
Example responses
200 Response
{
"id": "122342323",
"loan_id": "12840282",
"create_time": "1548000000",
"expire_time": "1548100000",
"status": "loaned",
"borrow_user_id": "******12",
"currency": "BTC",
"rate": "0.002",
"amount": "1.5",
"days": 10,
"auto_renew": false,
"repaid": "0",
"paid_interest": "0",
"unpaid_interest": "0"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Detail retrieved | LoanRecord |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/loan_records/12345'
query_param = ''
body='{"currency":"BTC","side":"borrow","currency_pair":"BTC_USDT","auto_renew":false}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PATCH', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="PATCH"
url="/margin/loan_records/12345"
query_param=""
body_param='{"currency":"BTC","side":"borrow","currency_pair":"BTC_USDT","auto_renew":false}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
PATCH /margin/loan_records/{loan_record_id}
Modify a loan record(Deprecated)
Only auto_renew modification is supported currently
Body parameter
{
"currency": "BTC",
"side": "borrow",
"currency_pair": "BTC_USDT",
"auto_renew": false
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Loan currency |
| » side | body | string | true | Loan side. Possible values are lend and borrow. For LoanRecord patching, only lend is supported |
| » auto_renew | body | boolean | true | Auto renew |
| » currency_pair | body | string | false | Currency pair. Required if borrowing |
| » loan_id | body | string | false | Loan ID. Required for LoanRecord patching |
| loan_record_id | path | string | true | Loan record ID |
| Parameter | Value |
|---|---|
| » side | lend |
| » side | borrow |
Example responses
200 Response
{
"id": "122342323",
"loan_id": "12840282",
"create_time": "1548000000",
"expire_time": "1548100000",
"status": "loaned",
"borrow_user_id": "******12",
"currency": "BTC",
"rate": "0.002",
"amount": "1.5",
"days": 10,
"auto_renew": false,
"repaid": "0",
"paid_interest": "0",
"unpaid_interest": "0"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Loan record updated | LoanRecord |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/borrowable'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/borrowable"
query_param="currency=BTC"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/borrowable
Get the max borrowable amount for a specific margin currency(Deprecated)
| 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"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
MarginBorrowable
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency detail |
| » currency_pair | string | Currency pair |
| » amount | string | Max borrowable amount |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/cross/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/margin/cross/currencies \
-H 'Accept: application/json'
GET /margin/cross/currencies
Currencies supported by cross margin.
Example responses
200 Response
[
{
"name": "BTC",
"rate": "0.0002",
"prec": "0.000001",
"discount": "1",
"min_borrow_amount": "0.01",
"user_max_borrow_amount": "1000000",
"total_max_borrow_amount": "10000000",
"price": "63015.5214",
"loanable": true,
"status": 1
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » name | string | Currency name |
| » rate | string | Minimum lending rate (hourly rate) |
| » prec | string | Currency precision |
| » discount | string | Currency value discount, which is used in total value calculation |
| » min_borrow_amount | string | Minimum currency borrow amount. Unit is currency itself |
| » user_max_borrow_amount | string | Maximum borrow value allowed per user, in USDT |
| » total_max_borrow_amount | string | Maximum borrow value allowed for this currency, in USDT |
| » price | string | Price change between this currency and USDT |
| » loanable | boolean | Whether currency is borrowed |
| » status | integer | status - 0 : disable- 1 : enable |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/cross/currencies/BTC'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/margin/cross/currencies/BTC \
-H 'Accept: application/json'
GET /margin/cross/currencies/{currency}
Retrieve detail of one single currency supported by cross margin
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | true | Currency name |
Example responses
200 Response
{
"name": "BTC",
"rate": "0.0002",
"prec": "0.000001",
"discount": "1",
"min_borrow_amount": "0.01",
"user_max_borrow_amount": "1000000",
"total_max_borrow_amount": "10000000",
"price": "63015.5214",
"loanable": true,
"status": 1
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » name | string | Currency name |
| » rate | string | Minimum lending rate (hourly rate) |
| » prec | string | Currency precision |
| » discount | string | Currency value discount, which is used in total value calculation |
| » min_borrow_amount | string | Minimum currency borrow amount. Unit is currency itself |
| » user_max_borrow_amount | string | Maximum borrow value allowed per user, in USDT |
| » total_max_borrow_amount | string | Maximum borrow value allowed for this currency, in USDT |
| » price | string | Price change between this currency and USDT |
| » loanable | boolean | Whether currency is borrowed |
| » status | integer | status - 0 : disable- 1 : enable |
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/cross/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/cross/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/cross/accounts
Retrieve cross margin account
Example responses
200 Response
{
"user_id": 10001,
"locked": false,
"balances": {
"ETH": {
"available": "0",
"freeze": "0",
"borrowed": "0.075393666654",
"interest": "0.0000106807603333",
"negative_liab": "0",
"futures_pos_liab": "0",
"equity": "1016.1",
"total_freeze": "0",
"total_liab": "0"
},
"POINT": {
"available": "9999999999.017023138734",
"freeze": "0",
"borrowed": "0",
"interest": "0",
"negative_liab": "0",
"futures_pos_liab": "0",
"equity": "12016.1",
"total_freeze": "0",
"total_liab": "0"
},
"USDT": {
"available": "0.00000062023",
"freeze": "0",
"borrowed": "0",
"interest": "0",
"negative_liab": "0",
"futures_pos_liab": "0",
"equity": "16.1",
"total_freeze": "0",
"total_liab": "0"
}
},
"total": "230.94621713",
"borrowed": "161.66395521",
"interest": "0.02290237",
"risk": "1.4284",
"total_initial_margin": "1025.0524665088",
"total_margin_balance": "3382495.944473949183",
"total_maintenance_margin": "205.01049330176",
"total_initial_margin_rate": "3299.827135672679",
"total_maintenance_margin_rate": "16499.135678363399",
"total_available_margin": "3381470.892007440383",
"portfolio_margin_total": "3381470.892007440383",
"portfolio_margin_total_liab": "0",
"portfolio_margin_total_equity": "100016.1"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » user_id | integer(int64) | User ID |
| » refresh_time | integer(int64) | Time of the most recent refresh |
| » 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 |
| »»» negative_liab | string | Negative Liabilities. Formula:Min[available+total+unrealized_pnl,0] |
| »»» futures_pos_liab | string | Borrowing to Open Positions in Futures |
| »»» equity | string | Equity. Formula: available + freeze - borrowed + futures account's total + unrealized_pnl |
| »»» total_freeze | string | Total freeze. Formula: freeze + position_initial_margin + order_margin |
| »»» total_liab | string | Total liabilities. Formula: Max[Abs[Min[quity - total_freeze,0], borrowed]] - futures_pos_liab |
| »» total | string | Total account value in USDT, i.e., the sum of all currencies' (available+freeze)*price*discount |
| »» borrowed | string | Total borrowed value in USDT, i.e., the sum of all currencies' borrowed*price*discount |
| »» interest | string | Total unpaid interests in USDT, i.e., the sum of all currencies' interest*price*discount |
| »» risk | string | Risk rate. When it belows 110%, liquidation will be triggered. Calculation formula: total / (borrowed+interest) |
| »» total_initial_margin | string | Total initial margin |
| »» total_margin_balance | string | Total Margin Balance (∑(positive equity ＊ index price * discount) + ∑(negative equity * index price)) |
| »» 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 |
| »» portfolio_margin_total | string | Total amount of the portfolio margin account |
| »» portfolio_margin_total_liab | string | Total liabilities of the portfolio margin account |
| »» portfolio_margin_total_equity | string | Total equity of the portfolio margin account |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/cross/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/cross/account_book"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/cross/account_book
Retrieve cross margin account change history
Record time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Filter by currency |
| from | query | integer(int64) | false | Start timestamp of the query |
| to | query | integer(int64) | false | Time range ending, default to current time |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| type | query | string | false | Only retrieve changes of the specified type. All types will be returned if not specified. |
Example responses
200 Response
[
{
"id": "123456",
"time": 1547633726123,
"currency": "BTC",
"change": "1.03",
"balance": "4.59316525194",
"type": "in"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
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 book type. Please refer to account book type for more detail |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/cross/loans'
query_param = ''
body='{"currency":"EOS","amount":"110.553635","text":"web"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/margin/cross/loans"
query_param=""
body_param='{"currency":"EOS","amount":"110.553635","text":"web"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /margin/cross/loans
Create a cross margin borrow loan
Borrow amount cannot be less than currency minimum borrow amount
Body parameter
{
"currency": "EOS",
"amount": "110.553635",
"text": "web"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Currency name |
| » amount | body | string | true | Borrowed amount |
| » text | body | string | false | User defined custom ID |
Example responses
200 Response
{
"id": "17",
"create_time": 1620381696159,
"update_time": 1620381696159,
"currency": "EOS",
"amount": "110.553635",
"text": "web",
"status": 2,
"repaid": "110.506649705159",
"repaid_interest": "0.046985294841",
"unpaid_interest": "0.0000074393366667"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully borrowed | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | string | Loan record ID |
| » create_time | integer(int64) | Creation timestamp, in milliseconds |
| » update_time | integer(int64) | Update timestamp, in milliseconds |
| » currency | string | Currency name |
| » amount | string | Borrowed amount |
| » text | string | User defined custom ID |
| » status | integer(int32) | Deprecated. Currently, all statuses have been set to 2. Borrow loan status, which includes: - 1: failed to borrow - 2: borrowed but not repaid - 3: repayment complete |
| » repaid | string | Repaid amount |
| » repaid_interest | string | Repaid interest |
| » unpaid_interest | string | Outstanding interest yet to be paid |
| Property | Value |
|---|---|
| status | 1 |
| status | 2 |
| status | 3 |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/cross/loans'
query_param = 'status=0'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/cross/loans"
query_param="status=0"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/cross/loans
List cross margin borrow history
Sort by creation time in descending order by default. Set reverse=false to return ascending results.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| status | query | integer | true | Filter by status. Supported values are 2 and 3. (deprecated.) |
| currency | query | string | false | Filter by currency |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| reverse | query | boolean | false | Whether to sort in descending order, which is the default. Set reverse=false to return ascending results |
Example responses
200 Response
[
{
"id": "17",
"create_time": 1620381696159,
"update_time": 1620381696159,
"currency": "EOS",
"amount": "110.553635",
"text": "web",
"status": 2,
"repaid": "110.506649705159",
"repaid_interest": "0.046985294841",
"unpaid_interest": "0.0000074393366667"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | string | Loan record ID |
| » create_time | integer(int64) | Creation timestamp, in milliseconds |
| » update_time | integer(int64) | Update timestamp, in milliseconds |
| » currency | string | Currency name |
| » amount | string | Borrowed amount |
| » text | string | User defined custom ID |
| » status | integer(int32) | Deprecated. Currently, all statuses have been set to 2. Borrow loan status, which includes: - 1: failed to borrow - 2: borrowed but not repaid - 3: repayment complete |
| » repaid | string | Repaid amount |
| » repaid_interest | string | Repaid interest |
| » unpaid_interest | string | Outstanding interest yet to be paid |
| Property | Value |
|---|---|
| status | 1 |
| status | 2 |
| status | 3 |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/cross/loans/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/cross/loans/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/cross/loans/{loan_id}
Retrieve single borrow loan detail
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| loan_id | path | string | true | Borrow loan ID |
Example responses
200 Response
{
"id": "17",
"create_time": 1620381696159,
"update_time": 1620381696159,
"currency": "EOS",
"amount": "110.553635",
"text": "web",
"status": 2,
"repaid": "110.506649705159",
"repaid_interest": "0.046985294841",
"unpaid_interest": "0.0000074393366667"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | string | Loan record ID |
| » create_time | integer(int64) | Creation timestamp, in milliseconds |
| » update_time | integer(int64) | Update timestamp, in milliseconds |
| » currency | string | Currency name |
| » amount | string | Borrowed amount |
| » text | string | User defined custom ID |
| » status | integer(int32) | Deprecated. Currently, all statuses have been set to 2. Borrow loan status, which includes: - 1: failed to borrow - 2: borrowed but not repaid - 3: repayment complete |
| » repaid | string | Repaid amount |
| » repaid_interest | string | Repaid interest |
| » unpaid_interest | string | Outstanding interest yet to be paid |
| Property | Value |
|---|---|
| status | 1 |
| status | 2 |
| status | 3 |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/cross/repayments'
query_param = ''
body='{"currency":"EOS","amount":"110.553635"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/margin/cross/repayments"
query_param=""
body_param='{"currency":"EOS","amount":"110.553635"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /margin/cross/repayments
Cross margin repayments
When the liquidity of the currency is insufficient and the transaction risk is high, the currency will be disabled, and funds cannot be transferred.When the available balance of cross-margin is insufficient, the balance of the spot account can be used for repayment. Please ensure that the balance of the spot account is sufficient, and system uses cross-margin account for repayment first
Body parameter
{
"currency": "EOS",
"amount": "110.553635"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Repayment currency |
| » amount | body | string | true | Repayment amount |
Example responses
200 Response
[
{
"id": "17",
"create_time": 1620381696159,
"update_time": 1620381696159,
"currency": "EOS",
"amount": "110.553635",
"text": "web",
"status": 2,
"repaid": "110.506649705159",
"repaid_interest": "0.046985294841",
"unpaid_interest": "0.0000074393366667"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Loan repaid | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | string | Loan record ID |
| » create_time | integer(int64) | Creation timestamp, in milliseconds |
| » update_time | integer(int64) | Update timestamp, in milliseconds |
| » currency | string | Currency name |
| » amount | string | Borrowed amount |
| » text | string | User defined custom ID |
| » status | integer(int32) | Deprecated. Currently, all statuses have been set to 2. Borrow loan status, which includes: - 1: failed to borrow - 2: borrowed but not repaid - 3: repayment complete |
| » repaid | string | Repaid amount |
| » repaid_interest | string | Repaid interest |
| » unpaid_interest | string | Outstanding interest yet to be paid |
| Property | Value |
|---|---|
| status | 1 |
| status | 2 |
| status | 3 |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/cross/repayments'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/cross/repayments"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/cross/repayments
Retrieve cross margin repayments
Sort by creation time in descending order by default. Set reverse=false to return ascending results.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | none |
| loan_id | query | string | false | none |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| reverse | query | boolean | false | Whether to sort in descending order, which is the default. Set reverse=false to return ascending results |
Example responses
200 Response
[
{
"id": "51",
"create_time": 1620696347990,
"loan_id": "30",
"currency": "BTC",
"principal": "5.385542",
"interest": "0.000044879516",
"repayment_type": "auto_repay"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | string | Loan record ID |
| » create_time | integer(int64) | Repayment time |
| » loan_id | string | Loan record ID |
| » currency | string | Currency name |
| » principal | string | Repaid principal |
| » interest | string | Repaid interest |
| » repayment_type | string | Repayment type: none - no repayment type, manual_repay - manual repayment, auto_repay - automatic repayment, cancel_auto_repay - automatic repayment after cancellation |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/cross/interest_records'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/cross/interest_records"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/cross/interest_records
Interest records for the cross margin account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Retrieve data of the specified currency |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
Example responses
200 Response
[
{
"status": 1,
"currency_pair": "BTC_USDT",
"currency": "USDT",
"actual_rate": "0.00000236",
"interest": "0.00006136",
"type": "platform",
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Interest record] |
| » None | object | Interest record |
| »» currency | string | Currency name |
| »» currency_pair | string | Currency pair |
| »» actual_rate | string | Actual rate |
| »» interest | string | Interest |
| »» status | integer | Status: 0 - fail, 1 - success |
| »» type | string | Type, platform - platform，margin - margin |
| »» create_time | integer(int64) | Created time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/cross/transferable'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/cross/transferable"
query_param="currency=BTC"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/cross/transferable
Get the max transferable amount for a specific cross margin currency
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Retrieve data of the specified currency |
Example responses
200 Response
{
"currency": "ETH",
"amount": "10000"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
CrossMarginTransferable
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency detail |
| » amount | string | Max transferable amount |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/cross/estimate_rate'
query_param = 'currencies=BTC,GT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/cross/estimate_rate"
query_param="currencies=BTC,GT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/cross/estimate_rate
Estimated interest rates
Please note that the interest rates are subject to change based on the borrowing and lending demand, and therefore, the provided rates may not be entirely accurate.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currencies | query | array[string] | true | An array of up to 10 specifying the currency name |
Example responses
200 Response
{
"BTC": "0.000002",
"GT": "0.000001"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
Estimate the current hourly lending rates, categorized by currency
| Name | Type | Description |
|---|---|---|
| » additionalProperties | string | none |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/cross/borrowable'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/cross/borrowable"
query_param="currency=BTC"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/cross/borrowable
Get the max borrowable amount for a specific cross margin currency
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Retrieve data of the specified currency |
Example responses
200 Response
{
"currency": "ETH",
"amount": "10000"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
CrossMarginBorrowable
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency detail |
| » amount | string | Max borrowable amount |
WARNING
To perform this operation, you must be authenticated by API key and secret
Margin API; margin trading uses spot trading API
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/uni/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/uni/currency_pairs \
-H 'Accept: application/json'
GET /margin/uni/currency_pairs
List lending markets
Example responses
200 Response
[
{
"currency_pair": "AE_USDT",
"base_min_borrow_amount": "100",
"quote_min_borrow_amount": "100",
"leverage": "3"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Currency pair of the loan] |
| » None | object | Currency pair of the loan |
| »» currency_pair | string | Currency pair |
| »» base_min_borrow_amount | string | Minimum borrow amount of base currency |
| »» quote_min_borrow_amount | string | Minimum borrow amount of quote currency |
| »» leverage | string | Position leverage |
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/uni/currency_pairs/AE_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/uni/currency_pairs/AE_USDT \
-H 'Accept: application/json'
GET /margin/uni/currency_pairs/{currency_pair}
Get detail of lending market
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | path | string | true | Currency pair |
Example responses
200 Response
{
"currency_pair": "AE_USDT",
"base_min_borrow_amount": "100",
"quote_min_borrow_amount": "100",
"leverage": "3"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
Currency pair of the loan
| Name | Type | Description |
|---|---|---|
| » currency_pair | string | Currency pair |
| » base_min_borrow_amount | string | Minimum borrow amount of base currency |
| » quote_min_borrow_amount | string | Minimum borrow amount of quote currency |
| » leverage | string | Position leverage |
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/uni/estimate_rate'
query_param = 'currencies=BTC,GT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/uni/estimate_rate"
query_param="currencies=BTC,GT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/uni/estimate_rate
Estimate interest Rate
Please note that the interest rates are subject to change based on the borrowing and lending demand, and therefore, the provided rates may not be entirely accurate.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currencies | query | array[string] | true | An array of up to 10 specifying the currency name |
Example responses
200 Response
{
"BTC": "0.000002",
"GT": "0.000001"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
Estimate the current hourly lending rates, categorized by currency
| Name | Type | Description |
|---|---|---|
| » additionalProperties | string | none |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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/uni/loans'
query_param = ''
body='{"currency":"BTC","amount":"0.1","type":"borrow","currency_pair":"BTC_USDT","repaid_all":false}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/margin/uni/loans"
query_param=""
body_param='{"currency":"BTC","amount":"0.1","type":"borrow","currency_pair":"BTC_USDT","repaid_all":false}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /margin/uni/loans
Borrow or repay
Body parameter
{
"currency": "BTC",
"amount": "0.1",
"type": "borrow",
"currency_pair": "BTC_USDT",
"repaid_all": false
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Currency |
| » type | body | string | true | type: borrow - borrow, repay - repay |
| » amount | body | string | true | The amount of lending or repaying |
| » repaid_all | body | boolean | false | Full repayment. Repay operation only. If the value is true, the amount will be ignored and the loan will be repaid in full. |
| » currency_pair | body | string | true | Currency pair |
| Parameter | Value |
|---|---|
| » type | borrow |
| » type | repay |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Operated successfully | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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/uni/loans'
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/uni/loans"
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/uni/loans
List loans
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Currency pair |
| currency | query | string | false | Retrieve data of the specified currency |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100 |
Example responses
200 Response
[
{
"currency": "USDT",
"currency_pari": "GT_USDT",
"amount": "1",
"type": "margin",
"change_time": 1673247054000,
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Loan] |
| » None | object | Loan |
| »» currency | string | Currency |
| »» currency_pair | string | Currency pair |
| »» amount | string | amount |
| »» type | string | Loan type, platform - platform, margin - margin |
| »» create_time | integer(int64) | Created time |
| »» update_time | integer(int64) | Updated time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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/uni/loan_records'
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/uni/loan_records"
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/uni/loan_records
Get load records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| type | query | string | false | type: borrow - borrow, repay - repay |
| currency | query | string | false | Retrieve data of the specified currency |
| currency_pair | query | string | false | Currency pair |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100 |
| Parameter | Value |
|---|---|
| type | borrow |
| type | repay |
Example responses
200 Response
[
{
"type": "borrow",
"currency_pair": "AE_USDT",
"currency": "USDT",
"amount": "1000",
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Loan records |
| »» type | string | type: borrow - borrow, repay - repay |
| »» currency_pair | string | Currency pair |
| »» currency | string | Currency |
| »» amount | string | The amount of lending or repaying |
| »» create_time | integer(int64) | Created time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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/uni/interest_records'
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/uni/interest_records"
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/uni/interest_records
List interest records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Currency pair |
| currency | query | string | false | Retrieve data of the specified currency |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
Example responses
200 Response
[
{
"status": 1,
"currency_pair": "BTC_USDT",
"currency": "USDT",
"actual_rate": "0.00000236",
"interest": "0.00006136",
"type": "platform",
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Interest record] |
| » None | object | Interest record |
| »» currency | string | Currency name |
| »» currency_pair | string | Currency pair |
| »» actual_rate | string | Actual rate |
| »» interest | string | Interest |
| »» status | integer | Status: 0 - fail, 1 - success |
| »» type | string | Type, platform - platform，margin - margin |
| »» create_time | integer(int64) | Created time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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/uni/borrowable'
query_param = 'currency=BTC¤cy_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="/margin/uni/borrowable"
query_param="currency=BTC¤cy_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 /margin/uni/borrowable
Get maximum borrowable
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Retrieve data of the specified currency |
| currency_pair | query | string | true | Currency pair |
Example responses
200 Response
{
"currency": "AE",
"borrowable": "1123.344",
"currency_pair": "AE_USDT"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
MaxUniBorrowable
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency |
| » currency_pair | string | Currency pair |
| » borrowable | string | Maximum borrowable |
WARNING
To perform this operation, you must be authenticated by API key and secret
Flash swap
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/flash_swap/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/flash_swap/currencies \
-H 'Accept: application/json'
GET /flash_swap/currencies
List All Supported Currencies In Flash Swap (deprecated)
Example responses
200 Response
[
{
"currency": "BTC",
"min_amount": "0.000001",
"max_amount": "1.000000",
"swappable": [
"USDT",
"GT",
"ETH"
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Currencies supported in flash swap |
| »» currency | string | Currency name |
| »» min_amount | string | Minimum amount required in flash swap |
| »» max_amount | string | Maximum amount allowed in flash swap |
| »» swappable | array | Currencies which can be swapped to from this currency |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/flash_swap/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/flash_swap/currency_pairs \
-H 'Accept: application/json'
GET /flash_swap/currency_pairs
List All Supported Currency Pairs In Flash Swap
BTC_GT represents selling BTC and buying GT. The limits for each currency may vary across different currency pairs.
It is not necessary that two currencies that can be swapped instantaneously can be exchanged with each other. For example, it is possible to sell BTC and buy GT, but it does not necessarily mean that GT can be sold to buy BTC.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Retrieve data of the specified currency |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 1000 |
Example responses
200 Response
[
{
"currency_pair": "BTC_USDT",
"sell_currency": "BTC",
"buy_currency": "USDT",
"sell_min_amount": "0.00001",
"sell_max_amount": "100",
"buy_min_amount": "10",
"buy_max_amount": "10000000"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | List all supported currencies in flash swap |
| »» currency_pair | string | The currency pair, BTC_USDT represents selling Bitcoin (BTC) and buying Tether (USDT). |
| »» sell_currency | string | The currency to be sold |
| »» buy_currency | string | The currency to be bought |
| »» sell_min_amount | string | The minimum quantity required for selling |
| »» sell_max_amount | string | The maximum quantity allowed for selling |
| »» buy_min_amount | string | The minimum quantity required for buying |
| »» buy_max_amount | string | The maximum quantity allowed for buying |
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/flash_swap/orders'
query_param = ''
body='{"preview_id":"4564564","sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT","buy_amount":"10"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/flash_swap/orders"
query_param=""
body_param='{"preview_id":"4564564","sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT","buy_amount":"10"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /flash_swap/orders
Create a flash swap order
Initiate a flash swap preview in advance because order creation requires a preview result
Body parameter
{
"preview_id": "4564564",
"sell_currency": "BTC",
"sell_amount": "0.1",
"buy_currency": "USDT",
"buy_amount": "10"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » preview_id | body | string | true | Preview result ID |
| » sell_currency | body | string | true | The name of the asset being sold, as obtained from the "GET /flash_swap/currency_pairs" API, which retrieves a list of supported flash swap currency pairs. |
| » sell_amount | body | string | true | Amount to sell (based on the preview result) |
| » buy_currency | body | string | true | The name of the asset being purchased, as obtained from the "GET /flash_swap/currency_pairs" API, which provides a list of supported flash swap currency pairs. |
| » buy_amount | body | string | true | Amount to buy (based on the preview result) |
Example responses
201 Response
{
"id": 54646,
"create_time": 1651116876378,
"update_time": 1651116876378,
"user_id": 11135567,
"sell_currency": "BTC",
"sell_amount": "0.01",
"buy_currency": "USDT",
"buy_amount": "10",
"price": "100",
"status": 1
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | The flash swap order is created successfully | Inline |
Status Code 201
Flash swap order
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Flash swap order ID |
| » create_time | integer(int64) | Creation time of order (in milliseconds) |
| » user_id | integer(int64) | User ID |
| » sell_currency | string | Currency to sell |
| » sell_amount | string | Amount to sell |
| » buy_currency | string | Currency to buy |
| » buy_amount | string | Amount to buy |
| » price | string | Price |
| » status | integer | Flash swap order status1 - success2 - failure |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/flash_swap/orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/flash_swap/orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /flash_swap/orders
List all flash swap orders
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| status | query | integer | false | Flash swap order status |
| sell_currency | query | string | false | Currency to sell which can be retrieved from supported currency list API GET /flash_swap/currencies |
| buy_currency | query | string | false | Currency to buy which can be retrieved from supported currency list API GET /flash_swap/currencies |
| reverse | query | boolean | false | If results are sorted by id in reverse order. Default to true |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| page | query | integer(int32) | false | Page number |
status: Flash swap order status
1 - success
2 - failure
reverse: If results are sorted by id in reverse order. Default to true
true: sort by id in descending order(recent first)false: sort by id in ascending order(oldest first)Example responses
200 Response
[
{
"id": 54646,
"create_time": 1651116876378,
"update_time": 1651116876378,
"user_id": 11135567,
"sell_currency": "BTC",
"sell_amount": "0.01",
"buy_currency": "USDT",
"buy_amount": "10",
"price": "100",
"status": 1
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Flash swap order] |
| » None | object | Flash swap order |
| »» id | integer(int64) | Flash swap order ID |
| »» create_time | integer(int64) | Creation time of order (in milliseconds) |
| »» user_id | integer(int64) | User ID |
| »» sell_currency | string | Currency to sell |
| »» sell_amount | string | Amount to sell |
| »» buy_currency | string | Currency to buy |
| »» buy_amount | string | Amount to buy |
| »» price | string | Price |
| »» status | integer | Flash swap order status1 - success2 - failure |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/flash_swap/orders/1'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/flash_swap/orders/1"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /flash_swap/orders/{order_id}
Get a single flash swap order's detail
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | integer | true | Flash swap order ID |
Example responses
200 Response
{
"id": 54646,
"create_time": 1651116876378,
"update_time": 1651116876378,
"user_id": 11135567,
"sell_currency": "BTC",
"sell_amount": "0.01",
"buy_currency": "USDT",
"buy_amount": "10",
"price": "100",
"status": 1
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
Flash swap order
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Flash swap order ID |
| » create_time | integer(int64) | Creation time of order (in milliseconds) |
| » user_id | integer(int64) | User ID |
| » sell_currency | string | Currency to sell |
| » sell_amount | string | Amount to sell |
| » buy_currency | string | Currency to buy |
| » buy_amount | string | Amount to buy |
| » price | string | Price |
| » status | integer | Flash swap order status1 - success2 - failure |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/flash_swap/orders/preview'
query_param = ''
body='{"sell_currency":"BTC","sell_amount":"0.1","buy_currency":"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="/flash_swap/orders/preview"
query_param=""
body_param='{"sell_currency":"BTC","sell_amount":"0.1","buy_currency":"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 /flash_swap/orders/preview
Initiate a flash swap order preview
Body parameter
{
"sell_currency": "BTC",
"sell_amount": "0.1",
"buy_currency": "USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » sell_currency | body | string | true | The name of the asset being sold, as obtained from the "GET /flash_swap/currency_pairs" API, which retrieves a list of supported flash swap currency pairs. |
| » sell_amount | body | string | false | Amount to sell. |
| » buy_currency | body | string | true | The name of the asset being purchased, as obtained from the "GET /flash_swap/currency_pairs" API, which provides a list of supported flash swap currency pairs. |
| » buy_amount | body | string | false | Amount to buy. |
» sell_amount: Amount to sell.
It is required to choose one parameter between sell_amount and buy_amount
» buy_amount: Amount to buy.
It is required to choose one parameter between sell_amount and buy_amount
Example responses
200 Response
{
"preview_id": "3453434",
"sell_currency": "BTC",
"sell_amount": "0.1",
"buy_currency": "USDT",
"buy_amount": "10",
"price": "100"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | The flash swap order successfully previewed | Inline |
Status Code 200
Initiate a flash swap order preview
| Name | Type | Description |
|---|---|---|
| » preview_id | string | Preview result ID |
| » sell_currency | string | Currency to sell which can be retrieved from supported currency list API GET /flash_swap/currencies |
| » sell_amount | string | Amount to sell |
| » buy_currency | string | Currency to buy which can be retrieved from supported currency list API GET /flash_swap/currencies |
| » buy_amount | string | Amount to buy |
| » price | string | Price |
WARNING
To perform this operation, you must be authenticated by API key and secret
Futures contract API
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/contracts'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/contracts \
-H 'Accept: application/json'
GET /futures/{settle}/contracts
List all futures contracts
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"name": "BTC_USDT",
"type": "direct",
"quanto_multiplier": "0.0001",
"ref_discount_rate": "0",
"order_price_deviate": "0.5",
"maintenance_rate": "0.005",
"mark_type": "index",
"last_price": "38026",
"mark_price": "37985.6",
"index_price": "37954.92",
"funding_rate_indicative": "0.000219",
"mark_price_round": "0.01",
"funding_offset": 0,
"in_delisting": false,
"risk_limit_base": "1000000",
"interest_rate": "0.0003",
"order_price_round": "0.1",
"order_size_min": 1,
"ref_rebate_rate": "0.2",
"funding_interval": 28800,
"risk_limit_step": "1000000",
"leverage_min": "1",
"leverage_max": "100",
"risk_limit_max": "8000000",
"maker_fee_rate": "-0.00025",
"taker_fee_rate": "0.00075",
"funding_rate": "0.002053",
"order_size_max": 1000000,
"funding_next_apply": 1610035200,
"short_users": 977,
"config_change_time": 1609899548,
"trade_size": 28530850594,
"position_size": 5223816,
"long_users": 455,
"funding_impact_value": "60000",
"orders_limit": 50,
"trade_id": 10851092,
"orderbook_id": 2129638396,
"enable_bonus": true,
"enable_credit": true,
"create_time": 1669688556,
"funding_cap_ratio": "0.75"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Contract] |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/contracts/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/contracts/BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/contracts/{contract}
Get a single contract
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"name": "BTC_USDT",
"type": "direct",
"quanto_multiplier": "0.0001",
"ref_discount_rate": "0",
"order_price_deviate": "0.5",
"maintenance_rate": "0.005",
"mark_type": "index",
"last_price": "38026",
"mark_price": "37985.6",
"index_price": "37954.92",
"funding_rate_indicative": "0.000219",
"mark_price_round": "0.01",
"funding_offset": 0,
"in_delisting": false,
"risk_limit_base": "1000000",
"interest_rate": "0.0003",
"order_price_round": "0.1",
"order_size_min": 1,
"ref_rebate_rate": "0.2",
"funding_interval": 28800,
"risk_limit_step": "1000000",
"leverage_min": "1",
"leverage_max": "100",
"risk_limit_max": "8000000",
"maker_fee_rate": "-0.00025",
"taker_fee_rate": "0.00075",
"funding_rate": "0.002053",
"order_size_max": 1000000,
"funding_next_apply": 1610035200,
"short_users": 977,
"config_change_time": 1609899548,
"trade_size": 28530850594,
"position_size": 5223816,
"long_users": 455,
"funding_impact_value": "60000",
"orders_limit": 50,
"trade_id": 10851092,
"orderbook_id": 2129638396,
"enable_bonus": true,
"enable_credit": true,
"create_time": 1669688556,
"funding_cap_ratio": "0.75"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Contract information | Contract |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/order_book'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/order_book?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/order_book
Futures order book
Bids will be sorted by price from high to low, while asks sorted reversely
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| interval | query | string | false | Order depth. 0 means no aggregation is applied. default to 0 |
| limit | query | integer | false | Maximum number of order depth data in asks or bids |
| with_id | query | boolean | false | Whether the order book update ID will be returned. This ID increases by 1 on every order book update |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"id": 123456,
"current": 1623898993.123,
"update": 1623898993.121,
"asks": [
{
"p": "1.52",
"s": 100
},
{
"p": "1.53",
"s": 40
}
],
"bids": [
{
"p": "1.17",
"s": 150
},
{
"p": "1.16",
"s": 203
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order book retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Order Book ID. Increases by 1 on every order book change. Set with_id=true to include this field in response |
| » current | number(double) | Response data generation timestamp |
| » update | number(double) | Order book changed timestamp |
| » asks | array | Asks order depth |
| »» futures_order_book_item | object | none |
| »»» p | string | Price (quote currency) |
| »»» s | integer(int64) | Size |
| »» bids | array | Bids order depth |
| »»» futures_order_book_item | object | none |
| »»»» p | string | Price (quote currency) |
| »»»» s | integer(int64) | Size |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/trades'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/trades?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/trades
Futures trading history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| last_id | query | string | false | Specify the starting point for this list based on a previously retrieved id |
| from | query | integer(int64) | false | Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items. |
| to | query | integer(int64) | false | Specify end time in Unix seconds, default to current time |
last_id: Specify the starting point for this list based on a previously retrieved id
This parameter is deprecated. Use from and to instead to limit time range
from: Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items.
If items between from and to are more than limit, only limit number will be returned.
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800,
"contract": "BTC_USDT",
"size": -100,
"price": "100.123"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | integer(int64) | Trade ID |
| » create_time | number(double) | Trading time |
| » create_time_ms | number(double) | Trading time, with milliseconds set to 3 decimal places. |
| » contract | string | Futures contract |
| » size | integer(int64) | Trading size |
| » price | string | Trading price (quote currency) |
| » is_internal | boolean | Whether internal trade. Internal trade refers to the takeover of liquidation orders by the insurance fund and ADL users. Since it is not a normal matching on the market depth, the transaction price may deviate, and it will not be recorded in the K-line. If it is not an internal trade, this field will not be returned. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/candlesticks'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/candlesticks?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/candlesticks
Get futures candlesticks
Return specified contract candlesticks.
If prefix contract with mark_, the contract's mark price candlesticks are returned;
if prefix with index_, index price candlesticks will be returned.
Maximum of 2000 points are returned in one query. Be sure not to exceed the limit when specifying from, to and interval
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| from | query | integer(int64) | false | Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified |
| to | query | integer(int64) | false | End time of candlesticks, formatted in Unix timestamp in seconds. Default to current time |
| limit | query | integer | false | Maximum recent data points to return. limit is conflicted with from and to. If either from or to is specified, request will be rejected. |
| interval | query | string | false | Interval time between data points. Note that 1w means natual week(Mon-Sun), while 7d means every 7d since unix 0. Note that 30d means 1 natual month, not 30 days |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"t": 1539852480,
"v": 97151,
"c": "1.032",
"h": "1.032",
"l": "1.032",
"o": "1.032",
"sum": "3580"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [data point in every timestamp] |
| » None | object | data point in every timestamp |
| »» t | number(double) | Unix timestamp in seconds |
| »» v | integer(int64) | size volume (contract size). Only returned if contract is not prefixed |
| »» c | string | Close price (quote currency) |
| »» h | string | Highest price (quote currency) |
| »» l | string | Lowest price (quote currency) |
| »» o | string | Open price (quote currency) |
| »» sum | string | Trading volume (unit: Quote 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 = '/futures/usdt/premium_index'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/premium_index?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/premium_index
Premium Index K-Line
Maximum of 1000 points can be returned in a query. Be sure not to exceed the limit when specifying from, to and interval
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| from | query | integer(int64) | false | Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified |
| to | query | integer(int64) | false | End time of candlesticks, formatted in Unix timestamp in seconds. Default to current time |
| limit | query | integer | false | Maximum recent data points to return. limit is conflicted with from and to. If either from or to is specified, request will be rejected. |
| interval | query | string | false | Interval time between data points |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"t": 1539852480,
"c": "0",
"h": "0.00023",
"l": "0",
"o": "0"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | data point in every timestamp |
| »» t | number(double) | Unix timestamp in seconds |
| »» c | string | Close price |
| »» h | string | Highest price |
| »» l | string | Lowest price` |
| »» o | string | Open price |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/tickers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/tickers \
-H 'Accept: application/json'
GET /futures/{settle}/tickers
List futures tickers
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"contract": "BTC_USDT",
"last": "6432",
"low_24h": "6278",
"high_24h": "6790",
"change_percentage": "4.43",
"total_size": "32323904",
"volume_24h": "184040233284",
"volume_24h_btc": "28613220",
"volume_24h_usd": "184040233284",
"volume_24h_base": "28613220",
"volume_24h_quote": "184040233284",
"volume_24h_settle": "28613220",
"mark_price": "6534",
"funding_rate": "0.0001",
"funding_rate_indicative": "0.0001",
"index_price": "6531",
"highest_bid": "34089.7",
"highest_size": "100",
"lowest_ask": "34217.9",
"lowest_size": "1000"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » contract | string | Futures contract |
| » last | string | Last trading price |
| » change_percentage | string | Change percentage. |
| » total_size | string | Contract total size |
| » low_24h | string | Lowest trading price in recent 24h |
| » high_24h | string | Highest trading price in recent 24h |
| » volume_24h | string | Trade size in recent 24h |
| » volume_24h_btc | string | Trade volumes in recent 24h in BTC(deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead) |
| » volume_24h_usd | string | Trade volumes in recent 24h in USD(deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead) |
| » volume_24h_base | string | Trade volume in recent 24h, in base currency |
| » volume_24h_quote | string | Trade volume in recent 24h, in quote currency |
| » volume_24h_settle | string | Trade volume in recent 24h, in settle currency |
| » mark_price | string | Recent mark price |
| » funding_rate | string | Funding rate |
| » funding_rate_indicative | string | Indicative Funding rate in next period |
| » index_price | string | Index price |
| » quanto_base_rate | string | Exchange rate of base currency and settlement currency in Quanto contract. Does not exists in contracts of other types |
| » basis_rate | string | Basis rate |
| » basis_value | string | Basis value |
| » lowest_ask | string | Recent lowest ask |
| » lowest_size | string | The latest seller's lowest price order quantity |
| » highest_bid | string | Recent highest bid |
| » highest_size | string | The latest buyer's highest price order volume |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/funding_rate'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/funding_rate?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/funding_rate
Funding rate history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"t": 1543968000,
"r": "0.000157"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | History retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » t | integer(int64) | Unix timestamp in seconds |
| » r | string | Funding rate |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/insurance'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/insurance \
-H 'Accept: application/json'
GET /futures/{settle}/insurance
Futures insurance balance history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"t": 1543968000,
"b": "83.0031"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » t | integer(int64) | Unix timestamp in seconds |
| » b | string | Insurance balance |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/contract_stats'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/contract_stats?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/contract_stats
Futures stats
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| from | query | integer(int64) | false | Start timestamp |
| interval | query | string | false | none |
| limit | query | integer | false | none |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"time": 1603865400,
"lsr_taker": 100,
"lsr_account": 0.5,
"long_liq_size": 0,
"short_liq_size": 0,
"open_interest": 124724,
"short_liq_usd": 0,
"mark_price": "8865",
"top_lsr_size": 1.02,
"short_liq_amount": 0,
"long_liq_amount": 0,
"open_interest_usd": 1511,
"top_lsr_account": 1.5,
"long_liq_usd": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | integer(int64) | Stat timestamp |
| » lsr_taker | number | Long/short account number ratio |
| » lsr_account | number | Long/short taker size ratio |
| » long_liq_size | integer(int64) | Long liquidation size |
| » long_liq_amount | number(double) | Long liquidation amount(base currency) |
| » long_liq_usd | number(double) | Long liquidation volume(quote currency) |
| » short_liq_size | integer(int64) | Short liquidation size |
| » short_liq_amount | number(double) | Short liquidation amount(base currency) |
| » short_liq_usd | number(double) | Short liquidation volume(quote currency) |
| » open_interest | integer(int64) | Open interest size |
| » open_interest_usd | number(double) | Open interest volume(quote currency) |
| » top_lsr_account | number(double) | Top trader long/short account ratio |
| » top_lsr_size | number(double) | Top trader long/short position ratio |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/index_constituents/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/index_constituents/BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/index_constituents/{index}
Get index constituents
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| index | path | string | true | Index name |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"index": "BTC_USDT",
"constituents": [
{
"exchange": "Binance",
"symbols": [
"BTC_USDT"
]
},
{
"exchange": "Gate.io",
"symbols": [
"BTC_USDT"
]
},
{
"exchange": "Huobi",
"symbols": [
"BTC_USDT"
]
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » index | string | Index name |
| » constituents | array | Constituents |
| »» IndexConstituent | object | none |
| »»» exchange | string | Exchange |
| »»» symbols | array | Symbol list |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/liq_orders'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/liq_orders \
-H 'Accept: application/json'
GET /futures/{settle}/liq_orders
Retrieve liquidation history
Interval between from and to cannot exceeds 3600. Some private fields will not be returned in public endpoints. Refer to field description for detail.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"time": 1548654951,
"contract": "BTC_USDT",
"size": 600,
"order_price": "3405",
"fill_price": "3424",
"left": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | integer(int64) | Liquidation time |
| » contract | string | Futures contract |
| » size | integer(int64) | User position size |
| » order_price | string | Liquidation order price |
| » fill_price | string | Liquidation order average taker price |
| » left | integer(int64) | System liquidation order maker size |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/risk_limit_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/risk_limit_tiers \
-H 'Accept: application/json'
GET /futures/{settle}/risk_limit_tiers
List risk limit tiers
When the 'contract' parameter is not passed, the default is to query the risk limits for the top 100 markets.'Limit' and 'offset' correspond to pagination queries at the market level, not to the length of the returned array. This only takes effect when the 'contract' parameter is empty.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"maintenance_rate": "0.01",
"tier": 1,
"initial_rate": "0.02",
"leverage_max": "50",
"risk_limit": "500000",
"contract": "BTC_USDT"
},
{
"initial_rate": "0.03",
"maintenance_rate": "0.02",
"tier": 2,
"risk_limit": "1000000",
"leverage_max": "33.33",
"contract": "BTC_USDT"
},
{
"maintenance_rate": "0.01",
"tier": 1,
"initial_rate": "0.02",
"leverage_max": "50",
"risk_limit": "500000",
"contract": "ETH_USDT"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Retrieve risk limit configurations for different tiers under a specified contract.] |
| » None | object | Retrieve risk limit configurations for different tiers under a specified contract. |
| »» tier | integer(int) | Tier |
| »» risk_limit | string | Position risk limit |
| »» initial_rate | string | Initial margin rate |
| »» maintenance_rate | string | Maintenance margin rate |
| »» leverage_max | string | Maximum leverage |
| »» contract | string | Markets, visible only during market pagination requests |
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/accounts
Query futures account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 1666,
"currency": "USDT",
"total": "9707.803567115145",
"unrealised_pnl": "3371.248828",
"position_margin": "38.712189181",
"order_margin": "0",
"available": "9669.091377934145",
"point": "0",
"bonus": "0",
"in_dual_mode": false,
"enable_evolved_classic": false,
"cross_initial_margin": "61855.56788525",
"cross_maintenance_margin": "682.04678105",
"cross_order_margin": "0",
"cross_unrealised_pnl": "1501.178222634128",
"cross_available": "27549.406108813951",
"isolated_position_margin": "0",
"history": {
"dnw": "10000",
"pnl": "68.3685",
"fee": "-1.645812875",
"refr": "0",
"fund": "-358.919120009855",
"point_dnw": "0",
"point_fee": "0",
"point_refr": "0",
"bonus_dnw": "0",
"bonus_offset": "0"
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » 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 | The maintenance deposit occupied by the position is suitable for the new classic account margin model and unified account model |
| » bonus | string | Perpetual Contract Bonus |
| » enable_evolved_classic | boolean | Classic account margin mode, true-new mode, false-old mode |
| » cross_order_margin | string | Full -warehouse hanging order deposit, suitable for the new classic account margin model |
| » cross_initial_margin | string | The initial security deposit of the full warehouse is suitable for the new classic account margin model |
| » cross_maintenance_margin | string | Maintain deposit in full warehouse, suitable for new classic account margin models |
| » cross_unrealised_pnl | string | The full warehouse does not achieve profit and loss, suitable for the new classic account margin model |
| » cross_available | string | Full warehouse available amount, suitable for the new classic account margin model |
| » isolated_position_margin | string | Ware -position margin, suitable for the new classic account margin model |
| » 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
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/account_book"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/account_book
Query account book
If the contract field is provided, it can only filter records that include this field after 2023-10-30.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
| type | query | string | false | Changing Type： |
type: Changing Type：
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"time": 1682294400.123456,
"change": "0.000010152188",
"balance": "4.59316525194",
"text": "ETH_USD:6086261",
"type": "fee",
"contract": "ETH_USD",
"trade_id": "1",
"id": "1"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » time | number(double) | Change time |
| » change | string | Change amount |
| » balance | string | Balance after change |
| » type | string | Changing Type： - dnw: Deposit & Withdraw - pnl: Profit & Loss by reducing position - fee: Trading fee - refr: Referrer rebate - fund: Funding - point_dnw: POINT Deposit & Withdraw - point_fee: POINT Trading fee - point_refr: POINT Referrer rebate - bonus_offset: bouns deduction |
| » text | string | Comment |
| » contract | string | Futures contract, the field is only available for data after 2023-10-30. |
| » trade_id | string | trade id |
| » id | string | 账户变更记录 id |
| Property | Value |
|---|---|
| type | dnw |
| type | pnl |
| type | fee |
| type | refr |
| type | fund |
| type | point_dnw |
| type | point_fee |
| type | point_refr |
| type | bonus_offset |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/positions"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/positions
List all positions of a user
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| holding | query | boolean | false | Return only real positions - true, return all - false. |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"cross_leverage_limit": "0"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Position] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions/BTC_USDT'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/positions/BTC_USDT"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/positions/{contract}
Get single position
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"cross_leverage_limit": "0"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions/BTC_USDT/margin'
query_param = 'change=0.01'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/positions/BTC_USDT/margin"
query_param="change=0.01"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/positions/{contract}/margin
Update position margin
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| change | query | string | true | Margin change. Use positive number to increase margin, negative number otherwise. |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"cross_leverage_limit": "0"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions/BTC_USDT/leverage'
query_param = 'leverage=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/positions/BTC_USDT/leverage"
query_param="leverage=10"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/positions/{contract}/leverage
Update position leverage
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| leverage | query | string | true | New position leverage |
| cross_leverage_limit | query | string | false | Cross margin leverage(valid only when leverage is 0) |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"cross_leverage_limit": "0"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions/BTC_USDT/risk_limit'
query_param = 'risk_limit=1000000'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/positions/BTC_USDT/risk_limit"
query_param="risk_limit=1000000"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/positions/{contract}/risk_limit
Update position risk limit
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| risk_limit | query | string | true | New Risk Limit Value |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"cross_leverage_limit": "0"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_mode'
query_param = 'dual_mode=true'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_mode"
query_param="dual_mode=true"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/dual_mode
Enable or disable dual mode
Before setting dual mode, make sure all positions are closed and no orders are open
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| dual_mode | query | boolean | true | Whether to enable dual mode |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 1666,
"currency": "USDT",
"total": "9707.803567115145",
"unrealised_pnl": "3371.248828",
"position_margin": "38.712189181",
"order_margin": "0",
"available": "9669.091377934145",
"point": "0",
"bonus": "0",
"in_dual_mode": false,
"enable_evolved_classic": false,
"cross_initial_margin": "61855.56788525",
"cross_maintenance_margin": "682.04678105",
"cross_order_margin": "0",
"cross_unrealised_pnl": "1501.178222634128",
"cross_available": "27549.406108813951",
"isolated_position_margin": "0",
"history": {
"dnw": "10000",
"pnl": "68.3685",
"fee": "-1.645812875",
"refr": "0",
"fund": "-358.919120009855",
"point_dnw": "0",
"point_fee": "0",
"point_refr": "0",
"bonus_dnw": "0",
"bonus_offset": "0"
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Updated | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » 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 | The maintenance deposit occupied by the position is suitable for the new classic account margin model and unified account model |
| » bonus | string | Perpetual Contract Bonus |
| » enable_evolved_classic | boolean | Classic account margin mode, true-new mode, false-old mode |
| » cross_order_margin | string | Full -warehouse hanging order deposit, suitable for the new classic account margin model |
| » cross_initial_margin | string | The initial security deposit of the full warehouse is suitable for the new classic account margin model |
| » cross_maintenance_margin | string | Maintain deposit in full warehouse, suitable for new classic account margin models |
| » cross_unrealised_pnl | string | The full warehouse does not achieve profit and loss, suitable for the new classic account margin model |
| » cross_available | string | Full warehouse available amount, suitable for the new classic account margin model |
| » isolated_position_margin | string | Ware -position margin, suitable for the new classic account margin model |
| » 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
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_comp/positions/BTC_USDT'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/dual_comp/positions/BTC_USDT"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/dual_comp/positions/{contract}
Retrieve position detail in dual mode
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"cross_leverage_limit": "0"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Position] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_comp/positions/BTC_USDT/margin'
query_param = 'change=0.01&dual_side=dual_long'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_comp/positions/BTC_USDT/margin"
query_param="change=0.01&dual_side=dual_long"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/dual_comp/positions/{contract}/margin
Update position margin in dual mode
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| change | query | string | true | Margin change. Use positive number to increase margin, negative number otherwise. |
| dual_side | query | string | true | Long or short position |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"cross_leverage_limit": "0"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Position] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_comp/positions/BTC_USDT/leverage'
query_param = 'leverage=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_comp/positions/BTC_USDT/leverage"
query_param="leverage=10"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/dual_comp/positions/{contract}/leverage
Update position leverage in dual mode
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| leverage | query | string | true | New position leverage |
| cross_leverage_limit | query | string | false | Cross margin leverage(valid only when leverage is 0) |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"cross_leverage_limit": "0"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Position] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_comp/positions/BTC_USDT/risk_limit'
query_param = 'risk_limit=1000000'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_comp/positions/BTC_USDT/risk_limit"
query_param="risk_limit=1000000"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/dual_comp/positions/{contract}/risk_limit
Update position risk limit in dual mode
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| risk_limit | query | string | true | New Risk Limit Value |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"cross_leverage_limit": "0"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Position] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders'
query_param = ''
body='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/orders"
query_param=""
body_param='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/orders
Create a futures order
size, which is number of contracts instead of currency amount. You can use quanto_multiplier in contract detail response to know how much currency 1 size contract representsreduce_only to true can keep the position from changing side when reducing position sizesize to 0 and close to trueauto_size side, reduce_only to true and size to 0stp_act to decide the strategy of self-trade prevention. For detailed usage, refer to the stp_act parameter in request bodyBody parameter
{
"contract": "BTC_USDT",
"size": 6024,
"iceberg": 0,
"price": "3765",
"tif": "gtc",
"text": "t-my-custom-id",
"stp_act": "-"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | integer(int64) | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | FuturesOrder | true | none |
| » contract | body | string | true | Futures contract |
| » size | body | integer(int64) | true | Order size. Specify positive number to make a bid, and negative number to ask |
| » iceberg | body | integer(int64) | false | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
| » price | body | string | false | Order price. 0 for market order with tif set as ioc |
| » close | body | boolean | false | Set as true to close the position, with size set to 0 |
| » reduce_only | body | boolean | false | Set as true to be reduce-only order |
| » tif | body | string | false | Time in force |
| » text | body | string | false | User defined information. If not empty, must follow the rules below: |
| » auto_size | body | string | false | Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0 |
| » stp_act | body | string | false | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies |
| settle | path | string | true | Settle currency |
» tif: Time in force
» text: User defined information. If not empty, must follow the rules below:
t-t- prefix» stp_act: Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies
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。STP group, an error will be returned when passing the stp_act parameter。| Parameter | Value |
|---|---|
| » tif | gtc |
| » tif | ioc |
| » tif | poc |
| » tif | fok |
| » auto_size | close_long |
| » auto_size | close_short |
| » stp_act | co |
| » stp_act | cn |
| » stp_act | cb |
| » stp_act | - |
| settle | btc |
| settle | usdt |
Example responses
201 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order details | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/orders
List futures orders
GET /futures/{settle}/orders_timerange.| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | false | Futures contract, return related data only if specified |
| status | query | string | true | Only list the orders with this status |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| last_id | query | string | false | Specify list staring point using the id of last record in previous list-query results |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [FuturesOrder] |
| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | X-Pagination-Limit | integer | Request limit specified | |
| 200 | X-Pagination-Offset | integer | Request offset specified |
WARNING
To perform this operation, you must be authenticated by API key and secret
open orders matchedCode samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders'
query_param = 'contract=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/usdt/orders"
query_param="contract=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /futures/{settle}/orders
Cancel all open orders matched
Zero-filled order cannot be retrieved 10 minutes after order cancellation
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | integer(int64) | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| contract | query | string | true | Futures contract |
| side | query | string | false | All bids or asks. Both included if not specified |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | All orders matched cancelled | [FuturesOrder] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders_timerange'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/orders_timerange"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/orders_timerange
List Futures Orders By Time Range
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [FuturesOrder] |
| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | X-Pagination-Limit | integer | Request limit specified | |
| 200 | X-Pagination-Offset | integer | Request offset specified |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/batch_orders'
query_param = ''
body='[{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/batch_orders"
query_param=""
body_param='[{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/batch_orders
Create a batch of futures orders
succeeded field of type bool indicates whether the execution was successful or notlabel field is included to indicate the cause of the errorBody parameter
[
{
"contract": "BTC_USDT",
"size": 6024,
"iceberg": 0,
"price": "3765",
"tif": "gtc",
"text": "t-my-custom-id",
"stp_act": "-"
}
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | integer(int64) | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | array[FuturesOrder] | true | none |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"succeeded": true,
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request is completed | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Futures order details] |
| » None | object | Futures order details |
| »» succeeded | boolean | Whether the batch of orders succeeded |
| »» label | string | Error label, only exists if execution fails |
| »» detail | string | Error detail, only present if execution failed and details need to be given |
| »» id | integer(int64) | Futures order ID |
| »» user | integer | User ID |
| »» create_time | number(double) | Creation time of order |
| »» finish_time | number(double) | Order finished time. Not returned if order is open |
| »» finish_as | string | How the order was finished. - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC, finish immediately- auto_deleveraged: finished by ADL - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because of position close- position_closed: canceled because the position was closed - reduce_out: only reduce positions by excluding hard-to-fill orders - stp: cancelled because self trade prevention |
| »» status | string | Order status - open: waiting to be traded- finished: finished |
| »» contract | string | Futures contract |
| »» size | integer(int64) | Order size. Specify positive number to make a bid, and negative number to ask |
| »» iceberg | integer(int64) | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
| »» price | string | Order price. 0 for market order with tif set as ioc |
| »» is_close | boolean | Is the order to close position |
| »» is_reduce_only | boolean | Is the order reduce-only |
| »» is_liq | boolean | Is the order for liquidation |
| »» tif | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none |
| »» left | integer(int64) | Size left to be traded |
| »» fill_price | string | Fill price of the order |
| »» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance |
| »» tkfr | string | Taker fee |
| »» mkfr | string | Maker fee |
| »» refu | integer | Reference user ID |
| »» 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 |
| »» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. 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 |
| Property | Value |
|---|---|
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidated |
| finish_as | ioc |
| finish_as | auto_deleveraged |
| finish_as | reduce_only |
| finish_as | position_closed |
| finish_as | reduce_out |
| finish_as | stp |
| status | open |
| status | finished |
| tif | gtc |
| tif | ioc |
| tif | poc |
| tif | fok |
| stp_act | co |
| stp_act | cn |
| stp_act | cb |
| stp_act | - |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/orders/{order_id}
Get a single order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| order_id | path | string | true | Order ID returned, or user custom ID(i.e., text field). |
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 60 seconds after the end of the order. After that, only order ID is accepted.
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order details | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/usdt/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /futures/{settle}/orders/{order_id}
Cancel a single order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | integer(int64) | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| settle | path | string | true | Settle currency |
| order_id | path | string | true | Order ID returned, or user custom ID(i.e., text field). |
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 60 seconds after the end of the order. After that, only order ID is accepted.
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order details | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders/12345'
query_param = ''
body='{"size":100,"price":"54321"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PUT', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="PUT"
url="/futures/usdt/orders/12345"
query_param=""
body_param='{"size":100,"price":"54321"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
PUT /futures/{settle}/orders/{order_id}
Amend an order
Body parameter
{
"size": 100,
"price": "54321"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | integer(int64) | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | object | true | none |
| » size | body | integer(int64) | false | New order size, including filled part. |
| » price | body | string | false | New order price. |
| » amend_text | body | string | false | Custom info during amending order |
| » biz_info | body | string | false | Users can annotate this modification with information. |
| » bbo | body | string | false | Users are able to modify the offer price manually. |
| settle | path | string | true | Settle currency |
| order_id | path | string | true | Order ID returned, or user custom ID(i.e., text field). |
» size: New order size, including filled part.
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 60 seconds after the end of the order. After that, only order ID is accepted.
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order details | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/my_trades'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/my_trades"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/my_trades
List personal trading history
By default, only data within the past 6 months is supported.
If you need to query data for a longer period, please use GET /futures/{settle}/my_trades_timerange.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| order | query | integer(int64) | false | Futures order ID, return related data only if specified |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| last_id | query | string | false | Specify the starting point for this list based on a previously retrieved id |
last_id: Specify the starting point for this list based on a previously retrieved id
This parameter is deprecated. If you need to iterate through and retrieve more records, we recommend using 'GET /futures/{settle}/my_trades_timerange'.
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800.123,
"contract": "BTC_USDT",
"order_id": "21893289839",
"size": 100,
"price": "100.123",
"text": "t-123456",
"fee": "0.01",
"point_fee": "0",
"role": "taker",
"close_size": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | integer(int64) | Trade ID |
| » create_time | number(double) | Trading time |
| » contract | string | Futures contract |
| » order_id | string | Order ID related |
| » size | integer(int64) | Trading size |
| » close_size | integer(int64) | Number of closed positions: close_size=0 && size＞0 Open long position close_size=0 && size＜0 Open short position close_size>0 && size>0 && size <= close_size Close short postion close_size>0 && size>0 && size > close_size Close short position and open long position close_size<0 && size<0 && size >= close_size Close long postion close_size<0 && size<0 && size < close_size Close long position and open short position |
| » price | string | Trading price |
| » role | string | Trade role. Available values are taker and maker |
| » text | string | User defined information |
| » fee | string | Fee deducted |
| » point_fee | string | Points used to deduct fee |
| Property | Value |
|---|---|
| role | taker |
| role | maker |
| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | X-Pagination-Limit | integer | Request limit specified | |
| 200 | X-Pagination-Offset | integer | Request offset specified |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/my_trades_timerange'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/my_trades_timerange"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/my_trades_timerange
List personal trading history by time range
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| role | query | string | false | Query role, maker or taker. |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"trade_id": "121234231",
"create_time": 1514764800.123,
"contract": "BTC_USDT",
"order_id": "21893289839",
"size": 100,
"price": "100.123",
"text": "t-123456",
"fee": "0.01",
"point_fee": "0",
"role": "taker",
"close_size": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » trade_id | string | Trade ID |
| » create_time | number(double) | Trading time |
| » contract | string | Futures contract |
| » order_id | string | Order ID related |
| » size | integer(int64) | Trading size |
| » close_size | integer(int64) | Number of closed positions: close_size=0 && size＞0 Open long position close_size=0 && size＜0 Open short position close_size>0 && size>0 && size <= close_size Close short postion close_size>0 && size>0 && size > close_size Close short position and open long position close_size<0 && size<0 && size >= close_size Close long postion close_size<0 && size<0 && size < close_size Close long position and open short position |
| » price | string | Trading price |
| » role | string | Trade role. Available values are taker and maker |
| » text | string | User defined information |
| » fee | string | Fee deducted |
| » point_fee | string | Points used to deduct fee |
| Property | Value |
|---|---|
| role | taker |
| role | maker |
| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | X-Pagination-Limit | integer | Request limit specified | |
| 200 | X-Pagination-Offset | integer | Request offset specified |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/position_close'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/position_close"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/position_close
List position close history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
| side | query | string | false | Query side. long or shot |
| pnl | query | string | false | Query profit or loss |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"time": 1546487347,
"pnl": "0.00013",
"pnl_pnl": "0.00011",
"pnl_fund": "0.00001",
"pnl_fee": "0.00001",
"side": "long",
"contract": "BTC_USDT",
"text": "web",
"max_size": "100",
"accum_size": "100",
"first_open_time": 1546487347,
"long_price": "2026.87",
"short_price": "2544.4"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » time | number(double) | Position close time |
| » contract | string | Futures contract |
| » side | string | Position side, long or short |
| » pnl | string | PNL |
| » pnl_pnl | string | PNL - Position P/L |
| » pnl_fund | string | PNL - Funding Fees |
| » pnl_fee | string | PNL - Transaction Fees |
| » text | string | Text of close order |
| » max_size | string | Max Trade Size |
| » accum_size | string | Cumulative closed position volume |
| » first_open_time | integer(int64) | First Open Time |
| » long_price | string | When 'side' is 'long,' it indicates the opening average price; when 'side' is 'short,' it indicates the closing average price. |
| » short_price | string | When 'side' is 'long,' it indicates the opening average price; when 'side' is 'short,' it indicates the closing average price |
| Property | Value |
|---|---|
| side | long |
| side | short |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/liquidates'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/liquidates"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/liquidates
List liquidation history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| at | query | integer | false | Specify a liquidation timestamp |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"time": 1548654951,
"contract": "BTC_USDT",
"size": 600,
"leverage": "25",
"margin": "0.006705256878",
"entry_price": "3536.123",
"liq_price": "3421.54",
"mark_price": "3420.27",
"order_id": 317393847,
"order_price": "3405",
"fill_price": "3424",
"left": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » time | integer(int64) | Liquidation time |
| » contract | string | Futures contract |
| » leverage | string | Position leverage. Not returned in public endpoints. |
| » size | integer(int64) | Position size |
| » margin | string | Position margin. Not returned in public endpoints. |
| » entry_price | string | Average entry price. Not returned in public endpoints. |
| » liq_price | string | Liquidation price. Not returned in public endpoints. |
| » mark_price | string | Mark price. Not returned in public endpoints. |
| » order_id | integer(int64) | Liquidation order ID. Not returned in public endpoints. |
| » order_price | string | Liquidation order price |
| » fill_price | string | Liquidation order average taker price |
| » left | integer(int64) | Liquidation order maker size |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/auto_deleverages'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/auto_deleverages"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/auto_deleverages
List Auto-Deleveraging History
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| at | query | integer | false | Specify an auto-deleveraging timestamp |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"time": 1675841679,
"contract": "ACH_USDT",
"order_id": 73873128,
"user": 1666,
"cross_leverage_limit": "0",
"leverage": "0",
"entry_price": "2649.648633636364",
"fill_price": "2790.8082",
"position_size": 1,
"trade_size": -10
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | integer(int64) | Automatic deleveraging time |
| » user | integer(int64) | User ID |
| » order_id | integer(int64) | Order ID. Order IDs before 2023-02-20 are null |
| » contract | string | Futures contract |
| » leverage | string | Position leverage |
| » cross_leverage_limit | string | Cross margin leverage(valid only when leverage is 0) |
| » entry_price | string | Average entry price |
| » fill_price | string | Average fill price |
| » trade_size | integer(int64) | Trading size |
| » position_size | integer(int64) | Positions after auto-deleveraging |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/countdown_cancel_all'
query_param = ''
body='{"timeout":30,"contract":"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="/futures/usdt/countdown_cancel_all"
query_param=""
body_param='{"timeout":30,"contract":"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 /futures/{settle}/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,
"contract": "BTC_USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » timeout | body | integer(int32) | true | Countdown time, in seconds |
| » contract | body | string | false | Futures contract |
| settle | path | string | true | Settle currency |
» timeout: Countdown time, in seconds At least 5 seconds, 0 means cancel the countdown
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"triggerTime": "1660039145000"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Set countdown successfully | Inline |
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
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/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="/futures/usdt/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 /futures/{settle}/fee
Query user trading fee rates
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"1INCH_USDT": {
"taker_fee": "0.00025",
"maker_fee": "-0.00010"
},
"AAVE_USDT": {
"taker_fee": "0.00025",
"maker_fee": "-0.00010"
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » additionalProperties | object | The returned result is a map type, where the key represents the market and the value represents the taker and maker fee rates. |
| »» taker_fee | string | Taker fee |
| »» maker_fee | string | maker fee |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/batch_cancel_orders'
query_param = ''
body='["1","2","3"]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/batch_cancel_orders"
query_param=""
body_param='["1","2","3"]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/batch_cancel_orders
Cancel a batch of orders with an ID list
Multiple distinct order ID list can be specified。Each request can cancel a maximum of 20 records.
Body parameter
[
"1",
"2",
"3"
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | integer(int64) | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | array[string] | true | none |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"user_id": 111,
"id": "123456",
"succeeded": true,
"message": ""
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order cancellation operation completed | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » FutureCancelOrderResult | object | Order cancellation result |
| »» id | string | Order ID |
| »» user_id | integer(int64) | User ID |
| »» succeeded | boolean | Whether cancellation succeeded |
| »» message | string | Error message when failed to cancel the order; empty if succeeded |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/batch_amend_orders'
query_param = ''
body='[{"order_id":121212,"amend_text":"batch amend text","size":100,"price":"54321"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/batch_amend_orders"
query_param=""
body_param='[{"order_id":121212,"amend_text":"batch amend text","size":100,"price":"54321"}]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/batch_amend_orders
Batch modify orders with specified IDs
You can specify multiple different order IDs. You can only modify up to 10 orders in one request.
Body parameter
[
{
"order_id": 121212,
"amend_text": "batch amend text",
"size": 100,
"price": "54321"
}
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | integer(int64) | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | array[BatchAmendOrderReq] | true | none |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"succeeded": true,
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request is completed | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Futures order details] |
| » None | object | Futures order details |
| »» succeeded | boolean | Whether the batch of orders succeeded |
| »» label | string | Error label, only exists if execution fails |
| »» detail | string | Error detail, only present if execution failed and details need to be given |
| »» id | integer(int64) | Futures order ID |
| »» user | integer | User ID |
| »» create_time | number(double) | Creation time of order |
| »» finish_time | number(double) | Order finished time. Not returned if order is open |
| »» finish_as | string | How the order was finished. - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC, finish immediately- auto_deleveraged: finished by ADL - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because of position close- position_closed: canceled because the position was closed - reduce_out: only reduce positions by excluding hard-to-fill orders - stp: cancelled because self trade prevention |
| »» status | string | Order status - open: waiting to be traded- finished: finished |
| »» contract | string | Futures contract |
| »» size | integer(int64) | Order size. Specify positive number to make a bid, and negative number to ask |
| »» iceberg | integer(int64) | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
| »» price | string | Order price. 0 for market order with tif set as ioc |
| »» is_close | boolean | Is the order to close position |
| »» is_reduce_only | boolean | Is the order reduce-only |
| »» is_liq | boolean | Is the order for liquidation |
| »» tif | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none |
| »» left | integer(int64) | Size left to be traded |
| »» fill_price | string | Fill price of the order |
| »» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance |
| »» tkfr | string | Taker fee |
| »» mkfr | string | Maker fee |
| »» refu | integer | Reference user ID |
| »» 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 |
| »» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. 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 |
| Property | Value |
|---|---|
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidated |
| finish_as | ioc |
| finish_as | auto_deleveraged |
| finish_as | reduce_only |
| finish_as | position_closed |
| finish_as | reduce_out |
| finish_as | stp |
| status | open |
| status | finished |
| tif | gtc |
| tif | ioc |
| tif | poc |
| tif | fok |
| stp_act | co |
| stp_act | cn |
| stp_act | cb |
| stp_act | - |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/price_orders'
query_param = ''
body='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/price_orders"
query_param=""
body_param='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/price_orders
Create a price-triggered order
Body parameter
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"order_type": "close-long-order"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | FuturesPriceTriggeredOrder | true | none |
| » initial | body | object | true | none |
| »» contract | body | string | true | Futures contract |
| »» size | body | integer(int64) | false | Order size. Positive size means to buy, while negative one means to sell. Set to 0 to close the position |
| »» price | body | string | true | Order price. Set to 0 to use market price |
| »» close | body | boolean | false | Set to true if trying to close the position |
| »» tif | body | string | false | Time in force. If using market price, only ioc is supported. |
| »» text | body | string | false | The source of the order, including: |
| »» reduce_only | body | boolean | false | Set to true to create a reduce-only order |
| »» auto_size | body | string | false | Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0 |
| » trigger | body | object | true | none |
| »» strategy_type | body | integer(int32) | false | How the order will be triggered |
| »» price_type | body | integer(int32) | false | Price type. 0 - latest deal price, 1 - mark price, 2 - index price |
| »» price | body | string | false | Value of price on price triggered, or price gap on price gap triggered |
| »» rule | body | integer(int32) | false | Trigger condition type |
| »» expiration | body | integer | false | How long (in seconds) to wait for the condition to be triggered before cancelling the order. |
| » order_type | body | string | false | Take-profit/stop-loss types, which include: |
| settle | path | string | true | Settle currency |
»» tif: Time in force. If using market price, only ioc is supported.
»» text: The source of the order, including:
»» strategy_type: How the order will be triggered
0: by price, which means the order will be triggered if price condition is satisfied1: by price gap, which means the order will be triggered if gap of recent two prices of specified price_type are satisfied.
Only 0 is supported currently»» rule: Trigger condition type
1: calculated price based on strategy_type and price_type >= price2: calculated price based on strategy_type and price_type <= price» order_type: Take-profit/stop-loss types, which include:
close-long-order: order take-profit/stop-loss, close long positionclose-short-order: order take-profit/stop-loss, close short positionclose-long-position: position take-profit/stop-loss, close long positionclose-short-position: position take-profit/stop-loss, close short positionplan-close-long-position: position planned take-profit/stop-loss, close long positionplan-close-short-position: position planned take-profit/stop-loss, close short positionThe order take-profit/stop-loss can not be passed by request. These two types are read only.
| Parameter | Value |
|---|---|
| »» tif | gtc |
| »» tif | ioc |
| »» strategy_type | 0 |
| »» strategy_type | 1 |
| »» price_type | 0 |
| »» price_type | 1 |
| »» price_type | 2 |
| »» rule | 1 |
| »» rule | 2 |
| settle | btc |
| settle | usdt |
Example responses
201 Response
{
"id": 1432329
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order created | Inline |
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
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/price_orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/price_orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/price_orders
List all auto orders
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| status | query | string | true | Only list the orders with this status |
| contract | query | string | false | Futures contract, return related data only if specified |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| status | open |
| status | finished |
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [FuturesPriceTriggeredOrder] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/price_orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/usdt/price_orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /futures/{settle}/price_orders
Cancel all open orders
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | false | Futures contract, return related data only if specified |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation request accepted. Query order status by listing orders | [FuturesPriceTriggeredOrder] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/price_orders/{order_id}
Get a price-triggered order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| order_id | path | string | true | Retrieve the data of the order with the specified ID |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Auto order detail | FuturesPriceTriggeredOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/usdt/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /futures/{settle}/price_orders/{order_id}
cancel a price-triggered order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| order_id | path | string | true | Retrieve the data of the order with the specified ID |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Auto order detail | FuturesPriceTriggeredOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Delivery contract API
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/contracts'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/contracts \
-H 'Accept: application/json'
GET /delivery/{settle}/contracts
List all futures contracts
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
[
{
"name": "BTC_USDT_20200814",
"underlying": "BTC_USDT",
"cycle": "WEEKLY",
"type": "direct",
"quanto_multiplier": "0.0001",
"mark_type": "index",
"last_price": "9017",
"mark_price": "9019",
"index_price": "9005.3",
"basis_rate": "0.185095",
"basis_value": "13.7",
"basis_impact_value": "100000",
"settle_price": "0",
"settle_price_interval": 60,
"settle_price_duration": 1800,
"settle_fee_rate": "0.0015",
"expire_time": 1593763200,
"order_price_round": "0.1",
"mark_price_round": "0.1",
"leverage_min": "1",
"leverage_max": "100",
"maintenance_rate": "1000000",
"risk_limit_base": "140.726652109199",
"risk_limit_step": "1000000",
"risk_limit_max": "8000000",
"maker_fee_rate": "-0.00025",
"taker_fee_rate": "0.00075",
"ref_discount_rate": "0",
"ref_rebate_rate": "0.2",
"order_price_deviate": "0.5",
"order_size_min": 1,
"order_size_max": 1000000,
"orders_limit": 50,
"orderbook_id": 63,
"trade_id": 26,
"trade_size": 435,
"position_size": 130,
"config_change_time": 1593158867,
"in_delisting": false
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [DeliveryContract] |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/contracts/BTC_USDT_20200814'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/contracts/BTC_USDT_20200814 \
-H 'Accept: application/json'
GET /delivery/{settle}/contracts/{contract}
Get a single contract
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
{
"name": "BTC_USDT_20200814",
"underlying": "BTC_USDT",
"cycle": "WEEKLY",
"type": "direct",
"quanto_multiplier": "0.0001",
"mark_type": "index",
"last_price": "9017",
"mark_price": "9019",
"index_price": "9005.3",
"basis_rate": "0.185095",
"basis_value": "13.7",
"basis_impact_value": "100000",
"settle_price": "0",
"settle_price_interval": 60,
"settle_price_duration": 1800,
"settle_fee_rate": "0.0015",
"expire_time": 1593763200,
"order_price_round": "0.1",
"mark_price_round": "0.1",
"leverage_min": "1",
"leverage_max": "100",
"maintenance_rate": "1000000",
"risk_limit_base": "140.726652109199",
"risk_limit_step": "1000000",
"risk_limit_max": "8000000",
"maker_fee_rate": "-0.00025",
"taker_fee_rate": "0.00075",
"ref_discount_rate": "0",
"ref_rebate_rate": "0.2",
"order_price_deviate": "0.5",
"order_size_min": 1,
"order_size_max": 1000000,
"orders_limit": 50,
"orderbook_id": 63,
"trade_id": 26,
"trade_size": 435,
"position_size": 130,
"config_change_time": 1593158867,
"in_delisting": false
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Contract information | DeliveryContract |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/order_book'
query_param = 'contract=BTC_USDT_20200814'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/order_book?contract=BTC_USDT_20200814 \
-H 'Accept: application/json'
GET /delivery/{settle}/order_book
Futures order book
Bids will be sorted by price from high to low, while asks sorted reversely
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| interval | query | string | false | Order depth. 0 means no aggregation is applied. default to 0 |
| limit | query | integer | false | Maximum number of order depth data in asks or bids |
| with_id | query | boolean | false | Whether the order book update ID will be returned. This ID increases by 1 on every order book update |
| Parameter | Value |
|---|---|
| settle | usdt |
| interval | 0 |
| interval | 0.1 |
| interval | 0.01 |
Example responses
200 Response
{
"id": 123456,
"current": 1623898993.123,
"update": 1623898993.121,
"asks": [
{
"p": "1.52",
"s": 100
},
{
"p": "1.53",
"s": 40
}
],
"bids": [
{
"p": "1.17",
"s": 150
},
{
"p": "1.16",
"s": 203
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order book retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Order Book ID. Increases by 1 on every order book change. Set with_id=true to include this field in response |
| » current | number(double) | Response data generation timestamp |
| » update | number(double) | Order book changed timestamp |
| » asks | array | Asks order depth |
| »» futures_order_book_item | object | none |
| »»» p | string | Price (quote currency) |
| »»» s | integer(int64) | Size |
| »» bids | array | Bids order depth |
| »»» futures_order_book_item | object | none |
| »»»» p | string | Price (quote currency) |
| »»»» s | integer(int64) | Size |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/trades'
query_param = 'contract=BTC_USDT_20200814'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/trades?contract=BTC_USDT_20200814 \
-H 'Accept: application/json'
GET /delivery/{settle}/trades
Futures trading history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| last_id | query | string | false | Specify the starting point for this list based on a previously retrieved id |
| from | query | integer(int64) | false | Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items. |
| to | query | integer(int64) | false | Specify end time in Unix seconds, default to current time |
last_id: Specify the starting point for this list based on a previously retrieved id
This parameter is deprecated. Use from and to instead to limit time range
from: Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items.
If items between from and to are more than limit, only limit number will be returned.
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800,
"contract": "BTC_USDT",
"size": -100,
"price": "100.123"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | integer(int64) | Trade ID |
| » create_time | number(double) | Trading time |
| » create_time_ms | number(double) | Trading time, with milliseconds set to 3 decimal places. |
| » contract | string | Futures contract |
| » size | integer(int64) | Trading size |
| » price | string | Trading price (quote currency) |
| » is_internal | boolean | Whether internal trade. Internal trade refers to the takeover of liquidation orders by the insurance fund and ADL users. Since it is not a normal matching on the market depth, the transaction price may deviate, and it will not be recorded in the K-line. If it is not an internal trade, this field will not be returned. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/candlesticks'
query_param = 'contract=BTC_USDT_20200814'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/candlesticks?contract=BTC_USDT_20200814 \
-H 'Accept: application/json'
GET /delivery/{settle}/candlesticks
Get futures candlesticks
Return specified contract candlesticks.
If prefix contract with mark_, the contract's mark price candlesticks are returned;
if prefix with index_, index price candlesticks will be returned.
Maximum of 2000 points are returned in one query. Be sure not to exceed the limit when specifying from, to and interval
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| from | query | integer(int64) | false | Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified |
| to | query | integer(int64) | false | End time of candlesticks, formatted in Unix timestamp in seconds. Default to current time |
| limit | query | integer | false | Maximum recent data points to return. limit is conflicted with from and to. If either from or to is specified, request will be rejected. |
| interval | query | string | false | Interval time between data points. Note that 1w means natual week(Mon-Sun), while 7d means every 7d since unix 0 |
| Parameter | Value |
|---|---|
| settle | usdt |
| interval | 10s |
| interval | 30s |
| interval | 1m |
| interval | 5m |
| interval | 15m |
| interval | 30m |
| interval | 1h |
| interval | 2h |
| interval | 4h |
| interval | 6h |
| interval | 8h |
| interval | 12h |
| interval | 1d |
| interval | 7d |
| interval | 1w |
| interval | 30d |
Example responses
200 Response
[
{
"t": 1539852480,
"v": 97151,
"c": "1.032",
"h": "1.032",
"l": "1.032",
"o": "1.032"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | data point in every timestamp |
| »» t | number(double) | Unix timestamp in seconds |
| »» v | integer(int64) | size volume (contract size). Only returned if contract is not prefixed |
| »» c | string | Close price (quote currency) |
| »» h | string | Highest price (quote currency) |
| »» l | string | Lowest price (quote currency) |
| »» o | string | Open price (quote 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 = '/delivery/usdt/tickers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/tickers \
-H 'Accept: application/json'
GET /delivery/{settle}/tickers
List futures tickers
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
[
{
"contract": "BTC_USDT",
"last": "6432",
"low_24h": "6278",
"high_24h": "6790",
"change_percentage": "4.43",
"total_size": "32323904",
"volume_24h": "184040233284",
"volume_24h_btc": "28613220",
"volume_24h_usd": "184040233284",
"volume_24h_base": "28613220",
"volume_24h_quote": "184040233284",
"volume_24h_settle": "28613220",
"mark_price": "6534",
"funding_rate": "0.0001",
"funding_rate_indicative": "0.0001",
"index_price": "6531",
"highest_bid": "34089.7",
"highest_size": "100",
"lowest_ask": "34217.9",
"lowest_size": "1000"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » contract | string | Futures contract |
| » last | string | Last trading price |
| » change_percentage | string | Change percentage. |
| » total_size | string | Contract total size |
| » low_24h | string | Lowest trading price in recent 24h |
| » high_24h | string | Highest trading price in recent 24h |
| » volume_24h | string | Trade size in recent 24h |
| » volume_24h_btc | string | Trade volumes in recent 24h in BTC(deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead) |
| » volume_24h_usd | string | Trade volumes in recent 24h in USD(deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead) |
| » volume_24h_base | string | Trade volume in recent 24h, in base currency |
| » volume_24h_quote | string | Trade volume in recent 24h, in quote currency |
| » volume_24h_settle | string | Trade volume in recent 24h, in settle currency |
| » mark_price | string | Recent mark price |
| » funding_rate | string | Funding rate |
| » funding_rate_indicative | string | Indicative Funding rate in next period |
| » index_price | string | Index price |
| » quanto_base_rate | string | Exchange rate of base currency and settlement currency in Quanto contract. Does not exists in contracts of other types |
| » basis_rate | string | Basis rate |
| » basis_value | string | Basis value |
| » lowest_ask | string | Recent lowest ask |
| » lowest_size | string | The latest seller's lowest price order quantity |
| » highest_bid | string | Recent highest bid |
| » highest_size | string | The latest buyer's highest price order volume |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/insurance'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/insurance \
-H 'Accept: application/json'
GET /delivery/{settle}/insurance
Futures insurance balance history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
[
{
"t": 1543968000,
"b": "83.0031"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » t | integer(int64) | Unix timestamp in seconds |
| » b | string | Insurance balance |
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/accounts
Query futures account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
{
"user": 1666,
"currency": "USDT",
"total": "9707.803567115145",
"unrealised_pnl": "3371.248828",
"position_margin": "38.712189181",
"order_margin": "0",
"available": "9669.091377934145",
"point": "0",
"bonus": "0",
"in_dual_mode": false,
"enable_evolved_classic": false,
"cross_initial_margin": "61855.56788525",
"cross_maintenance_margin": "682.04678105",
"cross_order_margin": "0",
"cross_unrealised_pnl": "1501.178222634128",
"cross_available": "27549.406108813951",
"isolated_position_margin": "0",
"history": {
"dnw": "10000",
"pnl": "68.3685",
"fee": "-1.645812875",
"refr": "0",
"fund": "-358.919120009855",
"point_dnw": "0",
"point_fee": "0",
"point_refr": "0",
"bonus_dnw": "0",
"bonus_offset": "0"
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » 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 | The maintenance deposit occupied by the position is suitable for the new classic account margin model and unified account model |
| » bonus | string | Perpetual Contract Bonus |
| » enable_evolved_classic | boolean | Classic account margin mode, true-new mode, false-old mode |
| » cross_order_margin | string | Full -warehouse hanging order deposit, suitable for the new classic account margin model |
| » cross_initial_margin | string | The initial security deposit of the full warehouse is suitable for the new classic account margin model |
| » cross_maintenance_margin | string | Maintain deposit in full warehouse, suitable for new classic account margin models |
| » cross_unrealised_pnl | string | The full warehouse does not achieve profit and loss, suitable for the new classic account margin model |
| » cross_available | string | Full warehouse available amount, suitable for the new classic account margin model |
| » isolated_position_margin | string | Ware -position margin, suitable for the new classic account margin model |
| » 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
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/account_book"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/account_book
Query account book
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
| type | query | string | false | Changing Type: |
type: Changing Type:
| Parameter | Value |
|---|---|
| settle | usdt |
| type | dnw |
| type | pnl |
| type | fee |
| type | refr |
| type | fund |
| type | point_dnw |
| type | point_fee |
| type | point_refr |
Example responses
200 Response
[
{
"time": 1682294400.123456,
"change": "0.000010152188",
"balance": "4.59316525194",
"text": "ETH_USD:6086261",
"type": "fee",
"contract": "ETH_USD",
"trade_id": "1",
"id": "1"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » time | number(double) | Change time |
| » change | string | Change amount |
| » balance | string | Balance after change |
| » type | string | Changing Type： - dnw: Deposit & Withdraw - pnl: Profit & Loss by reducing position - fee: Trading fee - refr: Referrer rebate - fund: Funding - point_dnw: POINT Deposit & Withdraw - point_fee: POINT Trading fee - point_refr: POINT Referrer rebate - bonus_offset: bouns deduction |
| » text | string | Comment |
| » contract | string | Futures contract, the field is only available for data after 2023-10-30. |
| » trade_id | string | trade id |
| » id | string | 账户变更记录 id |
| Property | Value |
|---|---|
| type | dnw |
| type | pnl |
| type | fee |
| type | refr |
| type | fund |
| type | point_dnw |
| type | point_fee |
| type | point_refr |
| type | bonus_offset |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/positions'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/positions"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/positions
List all positions of a user
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"cross_leverage_limit": "0"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Position] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/positions/BTC_USDT_20200814'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/positions/BTC_USDT_20200814"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/positions/{contract}
Get single position
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"cross_leverage_limit": "0"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/positions/BTC_USDT_20200814/margin'
query_param = 'change=0.01'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/positions/BTC_USDT_20200814/margin"
query_param="change=0.01"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /delivery/{settle}/positions/{contract}/margin
Update position margin
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| change | query | string | true | Margin change. Use positive number to increase margin, negative number otherwise. |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"cross_leverage_limit": "0"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/positions/BTC_USDT_20200814/leverage'
query_param = 'leverage=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/positions/BTC_USDT_20200814/leverage"
query_param="leverage=10"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /delivery/{settle}/positions/{contract}/leverage
Update position leverage
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| leverage | query | string | true | New position leverage |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"cross_leverage_limit": "0"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/positions/BTC_USDT_20200814/risk_limit'
query_param = 'risk_limit=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/positions/BTC_USDT_20200814/risk_limit"
query_param="risk_limit=10"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /delivery/{settle}/positions/{contract}/risk_limit
Update position risk limit
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| risk_limit | query | string | true | New position risk limit |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"cross_leverage_limit": "0"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/orders'
query_param = ''
body='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/orders"
query_param=""
body_param='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /delivery/{settle}/orders
Create a futures order
Zero-filled order cannot be retrieved 10 minutes after order cancellation
Body parameter
{
"contract": "BTC_USDT",
"size": 6024,
"iceberg": 0,
"price": "3765",
"tif": "gtc",
"text": "t-my-custom-id",
"stp_act": "-"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | FuturesOrder | true | none |
| » contract | body | string | true | Futures contract |
| » size | body | integer(int64) | true | Order size. Specify positive number to make a bid, and negative number to ask |
| » iceberg | body | integer(int64) | false | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
| » price | body | string | false | Order price. 0 for market order with tif set as ioc |
| » close | body | boolean | false | Set as true to close the position, with size set to 0 |
| » reduce_only | body | boolean | false | Set as true to be reduce-only order |
| » tif | body | string | false | Time in force |
| » text | body | string | false | User defined information. If not empty, must follow the rules below: |
| » auto_size | body | string | false | Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0 |
| » stp_act | body | string | false | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies |
| settle | path | string | true | Settle currency |
» tif: Time in force
» text: User defined information. If not empty, must follow the rules below:
t-t- prefix» stp_act: Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies
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。STP group, an error will be returned when passing the stp_act parameter。| Parameter | Value |
|---|---|
| » tif | gtc |
| » tif | ioc |
| » tif | poc |
| » tif | fok |
| » auto_size | close_long |
| » auto_size | close_short |
| » stp_act | co |
| » stp_act | cn |
| » stp_act | cb |
| » stp_act | - |
| settle | usdt |
Example responses
201 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order details | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/orders
List futures orders
Zero-filled order cannot be retrieved 10 minutes after order cancellation
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | false | Futures contract |
| status | query | string | true | Only list the orders with this status |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| last_id | query | string | false | Specify list staring point using the id of last record in previous list-query results |
| count_total | query | integer | false | Whether to return total number matched. Default to 0(no return) |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| status | open |
| status | finished |
| count_total | 0 |
| count_total | 1 |
| settle | usdt |
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [FuturesOrder] |
| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | X-Pagination-Limit | integer | Request limit specified | |
| 200 | X-Pagination-Offset | integer | Request offset specified | |
| 200 | X-Pagination-Total | integer | Total number matched. Only returned if count_total set to 1 |
WARNING
To perform this operation, you must be authenticated by API key and secret
open orders matchedCode samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/orders'
query_param = 'contract=BTC_USDT_20200814'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/delivery/usdt/orders"
query_param="contract=BTC_USDT_20200814"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /delivery/{settle}/orders
Cancel all open orders matched
Zero-filled order cannot be retrieved 10 minutes after order cancellation
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | true | Futures contract |
| side | query | string | false | All bids or asks. Both included if not specified |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| side | ask |
| side | bid |
| settle | usdt |
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | All orders matched cancelled | [FuturesOrder] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/orders/{order_id}
Get a single order
Zero-filled order cannot be retrieved 10 minutes after order cancellation
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| order_id | path | string | true | Retrieve the data of the order with the specified ID |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order details | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/delivery/usdt/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /delivery/{settle}/orders/{order_id}
Cancel a single order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| order_id | path | string | true | Retrieve the data of the order with the specified ID |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order details | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/my_trades'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/my_trades"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/my_trades
List personal trading history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract |
| order | query | integer(int64) | false | Futures order ID, return related data only if specified |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| last_id | query | string | false | Specify list staring point using the id of last record in previous list-query results |
| count_total | query | integer | false | Whether to return total number matched. Default to 0(no return) |
| Parameter | Value |
|---|---|
| settle | usdt |
| count_total | 0 |
| count_total | 1 |
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800.123,
"contract": "BTC_USDT",
"order_id": "21893289839",
"size": 100,
"price": "100.123",
"text": "t-123456",
"fee": "0.01",
"point_fee": "0",
"role": "taker",
"close_size": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | integer(int64) | Trade ID |
| » create_time | number(double) | Trading time |
| » contract | string | Futures contract |
| » order_id | string | Order ID related |
| » size | integer(int64) | Trading size |
| » close_size | integer(int64) | Number of closed positions: close_size=0 && size＞0 Open long position close_size=0 && size＜0 Open short position close_size>0 && size>0 && size <= close_size Close short postion close_size>0 && size>0 && size > close_size Close short position and open long position close_size<0 && size<0 && size >= close_size Close long postion close_size<0 && size<0 && size < close_size Close long position and open short position |
| » price | string | Trading price |
| » role | string | Trade role. Available values are taker and maker |
| » text | string | User defined information |
| » fee | string | Fee deducted |
| » point_fee | string | Points used to deduct fee |
| Property | Value |
|---|---|
| role | taker |
| role | maker |
| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | X-Pagination-Limit | integer | Request limit specified | |
| 200 | X-Pagination-Offset | integer | Request offset specified | |
| 200 | X-Pagination-Total | integer | Total number matched. Only returned if count_total set to 1 |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/position_close'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/position_close"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/position_close
List position close history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
[
{
"time": 1546487347,
"pnl": "0.00013",
"pnl_pnl": "0.00011",
"pnl_fund": "0.00001",
"pnl_fee": "0.00001",
"side": "long",
"contract": "BTC_USDT",
"text": "web",
"max_size": "100",
"accum_size": "100",
"first_open_time": 1546487347,
"long_price": "2026.87",
"short_price": "2544.4"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » time | number(double) | Position close time |
| » contract | string | Futures contract |
| » side | string | Position side, long or short |
| » pnl | string | PNL |
| » pnl_pnl | string | PNL - Position P/L |
| » pnl_fund | string | PNL - Funding Fees |
| » pnl_fee | string | PNL - Transaction Fees |
| » text | string | Text of close order |
| » max_size | string | Max Trade Size |
| » accum_size | string | Cumulative closed position volume |
| » first_open_time | integer(int64) | First Open Time |
| » long_price | string | When 'side' is 'long,' it indicates the opening average price; when 'side' is 'short,' it indicates the closing average price. |
| » short_price | string | When 'side' is 'long,' it indicates the opening average price; when 'side' is 'short,' it indicates the closing average price |
| Property | Value |
|---|---|
| side | long |
| side | short |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/liquidates'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/liquidates"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/liquidates
List liquidation history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| at | query | integer | false | Specify a liquidation timestamp |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
[
{
"time": 1548654951,
"contract": "BTC_USDT",
"size": 600,
"leverage": "25",
"margin": "0.006705256878",
"entry_price": "3536.123",
"liq_price": "3421.54",
"mark_price": "3420.27",
"order_id": 317393847,
"order_price": "3405",
"fill_price": "3424",
"left": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » time | integer(int64) | Liquidation time |
| » contract | string | Futures contract |
| » leverage | string | Position leverage. Not returned in public endpoints. |
| » size | integer(int64) | Position size |
| » margin | string | Position margin. Not returned in public endpoints. |
| » entry_price | string | Average entry price. Not returned in public endpoints. |
| » liq_price | string | Liquidation price. Not returned in public endpoints. |
| » mark_price | string | Mark price. Not returned in public endpoints. |
| » order_id | integer(int64) | Liquidation order ID. Not returned in public endpoints. |
| » order_price | string | Liquidation order price |
| » fill_price | string | Liquidation order average taker price |
| » left | integer(int64) | Liquidation order maker size |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/settlements'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/settlements"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/settlements
List settlement history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| at | query | integer | false | Specify a settlement timestamp |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
[
{
"time": 1548654951,
"contract": "BTC_USDT",
"size": 600,
"leverage": "25",
"margin": "0.006705256878",
"entry_price": "3536.123",
"settle_price": "3421.54",
"profit": "-6.87498",
"fee": "0.03079386"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | integer(int64) | Liquidation time |
| » contract | string | Futures contract |
| » leverage | string | Position leverage |
| » size | integer(int64) | Position size |
| » margin | string | Position margin |
| » entry_price | string | Average entry price |
| » settle_price | string | Settled price |
| » profit | string | Profit |
| » fee | string | Fee deducted |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/risk_limit_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/risk_limit_tiers \
-H 'Accept: application/json'
GET /delivery/{settle}/risk_limit_tiers
List risk limit tiers
When the 'contract' parameter is not passed, the default is to query the risk limits for the top 100 markets.'Limit' and 'offset' correspond to pagination queries at the market level, not to the length of the returned array. This only takes effect when the 'contract' parameter is empty.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
[
{
"maintenance_rate": "0.01",
"tier": 1,
"initial_rate": "0.02",
"leverage_max": "50",
"risk_limit": "500000",
"contract": "BTC_USDT"
},
{
"initial_rate": "0.03",
"maintenance_rate": "0.02",
"tier": 2,
"risk_limit": "1000000",
"leverage_max": "33.33",
"contract": "BTC_USDT"
},
{
"maintenance_rate": "0.01",
"tier": 1,
"initial_rate": "0.02",
"leverage_max": "50",
"risk_limit": "500000",
"contract": "ETH_USDT"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Retrieve risk limit configurations for different tiers under a specified contract.] |
| » None | object | Retrieve risk limit configurations for different tiers under a specified contract. |
| »» tier | integer(int) | Tier |
| »» risk_limit | string | Position risk limit |
| »» initial_rate | string | Initial margin rate |
| »» maintenance_rate | string | Maintenance margin rate |
| »» leverage_max | string | Maximum leverage |
| »» contract | string | Markets, visible only during market pagination requests |
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/price_orders'
query_param = ''
body='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/price_orders"
query_param=""
body_param='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /delivery/{settle}/price_orders
Create a price-triggered order
Body parameter
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"order_type": "close-long-order"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | FuturesPriceTriggeredOrder | true | none |
| » initial | body | object | true | none |
| »» contract | body | string | true | Futures contract |
| »» size | body | integer(int64) | false | Order size. Positive size means to buy, while negative one means to sell. Set to 0 to close the position |
| »» price | body | string | true | Order price. Set to 0 to use market price |
| »» close | body | boolean | false | Set to true if trying to close the position |
| »» tif | body | string | false | Time in force. If using market price, only ioc is supported. |
| »» text | body | string | false | The source of the order, including: |
| »» reduce_only | body | boolean | false | Set to true to create a reduce-only order |
| »» auto_size | body | string | false | Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0 |
| » trigger | body | object | true | none |
| »» strategy_type | body | integer(int32) | false | How the order will be triggered |
| »» price_type | body | integer(int32) | false | Price type. 0 - latest deal price, 1 - mark price, 2 - index price |
| »» price | body | string | false | Value of price on price triggered, or price gap on price gap triggered |
| »» rule | body | integer(int32) | false | Trigger condition type |
| »» expiration | body | integer | false | How long (in seconds) to wait for the condition to be triggered before cancelling the order. |
| » order_type | body | string | false | Take-profit/stop-loss types, which include: |
| settle | path | string | true | Settle currency |
»» tif: Time in force. If using market price, only ioc is supported.
»» text: The source of the order, including:
»» strategy_type: How the order will be triggered
0: by price, which means the order will be triggered if price condition is satisfied1: by price gap, which means the order will be triggered if gap of recent two prices of specified price_type are satisfied.
Only 0 is supported currently»» rule: Trigger condition type
1: calculated price based on strategy_type and price_type >= price2: calculated price based on strategy_type and price_type <= price» order_type: Take-profit/stop-loss types, which include:
close-long-order: order take-profit/stop-loss, close long positionclose-short-order: order take-profit/stop-loss, close short positionclose-long-position: position take-profit/stop-loss, close long positionclose-short-position: position take-profit/stop-loss, close short positionplan-close-long-position: position planned take-profit/stop-loss, close long positionplan-close-short-position: position planned take-profit/stop-loss, close short positionThe order take-profit/stop-loss can not be passed by request. These two types are read only.
| Parameter | Value |
|---|---|
| »» tif | gtc |
| »» tif | ioc |
| »» strategy_type | 0 |
| »» strategy_type | 1 |
| »» price_type | 0 |
| »» price_type | 1 |
| »» price_type | 2 |
| »» rule | 1 |
| »» rule | 2 |
| settle | usdt |
Example responses
201 Response
{
"id": 1432329
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order created | Inline |
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
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/price_orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/price_orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/price_orders
List all auto orders
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| status | query | string | true | Only list the orders with this status |
| contract | query | string | false | Futures contract, return related data only if specified |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| status | open |
| status | finished |
| settle | usdt |
Example responses
200 Response
[
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [FuturesPriceTriggeredOrder] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/price_orders'
query_param = 'contract=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/delivery/usdt/price_orders"
query_param="contract=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /delivery/{settle}/price_orders
Cancel all open orders
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | true | Futures contract |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
[
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation request accepted. Query order status by listing orders | [FuturesPriceTriggeredOrder] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/price_orders/{order_id}
Get a price-triggered order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| order_id | path | string | true | Retrieve the data of the order with the specified ID |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Auto order detail | FuturesPriceTriggeredOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/delivery/usdt/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /delivery/{settle}/price_orders/{order_id}
cancel a price-triggered order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| order_id | path | string | true | Retrieve the data of the order with the specified ID |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Auto order detail | FuturesPriceTriggeredOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Options API
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/underlyings'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/underlyings \
-H 'Accept: application/json'
GET /options/underlyings
List all underlyings
Example responses
200 Response
[
{
"name": "BTC_USDT",
"index_price": "70000"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » name | string | Underlying name |
| » index_price | string | Spot index price (quote 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 = '/options/expirations'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/expirations?underlying=BTC_USDT \
-H 'Accept: application/json'
GET /options/expirations
List all expiration times
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | true | Underlying (Obtained by listing underlying endpoint) |
Example responses
200 Response
[
1637913600
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List expiration times of specified underlying | [integer] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | integer(int64) | Unix timestamp of the expiration time |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/contracts'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/contracts?underlying=BTC_USDT \
-H 'Accept: application/json'
GET /options/contracts
List all the contracts with specified underlying and expiration time
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | true | Underlying (Obtained by listing underlying endpoint) |
| expiration | query | integer(int64) | false | Unix timestamp of the expiration time |
Example responses
200 Response
[
{
"name": "BTC_USDT-20211130-65000-C",
"tag": "WEEK",
"create_time": 1636702700,
"expiration_time": 1637913600,
"is_call": true,
"strike_price": "65000",
"last_price": "13000",
"mark_price": "14010",
"orderbook_id": 9,
"trade_id": 1,
"trade_size": 10,
"position_size": 10,
"underlying": "BTC_USDT",
"underlying_price": "70000",
"multiplier": "0.0001",
"order_price_round": "0.1",
"mark_price_round": "0.1",
"maker_fee_rate": "0.0004",
"taker_fee_rate": "0.0004",
"price_limit_fee_rate": "0.1",
"ref_discount_rate": "0",
"ref_rebate_rate": "0",
"order_price_deviate": "0.5",
"order_size_min": 1,
"order_size_max": 100000,
"orders_limit": 50
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Options contract detail] |
| » None | object | Options contract detail |
| »» name | string | Options contract name |
| »» tag | string | tag |
| »» create_time | number(double) | Creation time |
| »» expiration_time | number(double) | Expiration time |
| »» is_call | boolean | true means call options, while false is put options |
| »» multiplier | string | Multiplier used in converting from invoicing to settlement currency |
| »» underlying | string | Underlying |
| »» underlying_price | string | Underlying price (quote currency) |
| »» last_price | string | Last trading price |
| »» mark_price | string | Current mark price (quote currency) |
| »» index_price | string | Current index price (quote currency) |
| »» maker_fee_rate | string | Maker fee rate, where negative means rebate |
| »» taker_fee_rate | string | Taker fee rate |
| »» order_price_round | string | Minimum order price increment |
| »» mark_price_round | string | Minimum mark price increment |
| »» order_size_min | integer(int64) | Minimum order size the contract allowed |
| »» order_size_max | integer(int64) | Maximum order size the contract allowed |
| »» order_price_deviate | string | The positive and negative offset allowed between the order price and the current mark price, that is, the order price order_price must meet the following conditions:order_price is within the range of mark_price +/- order_price_deviate * underlying_price and does not distinguish between buy and sell orders |
| »» ref_discount_rate | string | Referral fee rate discount |
| »» ref_rebate_rate | string | Referrer commission rate |
| »» orderbook_id | integer(int64) | Current orderbook ID |
| »» trade_id | integer(int64) | Current trade ID |
| »» trade_size | integer(int64) | Historical accumulated trade size |
| »» position_size | integer(int64) | Current total long position size |
| »» orders_limit | integer | Maximum number of open orders |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/contracts/BTC_USDT-20211130-65000-C'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/contracts/BTC_USDT-20211130-65000-C \
-H 'Accept: application/json'
GET /options/contracts/{contract}
Query specified contract detail
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | path | string | true | none |
Example responses
200 Response
{
"name": "BTC_USDT-20211130-65000-C",
"tag": "WEEK",
"create_time": 1636702700,
"expiration_time": 1637913600,
"is_call": true,
"strike_price": "65000",
"last_price": "13000",
"mark_price": "14010",
"orderbook_id": 9,
"trade_id": 1,
"trade_size": 10,
"position_size": 10,
"underlying": "BTC_USDT",
"underlying_price": "70000",
"multiplier": "0.0001",
"order_price_round": "0.1",
"mark_price_round": "0.1",
"maker_fee_rate": "0.0004",
"taker_fee_rate": "0.0004",
"price_limit_fee_rate": "0.1",
"ref_discount_rate": "0",
"ref_rebate_rate": "0",
"order_price_deviate": "0.5",
"order_size_min": 1,
"order_size_max": 100000,
"orders_limit": 50
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
Options contract detail
| Name | Type | Description |
|---|---|---|
| » name | string | Options contract name |
| » tag | string | tag |
| » create_time | number(double) | Creation time |
| » expiration_time | number(double) | Expiration time |
| » is_call | boolean | true means call options, while false is put options |
| » multiplier | string | Multiplier used in converting from invoicing to settlement currency |
| » underlying | string | Underlying |
| » underlying_price | string | Underlying price (quote currency) |
| » last_price | string | Last trading price |
| » mark_price | string | Current mark price (quote currency) |
| » index_price | string | Current index price (quote currency) |
| » maker_fee_rate | string | Maker fee rate, where negative means rebate |
| » taker_fee_rate | string | Taker fee rate |
| » order_price_round | string | Minimum order price increment |
| » mark_price_round | string | Minimum mark price increment |
| » order_size_min | integer(int64) | Minimum order size the contract allowed |
| » order_size_max | integer(int64) | Maximum order size the contract allowed |
| » order_price_deviate | string | The positive and negative offset allowed between the order price and the current mark price, that is, the order price order_price must meet the following conditions:order_price is within the range of mark_price +/- order_price_deviate * underlying_price and does not distinguish between buy and sell orders |
| » ref_discount_rate | string | Referral fee rate discount |
| » ref_rebate_rate | string | Referrer commission rate |
| » orderbook_id | integer(int64) | Current orderbook ID |
| » trade_id | integer(int64) | Current trade ID |
| » trade_size | integer(int64) | Historical accumulated trade size |
| » position_size | integer(int64) | Current total long position size |
| » orders_limit | integer | Maximum number of open orders |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/settlements'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/settlements?underlying=BTC_USDT \
-H 'Accept: application/json'
GET /options/settlements
List settlement history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | true | Underlying (Obtained by listing underlying endpoint) |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
Example responses
200 Response
[
{
"time": 1598839200,
"profit": "312.35",
"fee": "0.3284",
"settle_price": "11687.65",
"contract": "BTC-WEEKLY-200824-11000-P",
"strike_price": "12000"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » time | number(double) | Last changed time of configuration |
| » contract | string | Options contract name |
| » profit | string | Settlement profit per size (quote currency) |
| » fee | string | Settlement fee per size (quote currency) |
| » strike_price | string | Strike price (quote currency) |
| » settle_price | string | Settlement price (quote 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 = '/options/settlements/BTC_USDT-20211130-65000-C'
query_param = 'underlying=BTC_USDT&at=0'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/settlements/BTC_USDT-20211130-65000-C?underlying=BTC_USDT&at=0 \
-H 'Accept: application/json'
GET /options/settlements/{contract}
Get specified contract's settlement
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | path | string | true | none |
| underlying | query | string | true | Underlying (Obtained by listing underlying endpoint) |
| at | query | integer(int64) | true | none |
Example responses
200 Response
{
"time": 1598839200,
"profit": "312.35",
"fee": "0.3284",
"settle_price": "11687.65",
"contract": "BTC-WEEKLY-200824-11000-P",
"strike_price": "12000"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | number(double) | Last changed time of configuration |
| » contract | string | Options contract name |
| » profit | string | Settlement profit per size (quote currency) |
| » fee | string | Settlement fee per size (quote currency) |
| » strike_price | string | Strike price (quote currency) |
| » settle_price | string | Settlement price (quote 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 = '/options/my_settlements'
query_param = 'underlying=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/my_settlements"
query_param="underlying=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/my_settlements
List my options settlements
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | true | Underlying (Obtained by listing underlying endpoint) |
| contract | query | string | false | Options contract name |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
Example responses
200 Response
[
{
"size": -1,
"settle_profit": "0",
"contract": "BTC_USDT-20220624-26000-C",
"strike_price": "26000",
"time": 1656057600,
"settle_price": "20917.461281337048",
"underlying": "BTC_USDT",
"realised_pnl": "-0.00116042",
"fee": "0"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | number(double) | Settlement time |
| » underlying | string | Underlying |
| » contract | string | Options contract name |
| » strike_price | string | Strike price (quote currency) |
| » settle_price | string | Settlement price (quote currency) |
| » size | integer(int64) | Size |
| » settle_profit | string | Settlement profit (quote currency) |
| » fee | string | Fee (quote currency) |
| » realised_pnl | string | The accumulated profit and loss of opening a position, including premium, fee, settlement profit, etc. (quote currency) |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/order_book'
query_param = 'contract=BTC_USDT-20210916-5000-C'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/order_book?contract=BTC_USDT-20210916-5000-C \
-H 'Accept: application/json'
GET /options/order_book
Options order book
Bids will be sorted by price from high to low, while asks sorted reversely
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | true | Options contract name |
| interval | query | string | false | Order depth. 0 means no aggregation is applied. default to 0 |
| limit | query | integer | false | Maximum number of order depth data in asks or bids |
| with_id | query | boolean | false | Whether the order book update ID will be returned. This ID increases by 1 on every order book update |
| Parameter | Value |
|---|---|
| interval | 0 |
| interval | 0.1 |
| interval | 0.01 |
Example responses
200 Response
{
"id": 123456,
"current": 1623898993.123,
"update": 1623898993.121,
"asks": [
{
"p": "1.52",
"s": 100
},
{
"p": "1.53",
"s": 40
}
],
"bids": [
{
"p": "1.17",
"s": 150
},
{
"p": "1.16",
"s": 203
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order book retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Order Book ID. Increases by 1 on every order book change. Set with_id=true to include this field in response |
| » current | number(double) | Response data generation timestamp |
| » update | number(double) | Order book changed timestamp |
| » asks | array | Asks order depth |
| »» futures_order_book_item | object | none |
| »»» p | string | Price (quote currency) |
| »»» s | integer(int64) | Size |
| »» bids | array | Bids order depth |
| »»» futures_order_book_item | object | none |
| »»»» p | string | Price (quote currency) |
| »»»» s | integer(int64) | Size |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/tickers'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/tickers?underlying=BTC_USDT \
-H 'Accept: application/json'
GET /options/tickers
List tickers of options contracts
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | true | Underlying (Obtained by listing underlying endpoint) |
Example responses
200 Response
[
{
"name": "BTC_USDT-20211130-65000-C",
"last_price": "13000",
"mark_price": "14010",
"position_size": 10,
"ask1_size": 0,
"ask1_price": "0",
"bid1_size": 1,
"bid1_price": "11",
"vega": "41.41202",
"theta": "-120.1506",
"rho": "6.52485",
"gamma": "0.00004",
"delta": "0.33505",
"mark_iv": "0.123",
"bid_iv": "0.023",
"ask_iv": "0.342",
"leverage": "13"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Options contract detail |
| »» name | string | Options contract name |
| »» last_price | string | Last trading price (quote currency) |
| »» mark_price | string | Current mark price (quote currency) |
| »» index_price | string | Current index price (quote currency) |
| »» ask1_size | integer(int64) | Best ask size |
| »» ask1_price | string | Best ask price |
| »» bid1_size | integer(int64) | Best bid size |
| »» bid1_price | string | Best bid price |
| »» position_size | integer(int64) | Current total long position size |
| »» mark_iv | string | Implied volatility |
| »» bid_iv | string | Bid side implied volatility |
| »» ask_iv | string | Ask side implied volatility |
| »» leverage | string | Current leverage. Formula: underlying_price / mark_price * delta |
| »» delta | string | Delta |
| »» gamma | string | Gamma |
| »» vega | string | Vega |
| »» theta | string | Theta |
| »» rho | string | Rho |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/underlying/tickers/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/underlying/tickers/BTC_USDT \
-H 'Accept: application/json'
GET /options/underlying/tickers/{underlying}
Get underlying ticker
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | path | string | true | Underlying |
Example responses
200 Response
{
"trade_put": 33505,
"trade_call": 123,
"index_price": "76543.3"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
Options underlying detail
| Name | Type | Description |
|---|---|---|
| » trade_put | integer(int64) | Total put options trades amount in last 24h |
| » trade_call | integer(int64) | Total call options trades amount in last 24h |
| » index_price | string | Index price (quote 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 = '/options/candlesticks'
query_param = 'contract=BTC_USDT-20210916-5000-C'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/candlesticks?contract=BTC_USDT-20210916-5000-C \
-H 'Accept: application/json'
GET /options/candlesticks
Get options candlesticks
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | true | Options contract name |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
| interval | query | string | false | Interval time between data points |
| Parameter | Value |
|---|---|
| interval | 1m |
| interval | 5m |
| interval | 15m |
| interval | 30m |
| interval | 1h |
Example responses
200 Response
[
{
"t": 1539852480,
"v": 97151,
"c": "1.032",
"h": "1.032",
"l": "1.032",
"o": "1.032"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | data point in every timestamp |
| »» t | number(double) | Unix timestamp in seconds |
| »» v | integer(int64) | size volume (contract size). Only returned if contract is not prefixed |
| »» c | string | Close price (quote currency, unit: underlying corresponding option price) |
| »» h | string | Highest price (quote currency, unit: underlying corresponding option price) |
| »» l | string | Lowest price (quote currency, unit: underlying corresponding option price) |
| »» o | string | Open price (quote currency, unit: underlying corresponding option price) |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/underlying/candlesticks'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/underlying/candlesticks?underlying=BTC_USDT \
-H 'Accept: application/json'
GET /options/underlying/candlesticks
Mark price candlesticks of an underlying
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | true | Underlying (Obtained by listing underlying endpoint) |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
| interval | query | string | false | Interval time between data points |
| Parameter | Value |
|---|---|
| interval | 1m |
| interval | 5m |
| interval | 15m |
| interval | 30m |
| interval | 1h |
Example responses
200 Response
[
{
"t": 1539852480,
"v": 97151,
"c": "1.032",
"h": "1.032",
"l": "1.032",
"o": "1.032",
"sum": "3580"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [data point in every timestamp] |
| » None | object | data point in every timestamp |
| »» t | number(double) | Unix timestamp in seconds |
| »» v | integer(int64) | size volume (contract size). Only returned if contract is not prefixed |
| »» c | string | Close price (quote currency) |
| »» h | string | Highest price (quote currency) |
| »» l | string | Lowest price (quote currency) |
| »» o | string | Open price (quote currency) |
| »» sum | string | Trading volume (unit: Quote 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 = '/options/trades'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/trades \
-H 'Accept: application/json'
GET /options/trades
Options trade history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | false | Options contract name |
| type | query | string(P) | false | C is call, while P is put |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800,
"contract": "BTC_USDT",
"size": -100,
"price": "100.123"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | integer(int64) | Trade ID |
| » create_time | number(double) | Trading time |
| » create_time_ms | number(double) | Trading time, with milliseconds set to 3 decimal places. |
| » contract | string | Futures contract |
| » size | integer(int64) | Trading size |
| » price | string | Trading price (quote currency) |
| » is_internal | boolean | Whether internal trade. Internal trade refers to the takeover of liquidation orders by the insurance fund and ADL users. Since it is not a normal matching on the market depth, the transaction price may deviate, and it will not be recorded in the K-line. If it is not an internal trade, this field will not be returned. |
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/accounts
List options account
Example responses
200 Response
{
"user": 666,
"currency": "USDT",
"short_enabled": true,
"mmp_enabled": false,
"liq_triggered": false,
"margin_mode": 0,
"total": "1650.443022",
"position_value": "-40.1136",
"equity": "1610.329422",
"unrealised_pnl": "-0.7811",
"init_margin": "0",
"maint_margin": "135.541485",
"order_margin": "139.74496",
"ask_order_margin": "139.74496",
"bid_order_margin": "0",
"available": "1514.901537",
"point": "0",
"orders_limit": 10,
"position_notional_limit": 1000000
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » user | integer(int64) | User ID |
| » total | string | 账户余额 |
| » position_value | string | 仓位价值，做多仓位价值为正，做空仓位价值为负 |
| » equity | string | 账户权益，账户余额与仓位价值的和 |
| » short_enabled | boolean | If the account is allowed to short |
| » mmp_enabled | boolean | 是否启用MMP |
| » liq_triggered | boolean | 是否触发仓位强平 |
| » margin_mode | integer(int32) | ｜ 保证金模式： - 0：经典现货保证金模式 - 1：跨币种保证金模式 - 2：组合保证金模式 |
| » unrealised_pnl | string | Unrealized PNL |
| » init_margin | string | Initial position margin |
| » maint_margin | string | Position maintenance margin |
| » order_margin | string | Order margin of unfinished orders |
| » ask_order_margin | string | 未完成卖单的保证金 |
| » bid_order_margin | string | 未完成买单的保证金 |
| » available | string | Available balance to transfer out or trade |
| » point | string | POINT amount |
| » currency | string | Settle currency |
| » orders_limit | integer(int32) | 未完成订单数量上限 |
| » position_notional_limit | integer(int64) | 名义价值上限，包含仓位以及未完成订单的名义价值 |
| Property | Value |
|---|---|
| margin_mode | 0 |
| margin_mode | 1 |
| margin_mode | 2 |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/account_book"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/account_book
List account changing history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
| type | query | string | false | Changing Type: |
type: Changing Type:
| Parameter | Value |
|---|---|
| type | dnw |
| type | prem |
| type | fee |
| type | refr |
| type | set |
Example responses
200 Response
[
{
"time": 1636426005,
"change": "-0.16",
"balance": "7378.189",
"text": "BTC_USDT-20211216-5000-P:25",
"type": "fee"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | number(double) | Change time |
| » change | string | Amount changed (USDT) |
| » balance | string | Account total balance after change (USDT) |
| » type | string | Changing Type: - dnw: Deposit & Withdraw - prem: Trading premium - fee: Trading fee - refr: Referrer rebate - point_dnw: POINT Deposit & Withdraw - point_fee: POINT Trading fee - point_refr: POINT Referrer rebate |
| » text | string | custom text |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/positions'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/positions"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/positions
List user's positions of specified underlying
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | false | Underlying |
Example responses
200 Response
[
{
"user": 11027586,
"underlying": "BTC_USDT",
"underlying_price": "70000",
"contract": "BTC_USDT-20211216-5000-P",
"size": 10,
"entry_price": "1234",
"realised_pnl": "120",
"mark_price": "6000",
"mark_iv": "0.9638",
"unrealised_pnl": "-320",
"pending_orders": 1,
"close_order": {
"id": 232323,
"price": "5779",
"is_liq": false
},
"delta": "-0.0046",
"gamma": "0",
"vega": "2.87656",
"theta": "-1.00247"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Options position information] |
| » None | object | Options position information |
| »» user | integer | User ID |
| »» underlying | string | Underlying |
| »» underlying_price | string | Underlying price (quote currency) |
| »» contract | string | Options contract name |
| »» size | integer(int64) | Position size (contract size) |
| »» entry_price | string | Entry size (quote currency) |
| »» mark_price | string | Current mark price (quote currency) |
| »» mark_iv | string | Implied volatility |
| »» realised_pnl | string | Realized PNL |
| »» unrealised_pnl | string | Unrealized PNL |
| »» pending_orders | integer | Current open orders |
| »» close_order | object|null | Current close order if any, or null |
| »»» id | integer(int64) | Close order ID |
| »»» price | string | Close order price （quote currency) |
| »»» is_liq | boolean | Is the close order from liquidation |
| »» delta | string | Delta |
| »» gamma | string | Gamma |
| »» vega | string | Vega |
| »» theta | string | Theta |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/positions/BTC_USDT-20211130-65000-C'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/positions/BTC_USDT-20211130-65000-C"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/positions/{contract}
Get specified contract position
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | path | string | true | none |
Example responses
200 Response
{
"user": 11027586,
"underlying": "BTC_USDT",
"underlying_price": "70000",
"contract": "BTC_USDT-20211216-5000-P",
"size": 10,
"entry_price": "1234",
"realised_pnl": "120",
"mark_price": "6000",
"mark_iv": "0.9638",
"unrealised_pnl": "-320",
"pending_orders": 1,
"close_order": {
"id": 232323,
"price": "5779",
"is_liq": false
},
"delta": "-0.0046",
"gamma": "0",
"vega": "2.87656",
"theta": "-1.00247"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
Options position information
| Name | Type | Description |
|---|---|---|
| » user | integer | User ID |
| » underlying | string | Underlying |
| » underlying_price | string | Underlying price (quote currency) |
| » contract | string | Options contract name |
| » size | integer(int64) | Position size (contract size) |
| » entry_price | string | Entry size (quote currency) |
| » mark_price | string | Current mark price (quote currency) |
| » mark_iv | string | Implied volatility |
| » realised_pnl | string | Realized PNL |
| » unrealised_pnl | string | Unrealized PNL |
| » pending_orders | integer | Current open orders |
| » close_order | object|null | Current close order if any, or null |
| »» id | integer(int64) | Close order ID |
| »» price | string | Close order price （quote currency) |
| »» is_liq | boolean | Is the close order from liquidation |
| » delta | string | Delta |
| » gamma | string | Gamma |
| » vega | string | Vega |
| » theta | string | Theta |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/position_close'
query_param = 'underlying=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/position_close"
query_param="underlying=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/position_close
List user's liquidation history of specified underlying
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | true | Underlying (Obtained by listing underlying endpoint) |
| contract | query | string | false | Options contract name |
Example responses
200 Response
[
{
"time": 1631764800,
"pnl": "-42914.291",
"settle_size": "-10001",
"side": "short",
"contract": "BTC_USDT-20210916-5000-C",
"text": "settled"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | number(double) | Position close time |
| » contract | string | Options contract name |
| » side | string | Position side, long or short |
| » pnl | string | PNL |
| » text | string | Text of close order |
| » settle_size | string | settlement size |
| Property | Value |
|---|---|
| side | long |
| side | short |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/orders'
query_param = ''
body='{"size":-1,"iceberg":0,"contract":"BTC_USDT-20210916-5000-C","text":"-","tif":"gtc","price":"100"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/options/orders"
query_param=""
body_param='{"size":-1,"iceberg":0,"contract":"BTC_USDT-20210916-5000-C","text":"-","tif":"gtc","price":"100"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /options/orders
Create an options order
Body parameter
{
"size": -1,
"iceberg": 0,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"tif": "gtc",
"price": "100"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » contract | body | string | true | Contract name |
| » size | body | integer(int64) | true | Order size. Specify positive number to make a bid, and negative number to ask |
| » iceberg | body | integer(int64) | false | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
| » price | body | string | false | Order price. 0 for market order with tif set as ioc (USDT) |
| » close | body | boolean | false | Set as true to close the position, with size set to 0 |
| » reduce_only | body | boolean | false | Set as true to be reduce-only order |
| » mmp | body | boolean | false | 设置为 true 的时候，为MMP委托 |
| » tif | body | string | false | Time in force |
| » text | body | string | false | User defined information. If not empty, must follow the rules below: |
» tif: Time in force
» text: User defined information. If not empty, must follow the rules below:
t-t- prefix| Parameter | Value |
|---|---|
| » tif | gtc |
| » tif | ioc |
| » tif | poc |
Example responses
201 Response
{
"status": "finished",
"size": -1,
"id": 2,
"iceberg": 0,
"is_liq": false,
"is_close": false,
"is_mmp": false,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"fill_price": "100",
"finish_as": "filled",
"left": 0,
"tif": "gtc",
"is_reduce_only": false,
"create_time": 1631763361,
"finish_time": 1631763397,
"price": "100"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order detail | Inline |
Status Code 201
Options order detail
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Options order ID |
| » user | integer | User ID |
| » create_time | number(double) | Creation time of order |
| » finish_time | number(double) | Order finished time. Not returned if order is open |
| » finish_as | string | 结束方式，包括： - filled: 完全成交 - cancelled: 用户撤销 - liquidated: 强制平仓撤销 - ioc: 未立即完全成交，因为tif设置为ioc - auto_deleveraged: 自动减仓撤销 - reduce_only: 增持仓位撤销，因为设置reduce_only或平仓 - position_closed: 因为仓位平掉了，所以挂单被撤掉 - reduce_out: 只减仓被排除的不容易成交的挂单 - mmp_cancelled: MMP撤销 |
| » status | string | Order status - open: waiting to be traded- finished: finished |
| » contract | string | Contract name |
| » size | integer(int64) | Order size. Specify positive number to make a bid, and negative number to ask |
| » iceberg | integer(int64) | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
| » price | string | Order price. 0 for market order with tif set as ioc (USDT) |
| » is_close | boolean | Is the order to close position |
| » is_reduce_only | boolean | Is the order reduce-only |
| » is_liq | boolean | Is the order for liquidation |
| » is_mmp | boolean | 是否为MMP委托。对应请求中的mmp。 |
| » tif | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee |
| » left | integer(int64) | Size left to be traded |
| » fill_price | string | Fill price of the order |
| » text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance |
| » tkfr | string | Taker fee |
| » mkfr | string | Maker fee |
| » refu | integer | Reference user ID |
| » refr | string | Referrer rebate |
| Property | Value |
|---|---|
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidated |
| finish_as | ioc |
| finish_as | auto_deleveraged |
| finish_as | reduce_only |
| finish_as | position_closed |
| finish_as | reduce_out |
| finish_as | mmp_cancelled |
| status | open |
| status | finished |
| tif | gtc |
| tif | ioc |
| tif | poc |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/orders
List options orders
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | false | Options contract name |
| underlying | query | string | false | Underlying |
| status | query | string | true | Only list the orders with this status |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
| Parameter | Value |
|---|---|
| status | open |
| status | finished |
Example responses
200 Response
[
{
"status": "finished",
"size": -1,
"id": 2,
"iceberg": 0,
"is_liq": false,
"is_close": false,
"is_mmp": false,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"fill_price": "100",
"finish_as": "filled",
"left": 0,
"tif": "gtc",
"is_reduce_only": false,
"create_time": 1631763361,
"finish_time": 1631763397,
"price": "100"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Options order detail] |
| » None | object | Options order detail |
| »» id | integer(int64) | Options order ID |
| »» user | integer | User ID |
| »» create_time | number(double) | Creation time of order |
| »» finish_time | number(double) | Order finished time. Not returned if order is open |
| »» finish_as | string | 结束方式，包括： - filled: 完全成交 - cancelled: 用户撤销 - liquidated: 强制平仓撤销 - ioc: 未立即完全成交，因为tif设置为ioc - auto_deleveraged: 自动减仓撤销 - reduce_only: 增持仓位撤销，因为设置reduce_only或平仓 - position_closed: 因为仓位平掉了，所以挂单被撤掉 - reduce_out: 只减仓被排除的不容易成交的挂单 - mmp_cancelled: MMP撤销 |
| »» status | string | Order status - open: waiting to be traded- finished: finished |
| »» contract | string | Contract name |
| »» size | integer(int64) | Order size. Specify positive number to make a bid, and negative number to ask |
| »» iceberg | integer(int64) | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
| »» price | string | Order price. 0 for market order with tif set as ioc (USDT) |
| »» is_close | boolean | Is the order to close position |
| »» is_reduce_only | boolean | Is the order reduce-only |
| »» is_liq | boolean | Is the order for liquidation |
| »» is_mmp | boolean | 是否为MMP委托。对应请求中的mmp。 |
| »» tif | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee |
| »» left | integer(int64) | Size left to be traded |
| »» fill_price | string | Fill price of the order |
| »» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance |
| »» tkfr | string | Taker fee |
| »» mkfr | string | Maker fee |
| »» refu | integer | Reference user ID |
| »» refr | string | Referrer rebate |
| Property | Value |
|---|---|
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidated |
| finish_as | ioc |
| finish_as | auto_deleveraged |
| finish_as | reduce_only |
| finish_as | position_closed |
| finish_as | reduce_out |
| finish_as | mmp_cancelled |
| status | open |
| status | finished |
| tif | gtc |
| tif | ioc |
| tif | poc |
WARNING
To perform this operation, you must be authenticated by API key and secret
open orders matchedCode samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/options/orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /options/orders
Cancel all open orders matched
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | false | Options contract name |
| underlying | query | string | false | Underlying |
| side | query | string | false | All bids or asks. Both included if not specified |
| Parameter | Value |
|---|---|
| side | ask |
| side | bid |
Example responses
200 Response
[
{
"status": "finished",
"size": -1,
"id": 2,
"iceberg": 0,
"is_liq": false,
"is_close": false,
"is_mmp": false,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"fill_price": "100",
"finish_as": "filled",
"left": 0,
"tif": "gtc",
"is_reduce_only": false,
"create_time": 1631763361,
"finish_time": 1631763397,
"price": "100"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | All orders matched cancelled | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Options order detail] |
| » None | object | Options order detail |
| »» id | integer(int64) | Options order ID |
| »» user | integer | User ID |
| »» create_time | number(double) | Creation time of order |
| »» finish_time | number(double) | Order finished time. Not returned if order is open |
| »» finish_as | string | 结束方式，包括： - filled: 完全成交 - cancelled: 用户撤销 - liquidated: 强制平仓撤销 - ioc: 未立即完全成交，因为tif设置为ioc - auto_deleveraged: 自动减仓撤销 - reduce_only: 增持仓位撤销，因为设置reduce_only或平仓 - position_closed: 因为仓位平掉了，所以挂单被撤掉 - reduce_out: 只减仓被排除的不容易成交的挂单 - mmp_cancelled: MMP撤销 |
| »» status | string | Order status - open: waiting to be traded- finished: finished |
| »» contract | string | Contract name |
| »» size | integer(int64) | Order size. Specify positive number to make a bid, and negative number to ask |
| »» iceberg | integer(int64) | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
| »» price | string | Order price. 0 for market order with tif set as ioc (USDT) |
| »» is_close | boolean | Is the order to close position |
| »» is_reduce_only | boolean | Is the order reduce-only |
| »» is_liq | boolean | Is the order for liquidation |
| »» is_mmp | boolean | 是否为MMP委托。对应请求中的mmp。 |
| »» tif | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee |
| »» left | integer(int64) | Size left to be traded |
| »» fill_price | string | Fill price of the order |
| »» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance |
| »» tkfr | string | Taker fee |
| »» mkfr | string | Maker fee |
| »» refu | integer | Reference user ID |
| »» refr | string | Referrer rebate |
| Property | Value |
|---|---|
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidated |
| finish_as | ioc |
| finish_as | auto_deleveraged |
| finish_as | reduce_only |
| finish_as | position_closed |
| finish_as | reduce_out |
| finish_as | mmp_cancelled |
| status | open |
| status | finished |
| tif | gtc |
| tif | ioc |
| tif | poc |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/orders/{order_id}
Get a single order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | integer(int64) | true | Order ID returned on successful order creation |
Example responses
200 Response
{
"status": "finished",
"size": -1,
"id": 2,
"iceberg": 0,
"is_liq": false,
"is_close": false,
"is_mmp": false,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"fill_price": "100",
"finish_as": "filled",
"left": 0,
"tif": "gtc",
"is_reduce_only": false,
"create_time": 1631763361,
"finish_time": 1631763397,
"price": "100"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order detail | Inline |
Status Code 200
Options order detail
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Options order ID |
| » user | integer | User ID |
| » create_time | number(double) | Creation time of order |
| » finish_time | number(double) | Order finished time. Not returned if order is open |
| » finish_as | string | 结束方式，包括： - filled: 完全成交 - cancelled: 用户撤销 - liquidated: 强制平仓撤销 - ioc: 未立即完全成交，因为tif设置为ioc - auto_deleveraged: 自动减仓撤销 - reduce_only: 增持仓位撤销，因为设置reduce_only或平仓 - position_closed: 因为仓位平掉了，所以挂单被撤掉 - reduce_out: 只减仓被排除的不容易成交的挂单 - mmp_cancelled: MMP撤销 |
| » status | string | Order status - open: waiting to be traded- finished: finished |
| » contract | string | Contract name |
| » size | integer(int64) | Order size. Specify positive number to make a bid, and negative number to ask |
| » iceberg | integer(int64) | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
| » price | string | Order price. 0 for market order with tif set as ioc (USDT) |
| » is_close | boolean | Is the order to close position |
| » is_reduce_only | boolean | Is the order reduce-only |
| » is_liq | boolean | Is the order for liquidation |
| » is_mmp | boolean | 是否为MMP委托。对应请求中的mmp。 |
| » tif | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee |
| » left | integer(int64) | Size left to be traded |
| » fill_price | string | Fill price of the order |
| » text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance |
| » tkfr | string | Taker fee |
| » mkfr | string | Maker fee |
| » refu | integer | Reference user ID |
| » refr | string | Referrer rebate |
| Property | Value |
|---|---|
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidated |
| finish_as | ioc |
| finish_as | auto_deleveraged |
| finish_as | reduce_only |
| finish_as | position_closed |
| finish_as | reduce_out |
| finish_as | mmp_cancelled |
| status | open |
| status | finished |
| tif | gtc |
| tif | ioc |
| tif | poc |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/options/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /options/orders/{order_id}
Cancel a single order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | integer(int64) | true | Order ID returned on successful order creation |
Example responses
200 Response
{
"status": "finished",
"size": -1,
"id": 2,
"iceberg": 0,
"is_liq": false,
"is_close": false,
"is_mmp": false,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"fill_price": "100",
"finish_as": "filled",
"left": 0,
"tif": "gtc",
"is_reduce_only": false,
"create_time": 1631763361,
"finish_time": 1631763397,
"price": "100"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order detail | Inline |
Status Code 200
Options order detail
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Options order ID |
| » user | integer | User ID |
| » create_time | number(double) | Creation time of order |
| » finish_time | number(double) | Order finished time. Not returned if order is open |
| » finish_as | string | 结束方式，包括： - filled: 完全成交 - cancelled: 用户撤销 - liquidated: 强制平仓撤销 - ioc: 未立即完全成交，因为tif设置为ioc - auto_deleveraged: 自动减仓撤销 - reduce_only: 增持仓位撤销，因为设置reduce_only或平仓 - position_closed: 因为仓位平掉了，所以挂单被撤掉 - reduce_out: 只减仓被排除的不容易成交的挂单 - mmp_cancelled: MMP撤销 |
| » status | string | Order status - open: waiting to be traded- finished: finished |
| » contract | string | Contract name |
| » size | integer(int64) | Order size. Specify positive number to make a bid, and negative number to ask |
| » iceberg | integer(int64) | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
| » price | string | Order price. 0 for market order with tif set as ioc (USDT) |
| » is_close | boolean | Is the order to close position |
| » is_reduce_only | boolean | Is the order reduce-only |
| » is_liq | boolean | Is the order for liquidation |
| » is_mmp | boolean | 是否为MMP委托。对应请求中的mmp。 |
| » tif | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee |
| » left | integer(int64) | Size left to be traded |
| » fill_price | string | Fill price of the order |
| » text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance |
| » tkfr | string | Taker fee |
| » mkfr | string | Maker fee |
| » refu | integer | Reference user ID |
| » refr | string | Referrer rebate |
| Property | Value |
|---|---|
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidated |
| finish_as | ioc |
| finish_as | auto_deleveraged |
| finish_as | reduce_only |
| finish_as | position_closed |
| finish_as | reduce_out |
| finish_as | mmp_cancelled |
| status | open |
| status | finished |
| tif | gtc |
| tif | ioc |
| tif | poc |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/countdown_cancel_all'
query_param = ''
body='{"timeout":30,"contract":"BTC_USDT-20241001-46000-C","underlying":"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="/options/countdown_cancel_all"
query_param=""
body_param='{"timeout":30,"contract":"BTC_USDT-20241001-46000-C","underlying":"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 /options/countdown_cancel_all
Countdown cancel orders
Option order heartbeat detection, when the timeout time set by the user is reached, if the existing countdown is not canceled or a new countdown is set, the related option pending order will be automatically canceled.
This interface can be called repeatedly to set a new countdown or cancel the countdown.
Usage example: Repeat this interface at intervals of 30 seconds, with each countdown timeout set to 30 (seconds).
If this interface is not called again within 30 seconds, all pending orders on the underlying contract you specified will be automatically cancelled. If underlying contract is not specified, all pending orders of the user will be automatically cancelled
If timeout is set to 0 within 30 seconds, the countdown timer will expire and the automatic order cancellation function will be cancelled.
Body parameter
{
"timeout": 30,
"contract": "BTC_USDT-20241001-46000-C",
"underlying": "BTC_USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » timeout | body | integer(int32) | true | Countdown time, in seconds |
| » contract | body | string | false | Options contract name |
| » underlying | body | string | false | Underlying |
» timeout: Countdown time, in seconds At least 5 seconds, 0 means cancel the countdown
Example responses
200 Response
{
"triggerTime": "1660039145000"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Set countdown successfully | Inline |
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
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/my_trades'
query_param = 'underlying=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/my_trades"
query_param="underlying=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/my_trades
List personal trading history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | true | Underlying (Obtained by listing underlying endpoint) |
| contract | query | string | false | Options contract name |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
Example responses
200 Response
[
{
"underlying_price": "48000",
"size": 1,
"contract": "BTC_USDT-20210916-5000-C",
"id": 1,
"role": "taker",
"create_time": 1631763397,
"order_id": 4,
"price": "100"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Trade ID |
| » create_time | number(double) | Trading time |
| » contract | string | Options contract name |
| » order_id | integer | Order ID related |
| » size | integer(int64) | Trading size |
| » price | string | Trading price (quote currency) |
| » underlying_price | string | Underlying price (quote currency) |
| » role | string | Trade role. Available values are taker and maker |
| Property | Value |
|---|---|
| role | taker |
| role | maker |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/mmp'
query_param = ''
body='{"underlying":"BTC_USDT","window":5000,"frozen_period":200,"qty_limit":"10","delta_limit":"10"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/options/mmp"
query_param=""
body_param='{"underlying":"BTC_USDT","window":5000,"frozen_period":200,"qty_limit":"10","delta_limit":"10"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /options/mmp
MMP Settings
Body parameter
{
"underlying": "BTC_USDT",
"window": 5000,
"frozen_period": 200,
"qty_limit": "10",
"delta_limit": "10"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » underlying | body | string | true | Underlying |
| » window | body | integer(int32) | true | 时间窗口（毫秒），1-5000之间，0表示停用MMP |
| » frozen_period | body | integer(int32) | true | 冻结时长（毫秒），0表示一直冻结，需要调用重置API解冻 |
| » qty_limit | body | string | true | 成交量上限（正数，至多2位小数） |
| » delta_limit | body | string | true | 净delta值上限（正数，至多2位小数） |
Example responses
200 Response
{
"underlying": "BTC_USDT",
"window": 5000,
"frozen_period": 200,
"qty_limit": "10",
"delta_limit": "10",
"trigger_time_ms": 0,
"frozen_until_ms": 0
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | MMP Information | Inline |
Status Code 200
MMP Settings
| Name | Type | Description |
|---|---|---|
| » underlying | string | Underlying |
| » window | integer(int32) | 时间窗口（毫秒），1-5000之间，0表示停用MMP |
| » frozen_period | integer(int32) | 冻结时长（毫秒），0表示一直冻结，需要调用重置API解冻 |
| » qty_limit | string | 成交量上限（正数，至多2位小数） |
| » delta_limit | string | 净delta值上限（正数，至多2位小数） |
| » trigger_time_ms | integer(int64) | 触发冻结时间（毫秒），0表示没有触发冻结 |
| » frozen_until_ms | integer(int64) | 解冻时间（毫秒），如果未配置冻结时长，触发冻结后无解冻时间 |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/mmp'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/mmp"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/mmp
MMP Query
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | false | Underlying |
Example responses
200 Response
[
{
"underlying": "BTC_USDT",
"window": 5000,
"frozen_period": 200,
"qty_limit": "10",
"delta_limit": "10",
"trigger_time_ms": 0,
"frozen_until_ms": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [MMP Settings] |
| » None | object | MMP Settings |
| »» underlying | string | Underlying |
| »» window | integer(int32) | 时间窗口（毫秒），1-5000之间，0表示停用MMP |
| »» frozen_period | integer(int32) | 冻结时长（毫秒），0表示一直冻结，需要调用重置API解冻 |
| »» qty_limit | string | 成交量上限（正数，至多2位小数） |
| »» delta_limit | string | 净delta值上限（正数，至多2位小数） |
| »» trigger_time_ms | integer(int64) | 触发冻结时间（毫秒），0表示没有触发冻结 |
| »» frozen_until_ms | integer(int64) | 解冻时间（毫秒），如果未配置冻结时长，触发冻结后无解冻时间 |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/mmp/reset'
query_param = ''
body='{"underlying":"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="/options/mmp/reset"
query_param=""
body_param='{"underlying":"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 /options/mmp/reset
MMP Reset
Body parameter
{
"underlying": "BTC_USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » underlying | body | string | true | Underlying |
Example responses
200 Response
{
"underlying": "BTC_USDT",
"window": 5000,
"frozen_period": 200,
"qty_limit": "10",
"delta_limit": "10",
"trigger_time_ms": 0,
"frozen_until_ms": 0
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | MMP Information | Inline |
Status Code 200
MMP Settings
| Name | Type | Description |
|---|---|---|
| » underlying | string | Underlying |
| » window | integer(int32) | 时间窗口（毫秒），1-5000之间，0表示停用MMP |
| » frozen_period | integer(int32) | 冻结时长（毫秒），0表示一直冻结，需要调用重置API解冻 |
| » qty_limit | string | 成交量上限（正数，至多2位小数） |
| » delta_limit | string | 净delta值上限（正数，至多2位小数） |
| » trigger_time_ms | integer(int64) | 触发冻结时间（毫秒），0表示没有触发冻结 |
| » frozen_until_ms | integer(int64) | 解冻时间（毫秒），如果未配置冻结时长，触发冻结后无解冻时间 |
WARNING
To perform this operation, you must be authenticated by API key and secret
Lend & Earn
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/earn/uni/currencies \
-H 'Accept: application/json'
GET /earn/uni/currencies
List currencies for lending
Example responses
200 Response
[
{
"currency": "AE",
"min_lend_amount": "100",
"max_lend_amount": "200000000",
"max_rate": "0.00057",
"min_rate": "0.000001"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Currency detail] |
| » None | object | Currency detail |
| »» currency | string | Currency name |
| »» min_lend_amount | string | The minimum lending amount, in the unit of the currency. |
| »» max_lend_amount | string | The total maximum lending amount, in USDT |
| »» max_rate | string | Maximum rate (Hourly) |
| »» min_rate | string | Minimum rate (Hourly) |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/currencies/btc'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/earn/uni/currencies/btc \
-H 'Accept: application/json'
GET /earn/uni/currencies/{currency}
Get currency detail for lending
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | true | Currency |
Example responses
200 Response
{
"currency": "AE",
"min_lend_amount": "100",
"max_lend_amount": "200000000",
"max_rate": "0.00057",
"min_rate": "0.000001"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
Currency detail
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency name |
| » min_lend_amount | string | The minimum lending amount, in the unit of the currency. |
| » max_lend_amount | string | The total maximum lending amount, in USDT |
| » max_rate | string | Maximum rate (Hourly) |
| » min_rate | string | Minimum rate (Hourly) |
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/lends'
query_param = ''
body='{"currency":"AE","amount":"100","min_rate":"0.00001","type":"lend"}'
# 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="/earn/uni/lends"
query_param=""
body_param='{"currency":"AE","amount":"100","min_rate":"0.00001","type":"lend"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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 /earn/uni/lends
Lend or redeem
Lending:
The minimum interest rate is required in lending. The lending result is updated hourly and the interest profit is paid on the next hour. A high interest rate might lead to unsuccessful lending and no profit will be gained for that hour. If the funds are redeemed before the hourly settlement, no interest can be obtained for that hour. About priority: the orders created or amended first under the same interest rate will be lent out first
Redemption:
Funds that failed to be lent can be redeemed immediately. For the successfully lent funds, enjoy the hourly income, and the redemption will arrive at the next hour
Note:
Two minutes before and after the hour is the settlement time, lending and redemption are prohibited.
Body parameter
{
"currency": "AE",
"amount": "100",
"min_rate": "0.00001",
"type": "lend"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Currency name |
| » amount | body | string | true | The amount of currency could be lent |
| » type | body | string | true | type: lend - lend, redeem - redeem |
| » min_rate | body | string | false | The minimum interest rate. If the value is too high, it might lead to the unsuccessful lending and no profit will be gained for that hour. |
| Parameter | Value |
|---|---|
| » type | lend |
| » type | redeem |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Operated successfully | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/lends'
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="/earn/uni/lends"
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 /earn/uni/lends
List user's lending orders
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Retrieve data of the specified currency |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100 |
Example responses
200 Response
[
{
"currency": "BTC",
"current_amount": "20.999992",
"amount": "20.999992",
"lent_amount": "0",
"frozen_amount": "0",
"min_rate": "0.1",
"interest_status": "interest_dividend",
"reinvest_left_amount": 0,
"create_time": 1673247054000,
"update_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Loan record |
| »» currency | string | Currency |
| »» current_amount | string | Current amount |
| »» amount | string | Total amount |
| »» lent_amount | string | Lent amount |
| »» frozen_amount | string | Frozen amount |
| »» min_rate | string | Minimum interest rate |
| »» interest_status | string | Interest status: interest_dividend - regular dividend, interest_reinvest - interest reinvestment |
| »» reinvest_left_amount | string | Amount not reinvested |
| »» create_time | integer(int64) | Created time of the lending order |
| »» update_time | integer(int64) | Upated time of the lending order |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/lends'
query_param = ''
body='{"currency":"AE","min_rate":"0.0001"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PATCH', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="PATCH"
url="/earn/uni/lends"
query_param=""
body_param='{"currency":"AE","min_rate":"0.0001"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
PATCH /earn/uni/lends
Amend lending order
Currently only supports amending the minimum interest rate (hour)
Body parameter
{
"currency": "AE",
"min_rate": "0.0001"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | false | Currency name |
| » min_rate | body | string | false | Minimum interest rate |
| 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
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/lend_records'
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="/earn/uni/lend_records"
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 /earn/uni/lend_records
List records of lending
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Retrieve data of the specified currency |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
| type | query | string | false | type: lend - lend, redeem - redeem |
| Parameter | Value |
|---|---|
| type | lend |
| type | redeem |
Example responses
200 Response
[
{
"type": "lend",
"currency": "BTC",
"amount": "1",
"last_wallet_amount": "0.2",
"last_lent_amount": "0",
"last_frozen_amount": "0",
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Interest Record |
| »» currency | string | Currency name |
| »» amount | string | current amount |
| »» last_wallet_amount | string | Last wallet amount |
| »» last_lent_amount | string | Last lent amount |
| »» last_frozen_amount | string | Last frozen amount |
| »» type | string | Record type: lend - lend, redeem - redeem |
| »» create_time | integer(int64) | Created time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/interests/btc'
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="/earn/uni/interests/btc"
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 /earn/uni/interests/{currency}
Get the user's total interest income of specified currency
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | true | Currency |
Example responses
200 Response
{
"currency": "AE",
"interest": "123.345"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
UniLendInterest
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency |
| » interest | string | Interest |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/interest_records'
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="/earn/uni/interest_records"
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 /earn/uni/interest_records
List interest records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Retrieve data of the specified currency |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
Example responses
200 Response
[
{
"status": 1,
"currency": "AE",
"actual_rate": "0.0005",
"interest": "0.05",
"interest_status": "interest_dividend",
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Interest Record |
| »» status | integer | Status: 0 - fail, 1 - success |
| »» currency | string | Currency |
| »» actual_rate | string | Actual Rate |
| »» interest | string | Interest |
| »» interest_status | string | Interest status: interest_dividend - regular dividend, interest_reinvest - interest reinvestment |
| »» create_time | integer(int64) | Created time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/interest_reinvest'
query_param = ''
body='{"currency":"BTC","status":true}'
# 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="/earn/uni/interest_reinvest"
query_param=""
body_param='{"currency":"BTC","status":true}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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 /earn/uni/interest_reinvest
Set interest reinvestment toggle
Body parameter
{
"currency": "BTC",
"status": true
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Currency |
| » status | body | boolean | true | Interest toggle settings, true - interest reinvestment, false - regular dividend |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Success | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/interest_status/btc'
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="/earn/uni/interest_status/btc"
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 /earn/uni/interest_status/{currency}
query currency interest compounding status
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | true | Currency |
Example responses
200 Response
{
"currency": "BTC",
"interest_status": "interest_dividend"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
UniCurrencyInterest
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency |
| » interest_status | string | Interest status: interest_dividend - regular dividend, interest_reinvest - interest reinvestment |
WARNING
To perform this operation, you must be authenticated by API key and secret
Collateral Loan
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/orders'
query_param = ''
body='{"collateral_amount":"1","collateral_currency":"BTC","borrow_amount":"49","borrow_currency":"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="/loan/collateral/orders"
query_param=""
body_param='{"collateral_amount":"1","collateral_currency":"BTC","borrow_amount":"49","borrow_currency":"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 /loan/collateral/orders
Place order
Body parameter
{
"collateral_amount": "1",
"collateral_currency": "BTC",
"borrow_amount": "49",
"borrow_currency": "USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » collateral_amount | body | string | true | Collateral amount |
| » collateral_currency | body | string | true | Collateral |
| » borrow_amount | body | string | true | Borrowing amount |
| » borrow_currency | body | string | true | Borrowed currency |
Example responses
200 Response
{
"order_id": 10005578
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » order_id | integer(int64) | Order ID |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/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="/loan/collateral/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 /loan/collateral/orders
List Orders
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| collateral_currency | query | string | false | Collateral |
| borrow_currency | query | string | false | Borrowed currency |
Example responses
200 Response
[
{
"order_id": 10000421,
"collateral_currency": "BTC",
"borrow_currency": "USDT",
"collateral_amount": "1",
"borrow_amount": "1000",
"repaid_amount": "10",
"repaid_principal": "10",
"repaid_interest": "0",
"init_ltv": "0.0003934533764831",
"current_ltv": "0.0004521768651985",
"liquidate_ltv": "0.9",
"status": "initial_status",
"borrow_time": 1688462668,
"left_repay_total": "990.0219384",
"left_repay_interest": "0.0219384"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Collateral Order] |
| » None | object | Collateral Order |
| »» order_id | integer(int64) | Order ID |
| »» collateral_currency | string | Collateral |
| »» collateral_amount | string | Collateral amount |
| »» borrow_currency | string | Borrowed currency |
| »» borrow_amount | string | Borrowing amount |
| »» repaid_amount | string | Repaid amount |
| »» repaid_principal | string | Repaid principal |
| »» repaid_interest | string | Repaid interest |
| »» init_ltv | string | The initial collateralization rate |
| »» current_ltv | string | The current collateralization rate |
| »» liquidate_ltv | string | The liquidation collateralization rate |
| »» status | string | Order status: - initial: Initial state after placing the order - collateral_deducted: Collateral deduction successful - collateral_returning: Loan failed - Collateral return pending - lent: Loan successful - repaying: Repayment in progress - liquidating: Liquidation in progress - finished: Order completed - closed_liquidated: Liquidation and repayment completed |
| »» borrow_time | integer(int64) | Borrowing time, timestamp in seconds |
| »» left_repay_total | string | Outstanding principal and interest (outstanding principal + outstanding interest) |
| »» left_repay_principal | string | outstanding principal |
| »» left_repay_interest | string | outstanding interest |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/orders/100001'
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="/loan/collateral/orders/100001"
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 /loan/collateral/orders/{order_id}
Get a single order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | integer(int64) | true | Order ID returned on successful order creation |
Example responses
200 Response
{
"order_id": 10000421,
"collateral_currency": "BTC",
"borrow_currency": "USDT",
"collateral_amount": "1",
"borrow_amount": "1000",
"repaid_amount": "10",
"repaid_principal": "10",
"repaid_interest": "0",
"init_ltv": "0.0003934533764831",
"current_ltv": "0.0004521768651985",
"liquidate_ltv": "0.9",
"status": "initial_status",
"borrow_time": 1688462668,
"left_repay_total": "990.0219384",
"left_repay_interest": "0.0219384"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | Inline |
Status Code 200
Collateral Order
| Name | Type | Description |
|---|---|---|
| » order_id | integer(int64) | Order ID |
| » collateral_currency | string | Collateral |
| » collateral_amount | string | Collateral amount |
| » borrow_currency | string | Borrowed currency |
| » borrow_amount | string | Borrowing amount |
| » repaid_amount | string | Repaid amount |
| » repaid_principal | string | Repaid principal |
| » repaid_interest | string | Repaid interest |
| » init_ltv | string | The initial collateralization rate |
| » current_ltv | string | The current collateralization rate |
| » liquidate_ltv | string | The liquidation collateralization rate |
| » status | string | Order status: - initial: Initial state after placing the order - collateral_deducted: Collateral deduction successful - collateral_returning: Loan failed - Collateral return pending - lent: Loan successful - repaying: Repayment in progress - liquidating: Liquidation in progress - finished: Order completed - closed_liquidated: Liquidation and repayment completed |
| » borrow_time | integer(int64) | Borrowing time, timestamp in seconds |
| » left_repay_total | string | Outstanding principal and interest (outstanding principal + outstanding interest) |
| » left_repay_principal | string | outstanding principal |
| » left_repay_interest | string | outstanding interest |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/repay'
query_param = ''
body='{"order_id":37438962,"repay_amount":"1000","repaid_all":false}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/loan/collateral/repay"
query_param=""
body_param='{"order_id":37438962,"repay_amount":"1000","repaid_all":false}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /loan/collateral/repay
Repayment
Body parameter
{
"order_id": 37438962,
"repay_amount": "1000",
"repaid_all": false
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » order_id | body | integer(int64) | true | Order ID |
| » repay_amount | body | string | true | Repayment amount, it is mandatory when making partial repayments |
| » repaid_all | body | boolean | true | Repayment method, set to true for full repayment, and false for partial repayment; |
» repaid_all: Repayment method, set to true for full repayment, and false for partial repayment;
When set to false for partial repayment, the repay_amount parameter cannot be greater than the remaining amount to be repaid by the user.
Example responses
200 Response
{
"repaid_principal": "11",
"repaid_interest": "111"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Operated successfully | Inline |
Status Code 200
Repay
| Name | Type | Description |
|---|---|---|
| » repaid_principal | string | Principal |
| » repaid_interest | string | Interest |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/repay_records'
query_param = 'source=repay'
# 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="/loan/collateral/repay_records"
query_param="source=repay"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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 /loan/collateral/repay_records
Repayment history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| source | query | string | true | Operation type: repay - Regular repayment, liquidate - Liquidation |
| borrow_currency | query | string | false | Borrowed currency |
| collateral_currency | query | string | false | Collateral |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| 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
[
{
"order_id": 10000425,
"record_id": 181,
"repaid_amount": "10.00000000000000000000",
"borrow_currency": "USDT",
"collateral_currency": "BTC",
"collateral_amount": "1.00000000000000000000",
"init_ltv": "0.00039345337648310000",
"borrow_time": 1688471851,
"repay_time": 1688526310,
"total_interest": "0.25446901544300000000",
"before_left_principal": "11.00000000",
"pre_left_principal": "990.00000000000000000000",
"after_left_principal": "990.00000000000000000000",
"before_left_collateral": "1.00000000000000000000",
"after_left_collateral": "1.00000000000000000000"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Repayment record |
| »» order_id | integer(int64) | Order ID |
| »» record_id | integer(int64) | Repayment record ID |
| »» repaid_amount | string | Repayment amount |
| »» borrow_currency | string | Borrowed currency |
| »» collateral_currency | string | Collateral |
| »» init_ltv | string | The initial collateralization rate |
| »» borrow_time | integer(int64) | Borrowing time, timestamp |
| »» repay_time | integer(int64) | Repayment time, timestamp |
| »» total_interest | string | Total interest |
| »» before_left_principal | string | Principal to be repaid before repayment |
| »» after_left_principal | string | Principal to be repaid after repayment |
| »» before_left_collateral | string | Collateral quantity before repayment |
| »» after_left_collateral | string | Collateral quantity after repayment |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/collaterals'
query_param = ''
body='{"collateral_amount":"1212","collateral_currency":"BTC","order_id":1130,"type":"append"}'
# 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="/loan/collateral/collaterals"
query_param=""
body_param='{"collateral_amount":"1212","collateral_currency":"BTC","order_id":1130,"type":"append"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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 /loan/collateral/collaterals
Increase or redeem collateral
Body parameter
{
"collateral_amount": "1212",
"collateral_currency": "BTC",
"order_id": 1130,
"type": "append"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » order_id | body | integer(int64) | true | Order ID |
| » collateral_currency | body | string | true | Collateral |
| » collateral_amount | body | string | true | Collateral amount |
| » type | body | string | true | Operation types: append - for adding collateral, redeem - for withdrawing collateral |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Operated successfully | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/collaterals'
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="/loan/collateral/collaterals"
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 /loan/collateral/collaterals
Query collateral adjustment records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| from | query | integer(int64) | false | Start timestamp of the query |
| to | query | integer(int64) | false | Time range ending, default to current time |
| borrow_currency | query | string | false | Borrowed currency |
| collateral_currency | query | string | false | Collateral |
Example responses
200 Response
[
{
"order_id": 10000417,
"record_id": 10000452,
"borrow_currency": "USDT",
"borrow_amount": "1000.00000000000000000000",
"collateral_currency": "BTC",
"pre_collateral": "1.00000000000000000000",
"after_collateral": "2.00000000000000000000",
"pre_ltv": "0.00039345555621480000",
"after_ltv": "0.00019672777810740000",
"operate_time": 1688461924
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Collateral record |
| »» order_id | integer(int64) | Order ID |
| »» record_id | integer(int64) | Collateral record ID |
| »» borrow_currency | string | Borrowed currency |
| »» borrow_amount | string | Borrowing amount |
| »» collateral_currency | string | Collateral |
| »» before_collateral | string | The collateral amount before adjustment |
| »» after_collateral | string | The collateral amount after adjustment |
| »» before_ltv | string | The collateral ratio before adjustment |
| »» after_ltv | string | The collateral ratio after adjustment |
| »» operate_time | integer(int64) | Timestamp of the operation, in seconds |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/total_amount'
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="/loan/collateral/total_amount"
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 /loan/collateral/total_amount
Query the total borrowing and collateral amount for the user
Example responses
200 Response
{
"borrow_amount": "11",
"collateral_amount": "111"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
Total borrowed amount and pledged collateral amount by the user
| Name | Type | Description |
|---|---|---|
| » borrow_amount | string | Total borrowing amount, calculated in USDT |
| » collateral_amount | string | Total collateral amount, calculated in USDT |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/ltv'
query_param = 'collateral_currency=BTC&borrow_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="/loan/collateral/ltv"
query_param="collateral_currency=BTC&borrow_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 /loan/collateral/ltv
Query user's collateralization ratio
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| collateral_currency | query | string | true | Collateral |
| borrow_currency | query | string | true | Borrowed currency |
Example responses
200 Response
{
"collateral_currency": "BTC",
"borrow_currency": "USDT",
"init_ltv": "0.7",
"alert_ltv": "0.8",
"liquidate_ltv": "0.9",
"min_borrow_amount": "3",
"left_borrowable_amount": "4233030.635065916703"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
User's currency statistics data
| Name | Type | Description |
|---|---|---|
| » collateral_currency | string | Collateral |
| » borrow_currency | string | Borrowed currency |
| » init_ltv | string | The initial collateralization rate |
| » alert_ltv | string | Warning collateralization ratio |
| » liquidate_ltv | string | The liquidation collateralization rate |
| » min_borrow_amount | string | Minimum borrowable amount for the loan currency |
| » left_borrowable_amount | string | Remaining borrowable amount for the loan currency |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/loan/collateral/currencies \
-H 'Accept: application/json'
GET /loan/collateral/currencies
Query supported borrowing and collateral currencies
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| loan_currency | query | string | false | The parameter loan_currency is used to specify the borrowing currency. If loan_currency is not provided, the API will return all supported borrowing currencies. If loan_currency is provided, the API will return an array of collateral currencies supported for the specified borrowing currency. |
Example responses
200 Response
[
{
"loan_currency": "BTC",
"collateral_currency": [
"BTC",
"ETH",
"GT"
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Supported borrowing and collateral currencies |
| »» loan_currency | string | Borrowed currency |
| »» collateral_currency | array | List of supported collateral currencies |
Multi-Collateral Loan
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/orders'
query_param = ''
body='{"order_id":1721387470,"order_type":"fixed","fixed_type":"7d","fixed_rate":0.00001,"auto_renew":true,"auto_repay":true,"borrow_currency":"BTC","borrow_amount":"1","collateral_currencies":[{"currency":"USDT","amount":"1000"}]}'
# 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="/loan/multi_collateral/orders"
query_param=""
body_param='{"order_id":1721387470,"order_type":"fixed","fixed_type":"7d","fixed_rate":0.00001,"auto_renew":true,"auto_repay":true,"borrow_currency":"BTC","borrow_amount":"1","collateral_currencies":[{"currency":"USDT","amount":"1000"}]}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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 /loan/multi_collateral/orders
Create Multi-Collateral Order
Body parameter
{
"order_id": 1721387470,
"order_type": "fixed",
"fixed_type": "7d",
"fixed_rate": 0.00001,
"auto_renew": true,
"auto_repay": true,
"borrow_currency": "BTC",
"borrow_amount": "1",
"collateral_currencies": [
{
"currency": "USDT",
"amount": "1000"
}
]
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » order_id | body | string | false | Order ID |
| » order_type | body | string | false | current - current, fixed - fixed, if not specified, default to current |
| » fixed_type | body | string | false | Fixed interest rate loan period: 7d - 7 days, 30d - 30 days. Must be provided for fixed |
| » fixed_rate | body | string | false | Fixed interest rate, must be specified for fixed |
| » auto_renew | body | boolean | false | Fixed interest rate, automatic renewal |
| » auto_repay | body | boolean | false | Fixed interest rate, automatic repayment |
| » borrow_currency | body | string | true | Borrowed currency |
| » borrow_amount | body | string | true | Borrowing amount |
| » collateral_currencies | body | array | false | Collateral currency and amount |
| »» CollateralCurrency | body | object | false | none |
| »»» currency | body | string | false | Currency |
| »»» amount | body | string | false | Size |
Example responses
200 Response
{
"order_id": 10005578
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » order_id | integer(int64) | Order ID |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/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="/loan/multi_collateral/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 /loan/multi_collateral/orders
List Multi-Collateral Orders
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer | false | Page number |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| sort | query | string | false | Sort types: time_desc - default sorting by creation time in descending order, ltv_asc - ascending order of ltv, ltv_desc - descending order of ltv. |
| order_type | query | string | false | Order type, current - query current orders, fixed - query fixed orders. If not specified, default to querying current orders |
Example responses
200 Response
[
{
"order_id": "10005578",
"order_type": "fixed",
"fixed_type": "7d",
"fixed_rate": 0.00001,
"expire_time": 1703820105,
"auto_renew": true,
"auto_repay": true,
"current_ltv": "0.0001004349664281",
"status": "lent",
"borrow_time": 1702615021,
"total_left_repay_usdt": "106.491212982",
"total_left_collateral_usdt": "1060300.18",
"borrow_currencies": [
{
"currency": "GT",
"index_price": "10.6491",
"left_repay_principal": "10",
"left_repay_interest": "0.00002",
"left_repay_usdt": "106.491212982"
}
],
"collateral_currencies": [
{
"currency": "BTC",
"index_price": "112794.7",
"left_collateral": "9.4",
"left_collateral_usdt": "1060270.18"
},
{
"currency": "USDT",
"index_price": "1",
"left_collateral": "30",
"left_collateral_usdt": "30"
}
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Multi-Collateral Order] |
| » None | object | Multi-Collateral Order |
| »» order_id | string | Order ID |
| »» order_type | string | current - current, fixed - fixed |
| »» fixed_type | string | Fixed interest rate loan periods: 7d - 7 days, 30d - 30 days. |
| »» fixed_rate | string | Fixed interest rate |
| »» expire_time | integer(int64) | Expiration time, timestamp, unit in seconds. |
| »» auto_renew | boolean | Fixed interest rate, automatic renewal |
| »» auto_repay | boolean | Fixed interest rate, automatic repayment |
| »» current_ltv | string | The current collateralization rate |
| »» status | string | Order status: - initial: Initial state after placing the order - collateral_deducted: Collateral deduction successful - collateral_returning: Loan failed - Collateral return pending - lent: Loan successful - repaying: Repayment in progress - liquidating: Liquidation in progress - finished: Order completed - closed_liquidated: Liquidation and repayment completed |
| »» borrow_time | integer(int64) | Borrowing time, timestamp in seconds |
| »» total_left_repay_usdt | string | Value of Left repay amount converted in USDT |
| »» total_left_collateral_usdt | string | Value of Collateral amount in USDT |
| »» borrow_currencies | array | Borrowing Currency List |
| »»» BorrowCurrencyInfo | object | none |
| »»»» currency | string | Currency |
| »»»» index_price | string | Currency Index Price |
| »»»» left_repay_principal | string | outstanding principal |
| »»»» left_repay_interest | string | outstanding interest |
| »»»» left_repay_usdt | string | Value of left total repayments amount in USDT |
| »»» collateral_currencies | array | Collateral Currency List |
| »»»» CollateralCurrencyInfo | object | none |
| »»»»» currency | string | Currency |
| »»»»» index_price | string | Currency Index Price |
| »»»»» left_collateral | string | Left Collateral Amount |
| »»»»» left_collateral_usdt | string | Value of left collateral amount in USDT |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/loan/multi_collateral/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /loan/multi_collateral/orders/{order_id}
Get Multi-Collateral Order Detail
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | string | true | Order ID returned on successful order creation |
Example responses
200 Response
{
"order_id": "10005578",
"order_type": "fixed",
"fixed_type": "7d",
"fixed_rate": 0.00001,
"expire_time": 1703820105,
"auto_renew": true,
"auto_repay": true,
"current_ltv": "0.0001004349664281",
"status": "lent",
"borrow_time": 1702615021,
"total_left_repay_usdt": "106.491212982",
"total_left_collateral_usdt": "1060300.18",
"borrow_currencies": [
{
"currency": "GT",
"index_price": "10.6491",
"left_repay_principal": "10",
"left_repay_interest": "0.00002",
"left_repay_usdt": "106.491212982"
}
],
"collateral_currencies": [
{
"currency": "BTC",
"index_price": "112794.7",
"left_collateral": "9.4",
"left_collateral_usdt": "1060270.18"
},
{
"currency": "USDT",
"index_price": "1",
"left_collateral": "30",
"left_collateral_usdt": "30"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | Inline |
Status Code 200
Multi-Collateral Order
| Name | Type | Description |
|---|---|---|
| » order_id | string | Order ID |
| » order_type | string | current - current, fixed - fixed |
| » fixed_type | string | Fixed interest rate loan periods: 7d - 7 days, 30d - 30 days. |
| » fixed_rate | string | Fixed interest rate |
| » expire_time | integer(int64) | Expiration time, timestamp, unit in seconds. |
| » auto_renew | boolean | Fixed interest rate, automatic renewal |
| » auto_repay | boolean | Fixed interest rate, automatic repayment |
| » current_ltv | string | The current collateralization rate |
| » status | string | Order status: - initial: Initial state after placing the order - collateral_deducted: Collateral deduction successful - collateral_returning: Loan failed - Collateral return pending - lent: Loan successful - repaying: Repayment in progress - liquidating: Liquidation in progress - finished: Order completed - closed_liquidated: Liquidation and repayment completed |
| » borrow_time | integer(int64) | Borrowing time, timestamp in seconds |
| » total_left_repay_usdt | string | Value of Left repay amount converted in USDT |
| » total_left_collateral_usdt | string | Value of Collateral amount in USDT |
| » borrow_currencies | array | Borrowing Currency List |
| »» BorrowCurrencyInfo | object | none |
| »»» currency | string | Currency |
| »»» index_price | string | Currency Index Price |
| »»» left_repay_principal | string | outstanding principal |
| »»» left_repay_interest | string | outstanding interest |
| »»» left_repay_usdt | string | Value of left total repayments amount in USDT |
| »» collateral_currencies | array | Collateral Currency List |
| »»» CollateralCurrencyInfo | object | none |
| »»»» currency | string | Currency |
| »»»» index_price | string | Currency Index Price |
| »»»» left_collateral | string | Left Collateral Amount |
| »»»» left_collateral_usdt | string | Value of left collateral amount in USDT |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/repay'
query_param = ''
body='{"order_id":10005578,"repay_items":[{"currency":"btc","amount":"1","repaid_all":false}]}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/loan/multi_collateral/repay"
query_param=""
body_param='{"order_id":10005578,"repay_items":[{"currency":"btc","amount":"1","repaid_all":false}]}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /loan/multi_collateral/repay
Repay Multi-Collateral Loan
Body parameter
{
"order_id": 10005578,
"repay_items": [
{
"currency": "btc",
"amount": "1",
"repaid_all": false
}
]
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » order_id | body | integer(int64) | true | Order ID |
| » repay_items | body | array | true | Repay Currency Item |
| »» MultiLoanRepayItem | body | object | false | none |
| »»» currency | body | string | false | Repayment currency |
| »»» amount | body | string | false | Size |
| »»» repaid_all | body | boolean | false | Repayment method, set to true for full repayment, false for partial repayment. |
Example responses
200 Response
{
"order_id": 10005679,
"repaid_currencies": [
{
"succeeded": false,
"label": "INVALID_PARAM_VALUE",
"message": "Invalid parameter value",
"currency": "BTC",
"repaid_principal": "1",
"repaid_interest": "0.0001"
},
{
"succeeded": true,
"currency": "BTC",
"repaid_principal": "1",
"repaid_interest": "0.0001"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Operated successfully | Inline |
Status Code 200
Repay Multi-Collateral Loan
| Name | Type | Description |
|---|---|---|
| » order_id | integer(int64) | Order ID |
| » repaid_currencies | array | Repay Currency List |
| »» RepayCurrencyRes | object | none |
| »»» succeeded | boolean | Has the repayment been successful |
| »»» label | string | Error identifier for unsuccessful operations; empty for successful. |
| »»» message | string | Error description in case of operation failure; empty when successful. |
| »»» currency | string | Repayment currency |
| »»» repaid_principal | string | Principal |
| »»» repaid_interest | string | Principal |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/repay'
query_param = 'type=repay'
# 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="/loan/multi_collateral/repay"
query_param="type=repay"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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 /loan/multi_collateral/repay
List Multi-Collateral Repay Records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| type | query | string | true | Operation type: repay - Regular repayment, liquidate - Liquidation |
| borrow_currency | query | string | false | Borrowed currency |
| page | query | integer | false | Page number |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| 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
[
{
"order_id": 10005679,
"record_id": 1348,
"init_ltv": "0.2141",
"before_ltv": "0.215",
"after_ltv": "0.312",
"borrow_time": 1702995889,
"repay_time": 1703053927,
"borrow_currencies": [
{
"currency": "BAT",
"index_price": "103.02",
"before_amount": "1",
"before_amount_usdt": "103.02",
"after_amount": "0.999017",
"after_amount_usdt": "102.91873134"
}
],
"collateral_currencies": [
{
"currency": "ETC",
"index_price": "0.6014228107",
"before_amount": "1000",
"before_amount_usdt": "601.4228107",
"after_amount": "1000",
"after_amount_usdt": "601.4228107"
}
],
"repaid_currencies": [
{
"currency": "BAT",
"index_price": "103.02",
"repaid_amount": "0.001",
"repaid_principal": "0.000983",
"repaid_interest": "0.000017",
"repaid_amount_usdt": "0.10302"
}
],
"total_interest_list": [
{
"currency": "BAT",
"index_price": "103.02",
"amount": "0.000017",
"amount_usdt": "0.00175134"
}
],
"left_repay_interest_list": [
{
"currency": "BAT",
"index_price": "103.02",
"before_amount": "0.000017",
"before_amount_usdt": "0.00175134",
"after_amount": "0",
"after_amount_usdt": "0"
}
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Mult Repay Record |
| »» order_id | integer(int64) | Order ID |
| »» record_id | integer(int64) | Repayment record ID |
| »» init_ltv | string | The initial collateralization rate |
| »» before_ltv | string | Ltv before the operation |
| »» after_ltv | string | Ltv after the operation |
| »» borrow_time | integer(int64) | Borrowing time, timestamp in seconds. |
| »» repay_time | integer(int64) | Repayment time, timestamp in seconds. |
| »» borrow_currencies | array | List of borrowing information |
| »»» currency | string | Currency |
| »»» index_price | string | Currency Index Price |
| »»» before_amount | string | Amount before the operation |
| »»» before_amount_usdt | string | USDT Amount before the operation. |
| »»» after_amount | string | Amount after the operation. |
| »»» after_amount_usdt | string | USDT Amount after the operation. |
| »» collateral_currencies | array | List of collateral information |
| »»» currency | string | Currency |
| »»» index_price | string | Currency Index Price |
| »»» before_amount | string | Amount before the operation |
| »»» before_amount_usdt | string | USDT Amount before the operation. |
| »»» after_amount | string | Amount after the operation. |
| »»» after_amount_usdt | string | USDT Amount after the operation. |
| »» repaid_currencies | array | Repay Currency List |
| »»» RepayRecordRepaidCurrency | object | none |
| »»»» currency | string | Repayment currency |
| »»»» index_price | string | Currency Index Price |
| »»»» repaid_amount | string | Repayment amount |
| »»»» repaid_principal | string | Principal |
| »»»» repaid_interest | string | Interest |
| »»»» repaid_amount_usdt | string | Value of the repayment amount in USDT |
| »»» total_interest_list | array | Total Interest List |
| »»»» RepayRecordTotalInterest | object | none |
| »»»»» currency | string | Currency |
| »»»»» index_price | string | Currency Index Price |
| »»»»» amount | string | Interest Amount |
| »»»»» amount_usdt | string | Interest amount converted to USDT |
| »»»» left_repay_interest_list | array | List of left repay interest |
| »»»»» RepayRecordLeftInterest | object | none |
| »»»»»» currency | string | Currency |
| »»»»»» index_price | string | Currency Index Price |
| »»»»»» before_amount | string | Interest amount before repayment |
| »»»»»» before_amount_usdt | string | Converted value of interest before repayment in USDT |
| »»»»»» after_amount | string | Interest amount after repayment |
| »»»»»» after_amount_usdt | string | Converted value of interest after repayment in USDT |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/mortgage'
query_param = ''
body='{"order_id":10005578,"type":"append","collaterals":[{"currency":"btc","amount":"0.5"}]}'
# 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="/loan/multi_collateral/mortgage"
query_param=""
body_param='{"order_id":10005578,"type":"append","collaterals":[{"currency":"btc","amount":"0.5"}]}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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 /loan/multi_collateral/mortgage
Operate Multi-Collateral
Body parameter
{
"order_id": 10005578,
"type": "append",
"collaterals": [
{
"currency": "btc",
"amount": "0.5"
}
]
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » order_id | body | integer(int64) | true | Order ID |
| » type | body | string | true | Operation types: append - for adding collateral, redeem - for withdrawing collateral |
| » collaterals | body | array | false | Collateral Currency List |
| »» currency | body | string | false | Currency |
| »» amount | body | string | false | Size |
Example responses
200 Response
{
"order_id": 10005679,
"collateral_currencies": [
{
"succeeded": true,
"currency": "btc",
"amount": "0.5"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Operated successfully | Inline |
Status Code 200
Result of multi-collateral adjustment
| Name | Type | Description |
|---|---|---|
| » order_id | integer(int64) | Order ID |
| » collateral_currencies | array | Collateral Currency Information |
| »» CollateralCurrencyRes | object | none |
| »»» succeeded | boolean | Update success status |
| »»» label | string | Error identifier for unsuccessful operations; empty for successful. |
| »»» message | string | Error description in case of operation failure; empty when successful. |
| »»» currency | string | Currency |
| »»» amount | string | Quantity of successful collateral operation; 0 if the operation fails. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/mortgage'
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="/loan/multi_collateral/mortgage"
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 /loan/multi_collateral/mortgage
Query collateral adjustment records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer | false | Page number |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| from | query | integer(int64) | false | Start timestamp of the query |
| to | query | integer(int64) | false | Time range ending, default to current time |
| collateral_currency | query | string | false | Collateral |
Example responses
200 Response
[
{
"order_id": 10000417,
"record_id": 10000452,
"before_ltv": "0.00039345555621480000",
"after_ltv": "0.00019672777810740000",
"operate_time": 1688461924,
"borrow_currencies": [
{
"currency": "BTC",
"index_price": "30000",
"before_amount": "0.1",
"before_amount_usdt": "1000",
"after_amount": "0.6",
"after_amount_usdt": "1006"
}
],
"collateral_currencies": [
{
"currency": "BTC",
"index_price": "30000",
"before_amount": "0.1",
"before_amount_usdt": "1000",
"after_amount": "0.6",
"after_amount_usdt": "1006"
}
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Multi-Collateral adjustment record. |
| »» order_id | integer(int64) | Order ID |
| »» record_id | integer(int64) | Collateral record ID |
| »» before_ltv | string | The collateral ratio before adjustment |
| »» after_ltv | string | The collateral ratio before adjustment |
| »» operate_time | integer(int64) | Operation time, timestamp in seconds. |
| »» borrow_currencies | array | Borrowing Currency List |
| »»» currency | string | Currency |
| »»» index_price | string | Currency Index Price |
| »»» before_amount | string | Amount before the operation |
| »»» before_amount_usdt | string | USDT Amount before the operation. |
| »»» after_amount | string | Amount after the operation. |
| »»» after_amount_usdt | string | USDT Amount after the operation. |
| »» collateral_currencies | array | Collateral Currency List |
| »»» currency | string | Currency |
| »»» index_price | string | Currency Index Price |
| »»» before_amount | string | Amount before the operation |
| »»» before_amount_usdt | string | USDT Amount before the operation. |
| »»» after_amount | string | Amount after the operation. |
| »»» after_amount_usdt | string | USDT Amount after the operation. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/currency_quota'
query_param = 'type=collateral¤cy=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="/loan/multi_collateral/currency_quota"
query_param="type=collateral¤cy=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 /loan/multi_collateral/currency_quota
List User Currency Quota
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| type | query | string | true | Currency types: collateral - collateral currency, borrow - borrowing currency. |
| currency | query | string | true | When specifying collateral currencies, you can use commas to separate multiple currencies; for borrowing currencies, only one currency can be provided. |
Example responses
200 Response
[
{
"currency": "BTC",
"index_price": "35306.1",
"min_quota": "0",
"left_quota": "2768152.4958445218723677",
"left_quote_usdt": "97732668833.536273678"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Currency Quota |
| »» currency | string | Currency |
| »» index_price | string | Currency Index Price |
| »» min_quota | string | Minimum borrowing/collateral quota for the currency |
| »» left_quota | string | Remaining borrowing/collateral limit for the currency |
| »» left_quote_usdt | string | Remaining currency limit converted to USDT |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/loan/multi_collateral/currencies \
-H 'Accept: application/json'
GET /loan/multi_collateral/currencies
*Query supported borrowing and collateral currencies in Multi-Collateral *
Example responses
200 Response
{
"loan_currencies": [
{
"currency": "BTC",
"price": "1212"
},
{
"currency": "GT",
"price": "12"
}
],
"collateral_currencies": [
{
"currency": "BTC",
"index_price": "1212",
"discount": "0.7"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
Borrowing and collateral currencies supported for Multi-Collateral.
| Name | Type | Description |
|---|---|---|
| » loan_currencies | array | List of supported borrowing currencies |
| »» MultiLoanItem | object | none |
| »»» currency | string | Currency |
| »»» price | string | Latest price of the currency |
| »» collateral_currencies | array | List of supported collateral currencies |
| »»» MultiCollateralItem | object | none |
| »»»» currency | string | Currency |
| »»»» index_price | string | Currency Index Price |
| »»»» discount | string | Discount |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/ltv'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/loan/multi_collateral/ltv \
-H 'Accept: application/json'
GET /loan/multi_collateral/ltv
Get Multi-Collateral ratio
The Multi-Collateral ratio is fixed, irrespective of the currency.
Example responses
200 Response
{
"init_ltv": "0.7",
"alert_ltv": "0.8",
"liquidate_ltv": "0.9"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
Collateral Ratio
| Name | Type | Description |
|---|---|---|
| » init_ltv | string | The initial collateralization rate |
| » alert_ltv | string | Warning collateralization ratio |
| » liquidate_ltv | string | The liquidation collateralization rate |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/fixed_rate'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/loan/multi_collateral/fixed_rate \
-H 'Accept: application/json'
GET /loan/multi_collateral/fixed_rate
Query fixed interest rates for the currency for 7 days and 30 days
Example responses
200 Response
[
{
"currency": "BTC",
"rate_7d": "0.000023",
"rate_30d": "0.1",
"update_time": 1703820105
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Multi-collateral fixed interest rate |
| »» currency | string | Currency |
| »» rate_7d | string | Fixed interest rate for a lending period of 7 days |
| »» rate_30d | string | Fixed interest rate for a lending period of 30 days |
| »» update_time | integer(int64) | Update time, timestamp, unit in seconds |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/current_rate'
query_param = 'currencies=BTC,GT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/loan/multi_collateral/current_rate?currencies=BTC,GT \
-H 'Accept: application/json'
GET /loan/multi_collateral/current_rate
Query the current interest rate of the currency
Query the current interest rate of the currency in the last hour. The current interest rate is updated every hour.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currencies | query | array[string] | true | Specify the currency name to query the array. The array is separated by commas and has a maximum of 100 items. |
| vip_level | query | string | false | VIP level, defaults to 0 if not transferred |
Example responses
200 Response
[
{
"currency": "BTC",
"current_rate": "0.000023"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Multi-currency pledge current interest rate |
| »» currency | string | Currency |
| »» current_rate | string | Currency current interest rate |
earn
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/staking/eth2/swap'
query_param = ''
body='{"side":"1","amount":"1.5"}'
# 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="/earn/staking/eth2/swap"
query_param=""
body_param='{"side":"1","amount":"1.5"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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 /earn/staking/eth2/swap
ETH2 swap
Body parameter
{
"side": "1",
"amount": "1.5"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » side | body | string | true | 1-Forward Swap（ETH -> ETH2）, 2-Reverse Swap（ETH2 -> ETH） |
| » amount | body | string | true | amount |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | swap success | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/dual/investment_plan'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/earn/dual/investment_plan \
-H 'Accept: application/json'
GET /earn/dual/investment_plan
Dual Investment product list
Example responses
200 Response
[
{
"id": 272,
"instrument_name": "DOGE-17NOV23-0.067-P",
"type": "put",
"invest_currency": "USDT",
"exercise_currency": "DOGE",
"exercise_price": 0.067,
"delivery_time": 1700208000,
"min_copies": 1,
"max_copies": 1000,
"start_time": 1697685172,
"end_time": 1697685172,
"status": "ONGOING",
"apy_display": "0.0114000000",
"per_value": "1"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int32) | Plan ID |
| » instrument_name | string | Instrument Name |
| » invest_currency | string | Investment Currency |
| » exercise_currency | string | Strike Currency |
| » exercise_price | number(double) | Strike price |
| » delivery_time | integer(int32) | Settlement time |
| » min_copies | integer(int32) | Minimum Copies |
| » max_copies | integer(int32) | Maximum Copies |
| » per_value | string | Per Unit Value |
| » apy_display | string | APY |
| » start_time | integer(int32) | start time |
| » end_time | integer(int32) | Finished time |
| » status | string | Status: NOTSTARTED-not started ONGOING-ongoing ENDED-ended |
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/dual/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="/earn/dual/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 /earn/dual/orders
Dual Investment order list
Example responses
200 Response
[
{
"id": 373,
"plan_id": 176,
"copies": "1.0000000000",
"invest_amount": "0.0000000000",
"settlement_amount": "0.0000000000",
"create_time": 1697685172,
"complete_time": 1697685172,
"status": "CANCELED",
"invest_currency": "USDT",
"exercise_currency": "BTC",
"settlement_currency": "",
"exercise_price": "24500.0000000000",
"settlement_price": "0.0000000000",
"delivery_time": 1697685172,
"apy_display": "0.6800000000",
"apy_settlement": "0.0000000000"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int32) | Order ID |
| » plan_id | integer(int32) | Plan ID |
| » copies | string | Copies |
| » invest_amount | string | Investment Amount |
| » settlement_amount | string | Settlement Amount |
| » create_time | integer(int32) | Creation time |
| » complete_time | integer(int32) | Completion Time |
| » status | string | Status:INIT-INITSETTLEMENT_SUCCESS-Settlement SuccessSETTLEMENT_PROCESSING-SEttlement ProcessingCANCELED-CanceledFAILED-Failed |
| » invest_currency | string | Investment Currency |
| » exercise_currency | string | Strike Currency |
| » exercise_price | string | Strike price |
| » settlement_price | string | settlement price |
| » settlement_currency | string | Settle currency |
| » apy_display | string | APY |
| » apy_settlement | string | Settlement APY |
| » delivery_time | integer(int32) | Settlement time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/dual/orders'
query_param = ''
body='{"plan_id":"176","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="/earn/dual/orders"
query_param=""
body_param='{"plan_id":"176","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 /earn/dual/orders
Place Dual Investment order
Body parameter
{
"plan_id": "176",
"amount": "1"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » plan_id | body | string | true | Plan ID |
| » copies | body | string | false | The number of copies is mutually exclusive with the amount field and will be deprecated soon. It is recommended to use the amount parameter. |
| » is_max | body | integer(int32) | false | Whether to purchase at the maximum. Mutually exclusive with the amount field. Will be deprecated soon. It is recommended to use the amount parameter. |
| » amount | body | string | true | Subscription amount, mutually exclusive with the copies field |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/structured/products'
query_param = 'status=in_process'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/earn/structured/products?status=in_process \
-H 'Accept: application/json'
GET /earn/structured/products
Structured Product List
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| type | query | string | false | Product Type (default all) |
| status | query | string | true | Status (default: all) |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
type: Product Type (default all)
SharkFin2.0-SharkFin
BullishSharkFin-BullishSharkFin
BearishSharkFin-BearishSharkFin
DoubleNoTouch-DoubleNoTouch
RangeAccrual-RangeAccrual
SnowBall-SnowBall
status: Status (default: all)
in_process-processing
will_begin-unstarted
wait_settlement-unsettled
done-finish
Example responses
200 Response
[
{
"id": 3700,
"type": "BullishSharkFin",
"name_en": "Bullish Sharkfin_USDT",
"investment_period": 7,
"min_annual_rate": "0.50",
"mid_annual_rate": "7.50",
"max_annual_rate": "13.00",
"watch_market": "BTC_USDT",
"investment_coin": "USDT",
"start_time": 1698224400,
"end_time": 1700902800,
"status": "in_process"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Structured Products |
| »» id | integer(int32) | Plan ID |
| »» type | string | product type: SharkFin2.0-Shark Fin2.0 BullishSharkFin-Bullish Shark Fin BearishSharkFin-Bearish Shark FinDoubleNoTouch-Double No-TouchRangeAccrual-Range AccrualSnowBall-Snow Ball |
| »» name_en | string | name |
| »» investment_coin | string | Investment Currency |
| »» investment_period | string | Investment term |
| »» min_annual_rate | string | Minimum annual rate |
| »» mid_annual_rate | string | Intermediate annual rate |
| »» max_annual_rate | string | Maximum annual rate |
| »» watch_market | string | Watch market |
| »» start_time | integer(int32) | start time |
| »» end_time | integer(int32) | Finished time |
| »» status | string | Status: in_process-in progress will_begin-will begin wait_settlement-waiting for settlement done-done |
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/structured/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="/earn/structured/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 /earn/structured/orders
Structured Product Order List
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | End timestamp |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records to be returned in a single list |
Example responses
200 Response
[
{
"id": 35,
"pid": "3691",
"lock_coin": "ETH",
"amount": "20",
"status": "SUCCESS",
"income": "0.000000",
"create_time": 1697685172
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Structured order |
| »» id | integer(int32) | Order ID |
| »» pid | string | Plan ID |
| »» lock_coin | string | Locked coin |
| »» amount | string | Locked amount |
| »» status | string | Status: SUCCESS - SUCCESS FAILED - FAILED DONE - DONE |
| »» income | string | Income |
| »» create_time | integer(int32) | Created time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/structured/orders'
query_param = ''
body='{"pid":"1","amount":"0.5"}'
# 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="/earn/structured/orders"
query_param=""
body_param='{"pid":"1","amount":"0.5"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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 /earn/structured/orders
Place Structured Product Order
Body parameter
{
"pid": "1",
"amount": "0.5"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » pid | body | string | false | Plan ID |
| » amount | body | string | false | Purchase Amount |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Get account detail
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/detail'
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="/account/detail"
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 /account/detail
Get account detail
Example responses
200 Response
{
"user_id": 1667201533,
"ip_whitelist": [
"127.0.0.1"
],
"currency_pairs": [
"USDT_BTC"
],
"key": {
"mode": 1
},
"tier": 2,
"copy_trading_role": 1
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successful | Inline |
Status Code 200
AccountDetail
| Name | Type | Description |
|---|---|---|
| » ip_whitelist | array | IP whitelist |
| » currency_pairs | array | CurrencyPair whitelisting |
| » user_id | integer(int64) | User ID |
| » tier | integer(int64) | User VIP level |
| » key | object | API Key detail |
| »» mode | integer(int32) | mode: 1 - classic account 2 - portfolio margin account |
| » copy_trading_role | integer(int32) | User role: 0 - Ordinary user 1 - Order leader 2 - Follower 3 - Order leader and follower |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/rate_limit'
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="/account/rate_limit"
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 /account/rate_limit
Get user transaction rate limit information
Example responses
200 Response
[
{
"type": "spot",
"tier": "1",
"ratio": "0",
"main_ratio": "0",
"updated_at": "1728230400"
},
{
"type": "futures",
"tier": "1",
"ratio": "0",
"main_ratio": "0",
"updated_at": "1728230400"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successful | [Inline] |
Status Code 200
AccountRateLimit
| Name | Type | Description |
|---|---|---|
| AccountRateLimit | array | Account flow limit |
| » tier | string | Frequency limit level (For detailed frequency limit rules, see Transaction ratio frequency limit) |
| » ratio | string | Transaction rate |
| » main_ratio | string | Total transaction ratio of main account |
| » updated_at | string | Update time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/stp_groups'
query_param = ''
body='{"name":"stp_name"}'
# 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="/account/stp_groups"
query_param=""
body_param='{"name":"stp_name"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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 /account/stp_groups
Create STP Group
Only the main account is allowed to create a new STP user group
Body parameter
{
"name": "stp_name"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » id | body | integer(int64) | false | STP Group ID |
| » name | body | string | true | STP Group name |
| » creator_id | body | integer(int64) | false | Creator ID |
| » create_time | body | integer(int64) | false | Creation time |
Example responses
200 Response
{
"id": 123435,
"name": "group",
"create_time": 1548000000,
"creator_id": 10000
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | User added successfully. Returning the current users within the STP group. | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | STP Group ID |
| » name | string | STP Group name |
| » creator_id | integer(int64) | Creator ID |
| » create_time | integer(int64) | Creation time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/stp_groups'
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="/account/stp_groups"
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 /account/stp_groups
List STP Groups
Retrieve the list of STP groups created by the main account user only
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| name | query | string | false | Perform a fuzzy search based on the name |
Example responses
200 Response
[
{
"id": 123435,
"name": "group",
"create_time": 1548000000,
"creator_id": 10000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | integer(int64) | STP Group ID |
| » name | string | STP Group name |
| » creator_id | integer(int64) | Creator ID |
| » create_time | integer(int64) | Creation time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/stp_groups/1/users'
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="/account/stp_groups/1/users"
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 /account/stp_groups/{stp_id}/users
List users of the STP group
Only the main account that created this STP group is allowed to list the user ID of the STP group
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| stp_id | path | integer(int64) | true | STP Group ID |
Example responses
200 Response
[
{
"user_id": 10000,
"stp_id": 1,
"create_time": 1548000000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » user_id | integer(int64) | User ID |
| » stp_id | integer(int64) | STP Group ID |
| » create_time | integer(int64) | Creation time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/stp_groups/1/users'
query_param = ''
body='[1,2,3]'
# 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="/account/stp_groups/1/users"
query_param=""
body_param='[1,2,3]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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 /account/stp_groups/{stp_id}/users
Add users to the STP group
Body parameter
[
1,
2,
3
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| stp_id | path | integer(int64) | true | STP Group ID |
| body | body | array[integer] | true | User ID |
Example responses
200 Response
[
{
"user_id": 10000,
"stp_id": 1,
"create_time": 1548000000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | User added successfully. Returning the current users within the STP group. | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » user_id | integer(int64) | User ID |
| » stp_id | integer(int64) | STP Group ID |
| » create_time | integer(int64) | Creation time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/stp_groups/1/users'
query_param = 'user_id=1'
# 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="/account/stp_groups/1/users"
query_param="user_id=1"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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 /account/stp_groups/{stp_id}/users
Delete the user in the STP group
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| stp_id | path | integer(int64) | true | STP Group ID |
| user_id | query | integer(int64) | true | STP user ID, multiple can be separated by commas |
Example responses
200 Response
[
{
"user_id": 10000,
"stp_id": 1,
"create_time": 1548000000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » user_id | integer(int64) | User ID |
| » stp_id | integer(int64) | STP Group ID |
| » create_time | integer(int64) | Creation time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/debit_fee'
query_param = ''
body='{"enabled":true}'
# 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="/account/debit_fee"
query_param=""
body_param='{"enabled":true}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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 /account/debit_fee
Set GT deduction.
Enable or disable GT deduction for the current account.
Body parameter
{
"enabled": true
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » enabled | body | boolean | true | Whether GT fee discount is used |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/debit_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="/account/debit_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 /account/debit_fee
Query GT deduction configuration.
Query the current GT deduction configuration for the account.
Example responses
200 Response
{
"enabled": true
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » enabled | boolean | Whether GT fee discount is used |
WARNING
To perform this operation, you must be authenticated by API key and secret
broker rebate endpints
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/agency/transaction_history'
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="/rebate/agency/transaction_history"
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 /rebate/agency/transaction_history
The agency obtains the transaction history of the recommended user
Record time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Specify the currency pair, if not specified, return all currency pairs |
| user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned |
| 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
{
"total": 100,
"list": [
{
"transaction_time": 1539852480,
"user_id": 10000,
"group_name": "gateio",
"fee": "1",
"fee_asset": "GT",
"currency_pair": "GT_USDT",
"amount": "1000",
"source": "SPOT",
"amount_asset": "GT"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency_pair | string | Currency pair |
| » total | integer(int64) | Total |
| » list | array | List of transaction history |
| »» AgencyTransaction | object | none |
| »»» transaction_time | integer(int64) | Transaction Time. (unix timestamp) |
| »»» user_id | integer(int64) | User ID |
| »»» group_name | string | Group name |
| »»» fee | string | Fee |
| »»» fee_asset | string | Fee currency |
| »»» currency_pair | string | Currency pair |
| »»» amount | string | Commission Amount |
| »»» amount_asset | string | Commission Asset |
| »»» source | string | Source. SPOT - SPOT Rebate, FUTURES - Futures Rebate |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/agency/commission_history'
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="/rebate/agency/commission_history"
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 /rebate/agency/commission_history
The agency obtains the commission history of the recommended user
Record time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Filter by currency. Return all currency records if not specified |
| user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned |
| 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
{
"total": 100,
"list": [
{
"commission_time": 1539852480,
"user_id": 10000,
"group_name": "gateio",
"commission_amount": "1000",
"source": "SPOT",
"commission_asset": "GT"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency_pair | string | Currency pair |
| » total | integer(int64) | Total |
| » list | array | List of comission history |
| »» AgencyCommission | object | none |
| »»» commission_time | integer(int64) | Commission Time. (unix timestamp) |
| »»» user_id | integer(int64) | User ID |
| »»» group_name | string | Group name |
| »»» commission_amount | string | Commission Amount |
| »»» commission_asset | string | Commission Asset |
| »»» source | string | Source. SPOT - SPOT Rebate, FUTURES - Futures Rebate |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/partner/transaction_history'
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="/rebate/partner/transaction_history"
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 /rebate/partner/transaction_history
Partner obtains transaction records of recommended users
Record time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Specify the currency pair, if not specified, return all currency pairs |
| user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned |
| 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
{
"total": 15,
"list": [
{
"user_id": 1879032535,
"group_name": "test",
"fee": "0.00044800",
"transaction_time": 1718615824,
"amount": "29.98688000USDT",
"amount_asset": "USDT",
"currency_pair": "BCH_USDT",
"source": "SPOT",
"fee_asset": "BCH"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » total | integer(int64) | Total |
| » list | array | List of transaction history |
| »» PartnerTransaction | object | none |
| »»» transaction_time | integer(int64) | Transaction Time. (unix timestamp) |
| »»» user_id | integer(int64) | User ID |
| »»» group_name | string | Group name |
| »»» fee | string | Fee |
| »»» fee_asset | string | Fee currency |
| »»» currency_pair | string | Currency pair |
| »»» amount | string | Commission Amount |
| »»» amount_asset | string | Commission Asset |
| »»» source | string | Source. SPOT - SPOT Rebate, FUTURES - Futures Rebate |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/partner/commission_history'
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="/rebate/partner/commission_history"
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 /rebate/partner/commission_history
Partner obtains commission records of recommended users
Record time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Filter by currency. Return all currency records if not specified |
| user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned |
| 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
{
"total": 52,
"list": [
{
"user_id": 1879043947,
"commission_time": 1718616728,
"commission_amount": "0.2216934846",
"commission_asset": "USDT",
"source": "SPOT",
"group_name": "test"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » total | integer(int64) | Total |
| » list | array | List of comission history |
| »» PartnerCommission | object | none |
| »»» commission_time | integer(int64) | Commission Time. (unix timestamp) |
| »»» user_id | integer(int64) | User ID |
| »»» group_name | string | Group name |
| »»» commission_amount | string | Commission Amount |
| »»» commission_asset | string | Commission Asset |
| »»» source | string | Source. SPOT - SPOT Rebate, FUTURES - Futures Rebate |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/partner/sub_list'
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="/rebate/partner/sub_list"
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 /rebate/partner/sub_list
Partner subordinate list
Including sub-agents, direct customers, indirect customers
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned |
| 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
{
"total": 3,
"list": [
{
"user_id": 1,
"user_join_time": 1666255731,
"type": 1
},
{
"user_id": 2,
"user_join_time": 1666271213,
"type": 2
},
{
"user_id": 3,
"user_join_time": 1666422143,
"type": 3
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » total | integer(int64) | Total |
| » list | array | Subordinate list |
| »» PartnerSub | object | none |
| »»» user_id | integer(int64) | User ID |
| »»» user_join_time | integer(int64) | The time when the user joined the system, in seconds Unix timestamp |
| »»» type | integer(int64) | Type (1-Sub-agent 2-Indirect Customer 3-Direct Customer) |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/broker/commission_history'
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="/rebate/broker/commission_history"
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 /rebate/broker/commission_history
The broker obtains the user's commission rebate records
Record time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned |
| from | query | integer(int64) | false | The start time of the query record. If not specified, the default is to push forward 30 days from the current time. |
| to | query | integer(int64) | false | Time range ending, default to current time |
Example responses
200 Response
{
"list": [
{
"user_id": 110285442,
"group_name": "",
"fee": "0.5000045000",
"transaction_time": 1702545051,
"amount": "-1000.00900000",
"currency_pair": "DOGE_USDT",
"source": "Futures",
"fee_asset": "USDT"
}
],
"total": 47
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » total | integer(int64) | Total |
| » list | array | List of comission history |
| »» BrokerCommission | object | none |
| »»» commission_time | integer(int64) | Commission Time. (unix timestamp) |
| »»» user_id | integer(int64) | User ID |
| »»» group_name | string | Group name |
| »»» amount | string | The amount of commission rebates |
| »»» fee | string | Fee |
| »»» fee_asset | string | Fee currency |
| »»» rebate_fee | string | The income from rebates, converted to USDT |
| »»» source | string | Rebate Type: Spot、Futures、Options |
| »»» currency_pair | string | Currency pair |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/broker/transaction_history'
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="/rebate/broker/transaction_history"
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 /rebate/broker/transaction_history
The broker obtains the user's trading history
Record time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| limit | query | integer | false | Maximum number of records to be returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned |
| from | query | integer(int64) | false | The start time of the query record. If not specified, the default is to push forward 30 days from the current time. |
| to | query | integer(int64) | false | Time range ending, default to current time |
Example responses
200 Response
{
"list": [
{
"user_id": 110285442,
"group_name": "",
"fee": "0.5000045000",
"transaction_time": 1702545051,
"amount": "-1000.00900000",
"currency_pair": "DOGE_USDT",
"source": "Futures",
"fee_asset": "USDT"
}
],
"total": 47
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » total | integer(int64) | Total |
| » list | array | List of transaction history |
| »» BrokerTransaction | object | none |
| »»» transaction_time | integer(int64) | Transaction Time. (unix timestamp) |
| »»» user_id | integer(int64) | User ID |
| »»» group_name | string | Group name |
| »»» fee | string | fee (usdt) |
| »»» currency_pair | string | Currency pair |
| »»» amount | string | Commission Amount |
| »»» fee_asset | string | Fee currency |
| »»» source | string | Rebate Type: Spot、Futures、Options |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/user/info'
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="/rebate/user/info"
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 /rebate/user/info
User retrieves rebate information
Example responses
200 Response
{
"invite_uid": 987
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Retrieve user rebate information |
| »» invite_uid | integer(int64) | My inviter's UID |
WARNING
To perform this operation, you must be authenticated by API key and secret
{
"user_id": "string",
"mode": 0,
"name": "string",
"perms": [
{
"name": "string",
"read_only": true
}
],
"ip_whitelist": [
"string"
],
"key": "string",
"state": 0,
"created_at": 0,
"updated_at": 0,
"last_access": 0
}
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| user_id | string | false | read-only | User ID |
| mode | integer(int32) | false | none | Mode: 1 - classic 2 - portfolio account |
| name | string | false | none | API key name |
| perms | array | false | none | none |
| » name | string | false | none | Permission name (all permissions will be removed if no value is passed) - wallet: wallet - spot: spot/margin - futures: perpetual contract - delivery: delivery - earn: earn - custody: custody - options: options - account: Account - unified: unified - loan: Loan - margin: margin - unified: unified - copy: copy - pilot：pilot |
| » read_only | boolean | false | none | read only |
| ip_whitelist | array | false | none | ip white list (list will be removed if no value is passed) |
| key | string | false | read-only | API Key |
| state | integer(int32) | false | read-only | State 1 - normal 2 - locked 3 - frozen |
| created_at | integer(int64) | false | read-only | Creation time |
| updated_at | integer(int64) | false | read-only | Last update time |
| last_access | integer(int64) | false | read-only | Last access time |
{
"id": "string",
"base": "string",
"quote": "string",
"fee": "string",
"min_base_amount": "string",
"min_quote_amount": "string",
"max_base_amount": "string",
"max_quote_amount": "string",
"amount_precision": 0,
"precision": 0,
"trade_status": "untradable",
"sell_start": 0,
"buy_start": 0
}
Spot currency pair
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | false | none | Currency pair |
| base | string | false | none | Base currency |
| quote | string | false | none | Quote currency |
| fee | string | false | none | Trading fee |
| min_base_amount | string | false | none | Minimum amount of base currency to trade, null means no limit |
| min_quote_amount | string | false | none | Minimum amount of quote currency to trade, null means no limit |
| max_base_amount | string | false | none | Maximum amount of base currency to trade, null means no limit |
| max_quote_amount | string | false | none | Maximum amount of quote currency to trade, null means no limit |
| amount_precision | integer | false | none | Amount scale |
| precision | integer | false | none | Price scale |
| trade_status | string | false | none | How currency pair can be traded - untradable: cannot be bought or sold - buyable: can be bought - sellable: can be sold - tradable: can be bought or sold |
| sell_start | integer(int64) | false | none | Sell start unix timestamp in seconds |
| buy_start | integer(int64) | false | none | Buy start unix timestamp in seconds |
| Property | Value |
|---|---|
| trade_status | untradable |
| trade_status | buyable |
| trade_status | sellable |
| trade_status | tradable |
{
"id": "string",
"text": "string",
"amend_text": "string",
"create_time": "string",
"update_time": "string",
"create_time_ms": 0,
"update_time_ms": 0,
"status": "open",
"currency_pair": "string",
"type": "limit",
"account": "spot",
"side": "buy",
"amount": "string",
"price": "string",
"time_in_force": "gtc",
"iceberg": "string",
"auto_borrow": true,
"auto_repay": true,
"left": "string",
"filled_amount": "string",
"fill_price": "string",
"filled_total": "string",
"avg_deal_price": "string",
"fee": "string",
"fee_currency": "string",
"point_fee": "string",
"gt_fee": "string",
"gt_maker_fee": "string",
"gt_taker_fee": "string",
"gt_discount": true,
"rebated_fee": "string",
"rebated_fee_currency": "string",
"stp_id": 0,
"stp_act": "cn",
"finish_as": "open",
"action_mode": "string"
}
Spot order details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | false | read-only | Order ID |
| text | string | false | none | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 |
| amend_text | string | false | read-only | The custom data that the user remarked when amending the order |
| create_time | string | false | read-only | Creation time of order |
| update_time | string | false | read-only | Last modification time of order |
| create_time_ms | integer(int64) | false | read-only | Creation time of order (in milliseconds) |
| update_time_ms | integer(int64) | false | read-only | Last modification time of order (in milliseconds) |
| status | string | false | read-only | Order status - open: to be filled- closed: filled- cancelled: cancelled |
| currency_pair | string | true | none | Currency pair |
| type | string | false | none | Order Type - limit : Limit Order - market : Market Order |
| account | string | false | none | Account types， spot - spot account, margin - margin account, unified - unified account, cross_margin - cross margin account. Portfolio margin accounts can only be set to cross_margin |
| side | string | true | none | Order side |
| amount | string | true | none | When type is limit, it refers to base currency. For instance, BTC_USDT means BTC When type is market, it refers to different currency according to side - side : buy means quote currency, BTC_USDT means USDT- side : sell means base currency，BTC_USDT means BTC |
| price | string | false | none | Price can't be empty when type= limit |
| time_in_force | string | false | none | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market |
| iceberg | string | false | none | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported. |
| auto_borrow | boolean | false | write-only | Used in margin or cross margin trading to allow automatic loan of insufficient amount if balance is not enough. |
| auto_repay | boolean | false | none | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order. |
| left | string | false | read-only | Amount left to fill |
| filled_amount | string | false | read-only | Amount traded to fill |
| fill_price | string | false | read-only | Total filled in quote currency. Deprecated in favor of filled_total |
| filled_total | string | false | read-only | Total filled in quote currency |
| avg_deal_price | string | false | read-only | Average fill price |
| fee | string | false | read-only | Fee deducted |
| fee_currency | string | false | read-only | Fee currency unit |
| point_fee | string | false | read-only | Points used to deduct fee |
| gt_fee | string | false | read-only | GT used to deduct fee |
| gt_maker_fee | string | false | read-only | GT used to deduct maker fee |
| gt_taker_fee | string | false | read-only | GT used to deduct taker fee |
| gt_discount | boolean | false | read-only | Whether GT fee discount is used |
| rebated_fee | string | false | read-only | Rebated fee |
| rebated_fee_currency | string | false | read-only | Rebated fee currency unit |
| stp_id | integer | false | read-only | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
| stp_act | string | false | none | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group, he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy。2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter。3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, Cancel old orders and keep new ones - cb: Cancel both, Both old and new orders will be cancelled |
| finish_as | string | false | read-only | Order completion statuses include: - open: Awaiting processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled due to liquidation - small: Order quantity too small - depth_not_enough: Cancelled due to insufficient market depth - trader_not_enough: Cancelled due to insufficient counterparty - ioc: Not immediately filled because tif is set to ioc - poc: Not met the order strategy because tif is set to poc - fok: Not fully filled immediately because tif is set to fok - stp: Cancelled due to self-trade prevention - unknown: Unknown |
| action_mode | string | false | write-only | Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default) |
| Property | Value |
|---|---|
| status | open |
| status | closed |
| status | cancelled |
| type | limit |
| type | market |
| 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 | liquidate_cancelled |
| finish_as | depth_not_enough |
| finish_as | trader_not_enough |
| finish_as | small |
| finish_as | ioc |
| finish_as | poc |
| finish_as | fok |
| finish_as | stp |
| finish_as | unknown |
{
"currency_pair": "string",
"id": "string",
"account": "string",
"action_mode": "string"
}
Info of order to be cancelled
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| currency_pair | string | true | none | Order currency pair |
| id | string | true | none | Order ID or user custom ID. Custom ID are accepted only within 30 minutes after order creation |
| account | string | false | none | If cancelled order is cross margin order or is portfolio margin account's API key, this field must be set and can only be cross_marginIf cancelled order is cross margin order, this field must be set and can only be cross_margin |
| action_mode | string | false | none | Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default) |
{
"order_id": "string",
"currency_pair": "string",
"account": "string",
"amount": "string",
"price": "string",
"amend_text": "string",
"action_mode": "string"
}
Order information that needs to be modified
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| order_id | string | true | none | The order ID returned upon successful creation or the custom ID specified by the user during creation (i.e., the 'text' field). |
| currency_pair | string | true | none | Currency pair |
| account | string | false | none | Default to spot, portfolio, and margin accounts if not specified. Use 'cross_margin' to query cross margin accounts. Only 'cross_margin' can be specified for portfolio margin accounts. |
| amount | string | false | none | trade amount, only one of amount and price can be specified |
| price | string | false | none | trade price, only one of amount and price can be specified |
| amend_text | string | false | none | Custom info during amending order |
| action_mode | string | false | none | Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default) |
{
"id": "string",
"create_time": "string",
"expire_time": "string",
"status": "open",
"side": "lend",
"currency": "string",
"rate": "string",
"amount": "string",
"days": 0,
"auto_renew": false,
"currency_pair": "string",
"left": "string",
"repaid": "string",
"paid_interest": "string",
"unpaid_interest": "string",
"fee_rate": "string",
"orig_id": "string",
"text": "string"
}
Margin loan details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | false | read-only | Loan ID |
| create_time | string | false | read-only | Creation time |
| expire_time | string | false | read-only | Repay time of the loan. No value will be returned for lending loan |
| status | string | false | read-only | Loan status open - not fully loaned loaned - all loaned out for lending loan; loaned in for borrowing side finished - loan is finished, either being all repaid or cancelled by the lender auto_repaid - automatically repaid by the system |
| side | string | true | none | Loan side |
| currency | string | true | none | Loan currency |
| rate | string | false | none | Loan rate. Only rates in [0.0001, 0.01] are supported. Not required in lending. Market rate calculated from recent rates will be used if not set |
| amount | string | true | none | Loan amount |
| days | integer | false | none | Loan days. Only 10 is supported for now |
| auto_renew | boolean | false | none | Whether to auto renew the loan upon expiration |
| currency_pair | string | false | none | Currency pair. Required if borrowing |
| left | string | false | read-only | Amount not lent out yet |
| repaid | string | false | read-only | Repaid amount |
| paid_interest | string | false | read-only | Repaid interest |
| unpaid_interest | string | false | read-only | Outstanding interest yet to be paid |
| fee_rate | string | false | none | Loan fee rate |
| orig_id | string | false | none | Original loan ID of the loan if auto-renewed, otherwise equals to id |
| text | string | false | none | User defined custom ID |
| Property | Value |
|---|---|
| status | open |
| status | loaned |
| status | finished |
| status | auto_repaid |
| side | lend |
| side | borrow |
{
"id": "string",
"loan_id": "string",
"create_time": "string",
"expire_time": "string",
"status": "loaned",
"borrow_user_id": "string",
"currency": "string",
"rate": "string",
"amount": "string",
"days": 0,
"auto_renew": false,
"repaid": "string",
"paid_interest": "string",
"unpaid_interest": "string"
}
Margin loaned record details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | false | none | Loan record ID |
| loan_id | string | false | none | Loan ID the record belongs to |
| create_time | string | false | none | Loan time |
| expire_time | string | false | none | Expiration time |
| status | string | false | none | Loan record status |
| borrow_user_id | string | false | none | Garbled user ID |
| currency | string | false | none | Loan currency |
| rate | string | false | none | Loan rate |
| amount | string | false | none | Loan amount |
| days | integer | false | none | Loan days |
| auto_renew | boolean | false | none | Whether the record will auto renew on expiration |
| repaid | string | false | none | Repaid amount |
| paid_interest | string | false | read-only | Repaid interest |
| unpaid_interest | string | false | read-only | Outstanding interest yet to be paid |
| Property | Value |
|---|---|
| status | loaned |
| status | finished |
{
"trigger": {
"price": "string",
"rule": ">=",
"expiration": 0
},
"put": {
"type": "limit",
"side": "buy",
"price": "string",
"amount": "string",
"account": "normal",
"time_in_force": "gtc",
"text": "string"
},
"id": 0,
"user": 0,
"market": "string",
"ctime": 0,
"ftime": 0,
"fired_order_id": 0,
"status": "string",
"reason": "string"
}
Spot order detail
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| trigger | object | true | none | none |
| » price | string | true | none | Trigger price |
| » rule | string | true | none | Price trigger condition - >=: triggered when market price larger than or equal to price field- <=: triggered when market price less than or equal to price field |
| » expiration | integer | true | none | How long (in seconds) to wait for the condition to be triggered before cancelling the order. |
| put | object | true | none | none |
| » type | string | false | none | Order type，default to limit- limit : Limit Order - market : Market Order |
| » side | string | true | none | Order side - buy: buy side - sell: sell side |
| » price | string | true | none | Order price |
| » amount | string | true | none | When type is limit, it refers to base currency. For instance, BTC_USDT means BTC When type is market, it refers to different currency according to side - side : buy means quote currency, BTC_USDT means USDT- side : sell means base currency，BTC_USDT means BTC |
| » account | string | true | none | Trading account type. Portfolio margin account must set to cross_margin- normal: spot trading - margin: margin trading - cross_margin: cross_margin trading |
| » time_in_force | string | false | none | time_in_force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only |
| » text | string | false | none | The source of the order, including: - web: web - api: api - app: app |
| id | integer(int64) | false | read-only | Auto order ID |
| user | integer | false | read-only | User ID |
| market | string | true | none | Currency pair |
| ctime | integer(int64) | false | read-only | Creation time |
| ftime | integer(int64) | false | read-only | Finished time |
| fired_order_id | integer(int64) | false | read-only | ID of the newly created order on condition triggered |
| status | string | false | read-only | Status - open: open - cancelled: being manually cancelled - finish: successfully executed - failed: failed to execute - expired - expired |
| reason | string | false | read-only | Additional remarks on how the order was finished |
| Property | Value |
|---|---|
| rule | >= |
| rule | <= |
| type | limit |
| type | market |
| side | buy |
| side | sell |
| account | normal |
| account | margin |
| account | cross_margin |
| time_in_force | gtc |
| time_in_force | ioc |
{
"name": "string",
"type": "inverse",
"quanto_multiplier": "string",
"leverage_min": "string",
"leverage_max": "string",
"maintenance_rate": "string",
"mark_type": "internal",
"mark_price": "string",
"index_price": "string",
"last_price": "string",
"maker_fee_rate": "string",
"taker_fee_rate": "string",
"order_price_round": "string",
"mark_price_round": "string",
"funding_rate": "string",
"funding_interval": 0,
"funding_next_apply": 0.1,
"risk_limit_base": "string",
"risk_limit_step": "string",
"risk_limit_max": "string",
"order_size_min": 0,
"order_size_max": 0,
"order_price_deviate": "string",
"ref_discount_rate": "string",
"ref_rebate_rate": "string",
"orderbook_id": 0,
"trade_id": 0,
"trade_size": 0,
"position_size": 0,
"config_change_time": 0.1,
"in_delisting": true,
"orders_limit": 0,
"enable_bonus": true,
"enable_credit": true,
"create_time": 0.1,
"funding_cap_ratio": "string"
}
Futures contract details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| name | string | false | none | Futures contract |
| type | string | false | none | Futures contract type |
| quanto_multiplier | string | false | none | Multiplier used in converting from invoicing to settlement currency |
| leverage_min | string | false | none | Minimum leverage |
| leverage_max | string | false | none | Maximum leverage |
| maintenance_rate | string | false | none | Maintenance rate of margin |
| mark_type | string | false | none | Mark price type, internal - based on internal trading, index - based on external index price |
| mark_price | string | false | none | Current mark price |
| index_price | string | false | none | Current index price |
| last_price | string | false | none | Last trading price |
| maker_fee_rate | string | false | none | Maker fee rate, where negative means rebate |
| taker_fee_rate | string | false | none | Taker fee rate |
| order_price_round | string | false | none | Minimum order price increment |
| mark_price_round | string | false | none | Minimum mark price increment |
| funding_rate | string | false | none | Current funding rate |
| funding_interval | integer | false | none | Funding application interval, unit in seconds |
| funding_next_apply | number(double) | false | none | Next funding time |
| risk_limit_base | string | false | none | Risk limit base,deprecated |
| risk_limit_step | string | false | none | Step of adjusting risk limit,deprecated |
| risk_limit_max | string | false | none | Maximum risk limit the contract allowed,deprecated,It is recommended to use /futures/{settle}/risk_limit_tiers to query risk limits. |
| order_size_min | integer(int64) | false | none | Minimum order size the contract allowed |
| order_size_max | integer(int64) | false | none | Maximum order size the contract allowed |
| order_price_deviate | string | false | none | deviation between order price and current index price. If price of an order is denoted as order_price, it must meet the following condition: abs(order_price - mark_price) <= mark_price * order_price_deviate |
| ref_discount_rate | string | false | none | Referral fee rate discount |
| ref_rebate_rate | string | false | none | Referrer commission rate |
| orderbook_id | integer(int64) | false | none | Current orderbook ID |
| trade_id | integer(int64) | false | none | Current trade ID |
| trade_size | integer(int64) | false | none | Historical accumulated trade size |
| position_size | integer(int64) | false | none | Current total long position size |
| config_change_time | number(double) | false | none | Last changed time of configuration |
| in_delisting | boolean | false | none | in_delisting=true And when position_size>0, it means the contract is in the offline transition periodin_delisting=true And when position_size=0, it means the contract is offline |
| orders_limit | integer | false | none | Maximum number of open orders |
| enable_bonus | boolean | false | none | Whether bouns is enabled |
| enable_credit | boolean | false | none | Whether portfolio margin account is enabled |
| create_time | number(double) | false | none | Created time of the contract |
| funding_cap_ratio | string | false | none | The factor for the maximum of the funding rate. Maximum of funding rate = (1/market maximum leverage - maintenance margin rate) * funding_cap_ratio |
| Property | Value |
|---|---|
| type | inverse |
| type | direct |
| mark_type | internal |
| mark_type | index |
{
"user": 0,
"contract": "string",
"size": 0,
"leverage": "string",
"risk_limit": "string",
"leverage_max": "string",
"maintenance_rate": "string",
"value": "string",
"margin": "string",
"entry_price": "string",
"liq_price": "string",
"mark_price": "string",
"initial_margin": "string",
"maintenance_margin": "string",
"unrealised_pnl": "string",
"realised_pnl": "string",
"pnl_pnl": "string",
"pnl_fund": "string",
"pnl_fee": "string",
"history_pnl": "string",
"last_close_pnl": "string",
"realised_point": "string",
"history_point": "string",
"adl_ranking": 0,
"pending_orders": 0,
"close_order": {
"id": 0,
"price": "string",
"is_liq": true
},
"mode": "single",
"cross_leverage_limit": "string",
"update_time": 0,
"open_time": 0
}
Futures position details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| user | integer(int64) | false | read-only | User ID |
| contract | string | false | read-only | Futures contract |
| size | integer(int64) | false | read-only | Position size |
| leverage | string | false | none | Position leverage. 0 means cross margin; positive number means isolated margin |
| risk_limit | string | false | none | Position risk limit |
| leverage_max | string | false | read-only | Maximum leverage under current risk limit |
| maintenance_rate | string | false | read-only | Maintenance rate under current risk limit |
| value | string | false | read-only | Position value calculated in settlement currency |
| margin | string | false | none | Position margin |
| entry_price | string | false | read-only | Entry price |
| liq_price | string | false | read-only | Liquidation price |
| mark_price | string | false | read-only | Current mark price |
| initial_margin | string | false | read-only | The initial margin occupied by the position, applicable to the portfolio margin account |
| maintenance_margin | string | false | read-only | Maintenance margin required for the position, applicable to portfolio margin account |
| unrealised_pnl | string | false | read-only | Unrealized PNL |
| realised_pnl | string | false | read-only | Realized PNL |
| pnl_pnl | string | false | read-only | Realized PNL - Position P/L |
| pnl_fund | string | false | read-only | Realized PNL - Funding Fees |
| pnl_fee | string | false | read-only | Realized PNL - Transaction Fees |
| history_pnl | string | false | read-only | History realized PNL |
| last_close_pnl | string | false | read-only | PNL of last position close |
| realised_point | string | false | read-only | Realized POINT PNL |
| history_point | string | false | read-only | History realized POINT PNL |
| adl_ranking | integer | false | read-only | Ranking of auto deleveraging, a total of 1-5 grades, 1 is the highest, 5 is the lowest, and 6 is the special case when there is no position held or in liquidation |
| pending_orders | integer | false | read-only | Current open orders |
| close_order | object|null | false | read-only | Current close order if any, or null |
| » id | integer(int64) | false | none | Close order ID |
| » price | string | false | none | Close order price |
| » is_liq | boolean | false | none | Is the close order from liquidation |
| mode | string | false | none | Position mode, including: - single: dual mode is not enabled- dual_long: long position in dual mode- dual_short: short position in dual mode |
| cross_leverage_limit | string | false | none | Cross margin leverage(valid only when leverage is 0) |
| update_time | integer(int64) | false | read-only | Last update time |
| open_time | integer(int64) | false | none | First Open Time |
| Property | Value |
|---|---|
| mode | single |
| mode | dual_long |
| mode | dual_short |
{
"id": 0,
"user": 0,
"create_time": 0.1,
"finish_time": 0.1,
"finish_as": "filled",
"status": "open",
"contract": "string",
"size": 0,
"iceberg": 0,
"price": "string",
"close": false,
"is_close": true,
"reduce_only": false,
"is_reduce_only": true,
"is_liq": true,
"tif": "gtc",
"left": 0,
"fill_price": "string",
"text": "string",
"tkfr": "string",
"mkfr": "string",
"refu": 0,
"auto_size": "close_long",
"stp_id": 0,
"stp_act": "co",
"amend_text": "string",
"biz_info": "string"
}
Futures order details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | integer(int64) | false | read-only | Futures order ID |
| user | integer | false | read-only | User ID |
| create_time | number(double) | false | read-only | Creation time of order |
| finish_time | number(double) | false | read-only | Order finished time. Not returned if order is open |
| finish_as | string | false | read-only | How the order was finished. - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC, finish immediately- auto_deleveraged: finished by ADL - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because of position close- position_closed: canceled because the position was closed - reduce_out: only reduce positions by excluding hard-to-fill orders - stp: cancelled because self trade prevention |
| status | string | false | read-only | Order status - open: waiting to be traded- finished: finished |
| contract | string | true | none | Futures contract |
| size | integer(int64) | true | none | Order size. Specify positive number to make a bid, and negative number to ask |
| iceberg | integer(int64) | false | none | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
| price | string | false | none | Order price. 0 for market order with tif set as ioc |
| close | boolean | false | write-only | Set as true to close the position, with size set to 0 |
| is_close | boolean | false | read-only | Is the order to close position |
| reduce_only | boolean | false | write-only | Set as true to be reduce-only order |
| is_reduce_only | boolean | false | read-only | Is the order reduce-only |
| is_liq | boolean | false | read-only | Is the order for liquidation |
| tif | string | false | none | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none |
| left | integer(int64) | false | read-only | Size left to be traded |
| fill_price | string | false | read-only | Fill price of the order |
| text | string | false | none | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance |
| tkfr | string | false | read-only | Taker fee |
| mkfr | string | false | read-only | Maker fee |
| refu | integer | false | read-only | Reference user ID |
| auto_size | string | false | write-only | Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0 |
| stp_id | integer | false | read-only | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
| stp_act | string | false | none | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group, he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy。2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter。3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, Cancel old orders and keep new ones - cb: Cancel both, Both old and new orders will be cancelled |
| amend_text | string | false | read-only | The custom data that the user remarked when amending the order |
| biz_info | string | false | read-only | Additional information |
| Property | Value |
|---|---|
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidated |
| finish_as | ioc |
| finish_as | auto_deleveraged |
| finish_as | reduce_only |
| finish_as | position_closed |
| finish_as | reduce_out |
| finish_as | stp |
| status | open |
| status | finished |
| tif | gtc |
| tif | ioc |
| tif | poc |
| tif | fok |
| auto_size | close_long |
| auto_size | close_short |
| stp_act | co |
| stp_act | cn |
| stp_act | cb |
| stp_act | - |
{
"order_id": 0,
"text": "string",
"size": 0,
"price": "string",
"amend_text": "string"
}
Modify contract order parameters
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| order_id | integer(int64) | false | none | Order id, order_id and text must contain at least one |
| text | string | false | none | User-defined order text, at least one of order_id and text must be passed |
| size | integer(int64) | false | none | The new order size, including the executed order size. - If it is less than or equal to the executed quantity, the order will be cancelled. - The new order direction must be consistent with the original one. - The size of the closing order cannot be modified. - For orders that only reduce positions, if the size is increased, other orders that only reduce positions may be kicked out. - If the price is not modified, reducing the size will not affect the depth of the queue, and increasing the size will place it at the end of the current price. |
| price | string | false | none | New order price. |
| amend_text | string | false | none | Custom info during amending order |
{
"initial": {
"contract": "string",
"size": 0,
"price": "string",
"close": false,
"tif": "gtc",
"text": "string",
"reduce_only": false,
"auto_size": "string",
"is_reduce_only": true,
"is_close": true
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "string",
"rule": 1,
"expiration": 0
},
"id": 0,
"user": 0,
"create_time": 0.1,
"finish_time": 0.1,
"trade_id": 0,
"status": "open",
"finish_as": "cancelled",
"reason": "string",
"order_type": "string",
"me_order_id": 0
}
Futures order details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| initial | object | true | none | none |
| » contract | string | true | none | Futures contract |
| » size | integer(int64) | false | none | Order size. Positive size means to buy, while negative one means to sell. Set to 0 to close the position |
| » price | string | true | none | Order price. Set to 0 to use market price |
| » close | boolean | false | write-only | Set to true if trying to close the position |
| » tif | string | false | none | Time in force. If using market price, only ioc is supported.- gtc: GoodTillCancelled - ioc: ImmediateOrCancelled |
| » text | string | false | none | The source of the order, including: - web: web - api: api - app: app |
| » reduce_only | boolean | false | none | Set to true to create a reduce-only order |
| » auto_size | string | false | write-only | Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0 |
| » is_reduce_only | boolean | false | read-only | Is the order reduce-only |
| » is_close | boolean | false | read-only | Is the order to close position |
| trigger | object | true | none | none |
| » strategy_type | integer(int32) | false | none | How the order will be triggered - 0: by price, which means the order will be triggered if price condition is satisfied- 1: by price gap, which means the order will be triggered if gap of recent two prices of specified price_type are satisfied. Only 0 is supported currently |
| » price_type | integer(int32) | false | none | Price type. 0 - latest deal price, 1 - mark price, 2 - index price |
| » price | string | false | none | Value of price on price triggered, or price gap on price gap triggered |
| » rule | integer(int32) | false | none | Trigger condition type - 1: calculated price based on strategy_type and price_type >= price- 2: calculated price based on strategy_type and price_type <= price |
| » expiration | integer | false | none | How long (in seconds) to wait for the condition to be triggered before cancelling the order. |
| id | integer(int64) | false | read-only | Auto order ID |
| user | integer | false | read-only | User ID |
| create_time | number(double) | false | read-only | Creation time |
| finish_time | number(double) | false | read-only | Finished time |
| trade_id | integer(int64) | false | read-only | ID of the newly created order on condition triggered |
| status | string | false | read-only | Auto order status - open: order is active- finished: order is finished- inactive: order is not active, only for close-long-order or close-short-order- invalid: order is invalid, only for close-long-order or close-short-order |
| finish_as | string | false | read-only | How order is finished |
| reason | string | false | read-only | Additional remarks on how the order was finished |
| order_type | string | false | none | Take-profit/stop-loss types, which include: - close-long-order: order take-profit/stop-loss, close long position- close-short-order: order take-profit/stop-loss, close short position- close-long-position: position take-profit/stop-loss, close long position- close-short-position: position take-profit/stop-loss, close short position- plan-close-long-position: position planned take-profit/stop-loss, close long position- plan-close-short-position: position planned take-profit/stop-loss, close short positionThe order take-profit/stop-loss can not be passed by request. These two types are read only. |
| me_order_id | integer(int64) | false | read-only | Corresponding order ID of order take-profit/stop-loss. |
| Property | Value |
|---|---|
| tif | gtc |
| tif | ioc |
| strategy_type | 0 |
| strategy_type | 1 |
| price_type | 0 |
| price_type | 1 |
| price_type | 2 |
| rule | 1 |
| rule | 2 |
| status | open |
| status | finished |
| status | inactive |
| status | invalid |
| finish_as | cancelled |
| finish_as | succeeded |
| finish_as | failed |
| finish_as | expired |
{
"name": "string",
"underlying": "string",
"cycle": "WEEKLY",
"type": "inverse",
"quanto_multiplier": "string",
"leverage_min": "string",
"leverage_max": "string",
"maintenance_rate": "string",
"mark_type": "internal",
"mark_price": "string",
"index_price": "string",
"last_price": "string",
"maker_fee_rate": "string",
"taker_fee_rate": "string",
"order_price_round": "string",
"mark_price_round": "string",
"basis_rate": "string",
"basis_value": "string",
"basis_impact_value": "string",
"settle_price": "string",
"settle_price_interval": 0,
"settle_price_duration": 0,
"expire_time": 0,
"risk_limit_base": "string",
"risk_limit_step": "string",
"risk_limit_max": "string",
"order_size_min": 0,
"order_size_max": 0,
"order_price_deviate": "string",
"ref_discount_rate": "string",
"ref_rebate_rate": "string",
"orderbook_id": 0,
"trade_id": 0,
"trade_size": 0,
"position_size": 0,
"config_change_time": 0.1,
"in_delisting": true,
"orders_limit": 0
}
Futures contract details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| name | string | false | none | Futures contract |
| underlying | string | false | none | Underlying |
| cycle | string | false | none | Cycle type, e.g. WEEKLY, QUARTERLY |
| type | string | false | none | Futures contract type |
| quanto_multiplier | string | false | none | Multiplier used in converting from invoicing to settlement currency |
| leverage_min | string | false | none | Minimum leverage |
| leverage_max | string | false | none | Maximum leverage |
| maintenance_rate | string | false | none | Maintenance rate of margin |
| mark_type | string | false | none | Mark price type, internal - based on internal trading, index - based on external index price |
| mark_price | string | false | none | Current mark price |
| index_price | string | false | none | Current index price |
| last_price | string | false | none | Last trading price |
| maker_fee_rate | string | false | none | Maker fee rate, where negative means rebate |
| taker_fee_rate | string | false | none | Taker fee rate |
| order_price_round | string | false | none | Minimum order price increment |
| mark_price_round | string | false | none | Minimum mark price increment |
| basis_rate | string | false | none | Fair basis rate |
| basis_value | string | false | none | Fair basis value |
| basis_impact_value | string | false | none | Funding used for calculating impact bid, ask price |
| settle_price | string | false | none | Settle price |
| settle_price_interval | integer | false | none | Settle price update interval |
| settle_price_duration | integer | false | none | Settle price update duration in seconds |
| expire_time | integer(int64) | false | none | Contract expiry timestamp |
| risk_limit_base | string | false | none | Risk limit base |
| risk_limit_step | string | false | none | Step of adjusting risk limit |
| risk_limit_max | string | false | none | Maximum risk limit the contract allowed |
| order_size_min | integer(int64) | false | none | Minimum order size the contract allowed |
| order_size_max | integer(int64) | false | none | Maximum order size the contract allowed |
| order_price_deviate | string | false | none | deviation between order price and current index price. If price of an order is denoted as order_price, it must meet the following condition: abs(order_price - mark_price) <= mark_price * order_price_deviate |
| ref_discount_rate | string | false | none | Referral fee rate discount |
| ref_rebate_rate | string | false | none | Referrer commission rate |
| orderbook_id | integer(int64) | false | none | Current orderbook ID |
| trade_id | integer(int64) | false | none | Current trade ID |
| trade_size | integer(int64) | false | none | Historical accumulated trade size |
| position_size | integer(int64) | false | none | Current total long position size |
| config_change_time | number(double) | false | none | Last changed time of configuration |
| in_delisting | boolean | false | none | Contract is delisting |
| orders_limit | integer | false | none | Maximum number of open orders |
| Property | Value |
|---|---|
| cycle | WEEKLY |
| cycle | BI-WEEKLY |
| cycle | QUARTERLY |
| cycle | BI-QUARTERLY |
| type | inverse |
| type | direct |
| mark_type | internal |
| mark_type | index |