Welcome to Gate API APIv4 provides operations related to spot, margin, and contract trading, including public interfaces for querying market data and authenticated private interfaces for implementing API-based automated trading.
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
REST API BaseURL:
https://api.gateio.ws/api/v4https://api-testnet.gateapi.io/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.com , 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.103.0
code field in GET /spot/account_book query parameter and response to filter account book entries by specific codetext parameter to closeAllPositions operation for order remarks when closing all positionsv4.102.6
SwapCoinStruct with additional fields: pid, subtype, exchange_amount, updateStamp, protocol_type, client_order_id, sourcev4.102.0
is_all_collateral field in GET /unified/accounts endpoint response to indicate if all currencies are used as collateralenabled_collateral field in balances array of unified accounts to show currency collateral statusPOST /unified/collateral_currencies endpoint, Set collateral currencies for cross-currency margin modev4.101.9
GET /futures/{settle}/risk_limit_table endpoint, Query risk limit tier table by table_idenable_tiered_mm field in futures account model for tiered maintenance margin calculationrisk_limit_table and average_maintenance_rate fields in position model for enhanced risk managementdeduction field in futures limit risk tiers for maintenance margin quick calculationFuturesRiskLimitTier and FuturesRiskLimitTierList for risk managementPOST /earn/staking/swap endpoint response structure with improved swap order detailsv4.100.0
GET /earn/staking/coins endpoint, Query on-chain staking coin typesPOST /earn/staking/swap endpoint, On-chain staking coin swapsub_broker_info object field in broker commission and transaction APIsv4.99.0
refresh_time field in GET /spot/accounts endpoint responsePUT /earn/uni/interest_reinvest endpointv4.98.0
/earn/uni/rate endpoint, Currency estimate annualized interest ratedelisting_time、trade_url field in GET /spot/currency_pairs、GET /spot/currency_pairs/{currency_pair}
endpointv4.97.0
GET /unified/batch_borrowable endpoint, Batch query unified account can be borrowed up to a maximumGET /spot/candlesticks endpoint, interval supports 1s granularityGET /earn/uni/chart endpoint, UniLoan currency annualized trend chartPOST /futures/{settle}/positions/cross_mode endpoint, Switch to the full position-by-store modev4.96.0
cross_margin_balance,cross_mmr,cross_imr field in GET /futures/{settle}/accounts responsev4.95.0
code field in GET /spot/account_book query & responseGET /unified/transferables endpoint, Batch query unified account can be transferred up to a maximum ofGET /margin/user/loan_margin_tiers endpoint, Check the user's own leverage lending gradient in the
current marketGET /margin/loan_margin_tiers endpoint, Query the current market leverage lending gradientPOST /margin/leverage/user_market_setting endpoint, Set the user market leverage multipleGET /margin/user/account endpoint, Query the user's leverage account listv4.94.0
GET /unified/currencies endpoint, List of loan currencies supported by unified accountsub_uid field in GET /unified/accounts queryv4.93.0
plan_id field in GET /earn/dual/investment_plan queryfrom、to、page、limit field in GET /earn/dual/orders querytext field in GET /earn/dual/orders responsetext field in POST /earn/dual/orders responseGET /earn/staking/eth2/rate_records endpoint, Query historical rate of ETH2v4.92.0
2025-02-24
name field in GET /spot/currencies querybase_name、quote_name field in GET /spot/currency_pairs responseunified field in GET /spot/price_orders querysub_uid field in GET /unified/accounts queryv4.91.0
2025-02-10
2025-04-01 After that, we will remove the following interface, please migrate to the new interface as soon as possible
v4.90.0
2025-01-20
transaction_type field in GET /wallet/push queryGET /rebate/user/sub_relation endpoint, Query whether the specified user is in the systemorder_size field inGET /futures/{settle}/liq_orders responsetype field in GET /spot/currency_pairs responsev4.88.0
2024-12-24
GET /spot/insurance_history endpoint, Query spot insurance fund historical datacross_balance、iso_balance、im、mm、imr、mmr、margin_balance、available_margin field
in GET /unified/accounts responsePUT /unified/unified_mode endpoint, Added single-currency margin modev4.87.0
GET /unified/history_loan_rate endpoint, Get historical lending ratesv4.86.0
2024-12-02
GET /wallet/order_status endpoint. Transfer status queryupdate_id field in GET /futures/{settle}/positions responsev4.85.0
2024-11-11
x-gate-exptime field in POST /futures/{settle}/orders、POST /spot/batch_order header.Add 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 fieldv4.81.0
2024-09-30
POST /options/countdown_cancel_all endpoint, Countdown to cancel ordermessage field in GET /wallet/push 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
tier 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 /portfolio/loan_records endpoint.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 endpoint.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 endpointv4.45.0
2023-04-21
Lend & Earn. For more information, please refer to
the Margin Migration InstructionsSelf-Trade Prevention feature in the POST /futures/{settle}/batch_orders 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.v4.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 endpointv4.41.0
2023-03-03
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 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
X-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
POST /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
30d 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 to retrieve maximum transferable amount from margin accountfrom and to parameter to specify time range for futures position closes history APIv4.21.4
2021-06-23
GET /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: USDT
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 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 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 |
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's Portfolio Margin
Account is a new feature of Gate'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.
The API response will carry the header: X-Gate-Trace-ID . This header is used 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 | Meaning |
|---|---|
| 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 API
POST /withdrawals
Withdraw
If the recipient's on-chain address is also Gate, no transaction fee will be charged
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » withdraw_order_id | body | string | false | User-defined order number for withdrawal. Default is empty. When not empty, the specified user-defined order number record will be queried |
| » amount | body | string | true | Token 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 |
| » withdraw_id | body | string | false | Withdrawal record ID starts with 'w', such as: w1879219868. When withdraw_id is not empty, only this specific withdrawal record will be queried, and time-based querying will be disabled |
| » asset_class | body | string | false | Withdrawal record currency type, empty by default. Supports users to query withdrawal records in main area and innovation area on demand. |
| » chain | body | string | true | Name of the chain used in withdrawals |
» asset_class: Withdrawal record currency type, empty by default. Supports users to query withdrawal records in main area and innovation area on demand. Valid values: SPOT, PILOT
SPOT: Main area PILOT: Innovation area
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Withdrawal request accepted. Check withdrawal record status for processing result | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | string | Record ID |
| » txid | string | Hash record of the withdrawal |
| » withdraw_order_id | string | User-defined order number for withdrawal. Default is empty. When not empty, the specified user-defined order number record will be queried |
| » timestamp | string | Operation time |
| » amount | string | Token amount |
| » currency | string | Currency name |
| » address | string | Withdrawal address. Required for withdrawals |
| » memo | string | Additional remarks with regards to the withdrawal |
| » withdraw_id | string | Withdrawal record ID starts with 'w', such as: w1879219868. When withdraw_id is not empty, only this specific withdrawal record will be queried, and time-based querying will be disabled |
| » asset_class | string | Withdrawal record currency type, empty by default. Supports users to query withdrawal records in main area and innovation area on demand. Valid values: SPOT, PILOT SPOT: Main area PILOT: Innovation area |
| » status | string | Transaction status - DONE: Completed - CANCEL: Cancelled - REQUEST: Requesting - MANUAL: Pending manual review - BCODE: GateCode operation - EXTPEND: Sent, waiting for confirmation - FAIL: Failed on chain, waiting for confirmation - INVALID: Invalid order - VERIFY: Verifying - PROCES: Processing - PEND: Processing - DMOVE: Pending manual review - REVIEW: Under review |
| » chain | string | Name of the chain used in withdrawals |
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'
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())
Body parameter
{
"withdraw_order_id": "order_123456",
"currency": "USDT",
"address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
"amount": "222.61",
"memo": "",
"chain": "TRX"
}
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"
}
POST /withdrawals/push
UID transfer
Transfers between main spot accounts. Both parties cannot be sub-accounts
| 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request accepted. Check withdrawal record status for 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/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())
Body parameter
{
"receive_uid": 12233,
"currency": "USDT",
"amount": "1.1"
}
Example responses
200 Response
{
"id": 111
}
DELETE /withdrawals/{withdrawal_id}
Cancel withdrawal with specified ID
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| withdrawal_id | path | string | true | none |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 202 | Accepted (opens new window) | Cancellation request accepted. Check record status for cancellation result | Inline |
Status Code 202
| Name | Type | Description |
|---|---|---|
| » id | string | Record ID |
| » txid | string | Hash record of the withdrawal |
| » withdraw_order_id | string | User-defined order number for withdrawal. Default is empty. When not empty, the specified user-defined order number record will be queried |
| » timestamp | string | Operation time |
| » amount | string | Token amount |
| » currency | string | Currency name |
| » address | string | Withdrawal address. Required for withdrawals |
| » memo | string | Additional remarks with regards to the withdrawal |
| » withdraw_id | string | Withdrawal record ID starts with 'w', such as: w1879219868. When withdraw_id is not empty, only this specific withdrawal record will be queried, and time-based querying will be disabled |
| » asset_class | string | Withdrawal record currency type, empty by default. Supports users to query withdrawal records in main area and innovation area on demand. Valid values: SPOT, PILOT SPOT: Main area PILOT: Innovation area |
| » status | string | Transaction status - DONE: Completed - CANCEL: Cancelled - REQUEST: Requesting - MANUAL: Pending manual review - BCODE: GateCode operation - EXTPEND: Sent, waiting for confirmation - FAIL: Failed on chain, waiting for confirmation - INVALID: Invalid order - VERIFY: Verifying - PROCES: Processing - PEND: Processing - DMOVE: Pending manual review - REVIEW: Under review |
| » chain | string | Name of the chain used in withdrawals |
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())
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"
}
Wallet API
GET /wallet/currency_chains
Query chains supported for specified currency
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Currency name |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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 disabled |
| » is_withdraw_disabled | integer(int32) | Is withdrawal disabled. 0 means not disabled |
| » decimal | string | Withdrawal precision |
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())
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
}
]
GET /wallet/deposit_address
Generate currency deposit address
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Currency name |
| 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/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())
Example responses
200 Response
{
"currency": "USDT",
"address": "LPXtk1kWHioP62SzfqwKbYE3Z7Wt2ujYEc",
"multichain_addresses": [
{
"chain": "TRX",
"address": "LPXtk1kWHioP62SzfqwKbYE3Z7Wt2ujYEc",
"payment_id": "",
"payment_name": "",
"obtain_failed": 0
}
]
}
GET /wallet/withdrawals
Get withdrawal records
Record query time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Specify the currency. If not specified, returns all currencies |
| withdraw_id | query | string | false | Withdrawal record ID starts with 'w', such as: w1879219868. When withdraw_id is not empty, only this specific withdrawal record will be queried, and time-based querying will be disabled |
| asset_class | query | string | false | Currency type of withdrawal record, empty by default. Supports querying withdrawal records in main zone and innovation zone on demand. |
| withdraw_order_id | query | string | false | User-defined order number for withdrawal. Default is empty. When not empty, the specified user-defined order number record will be queried |
| from | query | integer(int64) | false | Start time for querying records, defaults to 7 days before current time if not specified |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
asset_class: Currency type of withdrawal record, empty by default. Supports querying withdrawal records in main zone and innovation zone on demand. Value range: SPOT, PILOT
SPOT: Main Zone PILOT: Innovation Zone
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | string | Record ID |
| » txid | string | Hash record of the withdrawal |
| » block_number | string | Block Number |
| » 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 | Token amount |
| » fee | string | fee |
| » currency | string | Currency name |
| » address | string | Withdrawal address |
| » fail_reason | string | Reason for withdrawal failure. Has a value when status = CANCEL, empty for all other statuses |
| » timestamp2 | string | Withdrawal final time, i.e.: withdrawal cancellation time or withdrawal success time When status = CANCEL, corresponds to cancellation time When status = DONE and block_number > 0, it is the withdrawal success time |
| » memo | string | Additional remarks with regards to the withdrawal |
| » status | string | Transaction status - DONE: Completed (block_number > 0 is considered to be truly completed) - CANCEL: Canceled - REQUEST: Requesting - MANUAL: Pending manual review - BCODE: Recharge code operation - EXTPEND: Sent awaiting confirmation - FAIL: Failure on the chain awaiting confirmation - INVALID: Invalid order - VERIFY: Verifying - PROCES: Processing - PEND: Processing - DMOVE: pending manual review - REVIEW: Under review |
| » chain | string | Name of the chain used in withdrawals |
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())
Example responses
200 Response
[
[
{
"id": "w1879219868",
"currency": "USDT",
"address": "THISISTESTADDRESSFORGATEPAY",
"amount": "4.023",
"fee": "0",
"txid": "Internal transaction 260594131",
"chain": "BSC",
"timestamp": "1745220149",
"status": "DONE",
"withdraw_order_id": "202504211521368538928",
"block_number": "1000",
"fail_reason": "",
"type": "appbankgp",
"timestamp2": "1745220149",
"memo": ""
}
]
]
GET /wallet/deposits
Get deposit records
Record query time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Specify the currency. If not specified, returns all currencies |
| from | query | integer(int64) | false | Start time for querying records, defaults to 7 days before current time if not specified |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| limit | query | integer | false | Maximum number of entries returned in the list, limited to 500 transactions |
| offset | query | integer | false | List offset, starting from 0 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| 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 | Token amount |
| » currency | string | Currency name |
| » address | string | Withdrawal address. Required for withdrawals |
| » memo | string | Additional remarks with regards to the withdrawal |
| » status | string | Trading Status - REVIEW: Recharge review (compliance review) - PEND: Processing - DONE: Waiting for funds to be unlocked - INVALID: Invalid data - TRACK: Track the number of confirmations, waiting to add funds to the user (spot) - BLOCKED: Rejected Recharge - DEP_CREDITED: Recharge to account, withdrawal is not unlocked |
| » chain | string | Name of the chain used in withdrawals |
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())
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"
}
]
POST /wallet/transfers
Transfer between trading accounts
Balance transfers between personal trading accounts. Currently supports the following transfer operations:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Transfer currency name. For contract accounts, currency can be set to POINT (points) or supported settlement currencies (e.g., BTC, USDT) |
| » 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 trading pair. Required when transferring to or from margin account |
| » settle | body | string | false | Contract settlement currency. Required when transferring to or from contract account |
| Parameter | Value |
|---|---|
| » from | spot |
| » from | margin |
| » from | futures |
| » from | delivery |
| » from | options |
| » to | spot |
| » to | margin |
| » to | futures |
| » to | delivery |
| » to | options |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Transfer operation successful | 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/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())
Body parameter
{
"currency": "BTC",
"from": "spot",
"to": "margin",
"amount": "1",
"currency_pair": "BTC_USDT",
"settle": ""
}
Example responses
200 Response
{
"tx_id": 59636381286
}
POST /wallet/sub_account_transfers
Transfer between main and sub accounts
Supports transfers to/from sub-account's spot or futures accounts. Note that regardless of which sub-account is operated, only the main account's spot account is used
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » sub_account | body | string | true | Sub account user ID |
| » sub_account_type | body | string | false | Target sub-account trading account: spot - spot account, futures - perpetual contract account, delivery - delivery contract account, options - options account |
| » currency | body | string | true | Transfer currency name |
| » amount | body | string | true | Transfer amount |
| » direction | body | string | true | Transfer direction: to - transfer into sub-account, from - transfer out from sub-account |
| » client_order_id | body | string | false | Customer-defined ID to prevent duplicate transfers. Can be a combination of letters (case-sensitive), numbers, hyphens '-', and underscores '_'. Can be pure letters or pure numbers with length between 1-64 characters |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Transfer operation successful | 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='{"sub_account":"10002","sub_account_type":"spot","currency":"BTC","amount":"1","direction":"to","client_order_id":"da3ce7a088c8b0372b741419c7829033"}'
# 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())
Body parameter
{
"sub_account": "10002",
"sub_account_type": "spot",
"currency": "BTC",
"amount": "1",
"direction": "to",
"client_order_id": "da3ce7a088c8b0372b741419c7829033"
}
Example responses
200 Response
{
"tx_id": 59636381286
}
GET /wallet/sub_account_transfers
Get transfer records between main and sub accounts
Record query 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 | Sub-account user ID, you can query multiple records separated by ,. If not specified, it will return records of all sub-accounts |
| from | query | integer(int64) | false | Start time for querying records, defaults to 7 days before current time if not specified |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » timest | string | Transfer timestamp |
| » uid | string | Main account user ID |
| » sub_account | string | Sub account user ID |
| » sub_account_type | string | Target sub-account trading account: spot - spot account, futures - perpetual contract account, delivery - delivery contract account, options - options account |
| » currency | string | Transfer currency name |
| » amount | string | Transfer amount |
| » direction | string | Transfer direction: to - transfer into sub-account, from - transfer out from sub-account |
| » source | string | Source of the transfer operation |
| » client_order_id | string | Customer-defined ID to prevent duplicate transfers. Can be a combination of letters (case-sensitive), numbers, hyphens '-', and underscores '_'. Can be pure letters or pure numbers with length between 1-64 characters |
| » status | string | Sub-account transfer record status, currently only 'success' |
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())
Example responses
200 Response
[
{
"timest": "1592809000",
"uid": "10001",
"sub_account": "10002",
"sub_account_type": "spot",
"currency": "BTC",
"amount": "1",
"direction": "to",
"source": "web",
"client_order_id": "da3ce7a088c8b0372b741419c7829033",
"status": "success"
}
]
POST /wallet/sub_account_to_sub_account
Transfer between sub-accounts
Supports balance transfers between two sub-accounts under the same main account. You can use either the main account's API Key or the source sub-account's API Key to perform the operation
| 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 account (deprecated, 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 | Source sub-account 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 | Target sub-account trading account: spot - spot account, futures - perpetual contract account, delivery - delivery contract account |
| » amount | body | string | true | Transfer amount |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Transfer operation successful | 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_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())
Body parameter
{
"currency": "usdt",
"sub_account_from": "10001",
"sub_account_from_type": "spot",
"sub_account_to": "10002",
"sub_account_to_type": "spot",
"amount": "1"
}
Example responses
200 Response
{
"tx_id": 59636381286
}
GET /wallet/order_status
Transfer status query
Supports querying transfer status based on user-defined client_order_id or tx_id returned by the transfer interface
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| client_order_id | query | string | false | Customer-defined ID to prevent duplicate transfers. Can be a combination of letters (case-sensitive), numbers, hyphens '-', and underscores '_'. Can be pure letters or pure numbers with length between 1-64 characters |
| tx_id | query | string | false | Transfer operation number, cannot be empty at the same time as client_order_id |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Transfer status retrieved successfully | Inline |
Status Code 200
TransferOrderStatus
| Name | Type | Description |
|---|---|---|
| » tx_id | string | Order ID |
| » status | string | Transfer status: PENDING - Processing, SUCCESS - Transfer successful, FAIL - Transfer failed, PARTIAL_SUCCESS - Partially successful (this status appears when transferring between sub-accounts) |
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/order_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())
Example responses
200 Response
{
"tx_id": "59636381286",
"status": "SUCCESS"
}
GET /wallet/withdraw_status
Query withdrawal status
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency |
| » name | string | Currency name |
| » name_cn | string | Currency Chinese name |
| » deposit | string | Deposit 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/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())
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%"
}
}
]
GET /wallet/sub_account_balances
Query sub-account balance information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sub_uid | query | string | false | Sub-account user ID, you can query multiple records separated by ,. If not specified, it will return records of all sub-accounts |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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_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())
Example responses
200 Response
[
{
"uid": "10003",
"available": {
"BTC": "0.1",
"GT": "2000",
"USDT": "10"
}
}
]
GET /wallet/sub_account_margin_balances
Query sub-account isolated margin account balance information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sub_uid | query | string | false | Sub-account user ID, you can query multiple records separated by ,. If not specified, it will return records of all sub-accounts |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » uid | string | User ID |
| » available | array | Margin account balances |
| »» None | object | Margin account information for a trading pair. base corresponds to base currency account information, quote corresponds to quote currency account information |
| »»» currency_pair | string | Currency pair |
| »»» account_type | string | Account type: risk - risk rate account, mmr - maintenance margin rate account, inactive - market not activated |
| »»» leverage | string | User's current market leverage multiplier |
| »»» locked | boolean | Whether the account is locked |
| »»» risk | string | Current risk rate of the margin account (returned when the account is a risk rate account) |
| »»» mmr | string | Leveraged Account Current Maintenance Margin Rate (returned when the Account is Account) |
| »»» base | object | 货币账户信息 |
| »»»» currency | string | 货币名称 |
| »»»» available | string | 可用于杠杆交易的额度, available = 保证金 + borrowed |
| »»»» locked | string | 冻结资金, 如已经放在杠杆市场里挂单交易的数额 |
| »»»» borrowed | string | 借入资金 |
| »»»» interest | string | 未还利息 |
| »»» quote | object | 货币账户信息 |
| »»»» currency | string | 货币名称 |
| »»»» available | string | 可用于杠杆交易的额度, available = 保证金 + borrowed |
| »»»» locked | string | 冻结资金, 如已经放在杠杆市场里挂单交易的数额 |
| »»»» borrowed | string | 借入资金 |
| »»»» interest | string | 未还利息 |
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())
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"
}
}
]
}
]
GET /wallet/sub_account_futures_balances
Query sub-account perpetual futures account balance information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sub_uid | query | string | false | Sub-account user ID, you can query multiple records separated by ,. If not specified, it will return records of all sub-accounts |
| settle | query | string | false | Query balance of specified settlement currency |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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 | Available balance for transferring or trading (including bonus. Bonus cannot be withdrawn, so transfer amount needs to deduct bonus) |
| »»» point | string | Point card amount |
| »»» currency | string | Settlement 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 occupied by positions, applicable to unified account mode |
| »»» maintenance_margin | string | Maintenance margin occupied by positions, applicable to new classic account margin mode and unified account mode |
| »»» bonus | string | Bonus |
| »»» enable_evolved_classic | boolean | Classic account margin mode, true-new mode, false-old mode |
| »»» cross_order_margin | string | Cross margin order margin, applicable to new classic account margin mode |
| »»» cross_initial_margin | string | Cross margin initial margin, applicable to new classic account margin mode |
| »»» cross_maintenance_margin | string | Cross margin maintenance margin, applicable to new classic account margin mode |
| »»» cross_unrealised_pnl | string | Cross margin unrealized P&L, applicable to new classic account margin mode |
| »»» cross_available | string | Cross margin available balance, applicable to new classic account margin mode |
| »»» cross_margin_balance | string | Cross margin balance, applicable to new classic account margin mode |
| »»» cross_mmr | string | Cross margin maintenance margin rate, applicable to new classic account margin mode |
| »»» cross_imr | string | Cross margin initial margin rate, applicable to new classic account margin mode |
| »»» isolated_position_margin | string | Isolated position margin, applicable to new classic account margin mode |
| »»» enable_new_dual_mode | boolean | Whether to open a new two-way position mode |
| »»» margin_mode | integer | Margin mode, 0-classic margin mode, 1-cross-currency margin mode, 2-combined margin mode |
| »»» enable_tiered_mm | boolean | Whether to enable tiered maintenance margin calculation |
| »»» position_voucher_total | string | Total Position Experience Coupon Amount in Account |
| »»» 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_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())
Example responses
200 Response
[
[
{
"available": {
"btc": {
"available": "0.0009",
"bonus": "0",
"cross_available": "0.0009",
"cross_initial_margin": "0",
"cross_maintenance_margin": "0",
"cross_order_margin": "0",
"cross_unrealised_pnl": "0",
"currency": "BTC",
"enable_credit": false,
"enable_evolved_classic": true,
"enable_new_dual_mode": false,
"history": {
"bonus_dnw": "0",
"bonus_offset": "0",
"cross_settle": "0",
"dnw": "0.0009",
"fee": "0",
"fund": "0",
"pnl": "0",
"point_dnw": "0",
"point_fee": "0",
"point_refr": "0",
"refr": "0"
},
"in_dual_mode": false,
"isolated_position_margin": "0",
"maintenance_margin": "0",
"margin_mode": 0,
"margin_mode_name": "classic",
"order_margin": "0",
"point": "0",
"position_initial_margin": "0",
"position_margin": "0",
"total": "0.0009",
"unrealised_pnl": "0",
"update_id": 11,
"update_time": 1741766400,
"user": 10003
},
"usd": {},
"usdt": {
"available": "500.7",
"bonus": "0",
"cross_available": "500.7",
"cross_initial_margin": "0",
"cross_maintenance_margin": "0",
"cross_order_margin": "0",
"cross_unrealised_pnl": "0",
"currency": "USDT",
"enable_credit": true,
"enable_evolved_classic": true,
"enable_new_dual_mode": true,
"history": {
"bonus_dnw": "0",
"bonus_offset": "0",
"cross_settle": "-1.854650083",
"dnw": "1.89047097",
"fee": "-0.141010882",
"fund": "0",
"pnl": "0.10519",
"point_dnw": "0",
"point_fee": "0",
"point_refr": "0",
"refr": "0"
},
"in_dual_mode": true,
"isolated_position_margin": "0",
"maintenance_margin": "0",
"margin_mode": 1,
"margin_mode_name": "multi_currency",
"order_margin": "0",
"point": "0",
"position_initial_margin": "0",
"position_margin": "0",
"total": "0.000000005",
"unrealised_pnl": "0",
"update_id": 37,
"update_time": 1741766400,
"user": 10003
}
},
"uid": "10003"
}
]
]
GET /wallet/sub_account_cross_margin_balances
Query sub-account cross margin account balance information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sub_uid | query | string | false | Sub-account user ID, you can query multiple records separated by ,. If not specified, it will return records of all sub-accounts |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » uid | string | User ID |
| » available | object | none |
| »» user_id | integer(int64) | 全仓帐户用户ID, 如果 0 代表这个子帐号尚未开通全仓帐户 |
| »» locked | boolean | 账户是否被锁定 |
| »» balances | object | none |
| »»» CrossMarginBalance | object | none |
| »»»» available | string | 可用额度 |
| »»»» freeze | string | 被锁定的额度 |
| »»»» borrowed | string | 借入额度 |
| »»»» interest | string | 未还利息 |
| »»» total | string | 折算成 USDT 的账户总资产, 即所有币种(不包括点卡)的 (available+freeze)*price*discount 之和 |
| »»» borrowed | string | 折算成 USDT 的账户总借入数量, 即所有币种(不包括点卡)的 borrowed*price*discount 之和 |
| »»» borrowed_net | string | 折算成 USDT 的账户总借入数量 * 放大系数 |
| »»» net | string | 折算成 USDT 的净资产 |
| »»» leverage | string | Leverage multiplier |
| »»» interest | string | 折算成 USDT 的账户未接利息的总和, 即所有币种(不包括点卡)的 interest*price*discount 之和 |
| »»» risk | string | 风险率, 风险率小于 110% 会被爆仓, 计算方式 total / (borrowed+interest) |
| »»» total_initial_margin | string | 总初始保证金 |
| »»» total_margin_balance | string | 总保证金余额 |
| »»» total_maintenance_margin | string | 总维持保证金 |
| »»» total_initial_margin_rate | string | 总初始保证金率 |
| »»» total_maintenance_margin_rate | string | 总维持保证金率 |
| »»» total_available_margin | string | 可用的保证金额度 |
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())
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"
}
}
}
}
]
GET /wallet/saved_address
Query withdrawal address whitelist
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Currency |
| chain | query | string | false | Chain name |
| limit | query | string | false | Maximum number returned, up to 100 |
| page | query | integer | false | Page number |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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/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())
Example responses
200 Response
[
{
"currency": "usdt",
"chain": "TRX",
"address": "TWYirLzw2RARB2jfeFcfRPmeuU3rC7rakT",
"name": "gate",
"tag": "",
"verified": "1"
}
]
GET /wallet/fee
Query personal trading fees
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Specify currency pair to get more accurate fee settings. |
| settle | query | string | false | Specify the settlement currency of the contract to get more accurate fee settings. |
currency_pair: Specify currency pair to get more accurate fee settings.
This field is optional. Usually fee settings are the same for all currency pairs.
settle: Specify the settlement currency of the contract to get more accurate fee settings.
This field is optional. Generally, the fee settings for all settlement currencies are the same.
| Parameter | Value |
|---|---|
| settle | BTC |
| settle | USDT |
| settle | USD |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | 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 | Whether GT deduction discount 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 with GT deduction. Returns 0 if GT deduction is disabled |
| » loan_fee | string | Loan fee rate of margin lending |
| » point_type | string | Point card type: 0 - Original version, 1 - New version since 202009 |
| » futures_taker_fee | string | Perpetual contract taker fee rate |
| » futures_maker_fee | string | Perpetual contract maker fee rate |
| » delivery_taker_fee | string | Delivery contract taker fee rate |
| » delivery_maker_fee | string | Delivery contract maker fee rate |
| » 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/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())
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
}
GET /wallet/total_balance
Query personal account totals
This query endpoint returns the total estimated value of all currencies in each account converted to the input currency. Exchange rates and related account balance information may be cached for up to 1 minute. It is not recommended to use this interface data for real-time calculations.
For real-time calculations, query the corresponding balance interface based on account type, such as:
GET /spot/accounts to query spot accountGET /margin/accounts to query margin accountGET /futures/{settle}/accounts to query futures account| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Target currency type for statistical conversion. Accepts BTC, CNY, USD, and USDT. USDT is the default value |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request is valid and successfully returned | Inline |
Status Code 200
User's total balance information
| Name | Type | Description |
|---|---|---|
| » total | object | 换算成目标币种的账户总额 |
| »» amount | string | 账户总额数字 |
| »» currency | string | 币种 |
| »» unrealised_pnl | string | 未实现盈亏总和,这个 field只会在futures,options,delivery,total 账户中出现 |
| »» borrowed | string | 杠杆借贷总和,这个 field只会在margin,cross_margin账户中出现 |
| » 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: perpetual contract account - delivery: delivery contract account - warrant: warrant account - cbbc: CBBC account |
| »» additionalProperties | object | 换算成目标币种的账户总额 |
| »»» amount | string | 账户总额数字 |
| »»» currency | string | 币种 |
| »»» unrealised_pnl | string | 未实现盈亏总和,这个 field只会在futures,options,delivery,total 账户中出现 |
| »»» borrowed | string | 杠杆借贷总和,这个 field只会在margin,cross_margin账户中出现 |
| 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/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())
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"
}
}
GET /wallet/small_balance
Get list of convertible small balance currencies
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Small Balance Conversion |
| »» 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 = ''
# for `gen_sign` implementation, refer 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())
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"
}
]
]
POST /wallet/small_balance
Convert small balance currency
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | array | false | Currency to be converted |
| » is_all | body | boolean | false | Whether to convert 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'
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())
Body parameter
{
"currency": [
"FLOKI",
"MBLK"
],
"is_all": true
}
GET /wallet/small_balance_history
Get convertible small balance currency history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Currency to convert |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum number of items returned. Default: 100, minimum: 1, maximum: 100 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Small Balance Conversion |
| »» id | string | Order ID |
| »» currency | string | Currency |
| »» amount | string | Swap 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/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())
Example responses
200 Response
[
[
{
"id": "28583810",
"create_time": 1706670777,
"currency": "FLOKI",
"amount": "182.29400000",
"gt_amount": "0.001079"
}
]
]
GET /wallet/push
Get UID transfer history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | query | integer(int32) | false | Order ID |
| from | query | integer(int32) | false | Start time for querying records. If not specified, defaults to 7 days before the current time. Unix timestamp in seconds |
| to | query | integer(int32) | false | End time for querying records. If not specified, defaults to the current time. Unix timestamp in seconds |
| limit | query | integer(int32) | false | Maximum number of items returned in the list, default value is 100 |
| offset | query | integer(int32) | false | List offset, starting from 0 |
| transaction_type | query | string | false | Order type returned in the list: withdraw, deposit. Default is withdraw. |
| 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) | Created time |
| » status | string | Withdrawal status: - CREATING: Creating - PENDING: Waiting for recipient (Please contact the recipient to accept the transfer on Gate official website) - CANCELLING: Cancelling - CANCELLED: Cancelled - REFUSING: Refusing - REFUSED: Refused - RECEIVING: Receiving - RECEIVED: Success |
| » message | string | PENDING reason tips |
| » transaction_type | string | Order Type |
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())
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",
"transaction_type": "withdraw"
}
]
Sub-account management
POST /sub_accounts
Create a new sub-account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » remark | body | string | false | Remark |
| » login_name | body | string | true | Sub Account登陆名: 仅支持字母、数字、下划线, 不可包含其他非法字符. |
| » 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) |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Created successfully | Inline |
Status Code 201
| Name | Type | Description |
|---|---|---|
| » remark | string | Remark |
| » login_name | string | Sub Account登陆名: 仅支持字母、数字、下划线, 不可包含其他非法字符. |
| » 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) | Sub-account status: 1-normal, 2-locked |
| » type | integer(int32) | Sub-account type: 1-Regular sub-account, 3-Cross margin sub-account |
| » user_id | integer(int64) | Sub-account user ID |
| » 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 = ''
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())
Body parameter
{
"remark": "remark",
"login_name": "sub_account_for_trades"
}
Example responses
201 Response
{
"remark": "remark",
"login_name": "sub_account_for_trades",
"user_id": 10001,
"state": 1,
"create_time": 168888888
}
GET /sub_accounts
List sub-accounts
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| type | query | string | false | Enter 0 to list all types of sub-accounts (currently supporting cross-margin sub-accounts and regular sub-accounts). |
type: Enter 0 to list all types of sub-accounts (currently supporting cross-margin sub-accounts and regular sub-accounts).
Enter 1 to query regular sub-accounts only. If no parameter is passed, only regular sub-accounts will be queried by default.
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » remark | string | Remark |
| » login_name | string | Sub Account登陆名: 仅支持字母、数字、下划线, 不可包含其他非法字符. |
| » 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) | Sub-account status: 1-normal, 2-locked |
| » type | integer(int32) | Sub-account type: 1-Regular sub-account, 3-Cross margin sub-account |
| » user_id | integer(int64) | Sub-account user ID |
| » 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())
Example responses
200 Response
[
{
"remark": "remark",
"login_name": "sub_account_for_trades",
"user_id": 10001,
"state": 1,
"create_time": 168888888
}
]
GET /sub_accounts/{user_id}
Get sub-account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer(int64) | true | Sub-account user ID |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » remark | string | Remark |
| » login_name | string | Sub Account登陆名: 仅支持字母、数字、下划线, 不可包含其他非法字符. |
| » 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) | Sub-account status: 1-normal, 2-locked |
| » type | integer(int32) | Sub-account type: 1-Regular sub-account, 3-Cross margin sub-account |
| » user_id | integer(int64) | Sub-account user ID |
| » 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())
Example responses
200 Response
{
"remark": "remark",
"login_name": "sub_account_for_trades",
"user_id": 10001,
"state": 1,
"create_time": 168888888
}
POST /sub_accounts/{user_id}/keys
Create new sub-account API key pair
| 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 function name (no value will be cleared) |
| »» read_only | body | boolean | false | Read Only |
| » ip_whitelist | body | array | false | IP whitelist (list will be cleared if no value is passed) |
»» name: Permission function name (no value will be cleared)
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Created successfully | 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'
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())
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"
]
}
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
}
GET /sub_accounts/{user_id}/keys
List all API key pairs of the sub-account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer | true | Sub-account user ID |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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'
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())
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
}
]
PUT /sub_accounts/{user_id}/keys/{key}
Update sub-account API key pair
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer | true | Sub-account user ID |
| key | path | string | true | Sub-account API key |
| 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 function name (no value will be cleared) |
| »» read_only | body | boolean | false | Read Only |
| » ip_whitelist | body | array | false | IP whitelist (list will be cleared if no value is passed) |
»» name: Permission function name (no value will be cleared)
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Updated 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 = ''
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())
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"
]
}
DELETE /sub_accounts/{user_id}/keys/{key}
Delete sub-account API key pair
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer | true | Sub-account user ID |
| key | path | string | true | Sub-account API key |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Deleted 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('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
GET /sub_accounts/{user_id}/keys/{key}
Get specific API key pair of the sub-account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer | true | Sub-account user ID |
| key | path | string | true | Sub-account API key |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully 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 = ''
# for `gen_sign` implementation, refer 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())
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
}
POST /sub_accounts/{user_id}/lock
Lock sub-account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer(int64) | true | Sub-account user ID |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Locked 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/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())
POST /sub_accounts/{user_id}/unlock
Unlock sub-account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer(int64) | true | Sub-account user ID |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Unlocked 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())
GET /sub_accounts/unified_mode
Get sub-account mode
Unified account mode:
classic: Classic account modemulti_currency: Multi-currency margin modeportfolio: Portfolio margin mode| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » user_id | integer(int64) | User ID |
| » is_unified | boolean | Whether it is 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
Code samples
# coding: utf-8
import 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())
Example responses
200 Response
[
{
"user_id": 110285555,
"is_unified": true,
"mode": "multi_currency"
}
]
Unified account
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.
For specific formulas, please refer to Margin Formula
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
| sub_uid | query | string | false | Sub account user ID |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » user_id | integer(int64) | User ID |
| » refresh_time | integer(int64) | Last refresh time |
| » locked | boolean | Whether the account is locked, valid in cross-currency margin/combined margin mode, false in other modes such as single-currency margin mode |
| » balances | object | none |
| »» UnifiedBalance | object | none |
| »»» available | string | Available balance, valid in single currency margin/cross-currency margin/combined margin mode, calculation varies by mode |
| »»» freeze | string | Locked balance, valid in single currency margin/cross-currency margin/combined margin mode |
| »»» borrowed | string | Borrowed amount, valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
| »»» negative_liab | string | Negative balance borrowing, valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
| »»» futures_pos_liab | string | Contract opening position borrowing currency (abandoned, to be offline field) |
| »»» equity | string | Equity, valid in single currency margin/cross currency margin/combined margin mode |
| »»» total_freeze | string | Total frozen (deprecated, to be removed) |
| »»» total_liab | string | Total borrowed amount, valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
| »»» spot_in_use | string | The amount of spot hedging is valid in the combined margin mode, and is 0 in other margin modes such as single currency and cross-currency margin modes |
| »»» funding | string | Uniloan financial management amount, effective when turned on as a unified account margin switch |
| »»» funding_version | string | Funding version |
| »»» cross_balance | string | Full margin balance is valid in single currency margin mode, and is 0 in other modes such as cross currency margin/combined margin mode |
| »»» iso_balance | string | Isolated margin balance is valid in single-currency margin mode and is 0 in other modes such as cross-currency margin/combined margin mode |
| »»» im | string | Full-position initial margin is valid in single-currency margin mode and is 0 in other modes such as cross-currency margin/combined margin mode |
| »»» mm | string | Cross margin maintenance margin, valid in single-currency margin mode, 0 in other modes such as cross-currency margin/combined margin mode |
| »»» imr | string | Full-position initial margin rate is valid in single-currency margin mode and is 0 in other modes such as cross-currency margin/combined margin mode |
| »»» mmr | string | Full-position maintenance margin rate is valid in single-currency margin mode and is 0 in other modes such as cross-currency margin/combined margin mode |
| »»» margin_balance | string | Full margin balance is valid in single currency margin mode and is 0 in other modes such as cross currency margin/combined margin mode |
| »»» available_margin | string | Cross margin available balance, valid in single currency margin mode, 0 in other modes such as cross-currency margin/combined margin mode |
| »»» enabled_collateral | boolean | Currency enabled as margin: true - Enabled, false - Disabled |
| »» total | string | Total account assets converted to USD, i.e. the sum of (available + freeze) * price in all currencies (deprecated, to be removed, replaced by unified_account_total) |
| »» borrowed | string | Total borrowed amount converted to USD, i.e. the sum of borrowed * price of all currencies (excluding point cards), valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
| »» total_initial_margin | string | Total initial margin, valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
| »» total_margin_balance | string | Total margin balance, valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
| »» total_maintenance_margin | string | Total maintenance margin is valid in cross-currency margin/combined margin mode, and is 0 in other modes such as single-currency margin mode |
| »» total_initial_margin_rate | string | Total initial margin rate, valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
| »» total_maintenance_margin_rate | string | Total maintenance margin rate, valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
| »» total_available_margin | string | Available margin amount, valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
| »» unified_account_total | string | Total unified account assets, valid in single currency margin/cross-currency margin/combined margin mode |
| »» unified_account_total_liab | string | Total unified account borrowed amount, valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
| »» unified_account_total_equity | string | Total unified account equity, valid in single currency margin/cross-currency margin/combined margin mode |
| »» leverage | string | Actual leverage ratio, valid in cross-currency margin/combined margin mode |
| »» spot_order_loss | string | Total pending order loss, in USDT, valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
| »» spot_hedge | boolean | Spot hedging status: true - enabled, false - disabled |
| »» use_funding | boolean | Whether to use Earn funds as margin |
| »» is_all_collateral | boolean | Whether all currencies are used as margin: true - all currencies as margin, false - no |
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/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())
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
}
GET /unified/borrowable
Query maximum borrowable amount for unified account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Query by specified currency name |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | 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/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())
Example responses
200 Response
{
"currency": "ETH",
"amount": "10000"
}
GET /unified/transferable
Query maximum transferable amount for unified account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Query by specified currency name |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
UnifiedTransferable
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency detail |
| » amount | string | Maximum 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 = '/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())
Example responses
200 Response
{
"currency": "ETH",
"amount": "10000"
}
GET /unified/transferables
Batch query maximum transferable amount for unified accounts. Each currency shows the maximum value. After user withdrawal, the transferable amount for all currencies will change
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currencies | query | string | true | Specify the currency name to query in batches, and support up to 100 pass parameters at a time |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » TransferablesResult | object | Batch query unified account maximum transferable results |
| »» currency | string | Currency detail |
| »» amount | string | Maximum 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 = '/unified/transferables'
query_param = 'currencies=BTC,ETH'
# for `gen_sign` implementation, refer 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())
Example responses
200 Response
[
{
"currency": "BTC",
"amount": "123456"
}
]
GET /unified/batch_borrowable
Batch query unified account maximum borrowable amount
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currencies | query | array[string] | true | Specify currency names for querying in an array, separated by commas, maximum 10 currencies |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » UnifiedBorrowable | object | Batch query unified account maximum borrowable results |
| »» currency | string | Currency detail |
| »» amount | string | Maximum 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/batch_borrowable'
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())
Example responses
200 Response
[
{
"currency": "BTC",
"amount": "123456"
}
]
POST /unified/loans
Borrow or repay
When borrowing, ensure 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 user.
Loan interest will be automatically deducted from the account at regular intervals. Users are responsible for managing repayment of borrowed amounts.
For repayment, use repaid_all=true to repay all available amounts
| 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 | Borrow or repayment amount |
| » repaid_all | body | boolean | false | Full repayment, only used for repayment operations. When set to true, overrides amount and directly repays the full amount |
| » text | body | string | false | User defined custom ID |
| Parameter | Value |
|---|---|
| » type | borrow |
| » type | repay |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Operation successful | Inline |
Status Code 200
Unified account borrowing and repayment response result
| Name | Type | Description |
|---|---|---|
| » tran_id | integer(int64) | Transaction 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 = '/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())
Body parameter
{
"currency": "BTC",
"amount": "0.1",
"type": "borrow",
"repaid_all": false,
"text": "t-test"
}
Example responses
200 Response
{
"tran_id": 9527
}
GET /unified/loans
Query loans
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum number of items returned. Default: 100, minimum: 1, maximum: 100 |
| type | query | string | false | Loan type: platform borrowing - platform, margin borrowing - margin |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Borrowing] |
| » None | object | Borrowing |
| »» currency | string | Currency |
| »» currency_pair | string | Currency pair |
| »» amount | string | Amount to Repay |
| »» type | string | Loan type: platform borrowing - platform, margin borrowing - margin |
| »» create_time | integer(int64) | Created time |
| »» update_time | integer(int64) | Last 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 = '/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())
Example responses
200 Response
[
{
"currency": "USDT",
"currency_pari": "GT_USDT",
"amount": "1",
"type": "margin",
"change_time": 1673247054000,
"create_time": 1673247054000
}
]
GET /unified/loan_records
Query loan records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| type | query | string | false | Loan record type: borrow - borrowing, repay - repayment |
| currency | query | string | false | Query by specified currency name |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum number of items returned. Default: 100, minimum: 1, maximum: 100 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Borrowing 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 order cancellation, different_currencies_repayment - Cross-currency repayment |
| »» borrow_type | string | Borrowing type, returned when querying loan records: manual_borrow - Manual borrowing, auto_borrow - Automatic borrowing |
| »» currency_pair | string | Currency pair |
| »» currency | string | Currency |
| »» amount | string | Borrow or repayment amount |
| »» 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/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())
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"
}
]
GET /unified/interest_records
Query interest deduction records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum number of items returned. Default: 100, minimum: 1, maximum: 100 |
| from | query | integer(int64) | false | Start timestamp for the query |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| type | query | string | false | Loan type: platform borrowing - platform, margin borrowing - margin. Defaults to margin if not specified |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Interest Deduction Record] |
| » None | object | Interest Deduction 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 borrowing, margin - Margin borrowing |
| »» 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())
Example responses
200 Response
[
{
"status": 1,
"currency_pair": "BTC_USDT",
"currency": "USDT",
"actual_rate": "0.00000236",
"interest": "0.00006136",
"type": "platform",
"create_time": 1673247054000
}
]
GET /unified/risk_units
Get user risk unit details
Get user risk unit details, only valid in portfolio margin mode
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » user_id | integer(int64) | User ID |
| » spot_hedge | boolean | Spot hedging status: true - enabled, false - disabled |
| » risk_units | array | Risk unit |
| »» RiskUnits | object | none |
| »»» symbol | string | Risk unit flag |
| »»» spot_in_use | string | Spot hedging occupied amount |
| »»» 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/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())
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"
}
]
}
PUT /unified/unified_mode
Set unified account mode
Each account mode switch only requires passing the corresponding account mode parameter, and also supports turning on or off the configuration switches under the corresponding account mode during the switch.
PUT /unified/unified_mode
{
"mode": "classic"
}
- When enabling the portfolio margin mode, mode=portfolio
PUT /unified/unified_mode { "mode": "portfolio", "settings": { "spot_hedge": true } }
- When enabling the single-currency margin mode, mode=single_currency
PUT /unified/unified_mode { "mode": "single_currency" }
<Example>
> Body parameter
```json
{
"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 futures switch. In cross-currency margin mode, can only be enabled and cannot be disabled |
| »» spot_hedge | body | boolean | false | Spot hedging switch |
| »» use_funding | body | boolean | false | Earn switch, when mode is cross-currency margin mode, whether to use Earn funds as margin |
| »» options | body | boolean | false | Options switch. In cross-currency margin mode, can only be enabled and cannot be disabled |
» mode: Unified account mode:
classic: Classic account modemulti_currency: Cross-currency margin modeportfolio: Portfolio margin modesingle_currency: Single-currency margin mode| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Set 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/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())
GET /unified/unified_mode
Query mode of the unified account
Unified account mode:
classic: Classic account modemulti_currency: Cross-currency margin modeportfolio: Portfolio margin modesingle_currency: Single-currency margin mode| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » mode | string | Unified account mode: - classic: Classic account mode- multi_currency: Cross-currency margin mode- portfolio: Portfolio margin mode- single_currency: Single-currency margin mode |
| » settings | object | none |
| »» usdt_futures | boolean | USDT futures switch. In cross-currency margin mode, can only be enabled and cannot be disabled |
| »» spot_hedge | boolean | Spot hedging switch |
| »» use_funding | boolean | Earn switch, when mode is cross-currency margin mode, whether to use Earn funds as margin |
| »» options | boolean | Options switch. In cross-currency margin mode, can only be enabled and cannot be disabled |
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())
Example responses
200 Response
{
"mode": "portfolio",
"settings": {
"spot_hedge": true,
"usdt_futures": true,
"options": true
}
}
GET /unified/estimate_rate
Query unified account estimated interest rate
Interest rates fluctuate hourly based on lending depth, so exact rates cannot be provided. 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 currency names for querying in an array, separated by commas, maximum 10 currencies |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
Estimate current hourly lending rates, returned 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 = '/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())
Example responses
200 Response
{
"BTC": "0.000002",
"GT": "0.000001",
"ETH": ""
}
GET /unified/currency_discount_tiers
Query unified account tiered discount
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Unified account tiered discount |
| »» currency | string | Currency name |
| »» discount_tiers | array | Tiered discount |
| »»» tier | string | 档位 |
| »»» discount | string | 保证金折扣系数 |
| »»» lower_limit | string | 下限 |
| »»» upper_limit | string | 上限, +表示正无穷 |
| »»» leverage | string | Leverage multiplier |
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())
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": "+"
}
]
}
]
]
GET /unified/loan_margin_tiers
Query unified account tiered loan margin
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Unified account borrowing margin tiers |
| »» currency | string | Currency name |
| »» margin_tiers | array | Tiered margin |
| »»» 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/loan_margin_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "USDT",
"margin_tiers": [
{
"tier": "1",
"margin_rate": "0.02",
"lower_limit": "200000",
"upper_limit": "400000",
"leverage": "3"
}
]
}
]
POST /unified/portfolio_calculator
Portfolio margin calculator
Portfolio Margin Calculator
When inputting simulated position portfolios, 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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » spot_balances | body | array | false | Spot |
| »» None | body | object | false | 现货 |
| »»» currency | body | string | true | 币种名称 |
| »»» equity | body | string | true | 币种权益, 权益 = 余额 - 已借, 表示您在现货部位的净delta敞口, 可以为负数. 目前仅支持BTC、ETH三个币种 |
| »» spot_orders | body | array | false | Spot orders |
| »»» None | body | object | false | 现货订单 |
| »»»» currency_pairs | body | string | true | 市场 |
| »»»» order_price | body | string | true | 价格 |
| »»»» count | body | string | false | 现货交易对初始挂单数量, 不参与实际计算. 目前仅支持BTC、ETH三个币种 |
| »»»» left | body | string | true | 未成交数量, 参与实际计算 |
| »»»» type | body | string | true | 订单Type, sell - 卖出单, buy - 买入单 |
| »»» futures_positions | body | array | false | Futures positions |
| »»»» None | body | object | false | 合约仓位 |
| »»»»» contract | body | string | true | 合约名, 目前仅支持BTC、ETH的USDT永续合约 |
| »»»»» size | body | string | true | 仓位大小, 单位是张数 |
| »»»» futures_orders | body | array | false | Futures order |
| »»»»» None | body | object | false | 合约订单 |
| »»»»»» contract | body | string | true | 合约名, 目前仅支持BTC、ETH的USDT永续合约 |
| »»»»»» size | body | string | true | 合约张数, 为初始挂单数量, 不参与实际结算 |
| »»»»»» left | body | string | true | 未成交张数, 参与实际计算 |
| »»»»» options_positions | body | array | false | Options positions |
| »»»»»» None | body | object | false | 期权仓位 |
| »»»»»»» options_name | body | string | true | 期权名称, 目前只支持BTC、ETH的USDT期权 |
| »»»»»»» size | body | string | true | 仓位大小, 单位是张数 |
| »»»»»» options_orders | body | array | false | Option orders |
| »»»»»»» None | body | object | false | 期权订单 |
| »»»»»»»» options_name | body | string | true | 期权名称, 目前只支持BTC、ETH的USDT期权 |
| »»»»»»»» size | body | string | true | 初始挂单张数, 不参与实际计算 |
| »»»»»»»» left | body | string | true | 未成交张数, 参与实际计算 |
| »»»»»»» spot_hedge | body | boolean | false | Whether to enable spot hedging |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
Portfolio margin calculator output
| Name | Type | Description |
|---|---|---|
| » maintain_margin_total | string | Total maintenance margin, including only portfolio margin calculation results for positions in risk units, excluding borrowing 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) | Calculation time |
| » risk_unit | array | Risk unit |
| »» None | object | 风险单元 |
| »»» symbol | string | 风险单元名称 |
| »»» spot_in_use | string | 现货对冲使用量 |
| »»» maintain_margin | string | 维持保证金 |
| »»» initial_margin | string | 起始保证金 |
| »»» margin_result | array | 保证金结果 |
| »»»» None | object | 保证金结果 |
| »»»»» type | string | 仓位组合Typeoriginal_position - 原始仓位long_delta_original_position - 正向delta+原始仓位short_delta_original_position - 负向delta+原始仓位 |
| »»»»» profit_loss_ranges | array | mr1的33个压力场景测试结果 |
| »»»»»» None | object | 盈亏范围 |
| »»»»»»» price_percentage | string | 价格变动百分比 |
| »»»»»»» implied_volatility_percentage | string | 隐含波动率变动百分比 |
| »»»»»»» profit_loss | string | 盈亏 |
| »»»»»» max_loss | object | 盈亏范围 |
| »»»»»»» price_percentage | string | 价格变动百分比 |
| »»»»»»» implied_volatility_percentage | string | 隐含波动率变动百分比 |
| »»»»»»» profit_loss | string | 盈亏 |
| »»»»»» mr1 | string | 压力测试 |
| »»»»»» mr2 | string | 基差跨期风险 |
| »»»»»» mr3 | string | 波动率跨期风险 |
| »»»»»» mr4 | string | 期权空头风险 |
| »»»»» delta | string | 风险单元的 总 delta |
| »»»»» gamma | string | 风险单元的 总 gamma |
| »»»»» theta | string | 风险单元的 总 theta |
| »»»»» vega | string | 风险单元的 总 vega |
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())
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
}
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"
}
]
}
GET /unified/leverage/user_currency_config
Maximum and minimum currency leverage that can be set
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Currency |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | 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 | Maximum borrowable amount at current leverage |
| » except_leverage_borrowable | string | Maximum borrowable from margin and maximum borrowable from Earn, 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_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())
Example responses
200 Response
{
"current_leverage": "2",
"min_leverage": "0",
"max_leverage": "0",
"debit": "0",
"available_margin": "0",
"borrowable": "0",
"except_leverage_borrowable": "0"
}
GET /unified/leverage/user_currency_setting
Get user currency leverage
Get user currency leverage. If currency is not specified, query all currencies
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Currency |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Leverage multiplier for borrowing currency] |
| » None | object | Leverage multiplier for borrowing currency |
| »» currency | string | Currency name |
| »» leverage | string | Multiplier |
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())
Example responses
200 Response
[
{
"currency": "BTC",
"leverage": "3"
}
]
POST /unified/leverage/user_currency_setting
Set loan currency leverage
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Currency name |
| » leverage | body | string | true | Multiplier |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Set 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/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())
Body parameter
{
"currency": "BTC",
"leverage": "3"
}
GET /unified/currencies
List of loan currencies supported by unified account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Currency |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » name | string | Currency name |
| » prec | string | Currency precision |
| » min_borrow_amount | string | Minimum borrowable limit, in currency units |
| » user_max_borrow_amount | string | User's maximum borrowable limit, in USDT |
| » total_max_borrow_amount | string | Platform's maximum borrowable limit, in USDT |
| » loan_status | string | Lending status - disable : Lending prohibited- enable : Lending supported |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"name": "BTC",
"prec": "0.000001",
"min_borrow_amount": "0.01",
"user_max_borrow_amount": "1000000",
"total_max_borrow_amount": "1000000",
"loan_status": "enable"
}
]
GET /unified/history_loan_rate
Get historical lending rates
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| tier | query | string | false | VIP level for the floating rate to be queried |
| currency | query | string | true | Currency |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum number of items returned. Default: 100, minimum: 1, maximum: 100 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency name |
| » tier | string | VIP level for the floating rate to be retrieved |
| » tier_up_rate | string | Floating rate corresponding to VIP level |
| » rates | array | Historical interest rate information, one data point per hour, array size determined by page and limit parameters from the API request, sorted by time from recent to distant |
| »» time | integer(int64) | Hourly timestamp corresponding to this interest rate, in milliseconds |
| »» rate | string | Historical interest rate for this hour |
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/history_loan_rate'
query_param = 'currency=USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"currency": "USDT",
"tier": "1",
"tier_up_rate": "1.18",
"rates": [
{
"time": 1729047616000,
"rate": "0.00010287"
}
]
}
POST /unified/collateral_currencies
Set collateral currency
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » collateral_type | body | integer | false | User-set collateral mode: 0(all)-All currencies as collateral, 1(custom)-Custom currencies as collateral. When collateral_type is 0(all), enable_list and disable_list parameters are invalid |
| » enable_list | body | array | false | Currency list, where collateral_type=1(custom) indicates the addition logic |
| » disable_list | body | array | false | Disable list, indicating the disable logic |
| Parameter | Value |
|---|---|
| » collateral_type | 0 |
| » collateral_type | 1 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Updated successfully | Inline |
Status Code 200
Unified account collateral mode settings response
| Name | Type | Description |
|---|---|---|
| » is_success | boolean | Whether the setting was successful |
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/collateral_currencies'
query_param = ''
body='{"collateral_type":1,"enable_list":["BTC","ETH"],"disable_list":["SOL","GT"]}'
# 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())
Body parameter
{
"collateral_type": 1,
"enable_list": [
"BTC",
"ETH"
],
"disable_list": [
"SOL",
"GT"
]
}
Example responses
200 Response
{
"is_success": true
}
Isolated Margin
GET /margin/accounts
Margin account list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Currency pair |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Margin account information for a trading pair. base corresponds to base currency account information, quote corresponds to quote currency account information] |
| » None | object | Margin account information for a trading pair. base corresponds to base currency account information, quote corresponds to quote currency account information |
| »» currency_pair | string | Currency pair |
| »» account_type | string | Account type: risk - risk rate account, mmr - maintenance margin rate account, inactive - market not activated |
| »» leverage | string | User's current market leverage multiplier |
| »» locked | boolean | Whether the account is locked |
| »» risk | string | Current risk rate of the margin account (returned when the account is a risk rate account) |
| »» mmr | string | Leveraged Account Current Maintenance Margin Rate (returned when the Account is Account) |
| »» base | object | 货币账户信息 |
| »»» currency | string | 货币名称 |
| »»» available | string | 可用于杠杆交易的额度, available = 保证金 + borrowed |
| »»» locked | string | 冻结资金, 如已经放在杠杆市场里挂单交易的数额 |
| »»» borrowed | string | 借入资金 |
| »»» interest | string | 未还利息 |
| »» quote | object | 货币账户信息 |
| »»» currency | string | 货币名称 |
| »»» available | string | 可用于杠杆交易的额度, available = 保证金 + borrowed |
| »»» locked | string | 冻结资金, 如已经放在杠杆市场里挂单交易的数额 |
| »»» borrowed | string | 借入资金 |
| »»» interest | string | 未还利息 |
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/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())
Example responses
200 Response
[
{
"currency_pair": "BTC_USDT",
"account_type": "mmr",
"leverage": "20",
"locked": false,
"risk": "1.3318",
"mmr": "16.5949188975473644",
"base": {
"currency": "BTC",
"available": "0.047060413211",
"locked": "0",
"borrowed": "0.047233",
"interest": "0"
},
"quote": {
"currency": "USDT",
"available": "1234",
"locked": "0",
"borrowed": "0",
"interest": "0"
}
}
]
GET /margin/account_book
Query margin account balance change history
Currently only provides transfer history to and from margin accounts. Query time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query history for specified currency. If currency is specified, currency_pair must also be specified. |
| currency_pair | query | string | false | Specify margin account currency pair. Used in combination with currency. Ignored if currency is not specified |
| type | query | string | false | Query by specified account change type. If not specified, all change types will be included. |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records returned in a single list |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | string | Balance change record ID |
| » time | string | Account change timestamp |
| » time_ms | integer(int64) | The timestamp of the change (in milliseconds) |
| » currency | string | Currency changed |
| » currency_pair | string | Account trading 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/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())
Example responses
200 Response
[
{
"id": "123456",
"time": "1547633726",
"time_ms": 1547633726123,
"currency": "BTC",
"currency_pair": "BTC_USDT",
"change": "1.03",
"balance": "4.59316525194"
}
]
GET /margin/funding_accounts
Funding account list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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/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())
Example responses
200 Response
[
{
"currency": "BTC",
"available": "1.238",
"locked": "0",
"lent": "3.32",
"total_lent": "3.32"
}
]
POST /margin/auto_repay
Update user auto repayment settings
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| status | query | string | true | Whether to enable auto repayment: on - enabled, off - disabled |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | User's current auto repayment settings | 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 = '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())
Example responses
200 Response
{
"status": "on"
}
GET /margin/auto_repay
Query user auto repayment settings
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | User's current auto repayment settings | 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())
Example responses
200 Response
{
"status": "on"
}
GET /margin/transferable
Get maximum transferable amount for isolated margin
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Query by specified currency name |
| currency_pair | query | string | false | Currency pair |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | 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
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())
Example responses
200 Response
{
"currency": "ETH",
"currency_pair": "ETH_USDT",
"amount": "10000"
}
GET /margin/uni/currency_pairs
List lending markets
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency_pair": "AE_USDT",
"base_min_borrow_amount": "100",
"quote_min_borrow_amount": "100",
"leverage": "3"
}
]
GET /margin/uni/currency_pairs/{currency_pair}
Get lending market details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | path | string | true | Currency pair |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | 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
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())
Example responses
200 Response
{
"currency_pair": "AE_USDT",
"base_min_borrow_amount": "100",
"quote_min_borrow_amount": "100",
"leverage": "3"
}
GET /margin/uni/estimate_rate
Estimate interest rate for isolated margin currencies
Interest rates change hourly based on lending depth, so completely accurate rates cannot be provided.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currencies | query | array[string] | true | Array of currency names to query, maximum 10 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
Estimate current hourly lending rates, returned 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/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())
Example responses
200 Response
{
"BTC": "0.000002",
"GT": "0.000001"
}
POST /margin/uni/loans
Borrow or repay
| 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 | Borrow or repayment amount |
| » repaid_all | body | boolean | false | Full repayment. For repayment operations only. When true, overrides amount and repays the full amount |
| » currency_pair | body | string | true | Currency pair |
| Parameter | Value |
|---|---|
| » type | borrow |
| » type | repay |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Operation successful | 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())
Body parameter
{
"currency": "BTC",
"amount": "0.1",
"type": "borrow",
"currency_pair": "BTC_USDT",
"repaid_all": false
}
GET /margin/uni/loans
Query loans
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Currency pair |
| currency | query | string | false | Query by specified currency name |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records returned in a single list |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Borrowing] |
| » None | object | Borrowing |
| »» currency | string | Currency |
| »» currency_pair | string | Currency pair |
| »» amount | string | Amount to Repay |
| »» type | string | Loan type: platform borrowing - platform, margin borrowing - margin |
| »» create_time | integer(int64) | Created time |
| »» update_time | integer(int64) | Last 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 = '/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())
Example responses
200 Response
[
{
"currency": "USDT",
"currency_pari": "GT_USDT",
"amount": "1",
"type": "margin",
"change_time": 1673247054000,
"create_time": 1673247054000
}
]
GET /margin/uni/loan_records
Query loan records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| type | query | string | false | Type: borrow - borrow, repay - repay |
| currency | query | string | false | Query by specified currency name |
| currency_pair | query | string | false | Currency pair |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records returned in a single list |
| Parameter | Value |
|---|---|
| type | borrow |
| type | repay |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Borrowing Records |
| »» type | string | Type: borrow - borrow, repay - repay |
| »» currency_pair | string | Currency pair |
| »» currency | string | Currency |
| »» amount | string | Borrow or repayment amount |
| »» 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/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())
Example responses
200 Response
[
{
"type": "borrow",
"currency_pair": "AE_USDT",
"currency": "USDT",
"amount": "1000",
"create_time": 1673247054000
}
]
GET /margin/uni/interest_records
Query interest deduction records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Currency pair |
| currency | query | string | false | Query by specified currency name |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records returned in a single list |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Interest Deduction Record] |
| » None | object | Interest Deduction 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 borrowing, margin - Margin borrowing |
| »» 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())
Example responses
200 Response
[
{
"status": 1,
"currency_pair": "BTC_USDT",
"currency": "USDT",
"actual_rate": "0.00000236",
"interest": "0.00006136",
"type": "platform",
"create_time": 1673247054000
}
]
GET /margin/uni/borrowable
Query maximum borrowable amount by currency
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Query by specified currency name |
| currency_pair | query | string | true | Currency pair |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | 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
Code samples
# coding: utf-8
import 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())
Example responses
200 Response
{
"currency": "AE",
"borrowable": "1123.344",
"currency_pair": "AE_USDT"
}
GET /margin/user/loan_margin_tiers
Query user's own leverage lending tiers in current market
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | true | Currency pair |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Market gradient information] |
| » None | object | Market gradient information |
| »» upper_limit | string | Maximum loan limit |
| »» mmr | string | Maintenance margin rate |
| »» leverage | string | Maximum leverage 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 = '/margin/user/loan_margin_tiers'
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())
Example responses
200 Response
[
{
"tier_amount": "100",
"mmr": "0.9",
"leverage": "1"
}
]
GET /margin/loan_margin_tiers
Query current market leverage lending tiers
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | true | Currency pair |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Market gradient information] |
| » None | object | Market gradient information |
| »» upper_limit | string | Maximum loan limit |
| »» mmr | string | Maintenance margin rate |
| »» leverage | string | Maximum leverage multiple |
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/loan_margin_tiers'
query_param = 'currency_pair=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"tier_amount": "100",
"mmr": "0.9",
"leverage": "1"
}
]
POST /margin/leverage/user_market_setting
Set user market leverage multiplier
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency_pair | body | string | false | Market |
| » leverage | body | string | true | Position leverage |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Set 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/leverage/user_market_setting'
query_param = ''
body='{"currency_pair":"BTC_USDT","leverage":"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())
Body parameter
{
"currency_pair": "BTC_USDT",
"leverage": "10"
}
GET /margin/user/account
Query user's isolated margin account list
Supports querying risk ratio isolated accounts and margin ratio isolated accounts
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Currency pair |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Margin account information for a trading pair. base corresponds to base currency account information, quote corresponds to quote currency account information] |
| » None | object | Margin account information for a trading pair. base corresponds to base currency account information, quote corresponds to quote currency account information |
| »» currency_pair | string | Currency pair |
| »» account_type | string | Account type: risk - risk rate account, mmr - maintenance margin rate account, inactive - market not activated |
| »» leverage | string | User's current market leverage multiplier |
| »» locked | boolean | Whether the account is locked |
| »» risk | string | Current risk rate of the margin account (returned when the account is a risk rate account) |
| »» mmr | string | Leveraged Account Current Maintenance Margin Rate (returned when the Account is Account) |
| »» base | object | 货币账户信息 |
| »»» currency | string | 货币名称 |
| »»» available | string | 可用于杠杆交易的额度, available = 保证金 + borrowed |
| »»» locked | string | 冻结资金, 如已经放在杠杆市场里挂单交易的数额 |
| »»» borrowed | string | 借入资金 |
| »»» interest | string | 未还利息 |
| »» quote | object | 货币账户信息 |
| »»» currency | string | 货币名称 |
| »»» available | string | 可用于杠杆交易的额度, available = 保证金 + borrowed |
| »»» locked | string | 冻结资金, 如已经放在杠杆市场里挂单交易的数额 |
| »»» borrowed | string | 借入资金 |
| »»» interest | string | 未还利息 |
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/user/account'
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())
Example responses
200 Response
[
{
"currency_pair": "BTC_USDT",
"account_type": "mmr",
"leverage": "20",
"locked": false,
"risk": "1.3318",
"mmr": "16.5949188975473644",
"base": {
"currency": "BTC",
"available": "0.047060413211",
"locked": "0",
"borrowed": "0.047233",
"interest": "0"
},
"quote": {
"currency": "USDT",
"available": "1234",
"locked": "0",
"borrowed": "0",
"interest": "0"
}
}
]
Spot trading
GET /spot/currencies
Query all currency information
When a currency corresponds to multiple chains, you can query the information of multiple chains through the chains field, such as the charging and recharge status, identification, etc. of the chain
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » currency | string | Currency symbol |
| » name | string | Currency name |
| » delisted | boolean | Whether currency is de-listed |
| » withdraw_disabled | boolean | Whether currency's withdrawal is disabled (deprecated) |
| » withdraw_delayed | boolean | Whether currency's withdrawal is delayed (deprecated) |
| » deposit_disabled | boolean | Whether currency's deposit is disabled (deprecated) |
| » 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 | The main chain corresponding to the coin |
| » is_private | boolean | Is it a privacy currency? |
| » chains | array | All links corresponding to coins |
| »» SpotCurrencyChain | object | none |
| »»» name | string | Blockchain name |
| »»» addr | string | token address |
| »»» 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 |
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())
Example responses
200 Response
[
{
"currency": "GT",
"name": "GateToken",
"delisted": false,
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"trade_disabled": false,
"chain": "GT",
"chains": [
{
"name": "GT",
"addr": "",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false
},
{
"name": "ETH",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"addr": "0xE66747a101bFF2dBA3697199DCcE5b743b454759"
},
{
"name": "GTEVM",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"addr": ""
}
]
}
]
GET /spot/currencies/{currency}
Query single currency information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | true | Currency name |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency symbol |
| » name | string | Currency name |
| » delisted | boolean | Whether currency is de-listed |
| » withdraw_disabled | boolean | Whether currency's withdrawal is disabled (deprecated) |
| » withdraw_delayed | boolean | Whether currency's withdrawal is delayed (deprecated) |
| » deposit_disabled | boolean | Whether currency's deposit is disabled (deprecated) |
| » 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 | The main chain corresponding to the coin |
| » is_private | boolean | Is it a privacy currency? |
| » chains | array | All links corresponding to coins |
| »» SpotCurrencyChain | object | none |
| »»» name | string | Blockchain name |
| »»» addr | string | token address |
| »»» 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 |
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())
Example responses
200 Response
{
"currency": "GT",
"name": "GateToken",
"delisted": false,
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"trade_disabled": false,
"chain": "GT",
"chains": [
{
"name": "GT",
"addr": "",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false
},
{
"name": "ETH",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"addr": "0xE66747a101bFF2dBA3697199DCcE5b743b454759"
},
{
"name": "GTEVM",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"addr": ""
}
]
}
GET /spot/currency_pairs
Query all supported currency pairs
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | All currency pairs retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Spot currency pair] |
| » None | object | Spot currency pair |
| »» id | string | Currency pair |
| »» base | string | Base currency |
| »» base_name | string | Base currency name |
| »» quote | string | Quote currency |
| »» quote_name | string | Quote currency name |
| »» fee | string | Trading fee rate |
| »» min_base_amount | string | Minimum amount of base currency to trade, null means no limit |
| »» min_quote_amount | string | Minimum amount of quote currency to trade, null means no limit |
| »» max_base_amount | string | Maximum amount of base currency to trade, null means no limit |
| »» max_quote_amount | string | Maximum amount of quote currency to trade, null means no limit |
| »» amount_precision | integer | Amount scale |
| »» precision | integer | Price scale |
| »» trade_status | string | Trading status - untradable: cannot be traded - buyable: can be bought - sellable: can be sold - tradable: can be bought and sold |
| »» sell_start | integer(int64) | Sell start unix timestamp in seconds |
| »» buy_start | integer(int64) | Buy start unix timestamp in seconds |
| »» delisting_time | integer(int64) | Expected time to remove the shelves, Unix timestamp in seconds |
| »» type | string | Trading pair type, normal: normal, premarket: pre-market |
| »» trade_url | string | Transaction link |
| »» st_tag | boolean | Whether the trading pair is in ST risk assessment, false - No, true - Yes |
| Property | Value |
|---|---|
| trade_status | untradable |
| trade_status | buyable |
| trade_status | sellable |
| trade_status | tradable |
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())
Example responses
200 Response
[
{
"id": "ETH_USDT",
"base": "ETH",
"base_name": "Ethereum",
"quote": "USDT",
"quote_name": "Tether",
"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,
"delisting_time": 0,
"trade_url": "https://www.gate.io/trade/ETH_USDT",
"st_tag": false
}
]
GET /spot/currency_pairs/{currency_pair}
Query single currency pair details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | path | string | true | Currency pair |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
Spot currency pair
| Name | Type | Description |
|---|---|---|
| » id | string | Currency pair |
| » base | string | Base currency |
| » base_name | string | Base currency name |
| » quote | string | Quote currency |
| » quote_name | string | Quote currency name |
| » fee | string | Trading fee rate |
| » min_base_amount | string | Minimum amount of base currency to trade, null means no limit |
| » min_quote_amount | string | Minimum amount of quote currency to trade, null means no limit |
| » max_base_amount | string | Maximum amount of base currency to trade, null means no limit |
| » max_quote_amount | string | Maximum amount of quote currency to trade, null means no limit |
| » amount_precision | integer | Amount scale |
| » precision | integer | Price scale |
| » trade_status | string | Trading status - untradable: cannot be traded - buyable: can be bought - sellable: can be sold - tradable: can be bought and sold |
| » sell_start | integer(int64) | Sell start unix timestamp in seconds |
| » buy_start | integer(int64) | Buy start unix timestamp in seconds |
| » delisting_time | integer(int64) | Expected time to remove the shelves, Unix timestamp in seconds |
| » type | string | Trading pair type, normal: normal, premarket: pre-market |
| » trade_url | string | Transaction link |
| » st_tag | boolean | Whether the trading pair is in ST risk assessment, false - No, true - Yes |
| Property | Value |
|---|---|
| trade_status | untradable |
| trade_status | buyable |
| trade_status | sellable |
| trade_status | tradable |
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())
Example responses
200 Response
{
"id": "ETH_USDT",
"base": "ETH",
"base_name": "Ethereum",
"quote": "USDT",
"quote_name": "Tether",
"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,
"delisting_time": 0,
"trade_url": "https://www.gate.io/trade/ETH_USDT",
"st_tag": false
}
GET /spot/tickers
Get currency pair ticker information
If currency_pair is specified, only query that currency pair; otherwise return all information
| 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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 | Latest seller's lowest price quantity; not available for batch queries; available for single queries, empty if no data |
| » highest_bid | string | Recent highest bid |
| » highest_size | string | Latest buyer's highest price quantity; not available for batch queries; available for single queries, empty if no data |
| » change_percentage | string | 24h price change percentage (negative for decrease, e.g., -7.45) |
| » change_utc0 | string | UTC+0 timezone, 24h price change percentage, negative for decline (e.g., -7.45) |
| » change_utc8 | string | UTC+8 timezone, 24h price change percentage, negative for decline (e.g., -7.45) |
| » base_volume | string | Base currency trading volume in the last 24h |
| » quote_volume | string | Quote currency trading volume in the last 24h |
| » high_24h | string | 24h High |
| » low_24h | string | 24h Low |
| » etf_net_value | string | ETF net value |
| » etf_pre_net_value | string|null | ETF net value at previous rebalancing point |
| » etf_pre_timestamp | integer(int64)|null | ETF previous rebalancing 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/tickers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
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"
}
]
GET /spot/order_book
Get market depth information
Market depth buy orders are sorted by price from high to low, sell orders are sorted from low to high
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | true | Currency pair |
| interval | query | string | false | Price precision for depth aggregation, 0 means no aggregation, defaults to 0 if not specified |
| limit | query | integer | false | Number of depth levels |
| with_id | query | boolean | false | Return order book update ID |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | 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 | Ask Depth |
| »» None | array | Price and Quantity Pair |
| » bids | array | Bid Depth |
| »» None | array | Price and Quantity Pair |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/order_book'
query_param = 'currency_pair=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
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"
]
]
}
GET /spot/trades
Query market transaction records
Supports querying by time range using from and to parameters or pagination based on last_id. By default, queries the last 30 days.
Pagination based on last_id is no longer recommended. If last_id is specified, the time range query parameters will be ignored.
When using limit&page pagination to retrieve data, the maximum number of pages is 100,000, that is, limit * (page - 1) <= 100,000.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | true | Currency pair |
| limit | query | integer(int32) | false | Maximum number of items returned in list. Default: 100, minimum: 1, maximum: 1000 |
| last_id | query | string | false | Specify the currency name to query in batches, and support up to 100 pass parameters at a time |
| reverse | query | boolean | false | Whether to retrieve data less than last_id. Default returns records greater than last_id. |
| from | query | integer(int64) | false | Start timestamp for the query |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| page | query | integer(int32) | false | Page number |
reverse: Whether to retrieve data less than last_id. Default returns records greater than last_id.
Set to true to trace back market trade records, false to get latest trades.
No effect when last_id is not set.
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | string | Fill ID |
| » create_time | string | Fill Time |
| » create_time_ms | string | Trading time, with millisecond precision |
| » currency_pair | string | Currency pair |
| » side | string | Buy or sell order |
| » role | string | Trade role, not returned in public endpoints |
| » amount | string | Trade amount |
| » price | string | Order price |
| » order_id | string | Related order ID, not returned in public endpoints |
| » fee | string | Fee deducted, not returned in public endpoints |
| » fee_currency | string | Fee currency unit, not returned in public endpoints |
| » point_fee | string | Points used to deduct fee, not returned in public endpoints |
| » gt_fee | string | GT used to deduct fee, not returned in public endpoints |
| » amend_text | string | The custom data that the user remarked when amending the order |
| » sequence_id | string | Consecutive trade ID within a single market. Used to track and identify trades in the specific market |
| » text | string | User-defined information, not returned 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/trades'
query_param = 'currency_pair=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
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"
}
]
GET /spot/candlesticks
Market K-line chart
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 number of recent data points to return. limit conflicts 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 | Specify the end time of the K-line chart, defaults to current time if not specified, note that the time format is Unix timestamp with second precision |
| interval | query | string | false | Time interval between data points. Note that 30d represents a calendar month, not aligned to 30 days |
| Parameter | Value |
|---|---|
| interval | 1s |
| interval | 10s |
| interval | 1m |
| interval | 5m |
| interval | 15m |
| interval | 30m |
| interval | 1h |
| interval | 4h |
| interval | 8h |
| interval | 1d |
| interval | 7d |
| interval | 30d |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [[string]] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | array | Candlestick data for each time granularity, 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 window is closed; true means this candlestick data segment is complete, false means not yet complete |
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())
Example responses
200 Response
[
[
"1539852480",
"971519.677",
"0.0021724",
"0.0021922",
"0.0021724",
"0.0021737",
"true"
]
]
GET /spot/fee
Query account fee rates
This API is deprecated. The new fee query API is /wallet/fee
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Specify currency pair to get more accurate fee settings. |
currency_pair: Specify currency pair to get more accurate fee settings.
This field is optional. Usually fee settings are the same for all currency pairs.
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | 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 | Whether GT deduction discount 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 with GT deduction. Returns 0 if GT deduction is disabled |
| » loan_fee | string | Loan fee rate of margin lending |
| » point_type | string | Point card type: 0 - Original 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/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())
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
}
GET /spot/batch_fee
Batch query account fee rates
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pairs | query | string | true | Maximum 50 currency pairs per request |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | 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 | Whether GT deduction discount 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 with GT deduction. Returns 0 if GT deduction is disabled |
| »» loan_fee | string | Loan fee rate of margin lending |
| »» point_type | string | Point card type: 0 - Original 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())
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
}
}
GET /spot/accounts
List spot trading accounts
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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(int64) | 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/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())
Example responses
200 Response
[
{
"currency": "ETH",
"available": "968.8",
"locked": "0",
"update_id": 98
}
]
GET /spot/account_book
Query spot account transaction history
Record query time range cannot exceed 30 days.
When using limit&page pagination to retrieve data, the maximum number of pages is 100,000, that is, limit * (page - 1) <= 100,000.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
| from | query | integer(int64) | false | Start timestamp for the query |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records returned in a single list |
| type | query | string | false | Query by specified account change type. If not specified, all change types will be included. |
| code | query | string | false | Specify account change code for query. If not specified, all change types are included. This parameter has higher priority than type |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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 |
| » code | string | Account change code, see [Asset Record Code] (Asset Record Code) |
| » 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/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())
Example responses
200 Response
[
{
"id": "123456",
"time": 1547633726123,
"currency": "BTC",
"change": "1.03",
"balance": "4.59316525194",
"type": "margin_in",
"text": "3815099"
}
]
POST /spot/batch_orders
Batch place orders
Batch order requirements:
text is requiredaccount must be identical for all orders| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | 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 | true | none |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request execution 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 | Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: 1. Must start with t-2. Excluding t-, length cannot exceed 28 bytes3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.) |
| »» succeeded | boolean | Request execution result |
| »» 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 - spot account, margin - leveraged account, unified - unified account |
| »» side | string | Buy or sell order |
| »» 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 filled |
| »» 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 deduction is enabled |
| »» 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, 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/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())
Body 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"
}
]
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
}
]
GET /spot/open_orders
List all open orders
Query the current order list of all trading pairs. Please note that the paging parameter controls the number of pending orders in each trading pair. There is no paging control trading pairs. All trading pairs with pending orders will be returned.
| 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 query account |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency_pair | string | Currency pair |
| » total | integer | Total number of open 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 type, spot - spot account, margin - leveraged account, unified - unified account |
| »»» side | string | Buy or sell order |
| »»» amount | string | Trading quantity When type is limit, it refers to the base currency (the currency being traded), such as BTC in BTC_USDTWhen type is market, it refers to different currencies based on the side:- side: buy refers to quote currency, BTC_USDT means USDT- side: sell refers to base currency, BTC_USDT means BTC |
| »»» price | string | Trading price, required 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 filled |
| »»» 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 amount used to deduct maker fee |
| »»» gt_taker_fee | string | GT amount used to deduct taker fee |
| »»» gt_discount | boolean | Whether GT fee deduction is enabled |
| »»» 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 prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention 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 poc - fok: Not fully filled immediately because tif is set to fok - stp: Cancelled due to self-trade prevention - unknown: Unknown |
| »»» fee_discount | string | Fee rate discount |
| 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/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())
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"
}
]
}
]
POST /spot/cross_liquidate_orders
Close position when cross-currency is disabled
Currently, only cross-margin accounts are supported to place buy orders for disabled currencies. Maximum buy quantity = (unpaid principal and interest - currency balance - the amount of the currency in pending orders) / 0.998
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » text | body | string | false | Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: |
| » 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: Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions:
t-t-, length cannot exceed 28 bytes» 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 is not included in the response
ACK: Asynchronous mode, only returns key order fields
RESULT: No liquidation information
FULL: Full mode (default)
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order created successfully | Inline |
Status Code 201
Spot order details
| Name | Type | Description |
|---|---|---|
| » 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 type, spot - spot account, margin - leveraged account, unified - unified account |
| » side | string | Buy or sell order |
| » amount | string | Trading quantity When type is limit, it refers to the base currency (the currency being traded), such as BTC in BTC_USDTWhen type is market, it refers to different currencies based on the side:- side: buy refers to quote currency, BTC_USDT means USDT- side: sell refers to base currency, BTC_USDT means BTC |
| » price | string | Trading price, required 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 filled |
| » 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 amount used to deduct maker fee |
| » gt_taker_fee | string | GT amount used to deduct taker fee |
| » gt_discount | boolean | Whether GT fee deduction is enabled |
| » 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 prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention 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 poc - fok: Not fully filled immediately because tif is set to fok - stp: Cancelled due to self-trade prevention - unknown: Unknown |
| » fee_discount | string | Fee rate discount |
| 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())
Body parameter
{
"currency_pair": "GT_USDT",
"amount": "12",
"price": "10.15",
"text": "t-34535"
}
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"
}
POST /spot/orders
Create an order
Supports spot, margin, leverage, and cross-margin leverage orders. Use different accounts through the account field. Default is spot, which means using the spot account to place orders. If the user has a unified account, the default is to place orders with the unified account.
When using leveraged account trading (i.e., when account is set to margin), you can set auto_borrow to true.
In case of insufficient account balance, the system will automatically execute POST /margin/uni/loans to borrow the insufficient amount.
Whether assets obtained after leveraged order execution are automatically used to repay borrowing orders of the isolated margin account depends on the automatic repayment settings of the user's isolated margin account.
Account automatic repayment settings can be queried and set through /margin/auto_repay.
When using unified account trading (i.e., when account is set to unified), auto_borrow can also be enabled to realize automatic borrowing of insufficient amounts. However, unlike the isolated margin account, whether unified account orders are automatically repaid depends on the auto_repay setting when placing the order. This setting only applies to the current order, meaning only assets obtained after order execution will be used to repay borrowing orders of the cross-margin account.
Unified account ordering currently supports enabling both auto_borrow and auto_repay simultaneously.
Auto repayment will be triggered when the order ends, i.e., when status is cancelled or closed.
Order Status
The order status in pending orders is open, which remains open until all quantity is filled. If fully filled, the order ends and status becomes closed.
If the order is cancelled before all transactions are completed, regardless of partial fills, the status will become cancelled.
Iceberg Orders
iceberg is used to set the displayed quantity of iceberg orders and does not support complete hiding. Note that hidden portions are charged according to the taker's fee rate.
Self-Trade Prevention
Set stp_act to determine the self-trade prevention strategy to use
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | 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 |
| » text | body | string | false | User defined information. If not empty, must follow the rules below: |
| » currency_pair | body | string | true | Currency pair |
| » type | body | string | false | Order Type |
| » account | body | string | false | Account type, spot - spot account, margin - leveraged account, unified - unified account |
| » side | body | string | true | Buy or sell order |
| » amount | body | string | true | Trading quantity |
| » price | body | string | false | Trading price, required 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 prevention strategies |
| » fee_discount | body | string | false | Fee rate discount |
| » 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: Trading quantity
When type is limit, it refers to the base currency (the currency being traded), such as BTC in BTC_USDT
When type is market, it refers to different currencies based on the side:
side: buy refers to quote currency, BTC_USDT means USDTside: sell refers to 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 prevention strategies
STP Group, they can pass stp_act to limit the user's self-trade prevention 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.stp_act when placing the order, stp_act will return '-'» 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 | - |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order created | Inline |
Status Code 201
Spot order details
| Name | Type | Description |
|---|---|---|
| » 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 type, spot - spot account, margin - leveraged account, unified - unified account |
| » side | string | Buy or sell order |
| » amount | string | Trading quantity When type is limit, it refers to the base currency (the currency being traded), such as BTC in BTC_USDTWhen type is market, it refers to different currencies based on the side:- side: buy refers to quote currency, BTC_USDT means USDT- side: sell refers to base currency, BTC_USDT means BTC |
| » price | string | Trading price, required 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_borrow | boolean | Used in margin or cross margin trading to allow automatic loan of insufficient amount if balance is not enough |
| » 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 filled |
| » 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 amount used to deduct maker fee |
| » gt_taker_fee | string | GT amount used to deduct taker fee |
| » gt_discount | boolean | Whether GT fee deduction is enabled |
| » 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 prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention 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 poc - fok: Not fully filled immediately because tif is set to fok - stp: Cancelled due to self-trade prevention - unknown: Unknown |
| » fee_discount | string | Fee rate discount |
| » action_mode | string | 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 |
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())
Body 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"
}
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"
}
GET /spot/orders
List orders
status is set to open, that is, when querying the pending order list, only page and limit paging control are supported. limit The maximum setting is only 100.
Does not support side and from, to parameters for querying by time range.
status when querying historical orders, in addition to paging query, it also supports from and to query by time range.
In addition, it also supports setting the side parameter to filter unilateral history.
The parameters for time range filtering are all processed according to the end time of the order.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | true | Query by specified currency pair. Required for open orders, optional for filled orders |
| 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 query account |
| from | query | integer(int64) | false | Start timestamp for the query |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| side | query | string | false | Specify all bids or all 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Spot order details] |
| » 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 type, spot - spot account, margin - leveraged account, unified - unified account |
| »» side | string | Buy or sell order |
| »» amount | string | Trading quantity When type is limit, it refers to the base currency (the currency being traded), such as BTC in BTC_USDTWhen type is market, it refers to different currencies based on the side:- side: buy refers to quote currency, BTC_USDT means USDT- side: sell refers to base currency, BTC_USDT means BTC |
| »» price | string | Trading price, required 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 filled |
| »» 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 amount used to deduct maker fee |
| »» gt_taker_fee | string | GT amount used to deduct taker fee |
| »» gt_discount | boolean | Whether GT fee deduction is enabled |
| »» 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 prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention 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 poc - fok: Not fully filled immediately because tif is set to fok - stp: Cancelled due to self-trade prevention - unknown: Unknown |
| »» fee_discount | string | Fee rate discount |
| 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/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())
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"
}
]
open orders in specified currency pairDELETE /spot/orders
Cancel all open orders in specified currency pair
When the account parameter is not specified, all pending orders including spot, unified account, and isolated margin will be cancelled.
When currency_pair is not specified, all trading pair pending orders will be cancelled.
You can specify a particular account to cancel all pending orders under that account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Currency pair |
| side | query | string | false | Specify all bids or all asks, both included if not specified |
| account | query | string | false | Specify account type |
| action_mode | query | string | false | Processing Mode |
| x-gate-exptime | header | string | 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
Classic account: All are included if not specified
Unified account: Specify unified
action_mode: Processing Mode
When placing an order, different fields are returned based on the action_mode
ACK: Asynchronous mode, returns only key order fieldsRESULT: No clearing informationFULL: Full mode (default)| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation request accepted and processed, success determined by order list | [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 | Request execution result |
| »» 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 type, spot - spot account, margin - leveraged account, unified - unified account |
| »» side | string | Buy or sell order |
| »» amount | string | Trading quantity When type is limit, it refers to the base currency (the currency being traded), such as BTC in BTC_USDTWhen type is market, it refers to different currencies based on the side:- side: buy refers to quote currency, BTC_USDT means USDT- side: sell refers to base currency, BTC_USDT means BTC |
| »» price | string | Trading price, required 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 filled |
| »» 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 amount used to deduct maker fee |
| »» gt_taker_fee | string | GT amount used to deduct taker fee |
| »» gt_discount | boolean | Whether GT fee deduction is enabled |
| »» 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 prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention 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 |
| »» fee_discount | string | Fee rate discount |
| 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/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())
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"
}
]
POST /spot/cancel_batch_orders
Cancel batch orders by specified ID list
Multiple currency pairs can be specified, but maximum 20 orders are allowed per request
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | 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[object] | true | none |
| 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 description when cancellation fails, empty if successful |
| »» account | string | Default is empty (deprecated) |
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())
Body parameter
[
{
"currency_pair": "BTC_USDT",
"id": "123456"
}
]
Example responses
200 Response
[
{
"currency_pair": "BTC_USDT",
"id": "123456",
"text": "123456",
"succeeded": true,
"label": null,
"message": null
}
]
GET /spot/orders/{order_id}
Query single order details
By default, queries orders for spot, unified account, and isolated margin accounts.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | string | true | The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field). |
| currency_pair | query | string | true | Specify the trading pair to query. This field is required when querying pending order records. This field can be omitted when querying filled order records. |
| account | query | string | false | Specify query account |
order_id: The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field).
Operations based on custom IDs can only be checked in pending orders. Only order ID can be used after the order is finished (transaction/cancel)
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Detail retrieved | Inline |
Status Code 200
Spot order details
| Name | Type | Description |
|---|---|---|
| » 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 type, spot - spot account, margin - leveraged account, unified - unified account |
| » side | string | Buy or sell order |
| » amount | string | Trading quantity When type is limit, it refers to the base currency (the currency being traded), such as BTC in BTC_USDTWhen type is market, it refers to different currencies based on the side:- side: buy refers to quote currency, BTC_USDT means USDT- side: sell refers to base currency, BTC_USDT means BTC |
| » price | string | Trading price, required 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 filled |
| » 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 amount used to deduct maker fee |
| » gt_taker_fee | string | GT amount used to deduct taker fee |
| » gt_discount | boolean | Whether GT fee deduction is enabled |
| » 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 prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention 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 poc - fok: Not fully filled immediately because tif is set to fok - stp: Cancelled due to self-trade prevention - unknown: Unknown |
| » fee_discount | string | Fee rate discount |
| 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/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())
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"
}
PATCH /spot/orders/{order_id}
Amend single order
Modify orders in spot, unified account and isolated margin account by default.
Currently both request body and query support currency_pair and account parameters, but request body has higher priority.
currency_pair must be filled in one of the request body or query parameters.
About rate limit: Order modification and order creation share the same rate limit rules.
About matching priority: Only reducing the quantity does not affect the matching priority. Modifying the price or increasing the quantity will adjust the priority to the end of the new price level.
Note: Modifying the quantity to be less than the filled quantity will trigger a cancellation and isolated margin account by default.
Currently both request body and query support currency_pair and account parameters, but request body has higher priority.
currency_pair must be filled in one of the request body or query parameters.
About rate limit: Order modification and order creation share the same rate limit rules.
About matching priority: Only reducing the quantity does not affect the matching priority. Modifying the price or increasing the quantity will adjust the priority to the end of the new price level.
Note: Modifying the quantity to be less than the filled quantity will trigger a cancellation operation.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | string | true | The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field). |
| currency_pair | query | string | false | Currency pair |
| account | query | string | false | Specify query account |
| x-gate-exptime | header | string | 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 | Specify query account |
| » amount | body | string | false | Trading quantity. Either amount or price must be specified |
| » price | body | string | false | Trading price. Either amount or price must be specified |
| » amend_text | body | string | false | Custom info during order amendment |
| » action_mode | body | string | false | Processing Mode: |
order_id: The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field).
Operations based on custom IDs can only be checked in pending orders. Only order ID can be used after the order is finished (transaction/cancel)
» 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)
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Updated successfully | Inline |
Status Code 200
Spot order details
| Name | Type | Description |
|---|---|---|
| » 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 type, spot - spot account, margin - leveraged account, unified - unified account |
| » side | string | Buy or sell order |
| » amount | string | Trading quantity When type is limit, it refers to the base currency (the currency being traded), such as BTC in BTC_USDTWhen type is market, it refers to different currencies based on the side:- side: buy refers to quote currency, BTC_USDT means USDT- side: sell refers to base currency, BTC_USDT means BTC |
| » price | string | Trading price, required 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 filled |
| » 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 amount used to deduct maker fee |
| » gt_taker_fee | string | GT amount used to deduct taker fee |
| » gt_discount | boolean | Whether GT fee deduction is enabled |
| » 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 prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention 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 poc - fok: Not fully filled immediately because tif is set to fok - stp: Cancelled due to self-trade prevention - unknown: Unknown |
| » fee_discount | string | Fee rate discount |
| 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/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())
Body parameter
{
"currency_pair": "BTC_USDT",
"account": "spot",
"amount": "1"
}
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"
}
DELETE /spot/orders/{order_id}
Cancel single order
By default, orders for spot, unified accounts and leveraged accounts are revoked.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | string | true | The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field). |
| currency_pair | query | string | true | Currency pair |
| account | query | string | false | Specify query account |
| action_mode | query | string | false | Processing Mode |
| x-gate-exptime | header | string | 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: The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field).
Operations based on custom IDs can only be checked in pending orders. Only order ID can be used after the order is finished (transaction/cancel)
action_mode: Processing Mode
When placing an order, different fields are returned based on the action_mode
ACK: Asynchronous mode, returns only key order fieldsRESULT: No clearing informationFULL: Full mode (default)| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order cancelled | Inline |
Status Code 200
Spot order details
| Name | Type | Description |
|---|---|---|
| » 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 type, spot - spot account, margin - leveraged account, unified - unified account |
| » side | string | Buy or sell order |
| » amount | string | Trading quantity When type is limit, it refers to the base currency (the currency being traded), such as BTC in BTC_USDTWhen type is market, it refers to different currencies based on the side:- side: buy refers to quote currency, BTC_USDT means USDT- side: sell refers to base currency, BTC_USDT means BTC |
| » price | string | Trading price, required 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 filled |
| » 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 amount used to deduct maker fee |
| » gt_taker_fee | string | GT amount used to deduct taker fee |
| » gt_discount | boolean | Whether GT fee deduction is enabled |
| » 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 prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention 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 poc - fok: Not fully filled immediately because tif is set to fok - stp: Cancelled due to self-trade prevention - unknown: Unknown |
| » fee_discount | string | Fee rate discount |
| 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/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())
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"
}
GET /spot/my_trades
Query personal trading records
By default query of transaction records for spot, unified account and warehouse-by-site leverage accounts.
The history within a specified time range can be queried by specifying from or (and) to.
from or to is specified, only 7-day data from the start (or end) of the specified time is returned.The parameters of the time range filter are processed according to the order end time.
The maximum number of pages when searching data using limit&page paging function is 100,0, that is, limit * (page - 1) <= 100,0.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Retrieve results with specified currency pair |
| limit | query | integer | false | Maximum number of items returned in 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 query account |
| from | query | integer(int64) | false | Start timestamp for the query |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | string | Fill ID |
| » create_time | string | Fill Time |
| » create_time_ms | string | Trading time, with millisecond precision |
| » currency_pair | string | Currency pair |
| » side | string | Buy or sell order |
| » role | string | Trade role, not returned in public endpoints |
| » amount | string | Trade amount |
| » price | string | Order price |
| » order_id | string | Related order ID, not returned in public endpoints |
| » fee | string | Fee deducted, not returned in public endpoints |
| » fee_currency | string | Fee currency unit, not returned in public endpoints |
| » point_fee | string | Points used to deduct fee, not returned in public endpoints |
| » gt_fee | string | GT used to deduct fee, not returned in public endpoints |
| » amend_text | string | The custom data that the user remarked when amending the order |
| » sequence_id | string | Consecutive trade ID within a single market. Used to track and identify trades in the specific market |
| » text | string | User-defined information, not returned 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
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())
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"
}
]
GET /spot/time
Get server current time
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
SystemTime
| Name | Type | Description |
|---|---|---|
| » server_time | integer(int64) | Server current time(ms) |
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())
Example responses
200 Response
{
"server_time": 1597026383085
}
POST /spot/countdown_cancel_all
Countdown cancel orders
Spot order heartbeat detection. If there is no "cancel existing countdown" or "set new countdown" when the user-set timeout time is reached, the related spot pending orders will be automatically cancelled.
This interface can be called repeatedly to set a new countdown or cancel the countdown.
Usage example: Repeat this interface at 30s intervals, setting the countdown timeout to 30 (seconds) each time.
If this interface is not called again within 30 seconds, all pending orders on the market you specified will be automatically cancelled. If no market is specified, all market cancelled.
If the timeout is set to 0 within 30 seconds, the countdown timer will be terminated and the automatic order cancellation function will be cancelled.
| 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 countdown
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Countdown set successfully | Inline |
Status Code 200
triggerTime
| Name | Type | Description |
|---|---|---|
| » triggerTime | integer(int64) | Timestamp when countdown ends, 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/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())
Body parameter
{
"timeout": 30,
"currency_pair": "BTC_USDT"
}
Example responses
200 Response
{
"triggerTime": "1660039145000"
}
POST /spot/amend_batch_orders
Batch modification of orders
Modify orders in spot, unified account and isolated margin account by default. Modify uncompleted orders, up to 5 orders can be modified at a time. Request parameters should be passed in array format. If there are order modification failures during the batch modification process, the modification of the next order will continue to be executed, and the execution will return with the corresponding order failure information. The call order of batch modification orders is consistent with the order list order. The return content order of batch modification orders is consistent with the order list order.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | 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[object] | true | none |
| 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 | Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: 1. Must start with t-2. Excluding t-, length cannot exceed 28 bytes3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.) |
| »» succeeded | boolean | Request execution result |
| »» 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 - spot account, margin - leveraged account, unified - unified account |
| »» side | string | Buy or sell order |
| »» 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 filled |
| »» 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 deduction is enabled |
| »» 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, 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/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())
Body parameter
[
{
"order_id": "121212",
"currency_pair": "BTC_USDT",
"account": "spot",
"amount": "1",
"amend_text": "test"
}
]
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
}
]
GET /spot/insurance_history
Query spot insurance fund historical data
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| business | query | string | true | Leverage business, margin - position by position; unified - unified account |
| currency | query | string | true | Currency |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | The maximum number of items returned in the list, the default value is 30 |
| from | query | integer(int64) | true | Start timestamp in seconds |
| to | query | integer(int64) | true | End timestamp in seconds |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency |
| » balance | string | Balance |
| » time | integer(int64) | Creation time, timestamp, milliseconds |
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/insurance_history'
query_param = 'business=margin¤cy=BTC&from=1547706332&to=1547706332'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "BTC",
"balance": "1021.21",
"time": 1727054547
}
]
POST /spot/price_orders
Create price-triggered order
| 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 | Maximum wait time for trigger condition (in seconds). Order will be cancelled if timeout |
| » 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 | Trading quantity |
| »» account | body | string | true | Trading account type. Unified account must be set to unified |
| »» time_in_force | body | string | false | time_in_force |
| »» auto_borrow | body | boolean | false | Whether to borrow coins automatically |
| »» auto_repay | body | boolean | false | Whether to repay the loan automatically |
| »» text | body | string | false | The source of the order, including: |
| » market | body | string | true | Market |
»» rule: Price trigger condition
>=: triggered when market price is greater than or equal to price<=: triggered when market price is less than or equal to price»» type: Order type, default to limit
»» side: Order side
»» amount: Trading quantity
When type is limit, it refers to the base currency (the currency being traded), such as BTC in BTC_USDT
When type is market, it refers to different currencies based on the side:
side: buy refers to quote currency, BTC_USDT means USDTside: sell refers to base currency, BTC_USDT means BTC»» account: Trading account type. Unified account must be set to unified
»» 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 | unified |
| »» time_in_force | gtc |
| »» time_in_force | ioc |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order created successfully | 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 = ''
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())
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"
}
Example responses
201 Response
{
"id": 1432329
}
GET /spot/price_orders
Query running auto order list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| status | query | string | true | Query order list based on status |
| market | query | string | false | Trading market |
| account | query | string | false | Trading account type. Unified account must be set to unified |
| limit | query | integer | false | Maximum number of records 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 | unified |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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 = '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())
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": ""
}
]
DELETE /spot/price_orders
Cancel all auto orders
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| market | query | string | false | Trading market |
| account | query | string | false | Trading account type. Unified account must be set to unified |
| Parameter | Value |
|---|---|
| account | normal |
| account | margin |
| account | unified |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation request accepted and processed, success determined by order list | [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())
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": ""
}
]
GET /spot/price_orders/{order_id}
Query single auto order details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | string | true | ID returned when order is successfully created |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Auto order details | 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())
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": ""
}
DELETE /spot/price_orders/{order_id}
Cancel single auto order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | string | true | ID returned when order is successfully created |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Auto order details | 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())
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": ""
}
Flash exchange
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 | Query by specified currency name |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum number of items returned. Default: 1000, minimum: 1, maximum: 1000 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | List all supported currencies in flash swap |
| »» currency_pair | string | Currency pair, BTC_USDT represents selling BTC and buying USDT |
| »» sell_currency | string | Currency to sell |
| »» buy_currency | string | Currency to buy |
| »» sell_min_amount | string | Minimum sell quantity |
| »» sell_max_amount | string | Maximum sell quantity |
| »» buy_min_amount | string | Minimum buy quantity |
| »» buy_max_amount | string | Maximum buy quantity |
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())
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"
}
]
POST /flash_swap/orders
Create a flash swap order
Initiate a flash swap preview in advance because order creation requires a preview result
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » preview_id | body | string | true | Preview result ID |
| » sell_currency | body | string | true | Name of the asset to be sold, obtained from the interface GET /flash_swap/currency_pairs: Query the list of all trading pairs supporting flash swap |
| » sell_amount | body | string | true | Amount to sell (based on the preview result) |
| » buy_currency | body | string | true | Name of the asset to be bought, obtained from the interface GET /flash_swap/currency_pairs: Query the list of all trading pairs supporting flash swap |
| » buy_amount | body | string | true | Amount to buy (based on the preview result) |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Flash swap order 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 = ''
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())
Body parameter
{
"preview_id": "4564564",
"sell_currency": "BTC",
"sell_amount": "0.1",
"buy_currency": "USDT",
"buy_amount": "10"
}
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
}
GET /flash_swap/orders
Query flash swap order list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| status | query | integer | false | Flash swap order status |
| sell_currency | query | string | false | Asset name to sell |
| buy_currency | query | string | false | Asset name to buy |
| reverse | query | boolean | false | Sort by ID in ascending or descending order, default true |
| limit | query | integer | false | Maximum number of records returned in a single list |
| page | query | integer(int32) | false | Page number |
status: Flash swap order status
1 - success
2 - failed
sell_currency: Asset name to sell
GET /flash_swap/currencies for supported flash swap currenciesbuy_currency: Asset name to buy
GET /flash_swap/currencies for supported flash swap currenciesreverse: Sort by ID in ascending or descending order, default true
true: ID descending order (most recent data first)false: ID ascending order (oldest data first)| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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'
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())
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
}
]
GET /flash_swap/orders/{order_id}
Query single flash swap order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | integer | true | Flash swap order ID |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | 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/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())
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
}
POST /flash_swap/orders/preview
Flash swap order preview
| 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Flash swap order preview successful | Inline |
Status Code 200
Flash swap order preview
| Name | Type | Description |
|---|---|---|
| » preview_id | string | Preview result ID |
| » sell_currency | string | Name of the sold asset, Refer to the interface Query the list of currencies supported for flash swap GET /flash_swap/currenciesto obtain |
| » sell_amount | string | Amount to sell |
| » buy_currency | string | Name of the purchased asset, Refer to the interface Query the list of currencies supported for flash swap GET /flash_swap/currenciesto obtain |
| » buy_amount | string | Amount to buy |
| » price | string | Price |
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())
Body parameter
{
"sell_currency": "BTC",
"sell_amount": "0.1",
"buy_currency": "USDT"
}
Example responses
200 Response
{
"preview_id": "3453434",
"sell_currency": "BTC",
"sell_amount": "0.1",
"buy_currency": "USDT",
"buy_amount": "10",
"price": "100"
}
Perpetual futures
GET /futures/{settle}/contracts
Query all futures contracts
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
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": "trading",
"launch_time": 1609899548
}
]
GET /futures/{settle}/contracts/{contract}
Query single contract information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| 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/contracts/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
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": "trading",
"launch_time": 1609899548
}
GET /futures/{settle}/order_book
Query futures market depth information
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 | Price precision for depth aggregation, 0 means no aggregation, defaults to 0 if not specified |
| limit | query | integer | false | Number of depth levels |
| with_id | query | boolean | false | Whether to return depth update ID. This ID increments by 1 each time depth changes |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Depth query successful | 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 | Ask Depth |
| »» futures_order_book_item | object | none |
| »»» p | string | Price (quote currency) |
| »»» s | integer(int64) | Size |
| »» bids | array | Bid 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/order_book'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
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
}
]
}
GET /futures/{settle}/trades
Futures market transaction records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| limit | query | integer | false | Maximum number of records returned in 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | integer(int64) | Fill ID |
| » create_time | number(double) | Fill Time |
| » create_time_ms | number(double) | Trade time, with millisecond precision to 3 decimal places |
| » contract | string | Futures contract |
| » size | integer(int64) | Trading size |
| » price | string | Trade price (quote currency) |
| » is_internal | boolean | Whether it is an 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 trade price may deviate from the market, 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/trades'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800,
"contract": "BTC_USDT",
"size": -100,
"price": "100.123"
}
]
GET /futures/{settle}/candlesticks
Futures market K-line chart
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 | Specify the end time of the K-line chart, defaults to current time if not specified, note that the time format is Unix timestamp with second precision |
| limit | query | integer | false | Maximum number of recent data points to return. limit conflicts 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 natural week(Mon-Sun), while 7d means every 7d since unix 0. 30d represents a natural month, not 30 days |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| interval | 10s |
| interval | 1m |
| interval | 5m |
| interval | 15m |
| interval | 30m |
| interval | 1h |
| interval | 4h |
| interval | 8h |
| interval | 1d |
| interval | 7d |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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/candlesticks'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"t": 1539852480,
"v": 97151,
"c": "1.032",
"h": "1.032",
"l": "1.032",
"o": "1.032",
"sum": "3580"
}
]
GET /futures/{settle}/premium_index
Premium Index K-line chart
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 | Specify the end time of the K-line chart, defaults to current time if not specified, note that the time format is Unix timestamp with second precision |
| limit | query | integer | false | Maximum number of recent data points to return. limit conflicts with from and to. If either from or to is specified, request will be rejected. |
| interval | query | string | false | Time interval between data points |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| interval | 10s |
| interval | 1m |
| interval | 5m |
| interval | 15m |
| interval | 30m |
| interval | 1h |
| interval | 4h |
| interval | 8h |
| interval | 1d |
| interval | 7d |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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/premium_index'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"t": 1539852480,
"c": "0",
"h": "0.00023",
"l": "0",
"o": "0"
}
]
GET /futures/{settle}/tickers
Get all futures trading statistics
| 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » contract | string | Futures contract |
| » last | string | Last trading price |
| » change_percentage | string | Price change percentage. Negative values indicate price decrease, e.g. -7.45 |
| » total_size | string | Contract total size |
| » low_24h | string | 24-hour lowest price |
| » high_24h | string | 24-hour highest price |
| » volume_24h | string | 24-hour trading volume |
| » volume_24h_btc | string | 24-hour trading volume in BTC (deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead) |
| » volume_24h_usd | string | 24-hour trading volume in USD (deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead) |
| » volume_24h_base | string | 24-hour trading volume in base currency |
| » volume_24h_quote | string | 24-hour trading volume in quote currency |
| » volume_24h_settle | string | 24-hour trading volume in settle currency |
| » mark_price | string | Recent mark price |
| » funding_rate | string | Funding rate |
| » funding_rate_indicative | string | Indicative Funding rate in next period. (deprecated. use funding_rate) |
| » 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 |
| » 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/tickers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
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"
}
]
GET /futures/{settle}/funding_rate
Futures market historical funding rate
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| limit | query | integer | false | Maximum number of records returned in a single list |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | History query successful | [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/funding_rate'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"t": 1543968000,
"r": "0.000157"
}
]
GET /futures/{settle}/insurance
Futures market insurance fund history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| limit | query | integer | false | Maximum number of records returned in a single list |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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/insurance'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"t": 1543968000,
"b": "83.0031"
}
]
GET /futures/{settle}/contract_stats
Futures statistics
| 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | integer(int64) | Stat timestamp |
| » lsr_taker | number | Long/short taker ratio |
| » lsr_account | number | Long/short position user ratio |
| » long_liq_size | integer(int64) | Long liquidation size (contracts) |
| » 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 (contracts) |
| » short_liq_amount | number(double) | Short liquidation amount (base currency) |
| » short_liq_usd | number(double) | Short liquidation volume (quote currency) |
| » open_interest | integer(int64) | Total open interest size (contracts) |
| » open_interest_usd | number(double) | Total 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/contract_stats'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
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
}
]
GET /futures/{settle}/index_constituents/{index}
Query 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | 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/index_constituents/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"index": "BTC_USDT",
"constituents": [
{
"exchange": "Binance",
"symbols": [
"BTC_USDT"
]
},
{
"exchange": "Gate.com",
"symbols": [
"BTC_USDT"
]
},
{
"exchange": "Huobi",
"symbols": [
"BTC_USDT"
]
}
]
}
GET /futures/{settle}/liq_orders
Query liquidation order history
The time interval between from and to is maximum 3600. Some private fields are not returned by public interfaces, refer to field descriptions for details
| 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 | Termination Timestamp |
| limit | query | integer | false | Maximum number of records returned in a single list |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | integer(int64) | Liquidation time |
| » contract | string | Futures contract |
| » size | integer(int64) | User position size |
| » order_size | integer(int64) | Number of forced liquidation orders |
| » 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/liq_orders'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"time": 1548654951,
"contract": "BTC_USDT",
"size": 600,
"order_size": -600,
"order_price": "3405",
"fill_price": "3424",
"left": 0
}
]
GET /futures/{settle}/risk_limit_tiers
Query 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 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 returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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 | Market, only visible when market pagination is requested |
| »» deduction | string | Maintenance margin quick calculation deduction 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 = '/futures/usdt/risk_limit_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"maintenance_rate": "0.01",
"tier": 1,
"initial_rate": "0.02",
"leverage_max": "50",
"risk_limit": "20000",
"contract": "ZTX_USDT",
"deduction": "0"
},
{
"maintenance_rate": "0.013",
"tier": 2,
"initial_rate": "0.025",
"leverage_max": "40",
"risk_limit": "30000",
"contract": "ZTX_USDT",
"deduction": "60"
},
{
"maintenance_rate": "0.015",
"tier": 3,
"initial_rate": "0.02857",
"leverage_max": "35",
"risk_limit": "50000",
"contract": "ZTX_USDT",
"deduction": "120"
},
{
"maintenance_rate": "0.02",
"tier": 4,
"initial_rate": "0.03333",
"leverage_max": "30",
"risk_limit": "70000",
"contract": "ZTX_USDT",
"deduction": "370"
},
{
"maintenance_rate": "0.025",
"tier": 5,
"initial_rate": "0.04",
"leverage_max": "25",
"risk_limit": "100000",
"contract": "ZTX_USDT",
"deduction": "720"
}
]
GET /futures/{settle}/accounts
Get futures account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | 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 | Available balance for transferring or trading (including bonus. Bonus cannot be withdrawn, so transfer amount needs to deduct bonus) |
| » point | string | Point card amount |
| » currency | string | Settlement 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 occupied by positions, applicable to unified account mode |
| » maintenance_margin | string | Maintenance margin occupied by positions, applicable to new classic account margin mode and unified account mode |
| » bonus | string | Bonus |
| » enable_evolved_classic | boolean | Classic account margin mode, true-new mode, false-old mode |
| » cross_order_margin | string | Cross margin order margin, applicable to new classic account margin mode |
| » cross_initial_margin | string | Cross margin initial margin, applicable to new classic account margin mode |
| » cross_maintenance_margin | string | Cross margin maintenance margin, applicable to new classic account margin mode |
| » cross_unrealised_pnl | string | Cross margin unrealized P&L, applicable to new classic account margin mode |
| » cross_available | string | Cross margin available balance, applicable to new classic account margin mode |
| » cross_margin_balance | string | Cross margin balance, applicable to new classic account margin mode |
| » cross_mmr | string | Cross margin maintenance margin rate, applicable to new classic account margin mode |
| » cross_imr | string | Cross margin initial margin rate, applicable to new classic account margin mode |
| » isolated_position_margin | string | Isolated position margin, applicable to new classic account margin mode |
| » enable_new_dual_mode | boolean | Whether to open a new two-way position mode |
| » margin_mode | integer | Margin mode, 0-classic margin mode, 1-cross-currency margin mode, 2-combined margin mode |
| » enable_tiered_mm | boolean | Whether to enable tiered maintenance margin calculation |
| » position_voucher_total | string | Total Position Experience Coupon Amount in Account |
| » 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/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())
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",
"cross_margin_balance": "10371.77306201952",
"cross_mmr": "797.2134",
"cross_imr": "116.6097",
"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"
},
"enable_tiered_mm": true
}
GET /futures/{settle}/account_book
Query futures account change history
If the contract field is passed, only records containing this field after 2023-10-30 can be filtered.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
| type | query | string | false | Changing Type: |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
type: Changing Type:
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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_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 | Account change record 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/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())
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"
}
]
GET /futures/{settle}/positions
Get user position list
| 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 returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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'
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())
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,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
GET /futures/{settle}/positions/{contract}
Get single position information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| 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'
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())
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,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
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 amount, positive number increases, negative number decreases |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| 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())
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,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
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 |
| 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())
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,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
POST /futures/{settle}/positions/cross_mode
Switch Position Margin Mode
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| body | body | object | true | none |
| » mode | body | string | true | Cross margin or isolated margin mode. ISOLATED - isolated margin mode, CROSS - cross margin mode |
| » contract | body | string | true | Futures market |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| 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/cross_mode'
query_param = ''
body='{"mode":"ISOLATED","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())
Body parameter
{
"mode": "ISOLATED",
"contract": "BTC_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,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
POST /futures/{settle}/dual_comp/positions/cross_mode
Switch Between Cross and Isolated Margin Modes Under Hedge Mode
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| body | body | object | true | none |
| » mode | body | string | true | Cross margin or isolated margin mode. ISOLATED - isolated margin mode, CROSS - cross margin mode |
| » contract | body | string | true | Futures market |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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/cross_mode'
query_param = ''
body='{"mode":"ISOLATED","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())
Body parameter
{
"mode": "ISOLATED",
"contract": "BTC_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,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
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 |
| 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())
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,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
POST /futures/{settle}/dual_mode
Set position mode
The prerequisite for changing mode is that all positions have no holdings and no pending orders
| 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Updated successfully | 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 | Available balance for transferring or trading (including bonus. Bonus cannot be withdrawn, so transfer amount needs to deduct bonus) |
| » point | string | Point card amount |
| » currency | string | Settlement 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 occupied by positions, applicable to unified account mode |
| » maintenance_margin | string | Maintenance margin occupied by positions, applicable to new classic account margin mode and unified account mode |
| » bonus | string | Bonus |
| » enable_evolved_classic | boolean | Classic account margin mode, true-new mode, false-old mode |
| » cross_order_margin | string | Cross margin order margin, applicable to new classic account margin mode |
| » cross_initial_margin | string | Cross margin initial margin, applicable to new classic account margin mode |
| » cross_maintenance_margin | string | Cross margin maintenance margin, applicable to new classic account margin mode |
| » cross_unrealised_pnl | string | Cross margin unrealized P&L, applicable to new classic account margin mode |
| » cross_available | string | Cross margin available balance, applicable to new classic account margin mode |
| » cross_margin_balance | string | Cross margin balance, applicable to new classic account margin mode |
| » cross_mmr | string | Cross margin maintenance margin rate, applicable to new classic account margin mode |
| » cross_imr | string | Cross margin initial margin rate, applicable to new classic account margin mode |
| » isolated_position_margin | string | Isolated position margin, applicable to new classic account margin mode |
| » enable_new_dual_mode | boolean | Whether to open a new two-way position mode |
| » margin_mode | integer | Margin mode, 0-classic margin mode, 1-cross-currency margin mode, 2-combined margin mode |
| » enable_tiered_mm | boolean | Whether to enable tiered maintenance margin calculation |
| » position_voucher_total | string | Total Position Experience Coupon Amount in Account |
| » 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_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())
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",
"cross_margin_balance": "10371.77306201952",
"cross_mmr": "797.2134",
"cross_imr": "116.6097",
"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"
},
"enable_tiered_mm": true
}
GET /futures/{settle}/dual_comp/positions/{contract}
Get position information 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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'
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())
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,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
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 amount, positive number increases, negative number decreases |
| dual_side | query | string | true | Long or short position |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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())
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,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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())
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,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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())
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,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
POST /futures/{settle}/orders
Place futures order
size, not the number of coins. The number of coins corresponding to each contract is returned in the contract details interface
quanto_multiplierreduce_only to true can prevent the position from being penetrated when reducing the positionsize to 0 and close to truereduce_only to true
at the same time - reduce_only: Make sure to only perform position reduction operations to prevent increased positionsstp_act to determine the use of a strategy that restricts user transactions. For detailed usage, refer to the body parameter stp_act| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | 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 | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| » iceberg | body | integer(int64) | false | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| » price | body | string | false | Order price. Price of 0 with tif set to ioc represents a market order. |
| » 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 | Custom order 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 prevention strategies |
|settle|path|string|true|Settle currency|
» tif: Time in force
» text: Custom order information. If not empty, must follow the rules below:
t-t- prefixIn addition to user-defined information, the following are internal reserved fields that identify the order source:
» stp_act: Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies
STP Group, they can pass stp_act to limit the user's self-trade prevention 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.stp_act when placing the order, stp_act will return '-'| 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 |
| 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 = ''
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())
Body parameter
{
"contract": "BTC_USDT",
"size": 6024,
"iceberg": 0,
"price": "3765",
"tif": "gtc",
"text": "t-my-custom-id",
"stp_act": "-"
}
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": "-"
}
GET /futures/{settle}/orders
Query futures order list
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 | Query order list based on status |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| last_id | query | string | false | Specify the currency name to query in batches, and support up to 100 pass parameters at a time |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [FuturesOrder] |
| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | X-Pagination-Limit | integer | Limit specified for pagination | |
| 200 | X-Pagination-Offset | integer | Offset specified for pagination |
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())
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": "-"
}
]
DELETE /futures/{settle}/orders
Cancel all orders with 'open' status
Zero-fill orders cannot be retrieved 10 minutes after order cancellation
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | 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 | Specify all buy orders or all sell orders, both are included if not specified. Set to bid, set to ask to cancel all sell ordersspecified. Set to bid, set to ask to cancel all sell ordersspecified. Set to bid, set to ask to cancel all sell orders |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation successful | [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 = '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())
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": "-"
}
]
GET /futures/{settle}/orders_timerange
Query futures order list 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 | Termination Timestamp |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [FuturesOrder] |
| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | X-Pagination-Limit | integer | Limit specified for pagination | |
| 200 | X-Pagination-Offset | integer | Offset specified for pagination |
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())
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": "-"
}
]
POST /futures/{settle}/batch_orders
Place batch futures orders
succeeded field of type bool indicates whether the execution was successful or notlabel field is included to indicate the cause of the error| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request execution completed | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Futures order details] |
| » None | object | Futures order details |
| »» succeeded | boolean | Request execution result |
| »» 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 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: Pending- finished: Completed |
| »» contract | string | Futures contract |
| »» size | integer(int64) | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| »» iceberg | integer(int64) | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| »» price | string | Order price. Price of 0 with tif set to ioc represents a market order. |
| »» 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) | Unfilled quantity |
| »» fill_price | string | Fill price |
| »» 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 | Referrer user ID |
| »» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention 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/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())
Body parameter
[
{
"contract": "BTC_USDT",
"size": 6024,
"iceberg": 0,
"price": "3765",
"tif": "gtc",
"text": "t-my-custom-id",
"stp_act": "-"
}
]
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": "-"
}
]
GET /futures/{settle}/orders/{order_id}
Query single order details
| 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. 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 |
| 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('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
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": "-"
}
DELETE /futures/{settle}/orders/{order_id}
Cancel single order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | 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. 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 |
| 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())
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": "-"
}
PUT /futures/{settle}/orders/{order_id}
Amend single order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | 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 order amendment |
| 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. 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 |
| 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())
Body parameter
{
"size": 100,
"price": "54321"
}
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": "-"
}
GET /futures/{settle}/my_trades
Query personal trading records
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 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | integer(int64) | Fill ID |
| » create_time | number(double) | Fill Time |
| » contract | string | Futures contract |
| » order_id | string | Related order ID |
| » 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 position 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 position close_size<0 && size<0 && size < close_size Close long position and open short position |
| » price | string | Fill Price |
| » role | string | Trade role. taker - taker, maker - maker |
| » text | string | Order custom information |
| » fee | string | Trade fee |
| » point_fee | string | Points used to deduct trade fee |
| Property | Value |
|---|---|
| role | taker |
| role | maker |
| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | X-Pagination-Limit | integer | Limit specified for pagination | |
| 200 | X-Pagination-Offset | integer | Offset specified for pagination |
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())
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
}
]
GET /futures/{settle}/my_trades_timerange
Query personal trading records 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 | Termination Timestamp |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| role | query | string | false | Query role, maker or taker |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » trade_id | string | Fill ID |
| » create_time | number(double) | Fill Time |
| » contract | string | Futures contract |
| » order_id | string | Related order ID |
| » 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 position 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 position close_size<0 && size<0 && size < close_size Close long position and open short position |
| » price | string | Fill Price |
| » role | string | Trade role. taker - taker, maker - maker |
| » text | string | Order custom information |
| » fee | string | Trade fee |
| » point_fee | string | Points used to deduct trade fee |
| Property | Value |
|---|---|
| role | taker |
| role | maker |
| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | X-Pagination-Limit | integer | Limit specified for pagination | |
| 200 | X-Pagination-Offset | integer | Offset specified for pagination |
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())
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
}
]
GET /futures/{settle}/position_close
Query 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 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 | Termination Timestamp |
| side | query | string | false | Query side. long or shot |
| pnl | query | string | false | Query profit or loss |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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: Long position- short: Short position |
| » pnl | string | PnL |
| » pnl_pnl | string | PNL - Position P/L |
| » pnl_fund | string | PNL - Funding Fees |
| » pnl_fee | string | PNL - Transaction Fees |
| » text | string | Source of close order. See order.text field for specific values |
| » 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 closing average price; when side is 'short', it indicates the opening 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/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())
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"
}
]
GET /futures/{settle}/liquidates
Query 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 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 | Termination Timestamp |
| at | query | integer | false | Specify liquidation timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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/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())
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
}
]
GET /futures/{settle}/auto_deleverages
Query ADL auto-deleveraging order information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
| at | query | integer | false | Specify auto-deleveraging timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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/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())
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
}
]
POST /futures/{settle}/countdown_cancel_all
Countdown cancel orders
Heartbeat detection for contract orders: When the user-set timeout time is reached, if neither the existing countdown is canceled nor a new countdown is set, the relevant contract orders will be automatically canceled.
This API can be called repeatedly to or cancel the countdown.
Usage example: Repeatedly call this API at 30-second intervals, setting the timeout to 30 (seconds) each time.
If this API is not called again within 30 seconds, all open orders on your specified market will be automatically canceled.
If the timeout is set to 0 within 30 seconds, the countdown timer will terminate, and the automatic order cancellation function will be disabled.
| 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 countdown
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Countdown set successfully | Inline |
Status Code 200
triggerTime
| Name | Type | Description |
|---|---|---|
| » triggerTime | integer(int64) | Timestamp when countdown ends, 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/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())
Body parameter
{
"timeout": 30,
"contract": "BTC_USDT"
}
Example responses
200 Response
{
"triggerTime": "1660039145000"
}
GET /futures/{settle}/fee
Query futures market 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
FuturesFee
| Name | Type | Description |
|---|---|---|
| » additionalProperties | object | The returned result is a map type, where the key represents the market and 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/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())
Example responses
200 Response
{
"1INCH_USDT": {
"taker_fee": "0.00025",
"maker_fee": "-0.00010"
},
"AAVE_USDT": {
"taker_fee": "0.00025",
"maker_fee": "-0.00010"
}
}
POST /futures/{settle}/batch_cancel_orders
Cancel batch orders by specified ID list
Multiple different order IDs can be specified, maximum 20 records per request
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | 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 |
| 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 description when cancellation fails, empty if successful |
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())
Body parameter
[
"1",
"2",
"3"
]
Example responses
200 Response
[
{
"user_id": 111,
"id": "123456",
"succeeded": true,
"message": ""
}
]
POST /futures/{settle}/batch_amend_orders
Batch modify orders by specified IDs
Multiple different order IDs can be specified, maximum 10 orders per request
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request execution completed | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Futures order details] |
| » None | object | Futures order details |
| »» succeeded | boolean | Request execution result |
| »» 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 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: Pending- finished: Completed |
| »» contract | string | Futures contract |
| »» size | integer(int64) | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| »» iceberg | integer(int64) | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| »» price | string | Order price. Price of 0 with tif set to ioc represents a market order. |
| »» 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) | Unfilled quantity |
| »» fill_price | string | Fill price |
| »» 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 | Referrer user ID |
| »» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention 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/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())
Body parameter
[
{
"order_id": 121212,
"amend_text": "batch amend text",
"size": 100,
"price": "54321"
}
]
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": "-"
}
]
GET /futures/{settle}/risk_limit_table
Query risk limit table by table_id
Just pass table_id
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| table_id | query | string | true | Risk limit table ID |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Information for each tier of the gradient risk limit table |
| »» 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 |
| »» deduction | string | Maintenance margin quick calculation deduction 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 = '/futures/usdt/risk_limit_table'
query_param = 'table_id=CYBER_USDT_20241122'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"tier": 1,
"risk_limit": "10000",
"initial_rate": "0.025",
"maintenance_rate": "0.015",
"leverage_max": "40",
"deduction": "0"
},
{
"tier": 2,
"risk_limit": "30000",
"initial_rate": "0.03333",
"maintenance_rate": "0.02",
"leverage_max": "30",
"deduction": "50"
},
{
"tier": 3,
"risk_limit": "50000",
"initial_rate": "0.04545",
"maintenance_rate": "0.03",
"leverage_max": "22",
"deduction": "350"
},
{
"tier": 4,
"risk_limit": "70000",
"initial_rate": "0.05555",
"maintenance_rate": "0.04",
"leverage_max": "18",
"deduction": "850"
},
{
"tier": 5,
"risk_limit": "100000",
"initial_rate": "0.1",
"maintenance_rate": "0.085",
"leverage_max": "10",
"deduction": "4000"
},
{
"tier": 6,
"risk_limit": "150000",
"initial_rate": "0.333",
"maintenance_rate": "0.3",
"leverage_max": "3",
"deduction": "25500"
},
{
"tier": 7,
"risk_limit": "200000",
"initial_rate": "0.5",
"maintenance_rate": "0.45",
"leverage_max": "2",
"deduction": "48000"
},
{
"tier": 8,
"risk_limit": "300000",
"initial_rate": "1",
"maintenance_rate": "0.95",
"leverage_max": "1",
"deduction": "148000"
}
]
POST /futures/{settle}/price_orders
Create price-triggered order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | FuturesPriceTriggeredOrder | true | none |
| » initial | body | object | true | none |
| »» contract | body | string | true | 合约标识 |
| »» size | body | integer(int64) | false | 代表需要平仓的合约张数, 全平仓:size=0 |
| »» price | body | string | true | 交易价, 当价格为 0 时, 表示通过市价方式来下单 |
| »» close | body | boolean | false | 单仓模式全部平仓时,必须设置为true执行平仓操作 |
| »» tif | body | string | false | Time in force 策略,默认为gtc, 市价单当前只支持 ioc 模式市价单当前只支持 ioc 模式 |
| »» text | body | string | false | 订单的来源, 包括: |
| »» reduce_only | body | boolean | false | 设置为 true 的时候执行自动减仓操作, 设为 true可确保订单不会开新仓, 只用于平仓或减仓 |
| »» auto_size | body | string | false | 单仓模式不需设置auto_size |
| » trigger | body | object | true | none |
| »» strategy_type | body | integer(int32) | false | 触发策略 |
| »» price_type | body | integer(int32) | false | 参考价格Type. 0 - 最新成交价, 1 - 标记价格, 2 - 指数价格 |
| »» price | body | string | false | 价格触发时为价格, 价差触发时为价差 |
| »» rule | body | integer(int32) | false | 价格条件Type |
| »» expiration | body | integer | false | 最长等待触发时间, 超时则取消该订单, 单位是秒 s |
| » order_type | body | string | false | Types of take-profit and stop-loss orders, including: |
| settle | path | string | true | Settle currency |
部分平仓:plan-close-short-position size>0 部分平仓:plan-close-long-position size<0
gtc: GoodTillCancelled
ioc: ImmediateOrCancelled
web: 网页
api: API 调用
app: 移动端
»» auto_size: 单仓模式不需设置auto_size
»» strategy_type: 触发策略
»» rule: 价格条件Type
strategy_type 和 price_type 算出的价格大于等于 Trigger.Price 时触发, 同时Trigger.Price must > last_pricestrategy_type 和 price_type 算出的价格小于等于 Trigger.Price 时触发, 同时Trigger.Price must < last_price» order_type: Types of take-profit and stop-loss orders, including:
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, used to close all long positionsclose-short-position: Position take-profit/stop-loss, used to close all short positionsplan-close-long-position: Position plan take-profit/stop-loss, used to close all or partial long positionsplan-close-short-position: Position plan take-profit/stop-loss, used to close all or partial short positionsThe two types of order take-profit/stop-loss are read-only and cannot be passed in requests
| 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order created successfully | 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 = ''
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())
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"
}
Example responses
201 Response
{
"id": 1432329
}
GET /futures/{settle}/price_orders
Query auto order list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| status | query | string | true | Query order list based on status |
| contract | query | string | false | Futures contract, return related data only if specified |
| limit | query | integer | false | Maximum number of records returned in 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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 = '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())
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"
}
]
DELETE /futures/{settle}/price_orders
Cancel all auto 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation request accepted and processed, success determined by order list | [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())
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"
}
]
GET /futures/{settle}/price_orders/{order_id}
Query single auto order details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| order_id | path | string | true | ID returned when order is successfully created |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Auto order details | 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())
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"
}
DELETE /futures/{settle}/price_orders/{order_id}
Cancel single auto order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| order_id | path | string | true | ID returned when order is successfully created |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Auto order details | 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())
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"
}
Delivery contract
GET /delivery/{settle}/contracts
Query all futures contracts
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
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
}
]
GET /delivery/{settle}/contracts/{contract}
Query single contract information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| Parameter | Value |
|---|---|
| settle | usdt |
| 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/contracts/BTC_USDT_20200814'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
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
}
GET /delivery/{settle}/order_book
Query futures market depth information
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 | Price precision for depth aggregation, 0 means no aggregation, defaults to 0 if not specified |
| limit | query | integer | false | Number of depth levels |
| with_id | query | boolean | false | Whether to return depth update ID. This ID increments by 1 each time depth changes |
| Parameter | Value |
|---|---|
| settle | usdt |
| interval | 0 |
| interval | 0.1 |
| interval | 0.01 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Depth query successful | 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 | Ask Depth |
| »» futures_order_book_item | object | none |
| »»» p | string | Price (quote currency) |
| »»» s | integer(int64) | Size |
| »» bids | array | Bid 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/order_book'
query_param = 'contract=BTC_USDT_20200814'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
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
}
]
}
GET /delivery/{settle}/trades
Futures market transaction records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| limit | query | integer | false | Maximum number of records returned in 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | integer(int64) | Fill ID |
| » create_time | number(double) | Fill Time |
| » create_time_ms | number(double) | Trade time, with millisecond precision to 3 decimal places |
| » contract | string | Futures contract |
| » size | integer(int64) | Trading size |
| » price | string | Trade price (quote currency) |
| » is_internal | boolean | Whether it is an 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 trade price may deviate from the market, 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/trades'
query_param = 'contract=BTC_USDT_20200814'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800,
"contract": "BTC_USDT",
"size": -100,
"price": "100.123"
}
]
GET /delivery/{settle}/candlesticks
Futures market K-line chart
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 | Specify the end time of the K-line chart, defaults to current time if not specified, note that the time format is Unix timestamp with second precision |
| limit | query | integer | false | Maximum number of recent data points to return. limit conflicts with from and to. If either from or to is specified, request will be rejected. |
| interval | query | string | false | Time interval between data points, note that 1w represents a natural week, 7d time is aligned with Unix initial time |
| 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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/candlesticks'
query_param = 'contract=BTC_USDT_20200814'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"t": 1539852480,
"v": 97151,
"c": "1.032",
"h": "1.032",
"l": "1.032",
"o": "1.032"
}
]
GET /delivery/{settle}/tickers
Get all futures trading statistics
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract |
| Parameter | Value |
|---|---|
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » contract | string | Futures contract |
| » last | string | Last trading price |
| » change_percentage | string | Price change percentage. Negative values indicate price decrease, e.g. -7.45 |
| » total_size | string | Contract total size |
| » low_24h | string | 24-hour lowest price |
| » high_24h | string | 24-hour highest price |
| » volume_24h | string | 24-hour trading volume |
| » volume_24h_btc | string | 24-hour trading volume in BTC (deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead) |
| » volume_24h_usd | string | 24-hour trading volume in USD (deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead) |
| » volume_24h_base | string | 24-hour trading volume in base currency |
| » volume_24h_quote | string | 24-hour trading volume in quote currency |
| » volume_24h_settle | string | 24-hour trading volume in settle currency |
| » mark_price | string | Recent mark price |
| » funding_rate | string | Funding rate |
| » funding_rate_indicative | string | Indicative Funding rate in next period. (deprecated. use funding_rate) |
| » 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/tickers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
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"
}
]
GET /delivery/{settle}/insurance
Futures market insurance fund history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| limit | query | integer | false | Maximum number of records returned in a single list |
| Parameter | Value |
|---|---|
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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 = '/delivery/usdt/insurance'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"t": 1543968000,
"b": "83.0031"
}
]
GET /delivery/{settle}/accounts
Get futures account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | 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 | Available balance for transferring or trading (including bonus. Bonus cannot be withdrawn, so transfer amount needs to deduct bonus) |
| » point | string | Point card amount |
| » currency | string | Settlement 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 occupied by positions, applicable to unified account mode |
| » maintenance_margin | string | Maintenance margin occupied by positions, applicable to new classic account margin mode and unified account mode |
| » bonus | string | Bonus |
| » enable_evolved_classic | boolean | Classic account margin mode, true-new mode, false-old mode |
| » cross_order_margin | string | Cross margin order margin, applicable to new classic account margin mode |
| » cross_initial_margin | string | Cross margin initial margin, applicable to new classic account margin mode |
| » cross_maintenance_margin | string | Cross margin maintenance margin, applicable to new classic account margin mode |
| » cross_unrealised_pnl | string | Cross margin unrealized P&L, applicable to new classic account margin mode |
| » cross_available | string | Cross margin available balance, applicable to new classic account margin mode |
| » cross_margin_balance | string | Cross margin balance, applicable to new classic account margin mode |
| » cross_mmr | string | Cross margin maintenance margin rate, applicable to new classic account margin mode |
| » cross_imr | string | Cross margin initial margin rate, applicable to new classic account margin mode |
| » isolated_position_margin | string | Isolated position margin, applicable to new classic account margin mode |
| » enable_new_dual_mode | boolean | Whether to open a new two-way position mode |
| » margin_mode | integer | Margin mode, 0-classic margin mode, 1-cross-currency margin mode, 2-combined margin mode |
| » enable_tiered_mm | boolean | Whether to enable tiered maintenance margin calculation |
| » position_voucher_total | string | Total Position Experience Coupon Amount in Account |
| » 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/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())
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",
"cross_margin_balance": "10371.77306201952",
"cross_mmr": "797.2134",
"cross_imr": "116.6097",
"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"
},
"enable_tiered_mm": true
}
GET /delivery/{settle}/account_book
Query futures account change history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| limit | query | integer | false | Maximum number of records returned in a single list |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
| type | query | string | false | Changing Type: |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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_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 | Account change record 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/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())
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"
}
]
GET /delivery/{settle}/positions
Get user position list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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'
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())
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,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
GET /delivery/{settle}/positions/{contract}
Get single position information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| Parameter | Value |
|---|---|
| settle | usdt |
| 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'
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())
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,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
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 amount, positive number increases, negative number decreases |
| Parameter | Value |
|---|---|
| settle | usdt |
| 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())
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,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
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 |
| 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())
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,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
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 |
| 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())
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,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
POST /delivery/{settle}/orders
Place futures order
Zero-fill orders cannot be retrieved 10 minutes after order cancellation
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | FuturesOrder | true | none |
| » contract | body | string | true | Futures contract |
| » size | body | integer(int64) | true | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| » iceberg | body | integer(int64) | false | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| » price | body | string | false | Order price. Price of 0 with tif set to ioc represents a market order. |
| » 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 | Custom order 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 prevention strategies |
|settle|path|string|true|Settle currency|
» tif: Time in force
» text: Custom order information. If not empty, must follow the rules below:
t-t- prefixIn addition to user-defined information, the following are internal reserved fields that identify the order source:
» stp_act: Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies
STP Group, they can pass stp_act to limit the user's self-trade prevention 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.stp_act when placing the order, stp_act will return '-'| 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 |
| 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 = ''
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())
Body parameter
{
"contract": "BTC_USDT",
"size": 6024,
"iceberg": 0,
"price": "3765",
"tif": "gtc",
"text": "t-my-custom-id",
"stp_act": "-"
}
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": "-"
}
GET /delivery/{settle}/orders
Query futures order list
Zero-fill orders cannot be retrieved 10 minutes after order cancellation
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | false | Futures contract |
| status | query | string | true | Query order list based on status |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| last_id | query | string | false | Specify the currency name to query in batches, and support up to 100 pass parameters at a time |
| count_total | query | integer | false | Whether to return total number matched, defaults to 0 (no return) |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| status | open |
| status | finished |
| count_total | 0 |
| count_total | 1 |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [FuturesOrder] |
| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | X-Pagination-Limit | integer | Limit specified for pagination | |
| 200 | X-Pagination-Offset | integer | Offset specified for pagination | |
| 200 | X-Pagination-Total | integer | Total number matched, only returned if count_total is 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/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())
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": "-"
}
]
DELETE /delivery/{settle}/orders
Cancel all orders with 'open' status
Zero-fill orders cannot be retrieved 10 minutes after order cancellation
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | true | Futures contract |
| side | query | string | false | Specify all bids or all asks, both included if not specified |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| side | ask |
| side | bid |
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation successful | [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 = '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())
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": "-"
}
]
GET /delivery/{settle}/orders/{order_id}
Query single order details
Zero-fill orders cannot be retrieved 10 minutes after order cancellation
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| order_id | path | string | true | ID returned when order is successfully created |
| Parameter | Value |
|---|---|
| settle | usdt |
| 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('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
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": "-"
}
DELETE /delivery/{settle}/orders/{order_id}
Cancel single order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| order_id | path | string | true | ID returned when order is successfully created |
| Parameter | Value |
|---|---|
| settle | usdt |
| 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())
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": "-"
}
GET /delivery/{settle}/my_trades
Query personal trading records
| 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 returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| last_id | query | string | false | Specify the currency name to query in batches, and support up to 100 pass parameters at a time |
| count_total | query | integer | false | Whether to return total number matched, defaults to 0 (no return) |
| Parameter | Value |
|---|---|
| settle | usdt |
| count_total | 0 |
| count_total | 1 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | integer(int64) | Fill ID |
| » create_time | number(double) | Fill Time |
| » contract | string | Futures contract |
| » order_id | string | Related order ID |
| » 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 position 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 position close_size<0 && size<0 && size < close_size Close long position and open short position |
| » price | string | Fill Price |
| » role | string | Trade role. taker - taker, maker - maker |
| » text | string | Order custom information |
| » fee | string | Trade fee |
| » point_fee | string | Points used to deduct trade fee |
| Property | Value |
|---|---|
| role | taker |
| role | maker |
| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | X-Pagination-Limit | integer | Limit specified for pagination | |
| 200 | X-Pagination-Offset | integer | Offset specified for pagination | |
| 200 | X-Pagination-Total | integer | Total number matched, only returned if count_total is 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/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())
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
}
]
GET /delivery/{settle}/position_close
Query 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 returned in a single list |
| Parameter | Value |
|---|---|
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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: Long position- short: Short position |
| » pnl | string | PnL |
| » pnl_pnl | string | PNL - Position P/L |
| » pnl_fund | string | PNL - Funding Fees |
| » pnl_fee | string | PNL - Transaction Fees |
| » text | string | Source of close order. See order.text field for specific values |
| » 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 closing average price; when side is 'short', it indicates the opening 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/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())
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"
}
]
GET /delivery/{settle}/liquidates
Query 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 returned in a single list |
| at | query | integer | false | Specify liquidation timestamp |
| Parameter | Value |
|---|---|
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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/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())
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
}
]
GET /delivery/{settle}/settlements
Query settlement records
| 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 returned in a single list |
| at | query | integer | false | Specify settlement timestamp |
| Parameter | Value |
|---|---|
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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
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())
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"
}
]
GET /delivery/{settle}/risk_limit_tiers
Query 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 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 returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Parameter | Value |
|---|---|
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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 | Market, only visible when market pagination is requested |
| »» deduction | string | Maintenance margin quick calculation deduction 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 = '/delivery/usdt/risk_limit_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"maintenance_rate": "0.01",
"tier": 1,
"initial_rate": "0.02",
"leverage_max": "50",
"risk_limit": "20000",
"contract": "ZTX_USDT",
"deduction": "0"
},
{
"maintenance_rate": "0.013",
"tier": 2,
"initial_rate": "0.025",
"leverage_max": "40",
"risk_limit": "30000",
"contract": "ZTX_USDT",
"deduction": "60"
},
{
"maintenance_rate": "0.015",
"tier": 3,
"initial_rate": "0.02857",
"leverage_max": "35",
"risk_limit": "50000",
"contract": "ZTX_USDT",
"deduction": "120"
},
{
"maintenance_rate": "0.02",
"tier": 4,
"initial_rate": "0.03333",
"leverage_max": "30",
"risk_limit": "70000",
"contract": "ZTX_USDT",
"deduction": "370"
},
{
"maintenance_rate": "0.025",
"tier": 5,
"initial_rate": "0.04",
"leverage_max": "25",
"risk_limit": "100000",
"contract": "ZTX_USDT",
"deduction": "720"
}
]
POST /delivery/{settle}/price_orders
Create price-triggered order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | FuturesPriceTriggeredOrder | true | none |
| » initial | body | object | true | none |
| »» contract | body | string | true | 合约标识 |
| »» size | body | integer(int64) | false | 代表需要平仓的合约张数, 全平仓:size=0 |
| »» price | body | string | true | 交易价, 当价格为 0 时, 表示通过市价方式来下单 |
| »» close | body | boolean | false | 单仓模式全部平仓时,必须设置为true执行平仓操作 |
| »» tif | body | string | false | Time in force 策略,默认为gtc, 市价单当前只支持 ioc 模式市价单当前只支持 ioc 模式 |
| »» text | body | string | false | 订单的来源, 包括: |
| »» reduce_only | body | boolean | false | 设置为 true 的时候执行自动减仓操作, 设为 true可确保订单不会开新仓, 只用于平仓或减仓 |
| »» auto_size | body | string | false | 单仓模式不需设置auto_size |
| » trigger | body | object | true | none |
| »» strategy_type | body | integer(int32) | false | 触发策略 |
| »» price_type | body | integer(int32) | false | 参考价格Type. 0 - 最新成交价, 1 - 标记价格, 2 - 指数价格 |
| »» price | body | string | false | 价格触发时为价格, 价差触发时为价差 |
| »» rule | body | integer(int32) | false | 价格条件Type |
| »» expiration | body | integer | false | 最长等待触发时间, 超时则取消该订单, 单位是秒 s |
| » order_type | body | string | false | Types of take-profit and stop-loss orders, including: |
| settle | path | string | true | Settle currency |
部分平仓:plan-close-short-position size>0 部分平仓:plan-close-long-position size<0
gtc: GoodTillCancelled
ioc: ImmediateOrCancelled
web: 网页
api: API 调用
app: 移动端
»» auto_size: 单仓模式不需设置auto_size
»» strategy_type: 触发策略
»» rule: 价格条件Type
strategy_type 和 price_type 算出的价格大于等于 Trigger.Price 时触发, 同时Trigger.Price must > last_pricestrategy_type 和 price_type 算出的价格小于等于 Trigger.Price 时触发, 同时Trigger.Price must < last_price» order_type: Types of take-profit and stop-loss orders, including:
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, used to close all long positionsclose-short-position: Position take-profit/stop-loss, used to close all short positionsplan-close-long-position: Position plan take-profit/stop-loss, used to close all or partial long positionsplan-close-short-position: Position plan take-profit/stop-loss, used to close all or partial short positionsThe two types of order take-profit/stop-loss are read-only and cannot be passed in requests
| 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order created successfully | 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 = ''
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())
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"
}
Example responses
201 Response
{
"id": 1432329
}
GET /delivery/{settle}/price_orders
Query auto order list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| status | query | string | true | Query order list based on status |
| contract | query | string | false | Futures contract, return related data only if specified |
| limit | query | integer | false | Maximum number of records returned in 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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 = '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())
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"
}
]
DELETE /delivery/{settle}/price_orders
Cancel all auto orders
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | true | Futures contract |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation request accepted and processed, success determined by order list | [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())
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"
}
]
GET /delivery/{settle}/price_orders/{order_id}
Query single auto order details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| order_id | path | string | true | ID returned when order is successfully created |
| Parameter | Value |
|---|---|
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Auto order details | 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())
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"
}
DELETE /delivery/{settle}/price_orders/{order_id}
Cancel single auto order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| order_id | path | string | true | ID returned when order is successfully created |
| Parameter | Value |
|---|---|
| settle | usdt |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Auto order details | 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())
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"
}
Options API
GET /options/underlyings
List all underlying assets
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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/underlyings'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"name": "BTC_USDT",
"index_price": "70000"
}
]
GET /options/expirations
List all expiration dates
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | true | Underlying (Obtained by listing underlying endpoint) |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List expiration dates for specified underlying | [integer] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | integer(int64) | Unix timestamp of expiration date |
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())
Example responses
200 Response
[
1637913600
]
GET /options/contracts
List all contracts for specified underlying and expiration date
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | true | Underlying (Obtained by listing underlying endpoint) |
| expiration | query | integer(int64) | false | Unix timestamp of expiration date |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Options contract details] |
| » None | object | Options contract details |
| »» name | string | Options contract name |
| »» tag | string | Tag |
| »» create_time | number(double) | Created time |
| »» expiration_time | number(double) | Expiration time |
| »» is_call | boolean | true means call options, false means 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, negative values indicate rebates |
| »» 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 allowed by the contract |
| »» order_size_max | integer(int64) | Maximum order size allowed by the contract |
| »» order_price_deviate | string | The positive and negative offset allowed between the order price and the current mark price, that 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 | Trading fee discount for referred users |
| »» ref_rebate_rate | string | Commission rate for referrers |
| »» orderbook_id | integer(int64) | Orderbook update ID |
| »» trade_id | integer(int64) | Current trade ID |
| »» trade_size | integer(int64) | Historical cumulative trading volume |
| »» position_size | integer(int64) | Current total long position size |
| »» orders_limit | integer | Maximum number of pending 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'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
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
}
]
GET /options/contracts/{contract}
Query specified contract details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | path | string | true | none |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
Options contract details
| Name | Type | Description |
|---|---|---|
| » name | string | Options contract name |
| » tag | string | Tag |
| » create_time | number(double) | Created time |
| » expiration_time | number(double) | Expiration time |
| » is_call | boolean | true means call options, false means 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, negative values indicate rebates |
| » 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 allowed by the contract |
| » order_size_max | integer(int64) | Maximum order size allowed by the contract |
| » order_price_deviate | string | The positive and negative offset allowed between the order price and the current mark price, that 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 | Trading fee discount for referred users |
| » ref_rebate_rate | string | Commission rate for referrers |
| » orderbook_id | integer(int64) | Orderbook update ID |
| » trade_id | integer(int64) | Current trade ID |
| » trade_size | integer(int64) | Historical cumulative trading volume |
| » position_size | integer(int64) | Current total long position size |
| » orders_limit | integer | Maximum number of pending 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())
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
}
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 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 | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » time | number(double) | Last configuration update time |
| » contract | string | Options contract name |
| » profit | string | Settlement profit per contract (quote currency) |
| » fee | string | Settlement fee per contract (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'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
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"
}
]
GET /options/settlements/{contract}
Get specified contract settlement information
| 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | number(double) | Last configuration update time |
| » contract | string | Options contract name |
| » profit | string | Settlement profit per contract (quote currency) |
| » fee | string | Settlement fee per contract (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())
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"
}
GET /options/my_settlements
Query personal settlement records
| 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 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 | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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) | Settlement size |
| » settle_profit | string | Settlement profit (quote currency) |
| » fee | string | Settlement fee (quote currency) |
| » realised_pnl | string | Accumulated profit and loss from opening positions, including premium, fees, 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
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())
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"
}
]
GET /options/order_book
Query options contract 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 | Price precision for depth aggregation, 0 means no aggregation, defaults to 0 if not specified |
| limit | query | integer | false | Number of depth levels |
| with_id | query | boolean | false | Whether to return depth update ID. This ID increments by 1 each time depth changes |
| Parameter | Value |
|---|---|
| interval | 0 |
| interval | 0.1 |
| interval | 0.01 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Depth query successful | 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 | Ask Depth |
| »» futures_order_book_item | object | none |
| »»» p | string | Price (quote currency) |
| »»» s | integer(int64) | Size |
| »» bids | array | Bid 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/order_book'
query_param = 'contract=BTC_USDT-20210916-5000-C'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
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
}
]
}
GET /options/tickers
Query options market ticker information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | true | Underlying (Obtained by listing underlying endpoint) |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Options contract details |
| »» name | string | Options contract name |
| »» last_price | string | Last trade 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 | Greek letter delta |
| »» gamma | string | Greek letter gamma |
| »» vega | string | Greek letter vega |
| »» theta | string | Greek letter 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/tickers'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
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"
}
]
GET /options/underlying/tickers/{underlying}
Query underlying ticker information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | path | string | true | Underlying |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | 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/underlying/tickers/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"trade_put": 33505,
"trade_call": 123,
"index_price": "76543.3"
}
GET /options/candlesticks
Options contract market candlestick chart
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | true | Options contract name |
| limit | query | integer | false | Maximum number of records returned in a single list |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
| interval | query | string | false | Time interval between data points |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| interval | 1m |
| interval | 5m |
| interval | 15m |
| interval | 30m |
| interval | 1h |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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/candlesticks'
query_param = 'contract=BTC_USDT-20210916-5000-C'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"t": 1539852480,
"v": 97151,
"c": "1.032",
"h": "1.032",
"l": "1.032",
"o": "1.032"
}
]
GET /options/underlying/candlesticks
Underlying index price candlestick chart
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | true | Underlying (Obtained by listing underlying endpoint) |
| limit | query | integer | false | Maximum number of records returned in a single list |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
| interval | query | string | false | Time interval between data points |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| interval | 1m |
| interval | 5m |
| interval | 15m |
| interval | 30m |
| interval | 1h |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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/underlying/candlesticks'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"t": 1539852480,
"v": 97151,
"c": "1.032",
"h": "1.032",
"l": "1.032",
"o": "1.032",
"sum": "3580"
}
]
GET /options/trades
Market trade records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | false | Options contract name |
| type | query | string(P) | false | C for call, P for put |
| limit | query | integer | false | Maximum number of records 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 | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | integer(int64) | Fill ID |
| » create_time | number(double) | Fill Time |
| » create_time_ms | number(double) | Trade time, with millisecond precision to 3 decimal places |
| » contract | string | Futures contract |
| » size | integer(int64) | Trading size |
| » price | string | Trade price (quote currency) |
| » is_internal | boolean | Whether it is an 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 trade price may deviate from the market, 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 = '/options/trades'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800,
"contract": "BTC_USDT",
"size": -100,
"price": "100.123"
}
]
GET /options/accounts
Query account information
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » user | integer(int64) | User ID |
| » total | string | Account Balance |
| » position_value | string | Position value, long position value is positive, short position value is negative |
| » equity | string | Account equity, the sum of account balance and position value |
| » short_enabled | boolean | If the account is allowed to short |
| » mmp_enabled | boolean | Whether to enable MMP |
| » liq_triggered | boolean | Whether to trigger position liquidation |
| » margin_mode | integer(int32) | ｜ Margin模式: - 0: 经典SpotMargin模式 - 1: 跨CurrencyMargin模式 - 2: 组合Margin模式 |
| » 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 | Margin for outstanding sell orders |
| » bid_order_margin | string | Margin for outstanding buy orders |
| » available | string | Available balance to transfer out or trade |
| » point | string | Point card amount |
| » currency | string | Settlement currency |
| » orders_limit | integer(int32) | Maximum number of outstanding orders |
| » position_notional_limit | integer(int64) | Notional value upper limit, including the nominal value of positions and outstanding orders |
| 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/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())
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
}
GET /options/account_book
Query account change history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| limit | query | integer | false | Maximum number of records 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 | Termination Timestamp |
| type | query | string | false | Change types: |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
type: Change types:
| Parameter | Value |
|---|---|
| type | dnw |
| type | prem |
| type | fee |
| type | refr |
| type | set |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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_fee: POINT Trading fee - point_refr: POINT Referrer rebate |
| » text | string | Remark |
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())
Example responses
200 Response
[
{
"time": 1636426005,
"change": "-0.16",
"balance": "7378.189",
"text": "BTC_USDT-20211216-5000-P:25",
"type": "fee"
}
]
GET /options/positions
List user's positions of specified underlying
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | false | Underlying |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Options contract position details] |
| » None | object | Options contract position details |
| »» 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 quantity) |
| »» 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 pending order quantity |
| »» close_order | object|null | Current close order information, or null if no close order |
| »»» id | integer(int64) | Order ID |
| »»» price | string | Order price (quote currency) |
| »»» is_liq | boolean | Whether the close order is from liquidation |
| »» delta | string | Greek letter delta |
| »» gamma | string | Greek letter gamma |
| »» vega | string | Greek letter vega |
| »» theta | string | Greek letter 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'
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())
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"
}
]
GET /options/positions/{contract}
Get specified contract position
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | path | string | true | none |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
Options contract position details
| 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 quantity) |
| » 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 pending order quantity |
| » close_order | object|null | Current close order information, or null if no close order |
| »» id | integer(int64) | Order ID |
| »» price | string | Order price (quote currency) |
| »» is_liq | boolean | Whether the close order is from liquidation |
| » delta | string | Greek letter delta |
| » gamma | string | Greek letter gamma |
| » vega | string | Greek letter vega |
| » theta | string | Greek letter 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())
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"
}
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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | number(double) | Position close time |
| » contract | string | Options contract name |
| » side | string | Position side - long: Long position- short: Short position |
| » pnl | string | PnL |
| » text | string | Source of close order. See order.text field for specific values |
| » 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/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())
Example responses
200 Response
[
{
"time": 1631764800,
"pnl": "-42914.291",
"settle_size": "-10001",
"side": "short",
"contract": "BTC_USDT-20210916-5000-C",
"text": "settled"
}
]
POST /options/orders
Create an options order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » contract | body | string | true | Options identifier |
| » size | body | integer(int64) | true | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| » iceberg | body | integer(int64) | false | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| » price | body | string | false | Order price. Price of 0 with tif set as ioc represents market order (quote currency) |
| » 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 | When set to true, it is an MMP order |
| » tif | body | string | false | Time in force strategy. Market orders currently only support IOC mode |
| » text | body | string | false | User defined information. If not empty, must follow the rules below: |
» tif: Time in force strategy. Market orders currently only support IOC mode
» text: User defined information. If not empty, must follow the rules below:
t-t- prefix| Parameter | Value |
|---|---|
| » tif | gtc |
| » tif | ioc |
| » tif | poc |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order detail | Inline |
Status Code 201
Options order details
| 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 | Order finish reason: - filled: Fully filled - cancelled: User cancelled - liquidated: Cancelled due to liquidation - ioc: Not immediately fully filled due to IOC time-in-force setting - auto_deleveraged: Cancelled due to auto-deleveraging - reduce_only: Cancelled due to position increase while reduce-only is set - position_closed: Cancelled because the position was closed - reduce_out: Only reduce positions by excluding hard-to-fill orders - mmp_cancelled: Cancelled by MMP |
| » status | string | Order status - open: Pending- finished: Completed |
| » contract | string | Options identifier |
| » size | integer(int64) | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| » iceberg | integer(int64) | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| » price | string | Order price. Price of 0 with tif set as ioc represents market order (quote currency) |
| » 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 | Whether it is an MMP order. Corresponds to mmp in the request |
| » tif | string | Time in force strategy. Market orders currently only support IOC mode - gtc: Good Till Cancelled - ioc: Immediate Or Cancelled, execute immediately or cancel, taker only - poc: Pending Or Cancelled, passive order, maker only |
| » left | integer(int64) | Unfilled quantity |
| » fill_price | string | Fill price |
| » 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 | Referrer 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 = ''
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())
Body parameter
{
"size": -1,
"iceberg": 0,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"tif": "gtc",
"price": "100"
}
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"
}
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 | Query order list based on status |
| limit | query | integer | false | Maximum number of records 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 | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| status | open |
| status | finished |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Options order details] |
| » None | object | Options order details |
| »» 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 | Order finish reason: - filled: Fully filled - cancelled: User cancelled - liquidated: Cancelled due to liquidation - ioc: Not immediately fully filled due to IOC time-in-force setting - auto_deleveraged: Cancelled due to auto-deleveraging - reduce_only: Cancelled due to position increase while reduce-only is set - position_closed: Cancelled because the position was closed - reduce_out: Only reduce positions by excluding hard-to-fill orders - mmp_cancelled: Cancelled by MMP |
| »» status | string | Order status - open: Pending- finished: Completed |
| »» contract | string | Options identifier |
| »» size | integer(int64) | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| »» iceberg | integer(int64) | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| »» price | string | Order price. Price of 0 with tif set as ioc represents market order (quote currency) |
| »» 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 | Whether it is an MMP order. Corresponds to mmp in the request |
| »» tif | string | Time in force strategy. Market orders currently only support IOC mode - gtc: Good Till Cancelled - ioc: Immediate Or Cancelled, execute immediately or cancel, taker only - poc: Pending Or Cancelled, passive order, maker only |
| »» left | integer(int64) | Unfilled quantity |
| »» fill_price | string | Fill price |
| »» 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 | Referrer 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())
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"
}
]
DELETE /options/orders
Cancel all orders with 'open' status
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | false | Options contract name |
| underlying | query | string | false | Underlying |
| side | query | string | false | Specify all bids or all asks, both included if not specified |
| Parameter | Value |
|---|---|
| side | ask |
| side | bid |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Options order details] |
| » None | object | Options order details |
| »» 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 | Order finish reason: - filled: Fully filled - cancelled: User cancelled - liquidated: Cancelled due to liquidation - ioc: Not immediately fully filled due to IOC time-in-force setting - auto_deleveraged: Cancelled due to auto-deleveraging - reduce_only: Cancelled due to position increase while reduce-only is set - position_closed: Cancelled because the position was closed - reduce_out: Only reduce positions by excluding hard-to-fill orders - mmp_cancelled: Cancelled by MMP |
| »» status | string | Order status - open: Pending- finished: Completed |
| »» contract | string | Options identifier |
| »» size | integer(int64) | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| »» iceberg | integer(int64) | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| »» price | string | Order price. Price of 0 with tif set as ioc represents market order (quote currency) |
| »» 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 | Whether it is an MMP order. Corresponds to mmp in the request |
| »» tif | string | Time in force strategy. Market orders currently only support IOC mode - gtc: Good Till Cancelled - ioc: Immediate Or Cancelled, execute immediately or cancel, taker only - poc: Pending Or Cancelled, passive order, maker only |
| »» left | integer(int64) | Unfilled quantity |
| »» fill_price | string | Fill price |
| »» 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 | Referrer 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 = ''
# 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())
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"
}
]
GET /options/orders/{order_id}
Query single order details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | integer(int64) | true | Order ID returned when order is successfully created |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order detail | Inline |
Status Code 200
Options order details
| 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 | Order finish reason: - filled: Fully filled - cancelled: User cancelled - liquidated: Cancelled due to liquidation - ioc: Not immediately fully filled due to IOC time-in-force setting - auto_deleveraged: Cancelled due to auto-deleveraging - reduce_only: Cancelled due to position increase while reduce-only is set - position_closed: Cancelled because the position was closed - reduce_out: Only reduce positions by excluding hard-to-fill orders - mmp_cancelled: Cancelled by MMP |
| » status | string | Order status - open: Pending- finished: Completed |
| » contract | string | Options identifier |
| » size | integer(int64) | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| » iceberg | integer(int64) | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| » price | string | Order price. Price of 0 with tif set as ioc represents market order (quote currency) |
| » 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 | Whether it is an MMP order. Corresponds to mmp in the request |
| » tif | string | Time in force strategy. Market orders currently only support IOC mode - gtc: Good Till Cancelled - ioc: Immediate Or Cancelled, execute immediately or cancel, taker only - poc: Pending Or Cancelled, passive order, maker only |
| » left | integer(int64) | Unfilled quantity |
| » fill_price | string | Fill price |
| » 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 | Referrer 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())
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"
}
DELETE /options/orders/{order_id}
Cancel single order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | integer(int64) | true | Order ID returned when order is successfully created |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order detail | Inline |
Status Code 200
Options order details
| 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 | Order finish reason: - filled: Fully filled - cancelled: User cancelled - liquidated: Cancelled due to liquidation - ioc: Not immediately fully filled due to IOC time-in-force setting - auto_deleveraged: Cancelled due to auto-deleveraging - reduce_only: Cancelled due to position increase while reduce-only is set - position_closed: Cancelled because the position was closed - reduce_out: Only reduce positions by excluding hard-to-fill orders - mmp_cancelled: Cancelled by MMP |
| » status | string | Order status - open: Pending- finished: Completed |
| » contract | string | Options identifier |
| » size | integer(int64) | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| » iceberg | integer(int64) | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| » price | string | Order price. Price of 0 with tif set as ioc represents market order (quote currency) |
| » 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 | Whether it is an MMP order. Corresponds to mmp in the request |
| » tif | string | Time in force strategy. Market orders currently only support IOC mode - gtc: Good Till Cancelled - ioc: Immediate Or Cancelled, execute immediately or cancel, taker only - poc: Pending Or Cancelled, passive order, maker only |
| » left | integer(int64) | Unfilled quantity |
| » fill_price | string | Fill price |
| » 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 | Referrer 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())
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"
}
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, 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.
| 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 countdown
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Countdown set successfully | Inline |
Status Code 200
triggerTime
| Name | Type | Description |
|---|---|---|
| » triggerTime | integer(int64) | Timestamp when countdown ends, 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/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())
Body parameter
{
"timeout": 30,
"contract": "BTC_USDT-20241001-46000-C",
"underlying": "BTC_USDT"
}
Example responses
200 Response
{
"triggerTime": "1660039145000"
}
GET /options/my_trades
Query personal trading records
| 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 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 | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Fill ID |
| » create_time | number(double) | Fill Time |
| » contract | string | Options contract name |
| » order_id | integer | Related order ID |
| » size | integer(int64) | Trading size |
| » price | string | Trade price (quote currency) |
| » underlying_price | string | Underlying price (quote currency) |
| » role | string | Trade role. taker - taker, maker - 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/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())
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"
}
]
POST /options/mmp
MMP Settings
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » underlying | body | string | true | Underlying |
| » window | body | integer(int32) | true | Time window (milliseconds), between 1-5000, 0 means disable MMP |
| » frozen_period | body | integer(int32) | true | Freeze duration (milliseconds), 0 means always frozen, need to call reset API to unfreeze |
| » qty_limit | body | string | true | Trading volume upper limit (positive number, up to 2 decimal places) |
| » delta_limit | body | string | true | Upper limit of net delta value (positive number, up to 2 decimal places) |
| 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) | Time window (milliseconds), between 1-5000, 0 means disable MMP |
| » frozen_period | integer(int32) | Freeze duration (milliseconds), 0 means always frozen, need to call reset API to unfreeze |
| » qty_limit | string | Trading volume upper limit (positive number, up to 2 decimal places) |
| » delta_limit | string | Upper limit of net delta value (positive number, up to 2 decimal places) |
| » trigger_time_ms | integer(int64) | Trigger freeze time (milliseconds), 0 means no freeze is triggered |
| » frozen_until_ms | integer(int64) | Unfreeze time (milliseconds). If the freeze duration is not configured, there will be no unfreeze time after the freeze is triggered |
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())
Body parameter
{
"underlying": "BTC_USDT",
"window": 5000,
"frozen_period": 200,
"qty_limit": "10",
"delta_limit": "10"
}
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
}
GET /options/mmp
MMP Query.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | false | Underlying |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [MMP Settings] |
| » None | object | MMP Settings |
| »» underlying | string | Underlying |
| »» window | integer(int32) | Time window (milliseconds), between 1-5000, 0 means disable MMP |
| »» frozen_period | integer(int32) | Freeze duration (milliseconds), 0 means always frozen, need to call reset API to unfreeze |
| »» qty_limit | string | Trading volume upper limit (positive number, up to 2 decimal places) |
| »» delta_limit | string | Upper limit of net delta value (positive number, up to 2 decimal places) |
| »» trigger_time_ms | integer(int64) | Trigger freeze time (milliseconds), 0 means no freeze is triggered |
| »» frozen_until_ms | integer(int64) | Unfreeze time (milliseconds). If the freeze duration is not configured, there will be no unfreeze time after the freeze is triggered |
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())
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
}
]
POST /options/mmp/reset
MMP Reset
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » underlying | body | string | true | Underlying |
| 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) | Time window (milliseconds), between 1-5000, 0 means disable MMP |
| » frozen_period | integer(int32) | Freeze duration (milliseconds), 0 means always frozen, need to call reset API to unfreeze |
| » qty_limit | string | Trading volume upper limit (positive number, up to 2 decimal places) |
| » delta_limit | string | Upper limit of net delta value (positive number, up to 2 decimal places) |
| » trigger_time_ms | integer(int64) | Trigger freeze time (milliseconds), 0 means no freeze is triggered |
| » frozen_until_ms | integer(int64) | Unfreeze time (milliseconds). If the freeze duration is not configured, there will be no unfreeze time after the freeze is triggered |
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())
Body parameter
{
"underlying": "BTC_USDT"
}
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
}
Lend & Earn
GET /earn/uni/currencies
Query lending currency list
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "AE",
"min_lend_amount": "100",
"max_lend_amount": "200000000",
"max_rate": "0.00057",
"min_rate": "0.000001"
}
]
GET /earn/uni/currencies/{currency}
Query single lending currency details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | true | Currency |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | 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
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())
Example responses
200 Response
{
"currency": "AE",
"min_lend_amount": "100",
"max_lend_amount": "200000000",
"max_rate": "0.00057",
"min_rate": "0.000001"
}
POST /earn/uni/lends
Create lending or redemption
Lending: When lending, a minimum lending rate must be set. After successful lending is determined on an hourly basis, earnings will be calculated based on the determined rate. Earnings for each hour will be settled at the top of the hour. If lending fails due to an excessively high interest rate, no interest will be earned for that hour. If funds are redeemed before the hourly for that hour. Priority: Under the same interest rate, wealth management products created or modified earlier will be prioritized for lending. Redemption: For funds that failed to be lent, redemption will be credited immediately. For funds successfully lent, they are entitled to the earnings for that hour, and redemption will be credited in the next hourly interval. Note: The two minutes before and after the hourly mark are the settlement period, during which lending and redemption are prohibited.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Currency name |
| » amount | body | string | true | Amount to deposit into lending pool |
| » type | body | string | true | Operation type: lend - Lend, redeem - Redeem |
| » min_rate | body | string | false | Minimum interest rate. If set too high, lending may fail and no interest will be earned. Required for lending operations. |
| Parameter | Value |
|---|---|
| » type | lend |
| » type | redeem |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Operation successful | 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 = ''
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())
Body parameter
{
"currency": "AE",
"amount": "100",
"min_rate": "0.00001",
"type": "lend"
}
GET /earn/uni/lends
Query user's lending order list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum number of items returned. Default: 100, minimum: 1, maximum: 100 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Loan record |
| »» currency | string | Currency |
| »» current_amount | string | Current amount |
| »» amount | string | Total Lending Amount |
| »» lent_amount | string | Lent Amount |
| »» frozen_amount | string | Pending Redemption Amount |
| »» min_rate | string | Minimum interest rate |
| »» interest_status | string | Interest status: interest_dividend - Normal dividend, interest_reinvest - Interest reinvestment |
| »» reinvest_left_amount | string | Non-reinvested Amount |
| »» create_time | integer(int64) | Lending Order Creation Time |
| »» update_time | integer(int64) | Lending Order Last 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 = '/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())
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
}
]
PATCH /earn/uni/lends
Amend user lending information
Currently only supports amending minimum interest rate (hourly)
| 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 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 = ''
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())
Body parameter
{
"currency": "AE",
"min_rate": "0.0001"
}
GET /earn/uni/lend_records
Query lending transaction records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum number of items returned. Default: 100, minimum: 1, maximum: 100 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
| type | query | string | false | Operation type: lend - Lend, redeem - Redeem |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| type | lend |
| type | redeem |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Lending Record |
| »» currency | string | Currency name |
| »» amount | string | Current Amount |
| »» last_wallet_amount | string | Previous Available Amount |
| »» last_lent_amount | string | Previous Lent Amount |
| »» last_frozen_amount | string | Previous 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/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())
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
}
]
GET /earn/uni/interests/{currency}
Query user's total interest income for specified currency
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | true | Currency |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
UniLendInterest
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency |
| » interest | string | Interest income |
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())
Example responses
200 Response
{
"currency": "AE",
"interest": "123.345"
}
GET /earn/uni/interest_records
Query user dividend records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum number of items returned. Default: 100, minimum: 1, maximum: 100 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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 - Normal 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_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())
Example responses
200 Response
[
{
"status": 1,
"currency": "AE",
"actual_rate": "0.0005",
"interest": "0.05",
"interest_status": "interest_dividend",
"create_time": 1673247054000
}
]
GET /earn/uni/interest_status/{currency}
Query currency interest compounding status
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | true | Currency |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
UniCurrencyInterest
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency |
| » interest_status | string | Interest status: interest_dividend - Normal dividend, interest_reinvest - Interest reinvestment |
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())
Example responses
200 Response
{
"currency": "BTC",
"interest_status": "interest_dividend"
}
GET /earn/uni/chart
UniLoan currency annualized trend chart
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| from | query | integer(int64) | true | Start timestamp in seconds, maximum span 30 days |
| to | query | integer(int64) | true | End timestamp in seconds, maximum span 30 days |
| asset | query | string | true | Currency name |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | none | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | integer(int64) | none |
| » value | 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 = '/earn/uni/chart'
query_param = 'from=1719763200&to=1722441600&asset=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())
Example responses
200 Response
[
{
"time": 1719705600,
"value": "0.01"
}
]
GET /earn/uni/rate
Currency estimated annualized interest rate
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | none | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency | string | none |
| » est_rate | string | Unconverted percentage |
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/rate'
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())
Example responses
200 Response
[
{
"currency": "USDT",
"est_rate": "0.0226"
}
]
Collateral loan, only for single currency collateral
POST /loan/collateral/orders
Place collateral loan order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » collateral_amount | body | string | true | Collateral amount |
| » collateral_currency | body | string | true | Collateral currency |
| » borrow_amount | body | string | true | Borrowed amount |
| » borrow_currency | body | string | true | Borrowed currency |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order placed successfully | 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 = ''
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())
Body parameter
{
"collateral_amount": "1",
"collateral_currency": "BTC",
"borrow_amount": "49",
"borrow_currency": "USDT"
}
Example responses
200 Response
{
"order_id": 10005578
}
GET /loan/collateral/orders
Query collateral loan order list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records returned in a single list |
| collateral_currency | query | string | false | Collateral currency |
| borrow_currency | query | string | false | Borrowed currency |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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 currency |
| »» collateral_amount | string | Collateral amount |
| »» borrow_currency | string | Borrowed currency |
| »» borrow_amount | string | Borrowed amount |
| »» repaid_amount | string | Repaid amount |
| »» repaid_principal | string | Repaid principal |
| »» repaid_interest | string | Repaid interest |
| »» init_ltv | string | Initial collateralization rate |
| »» current_ltv | string | Current collateralization rate |
| »» liquidate_ltv | string | 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'
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())
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"
}
]
GET /loan/collateral/orders/{order_id}
Query single order details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | integer(int64) | true | Order ID returned when order is successfully created |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order details queried successfully | Inline |
Status Code 200
Collateral order
| Name | Type | Description |
|---|---|---|
| » order_id | integer(int64) | Order ID |
| » collateral_currency | string | Collateral currency |
| » collateral_amount | string | Collateral amount |
| » borrow_currency | string | Borrowed currency |
| » borrow_amount | string | Borrowed amount |
| » repaid_amount | string | Repaid amount |
| » repaid_principal | string | Repaid principal |
| » repaid_interest | string | Repaid interest |
| » init_ltv | string | Initial collateralization rate |
| » current_ltv | string | Current collateralization rate |
| » liquidate_ltv | string | 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())
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"
}
POST /loan/collateral/repay
Collateral loan repayment
| 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 partial repayment, the repay_amount parameter cannot be greater than the remaining amount to be repaid by the user.
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Operation successful | 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'
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())
Body parameter
{
"order_id": 37438962,
"repay_amount": "1000",
"repaid_all": false
}
Example responses
200 Response
{
"repaid_principal": "11",
"repaid_interest": "111"
}
GET /loan/collateral/repay_records
Query collateral loan repayment records
| 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 currency |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records returned in a single list |
| from | query | integer(int64) | false | Start timestamp for the query |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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 currency |
| »» init_ltv | string | 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 amount before repayment |
| »» after_left_collateral | string | Collateral amount 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/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())
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"
}
]
POST /loan/collateral/collaterals
Increase or redeem collateral
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » order_id | body | integer(int64) | true | Order ID |
| » collateral_currency | body | string | true | Collateral currency |
| » collateral_amount | body | string | true | Collateral amount |
| » type | body | string | true | Operation type: append - add collateral, redeem - withdraw collateral |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Operation successful | 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 = ''
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())
Body parameter
{
"collateral_amount": "1212",
"collateral_currency": "BTC",
"order_id": 1130,
"type": "append"
}
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 returned in a single list |
| from | query | integer(int64) | false | Start timestamp for the query |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| borrow_currency | query | string | false | Borrowed currency |
| collateral_currency | query | string | false | Collateral currency |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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 | Borrowed amount |
| »» collateral_currency | string | Collateral currency |
| »» before_collateral | string | Collateral amount before adjustment |
| »» after_collateral | string | Collateral amount after adjustment |
| »» before_ltv | string | Collateral ratio before adjustment |
| »» after_ltv | string | Collateral ratio after adjustment |
| »» operate_time | integer(int64) | Operation time, timestamp 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/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())
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
}
]
GET /loan/collateral/total_amount
Query user's total borrowing and collateral amount
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
User's total borrowing and collateral amount
| Name | Type | Description |
|---|---|---|
| » borrow_amount | string | Total borrowing amount in USDT |
| » collateral_amount | string | Total 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/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())
Example responses
200 Response
{
"borrow_amount": "11",
"collateral_amount": "111"
}
GET /loan/collateral/ltv
Query user's collateralization ratio and remaining borrowable currencies
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| collateral_currency | query | string | true | Collateral currency |
| borrow_currency | query | string | true | Borrowed currency |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
User's currency statistics data
| Name | Type | Description |
|---|---|---|
| » collateral_currency | string | Collateral currency |
| » borrow_currency | string | Borrowed currency |
| » init_ltv | string | Initial collateralization rate |
| » alert_ltv | string | Warning collateralization rate |
| » liquidate_ltv | string | 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
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())
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"
}
GET /loan/collateral/currencies
Query supported borrowing and collateral currencies
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| loan_currency | query | string | false | Parameter loan_currency. If omitted, returns all supported borrowing currencies; if provided, returns the array of collateral currencies supported for that borrowing currency |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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 |
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())
Example responses
200 Response
[
{
"loan_currency": "BTC",
"collateral_currency": [
"BTC",
"ETH",
"GT"
]
}
]
Multi-currency collateral
POST /loan/multi_collateral/orders
Place multi-currency collateral order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » order_id | body | string | false | Order ID |
| » order_type | body | string | false | current - current rate, fixed - fixed rate, defaults to current if not specified |
| » fixed_type | body | string | false | Fixed interest rate lending period: 7d - 7 days, 30d - 30 days. Required for fixed rate |
| » fixed_rate | body | string | false | Fixed interest rate, required for fixed rate |
| » auto_renew | body | boolean | false | Fixed interest rate, auto-renewal |
| » auto_repay | body | boolean | false | Fixed interest rate, auto-repayment |
| » borrow_currency | body | string | true | Borrowed currency |
| » borrow_amount | body | string | true | Borrowed 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order placed successfully | 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 = ''
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())
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"
}
]
}
Example responses
200 Response
{
"order_id": 10005578
}
GET /loan/multi_collateral/orders
Query multi-currency collateral order list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer | false | Page number |
| limit | query | integer | false | Maximum number of records returned in a single list |
| sort | query | string | false | Sort type: time_desc - Created time descending (default), ltv_asc - Collateral ratio ascending, ltv_desc - Collateral ratio descending. |
| order_type | query | string | false | Order type: current - Query current orders, fixed - Query fixed orders, defaults to current orders if not specified |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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, auto-renewal |
| »» auto_repay | boolean | Fixed interest rate, auto-repayment |
| »» current_ltv | string | 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 | Total outstanding value converted to USDT |
| »» total_left_collateral_usdt | string | Total collateral value converted to 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 | Remaining total outstanding value converted to USDT |
| »»» collateral_currencies | array | Collateral Currency List |
| »»»» CollateralCurrencyInfo | object | none |
| »»»»» currency | string | Currency |
| »»»»» index_price | string | Currency Index Price |
| »»»»» left_collateral | string | Remaining collateral amount |
| »»»»» left_collateral_usdt | string | Remaining collateral value converted to 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'
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())
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"
}
]
}
]
GET /loan/multi_collateral/orders/{order_id}
Query order details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | string | true | Order ID returned when order is successfully created |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order details queried successfully | 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, auto-renewal |
| » auto_repay | boolean | Fixed interest rate, auto-repayment |
| » current_ltv | string | 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 | Total outstanding value converted to USDT |
| » total_left_collateral_usdt | string | Total collateral value converted to 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 | Remaining total outstanding value converted to USDT |
| »» collateral_currencies | array | Collateral Currency List |
| »»» CollateralCurrencyInfo | object | none |
| »»»» currency | string | Currency |
| »»»» index_price | string | Currency Index Price |
| »»»» left_collateral | string | Remaining collateral amount |
| »»»» left_collateral_usdt | string | Remaining collateral value converted to 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())
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"
}
]
}
POST /loan/multi_collateral/repay
Multi-currency collateral repayment
| 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 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Operation successful | Inline |
Status Code 200
Multi-currency collateral repayment
| Name | Type | Description |
|---|---|---|
| » order_id | integer(int64) | Order ID |
| » repaid_currencies | array | Repay Currency List |
| »» RepayCurrencyRes | object | none |
| »»» succeeded | boolean | Whether the repayment was successful |
| »»» label | string | Error identifier for failed operations; empty when successful |
| »»» message | string | Error description for failed operations; 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 = ''
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())
Body parameter
{
"order_id": 10005578,
"repay_items": [
{
"currency": "btc",
"amount": "1",
"repaid_all": false
}
]
}
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"
}
]
}
GET /loan/multi_collateral/repay
Query multi-currency collateral repayment 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 returned in a single list |
| from | query | integer(int64) | false | Start timestamp for the query |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Multi-Collateral Repayment Record |
| »» order_id | integer(int64) | Order ID |
| »» record_id | integer(int64) | Repayment record ID |
| »» init_ltv | string | 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 | 币种 |
| »»» index_price | string | 币种指数价格 |
| »»» before_amount | string | 操作前数量 |
| »»» before_amount_usdt | string | 换算成usdt的操作前价值 |
| »»» after_amount | string | 操作后数量 |
| »»» after_amount_usdt | string | 换算成usdt的操作后价值 |
| »» collateral_currencies | array | List of collateral information |
| »»» currency | string | 币种 |
| »»» index_price | string | 币种指数价格 |
| »»» before_amount | string | 操作前数量 |
| »»» before_amount_usdt | string | 换算成usdt的操作前价值 |
| »»» after_amount | string | 操作后数量 |
| »»» after_amount_usdt | string | 换算成usdt的操作后价值 |
| »» 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 | Repayment amount converted to 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 remaining interest to be repaid |
| »»»»» 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/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())
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"
}
]
}
]
POST /loan/multi_collateral/mortgage
Add or withdraw collateral
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » order_id | body | integer(int64) | true | Order ID |
| » type | body | string | true | Operation type: append - add collateral, redeem - withdraw collateral |
| » collaterals | body | array | false | Collateral currency list |
| »» currency | body | string | false | Currency |
| »» amount | body | string | false | Size |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Operation successful | Inline |
Status Code 200
Multi-collateral adjustment result
| 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 failed operations; empty when successful |
| »»» message | string | Error description for failed operations; empty when successful |
| »»» currency | string | Currency |
| »»» amount | string | Successfully operated collateral quantity; 0 if 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 = ''
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())
Body parameter
{
"order_id": 10005578,
"type": "append",
"collaterals": [
{
"currency": "btc",
"amount": "0.5"
}
]
}
Example responses
200 Response
{
"order_id": 10005679,
"collateral_currencies": [
{
"succeeded": true,
"currency": "btc",
"amount": "0.5"
}
]
}
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 returned in a single list |
| from | query | integer(int64) | false | Start timestamp for the query |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| collateral_currency | query | string | false | Collateral currency |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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 | Collateral ratio before adjustment |
| »» after_ltv | string | Collateral ratio before adjustment |
| »» operate_time | integer(int64) | Operation time, timestamp in seconds |
| »» borrow_currencies | array | Borrowing Currency List |
| »»» currency | string | 币种 |
| »»» index_price | string | 币种指数价格 |
| »»» before_amount | string | 操作前数量 |
| »»» before_amount_usdt | string | 换算成usdt的操作前价值 |
| »»» after_amount | string | 操作后数量 |
| »»» after_amount_usdt | string | 换算成usdt的操作后价值 |
| »» collateral_currencies | array | Collateral Currency List |
| »»» currency | string | 币种 |
| »»» index_price | string | 币种指数价格 |
| »»» before_amount | string | 操作前数量 |
| »»» before_amount_usdt | string | 换算成usdt的操作前价值 |
| »»» after_amount | string | 操作后数量 |
| »»» after_amount_usdt | string | 换算成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 = ''
# for `gen_sign` implementation, refer 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())
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"
}
]
}
]
GET /loan/multi_collateral/currency_quota
Query user's collateral and borrowing currency quota information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| type | query | string | true | Currency type: collateral - Collateral currency, borrow - Borrowing currency |
| currency | query | string | true | When it is a collateral currency, multiple currencies can be provided separated by commas; when it is a borrowing currency, only one currency can be provided. |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [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 limit for the currency |
| »» left_quota | string | Remaining borrowing/collateral quota 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
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())
Example responses
200 Response
[
{
"currency": "BTC",
"index_price": "35306.1",
"min_quota": "0",
"left_quota": "2768152.4958445218723677",
"left_quote_usdt": "97732668833.536273678"
}
]
GET /loan/multi_collateral/currencies
Query supported borrowing and collateral currencies for multi-currency collateral
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | 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/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"loan_currencies": [
{
"currency": "BTC",
"price": "1212"
},
{
"currency": "GT",
"price": "12"
}
],
"collateral_currencies": [
{
"currency": "BTC",
"index_price": "1212",
"discount": "0.7"
}
]
}
GET /loan/multi_collateral/ltv
Query collateralization ratio information
Multi-currency collateral ratio is fixed, independent of currency
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
Multi-collateral ratio
| Name | Type | Description |
|---|---|---|
| » init_ltv | string | Initial collateralization rate |
| » alert_ltv | string | Warning collateralization rate |
| » liquidate_ltv | string | 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/ltv'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"init_ltv": "0.7",
"alert_ltv": "0.8",
"liquidate_ltv": "0.9"
}
GET /loan/multi_collateral/fixed_rate
Query currency's 7-day and 30-day fixed interest rates
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Multi-collateral fixed interest rate |
| »» currency | string | Currency |
| »» rate_7d | string | Fixed interest rate for 7-day lending period |
| »» rate_30d | string | Fixed interest rate for 30-day lending period |
| »» update_time | integer(int64) | Update time, timestamp 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/fixed_rate'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "BTC",
"rate_7d": "0.000023",
"rate_30d": "0.1",
"update_time": 1703820105
}
]
GET /loan/multi_collateral/current_rate
Query currency's current interest rate
Query currency's current interest rate for the previous hour, current interest rate updates hourly
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currencies | query | array[string] | true | Specify currency name query array, separated by commas, maximum 100 items |
| vip_level | query | string | false | VIP level, defaults to 0 if not specified |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Multi-collateral current interest rate |
| »» currency | string | Currency |
| »» current_rate | string | Currency current interest 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/current_rate'
query_param = 'currencies=BTC,GT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "BTC",
"current_rate": "0.000023"
}
]
Earn service
POST /earn/staking/eth2/swap
ETH2 swap
| 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 | Swap Amount |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Swap successful | 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/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())
Body parameter
{
"side": "1",
"amount": "1.5"
}
GET /earn/staking/eth2/rate_records
ETH2 historical return rate query
Query ETH earnings rate records for the last 31 days
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » date_time | integer(int64) | Date Timestamp |
| » date | string | Date |
| » rate | string | Percentage Rate |
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/staking/eth2/rate_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())
Example responses
200 Response
[
{
"date_time": 1690348815,
"date": "2023-07-26",
"rate": "60.00"
},
{
"date_time": 1690435215,
"date": "2023-07-27",
"rate": "20.00"
}
]
GET /earn/dual/investment_plan
Dual Investment product list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| plan_id | query | integer(int64) | false | Financial project ID |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int32) | Product ID |
| » instrument_name | string | Product Name |
| » invest_currency | string | Investment Token |
| » exercise_currency | string | Strike Token |
| » exercise_price | number(double) | Strike price |
| » delivery_time | integer(int32) | Settlement time |
| » min_copies | integer(int32) | Minimum Units |
| » max_copies | integer(int32) | Maximum Units |
| » per_value | string | Value Per Unit |
| » apy_display | string | Annual Yield |
| » start_time | integer(int32) | Start Time |
| » end_time | integer(int32) | End time |
| » status | string | Status: NOTSTARTED-Not Started ONGOING-In Progress ENDED-Ended |
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())
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"
}
]
GET /earn/dual/orders
Dual Investment order list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| from | query | integer(int64) | false | Start settlement time |
| to | query | integer(int64) | false | End settlement time |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records returned in a single list |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int32) | Order ID |
| » plan_id | integer(int32) | Product ID |
| » copies | string | Units |
| » invest_amount | string | Investment Quantity |
| » settlement_amount | string | Settlement Quantity |
| » create_time | integer(int32) | Created time |
| » complete_time | integer(int32) | Completed Time |
| » status | string | Status:INIT-CreatedSETTLEMENT_SUCCESS-Settlement SuccessSETTLEMENT_PROCESSING-Settlement ProcessingCANCELED-CanceledFAILED-Failed |
| » invest_currency | string | Investment Token |
| » exercise_currency | string | Strike Token |
| » exercise_price | string | Strike price |
| » settlement_price | string | Settlement price |
| » settlement_currency | string | Settlement currency |
| » apy_display | string | Annual Yield |
| » apy_settlement | string | Settlement Annual Yield |
| » delivery_time | integer(int32) | Settlement time |
| » text | string | Custom order 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 = '/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())
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",
"text": "t-custom-text"
}
]
POST /earn/dual/orders
Place Dual Investment order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » plan_id | body | string | true | Product ID |
| » amount | body | string | true | Subscription amount, mutually exclusive with copies field |
| » text | body | string | false | Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: |
» text: Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions:
t-t-, length cannot exceed 28 bytes| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order placed 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/dual/orders'
query_param = ''
body='{"plan_id":"176","amount":"1","text":"t-custom-text"}'
# 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())
Body parameter
{
"plan_id": "176",
"amount": "1",
"text": "t-custom-text"
}
GET /earn/structured/products
Structured Product List
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| type | query | string | false | Product Type (Default empty to query all) |
| status | query | string | true | Status (Default empty to query all) |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records returned in a single list |
type: Product Type (Default empty to query all)
SharkFin2.0-Shark Fin
BullishSharkFin-Bullish Treasure
BearishSharkFin-Bearish Treasure
DoubleNoTouch-Volatility Treasure
RangeAccrual-Range Smart Yield
SnowBall-Snowball
status: Status (Default empty to query all)
in_process-In progress
will_begin-Not started
wait_settlement-Pending settlement
done-Completed
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Structured Investment |
| »» id | integer(int32) | Product ID |
| »» type | string | Product Type: SharkFin2.0-Shark Fin 2.0 BullishSharkFin-Bullish Shark Fin BearishSharkFin-Bearish Shark FinDoubleNoTouch-Double No-TouchRangeAccrual-Range AccrualSnowBall-Snow Ball |
| »» name_en | string | Product Name |
| »» investment_coin | string | Investment Token |
| »» investment_period | string | Investment Period |
| »» min_annual_rate | string | Minimum Annual Rate |
| »» mid_annual_rate | string | Intermediate Annual Rate |
| »» max_annual_rate | string | Maximum Annual Rate |
| »» watch_market | string | Underlying Market |
| »» start_time | integer(int32) | Start Time |
| »» end_time | integer(int32) | End 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
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())
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"
}
]
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 | Termination Timestamp |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records returned in a single list |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Structured order |
| »» id | integer(int32) | Order ID |
| »» pid | string | Product 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 = ''
# for `gen_sign` implementation, refer 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())
Example responses
200 Response
[
{
"id": 35,
"pid": "3691",
"lock_coin": "ETH",
"amount": "20",
"status": "SUCCESS",
"income": "0.000000",
"create_time": 1697685172
}
]
POST /earn/structured/orders
Place Structured Product Order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » pid | body | string | false | Product ID |
| » amount | body | string | false | Buy Quantity |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order placed 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/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())
Body parameter
{
"pid": "1",
"amount": "0.5"
}
GET /earn/staking/coins
Staking coins
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » coin | body | string | false | Currency |
| » cointype | body | string | false | Token Type: swap-Voucher, lock-Locked |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [string] |
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/staking/coins'
query_param = ''
body='{"coin":"string","cointype":"string"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"coin": "string",
"cointype": "string"
}
Example responses
200 Response
[
"GT",
"SOL",
"USDT",
"ALEO",
"DOT",
"TRX",
"ADA"
]
POST /earn/staking/swap
On-chain token swap for earned coins
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » coin | body | string | true | Currency |
| » side | body | string | true | 0 - Stake 1 - Redeem |
| » amount | body | string | true | Size |
| » pid | body | integer(int32) | false | DeFi-type Mining Protocol Identifier |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Swap successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer | Order ID |
| » pid | integer | Product ID |
| » uid | integer | User ID |
| » coin | string | Currency |
| » type | integer | Type 0-Staking 1-Redemption |
| » subtype | string | 子Type |
| » amount | string | Amount |
| » exchange_rate | string | Exchange ratio |
| » exchange_amount | string | Redemption Amount |
| » updateStamp | integer | 更新Timestamp |
| » createStamp | integer | Transaction timestamp |
| » status | integer | status 1-success |
| » protocol_type | integer | DEFI Protocol Type |
| » client_order_id | string | Reference ID |
| » source | string | Order Origin |
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/staking/swap'
query_param = ''
body='{"coin":"GT","side":"0","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())
Body parameter
{
"coin": "GT",
"side": "0",
"amount": "1.5"
}
Example responses
200 Response
{
"id": 21000,
"uid": 12345,
"coin": "GT",
"type": 0,
"exchange_rate": "1.00000000",
"amount": "2",
"pid": 1,
"status": 1,
"createStamp": 1752200661
}
Retrieve user account information
GET /account/detail
Retrieve user account information
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
AccountDetail
| Name | Type | Description |
|---|---|---|
| » ip_whitelist | array | IP Whitelist |
| » currency_pairs | array | Trading pair whitelist |
| » user_id | integer(int64) | User ID |
| » tier | integer(int64) | User VIP level |
| » key | object | API Key details |
| »» mode | integer(int32) | Mode: 1 - Classic mode, 2 - Legacy unified mode |
| » copy_trading_role | integer(int32) | User role: 0 - Normal user, 1 - Copy trading leader, 2 - Follower, 3 - Both 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/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())
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
}
GET /account/rate_limit
Get user transaction rate limit information
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
AccountRateLimit
| Name | Type | Description |
|---|---|---|
| AccountRateLimit | array | Account rate limit |
| » tier | string | Frequency limit level (For detailed frequency limit rules, see Transaction ratio frequency limit) |
| » ratio | string | Fill rate |
| » main_ratio | string | Total fill 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/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())
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"
}
]
POST /account/stp_groups
Create STP user group
Only the main account is allowed to create a new STP user group
| 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 | Created time |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | User added successfully, returning current users in 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) | 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 = '/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())
Body parameter
{
"name": "stp_name"
}
Example responses
200 Response
{
"id": 123435,
"name": "group",
"create_time": 1548000000,
"creator_id": 10000
}
GET /account/stp_groups
Query STP user groups created by the user
Only query STP user groups created by the current main account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| name | query | string | false | Fuzzy search by name |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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) | 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 = '/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())
Example responses
200 Response
[
{
"id": 123435,
"name": "group",
"create_time": 1548000000,
"creator_id": 10000
}
]
GET /account/stp_groups/{stp_id}/users
Query users in the STP user group
Only the main account that created this STP group can query the account ID list in the current STP group
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| stp_id | path | integer(int64) | true | STP Group ID |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [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) | 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 = '/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())
Example responses
200 Response
[
{
"user_id": 10000,
"stp_id": 1,
"create_time": 1548000000
}
]
POST /account/stp_groups/{stp_id}/users
Add users to the STP user group
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| stp_id | path | integer(int64) | true | STP Group ID |
| body | body | array[integer] | true | User ID |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | User added successfully, returning current users in 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) | 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 = '/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())
Body parameter
[
1,
2,
3
]
Example responses
200 Response
[
{
"user_id": 10000,
"stp_id": 1,
"create_time": 1548000000
}
]
DELETE /account/stp_groups/{stp_id}/users
Delete users from the STP user group
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| stp_id | path | integer(int64) | true | STP Group ID |
| user_id | query | integer(int64) | true | STP user IDs, multiple IDs can be separated by commas |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Users deleted successfully, returns current users in 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) | 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 = '/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())
Example responses
200 Response
[
{
"user_id": 10000,
"stp_id": 1,
"create_time": 1548000000
}
]
POST /account/debit_fee
Configure GT fee deduction
Enable or disable GT fee deduction for the current account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | DebitFee | true | none |
| » enabled | body | boolean | true | Whether GT fee deduction is enabled |
| 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 = ''
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())
Body parameter
{
"enabled": true
}
GET /account/debit_fee
Query GT fee deduction configuration
Query the GT fee deduction configuration for the current account
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | DebitFee |
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())
Example responses
200 Response
{
"enabled": true
}
Broker rebate endpoints
GET /rebate/agency/transaction_history
Broker obtains transaction history of recommended users
Record query time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Specify the trading pair. If not specified, returns all trading pairs |
| user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned |
| from | query | integer(int64) | false | Start time for querying records, defaults to 7 days before current time if not specified |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | 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 | Transaction amount |
| »»» amount_asset | string | Commission Asset |
| »»» source | string | Commission source: SPOT - Spot commission, FUTURES - Futures commission |
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/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())
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"
}
]
}
GET /rebate/agency/commission_history
Broker obtains rebate history of recommended users
Record query time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Specify the currency. If not specified, returns all currencies |
| user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned |
| from | query | integer(int64) | false | Start time for querying records, defaults to 7 days before current time if not specified |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency_pair | string | Currency pair |
| » total | integer(int64) | Total |
| » list | array | List of commission history |
| »» AgencyCommission | object | none |
| »»» commission_time | integer(int64) | Commission time (Unix timestamp in seconds) |
| »»» user_id | integer(int64) | User ID |
| »»» group_name | string | Group name |
| »»» commission_amount | string | Transaction amount |
| »»» commission_asset | string | Commission Asset |
| »»» source | string | Commission source: SPOT - Spot commission, FUTURES - Futures commission |
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())
Example responses
200 Response
{
"total": 100,
"list": [
{
"commission_time": 1539852480,
"user_id": 10000,
"group_name": "gateio",
"commission_amount": "1000",
"source": "SPOT",
"commission_asset": "GT"
}
]
}
GET /rebate/partner/transaction_history
Partner obtains transaction history of recommended users
Record query time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Specify the trading pair. If not specified, returns all trading pairs |
| user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned |
| from | query | integer(int64) | false | Start time for querying records, defaults to 7 days before current time if not specified |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | 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 | Transaction amount |
| »»» amount_asset | string | Commission Asset |
| »»» source | string | Commission source: SPOT - Spot commission, FUTURES - Futures commission |
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())
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"
}
]
}
GET /rebate/partner/commission_history
Partner obtains rebate records of recommended users
Record query time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Specify the currency. If not specified, returns all currencies |
| user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned |
| from | query | integer(int64) | false | Start time for querying records, defaults to 7 days before current time if not specified |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » total | integer(int64) | Total |
| » list | array | List of commission history |
| »» PartnerCommission | object | none |
| »»» commission_time | integer(int64) | Commission time (Unix timestamp in seconds) |
| »»» user_id | integer(int64) | User ID |
| »»» group_name | string | Group name |
| »»» commission_amount | string | Transaction amount |
| »»» commission_asset | string | Commission Asset |
| »»» source | string | Commission source: SPOT - Spot commission, FUTURES - Futures commission |
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())
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"
}
]
}
GET /rebate/partner/sub_list
Partner subordinate list
Including sub-agents, direct customers, and 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 returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | 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) | Time when user joined the system, Unix timestamp in seconds |
| »»» type | integer(int64) | Type (1-Sub-agent 2-Indirect direct customer 3-Direct 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/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())
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
}
]
}
GET /rebate/broker/commission_history
Broker obtains user's rebate records
Record query time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| limit | query | integer | false | Maximum number of records 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 | Start time of the query record. If not specified, defaults to 30 days before the current time |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » total | integer(int64) | Total |
| » list | array | List of commission history |
| »» BrokerCommission | object | none |
| »»» commission_time | integer(int64) | Commission time (Unix timestamp in seconds) |
| »»» 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 | Commission transaction type: Spot, Futures, Options, Alpha |
| »»» currency_pair | string | Currency pair |
| »»» sub_broker_info | object | Sub-broker information |
| »»»» user_id | integer(int64) | Sub-broker user ID |
| »»»» original_commission_rate | string | Sub-broker original commission rate |
| »»»» relative_commission_rate | string | Sub-broker relative commission rate |
| »»»» commission_rate | string | Sub-broker actual commission rate |
| »»» alpha_contract_addr | string | Alpha contract 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 = '/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())
Example responses
200 Response
{
"list": [
{
"user_id": 110285113,
"group_name": "",
"commission_time": 1702545051,
"fee": "0.0020000000",
"source": "SPOT",
"amount": "0.00040000",
"rebate_fee": "0.0004000000",
"fee_asset": "BEAM",
"currency_pair": "BEAM_USDT",
"sub_broker_info": {
"user_id": 110285114,
"original_commission_rate": "0.2",
"relative_commission_rate": "0.5",
"commission_rate": "0.1"
},
"alpha_contract_addr": "0x9a26f5433671751c3276a065f57e5a02d2817973"
}
],
"total": 47
}
GET /rebate/broker/transaction_history
Broker obtains user's trading history
Record query time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| limit | query | integer | false | Maximum number of records 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 | Start time of the query record. If not specified, defaults to 30 days before the current time |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | 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 amount (USDT) |
| »»» currency_pair | string | Currency pair |
| »»» amount | string | Transaction amount |
| »»» fee_asset | string | Fee currency |
| »»» source | string | Commission transaction type: Spot, Futures, Options, Alpha |
| »»» sub_broker_info | object | Sub-broker information |
| »»»» user_id | integer(int64) | Sub-broker user ID |
| »»»» original_commission_rate | string | Sub-broker original commission rate |
| »»»» relative_commission_rate | string | Sub-broker relative commission rate |
| »»»» commission_rate | string | Sub-broker actual commission rate |
| »»» alpha_contract_addr | string | Alpha contract 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 = '/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())
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",
"sub_broker_info": {
"user_id": 110285114,
"original_commission_rate": "0.2",
"relative_commission_rate": "0.5",
"commission_rate": "0.1"
},
"alpha_contract_addr": "0x9a26f5433671751c3276a065f57e5a02d2817973"
}
],
"total": 47
}
GET /rebate/user/info
User obtains rebate information
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | 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
Code samples
# coding: utf-8
import 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())
Example responses
200 Response
{
"invite_uid": 987
}
GET /rebate/user/sub_relation
User subordinate relationship
Query whether the specified user is within the system
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id_list | query | string | true | Query user ID list, separated by commas. If more than 100, only 100 will be returned |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » list | array | Subordinate relationship list |
| »» UserSub | object | none |
| »»» uid | integer(int64) | User ID |
| »»» belong | string | User's system affiliation (partner/referral). Empty means not belonging to any system |
| »»» type | integer(int64) | Type (0-Not in system 1-Direct subordinate agent 2-Indirect subordinate agent 3-Direct direct customer 4-Indirect direct customer 5-Regular user) |
| »»» ref_uid | integer(int64) | Inviter user 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 = '/rebate/user/sub_relation'
query_param = 'user_id_list=1, 2, 3'
# for `gen_sign` implementation, refer 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())
Example responses
200 Response
{
"list": [
{
"belong": "",
"ref_uid": 0,
"type": 0,
"uid": 9
},
{
"belong": "partner",
"type": 1,
"ref_uid": 1,
"uid": 2
},
{
"belong": "referral",
"type": 5,
"ref_uid": 1,
"uid": 3
}
]
}
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| user_id | integer(int64) | 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 function name (no value will be cleared) - wallet: wallet - spot: spot/margin - futures: perpetual contract - delivery: delivery contract - earn: earn - custody: custody - options: options - account: account information - loan: lending - margin: margin - unified: unified account - copy: copy trading |
| » read_only | boolean | false | none | Read Only |
| ip_whitelist | array | false | none | IP whitelist (list will be cleared if no value is passed) |
| key | string | false | read-only | API Key |
| state | integer(int32) | false | read-only | Status: 1-Normal 2-Frozen 3-Locked |
| created_at | integer(int64) | false | read-only | Created time |
| updated_at | integer(int64) | false | read-only | Last Update Time |
| last_access | integer(int64) | false | read-only | Last Access Time |
{
"user_id": 0,
"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
}
Spot price order details
| 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 is greater than or equal to price- <=: triggered when market price is less than or equal to price |
| » expiration | integer | true | none | Maximum wait time for trigger condition (in seconds). Order will be cancelled if timeout |
| 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 | Trading quantity When type is limit, it refers to the base currency (the currency being traded), such as BTC in BTC_USDTWhen type is market, it refers to different currencies based on the side:- side: buy refers to quote currency, BTC_USDT means USDT- side: sell refers to base currency, BTC_USDT means BTC |
| » account | string | true | none | Trading account type. Unified account must be set to unified- normal: spot trading - margin: margin trading - unified: unified account |
| » time_in_force | string | false | none | time_in_force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only |
| » auto_borrow | boolean | false | none | Whether to borrow coins automatically |
| » auto_repay | boolean | false | none | Whether to repay the loan automatically |
| » text | string | false | none | The source of the order, including: - web: Web - api: API call - app: Mobile app |
| id | integer(int64) | false | read-only | Auto order ID |
| user | integer | false | read-only | User ID |
| market | string | true | none | Market |
| ctime | integer(int64) | false | read-only | Created time |
| ftime | integer(int64) | false | read-only | End time |
| fired_order_id | integer(int64) | false | read-only | ID of the order created after trigger |
| status | string | false | read-only | Status - open: Running - cancelled: Manually cancelled - finish: Successfully completed - failed: Failed to execute - expired: Expired |
| reason | string | false | read-only | Additional description of how the order was completed |
| Property | Value |
|---|---|
| rule | >= |
| rule | <= |
| type | limit |
| type | market |
| side | buy |
| side | sell |
| account | normal |
| account | margin |
| account | unified |
| time_in_force | gtc |
| time_in_force | ioc |
{
"trigger": {
"price": "string",
"rule": ">=",
"expiration": 0
},
"put": {
"type": "limit",
"side": "buy",
"price": "string",
"amount": "string",
"account": "normal",
"time_in_force": "gtc",
"auto_borrow": false,
"auto_repay": false,
"text": "string"
},
"id": 0,
"user": 0,
"market": "string",
"ctime": 0,
"ftime": 0,
"fired_order_id": 0,
"status": "string",
"reason": "string"
}
Futures contract details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| name | string | false | none | Futures contract |
| type | string | false | none | Contract type: inverse - inverse contract, direct - direct contract |
| 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 - internal trading price, index - 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, negative values indicate rebates |
| 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 | Base risk limit (deprecated) |
| risk_limit_step | string | false | none | Risk limit adjustment step (deprecated) |
| risk_limit_max | string | false | none | Maximum risk limit allowed by the contract (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 allowed by the contract |
| order_size_max | integer(int64) | false | none | Maximum order size allowed by the contract |
| order_price_deviate | string | false | none | Maximum allowed deviation between order price and current mark price. The order price order_price must satisfy the following condition:abs(order_price - mark_price) <= mark_price * order_price_deviate |
| ref_discount_rate | string | false | none | Trading fee discount for referred users |
| ref_rebate_rate | string | false | none | Commission rate for referrers |
| orderbook_id | integer(int64) | false | none | Orderbook update ID |
| trade_id | integer(int64) | false | none | Current trade ID |
| trade_size | integer(int64) | false | none | Historical cumulative trading volume |
| position_size | integer(int64) | false | none | Current total long position size |
| config_change_time | number(double) | false | none | Last configuration update time |
| in_delisting | boolean | false | none | in_delisting=true and position_size>0 indicates the contract is in delisting transition periodin_delisting=true and position_size=0 indicates the contract is delisted |
| orders_limit | integer | false | none | Maximum number of pending orders |
| enable_bonus | boolean | false | none | Whether bonus 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 |
| status | string | false | none | Contract status types include: prelaunch (pre-launch), trading (active), delisting (delisting), delisted (delisted) |
| launch_time | integer(int64) | false | none | Contract expiry timestamp |
| Property | Value |
|---|---|
| type | inverse |
| type | direct |
| mark_type | internal |
| mark_type | index |
{
"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",
"status": "string",
"launch_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 | Total realized PnL from closed positions |
| 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 pending order quantity |
| close_order | object|null | false | read-only | Current close order information, or null if no close order |
| » id | integer(int64) | false | none | Order ID |
| » price | string | false | none | Order price |
| » is_liq | boolean | false | none | Whether the close order is from liquidation |
| mode | string | false | none | Position mode, including: - single: Single position mode- dual_long: Long position in dual position mode- dual_short: Short position in dual position 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 |
| update_id | integer(int64) | false | read-only | Update ID. The value increments by 1 each time the position is updated |
| trade_long_size | integer(int64) | false | read-only | Cumulative long size |
| trade_long_xprice | string | false | read-only | Cumulative long size*price |
| trade_short_size | integer(int64) | false | read-only | Cumulative short size |
| trade_short_xprice | string | false | read-only | Cumulative short size*price |
| trade_max_size | string | false | none | Maximum position |
| open_time | integer(int64) | false | none | First Open Time |
| risk_limit_table | string | false | read-only | Risk limit table ID |
| average_maintenance_rate | string | false | read-only | Average maintenance margin rate |
| voucher_size | string | false | read-only | Experience Coupon Position Size |
| voucher_margin | string | false | read-only | Experience Coupon Position Margin |
| voucher_id | integer(int64) | false | read-only | Experience Coupon ID |
| Property | Value |
|---|---|
| mode | single |
| mode | dual_long |
| mode | dual_short |
{
"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,
"update_id": 0,
"trade_long_size": 0,
"trade_long_xprice": "string",
"trade_short_size": 0,
"trade_short_xprice": "string",
"trade_max_size": "string",
"open_time": 0,
"risk_limit_table": "string",
"average_maintenance_rate": "string",
"voucher_size": "string",
"voucher_margin": "string",
"voucher_id": 0
}
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 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: Pending- finished: Completed |
| contract | string | true | none | Futures contract |
| size | integer(int64) | true | none | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| iceberg | integer(int64) | false | none | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| price | string | false | none | Order price. Price of 0 with tif set to ioc represents a market order. |
| 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 | Unfilled quantity |
| fill_price | string | false | read-only | Fill price |
| text | string | false | none | Custom order 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(.) In addition to user-defined information, the following are internal reserved fields that identify the order source: - web: Web - api: API call - app: Mobile app - auto_deleveraging: Automatic deleveraging - liquidation: Forced liquidation of positions under the old classic mode - liq-xxx: a. Forced liquidation of positions under the new classic mode, including isolated margin, one-way cross margin, and non-hedged positions under two-way cross margin. b. Forced liquidation of isolated positions under the unified account single-currency margin mode - hedge-liq-xxx: Forced liquidation of hedged positions under the new classic mode two-way cross margin, i.e., simultaneously closing long and short positions - pm_liquidate: Forced liquidation under unified account multi-currency margin mode - comb_margin_liquidate: Forced liquidation under unified account portfolio margin mode - scm_liquidate: Forced liquidation of positions under unified account single-currency margin mode - insurance: Insurance |
| tkfr | string | false | read-only | Taker fee |
| mkfr | string | false | read-only | Maker fee |
| refu | integer | false | read-only | Referrer 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 prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention 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 |
| 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 | - |
{
"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",
}
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 | New order size, including filled size. - If less than or equal to the filled quantity, the order will be cancelled. - The new order side must be identical to the original one. - Close order size cannot be modified. - For reduce-only orders, increasing the size may cancel other reduce-only orders. - If the price is not modified, decreasing the size will not affect the depth queue, while increasing the size will place it at the end of the current price level. |
| price | string | false | none | New order price |
| amend_text | string | false | none | Custom info during order amendment |
{
"order_id": 0,
"text": "string",
"size": 0,
"price": "string",
"amend_text": "string",
}
Futures price-triggered order details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| initial | object | true | none | none |
| » contract | string | true | none | 合约标识 |
| » size | integer(int64) | false | none | 代表需要平仓的合约张数, 全平仓:size=0 部分平仓:plan-close-short-position size>0 部分平仓:plan-close-long-position size<0 |
| » price | string | true | none | 交易价, 当价格为 0 时, 表示通过市价方式来下单 |
| » close | boolean | false | write-only | 单仓模式全部平仓时,必须设置为true执行平仓操作 单仓模式部分平仓时/双仓模式下, 可以不设置close, 或close=false |
| » tif | string | false | none | Time in force 策略,默认为gtc, 市价单当前只支持 ioc 模式市价单当前只支持 ioc 模式 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled |
| » text | string | false | none | 订单的来源, 包括: - web: 网页 - api: API 调用 - app: 移动端 |
| » reduce_only | boolean | false | none | 设置为 true 的时候执行自动减仓操作, 设为 true可确保订单不会开新仓, 只用于平仓或减仓 |
| » auto_size | string | false | write-only | 单仓模式不需设置auto_size 双仓模式全部平仓(size=0)时, 必须设置auto_size, close_long 平多头, close_short 平空头 双仓模式部分平仓(size≠0)时, 不需设置auto_size |
| » is_reduce_only | boolean | false | read-only | 是否为只减仓委托. 对应请求中的reduce_only. |
| » is_close | boolean | false | read-only | 是否为平仓委托. 对应请求中的close. |
| trigger | object | true | none | none |
| » strategy_type | integer(int32) | false | none | 触发策略 - 0: 价格触发, 即当价格满足条件时触发 - 1: 价差触发, 即指定 price_type 的最近一次价格减去倒数第二个价格的差值目前暂时只支持0即最新成交价 |
| » price_type | integer(int32) | false | none | 参考价格Type. 0 - 最新成交价, 1 - 标记价格, 2 - 指数价格 |
| » price | string | false | none | 价格触发时为价格, 价差触发时为价差 |
| » rule | integer(int32) | false | none | 价格条件Type - 1: 表示根据 strategy_type 和 price_type 算出的价格大于等于 Trigger.Price 时触发, 同时Trigger.Price must > last_price- 2: 表示根据 strategy_type 和 price_type 算出的价格小于等于 Trigger.Price 时触发, 同时Trigger.Price must < last_price |
| » expiration | integer | false | none | 最长等待触发时间, 超时则取消该订单, 单位是秒 s |
| id | integer(int64) | false | read-only | Auto order ID |
| user | integer | false | read-only | User ID |
| create_time | number(double) | false | read-only | Created time |
| finish_time | number(double) | false | read-only | End time |
| trade_id | integer(int64) | false | read-only | ID of the order created after trigger |
| status | string | false | read-only | Order status - open: Active- finished: Finished- inactive: Inactive, only applies to order take-profit/stop-loss- invalid: Invalid, only applies to order take-profit/stop-loss |
| finish_as | string | false | read-only | Finish status: cancelled - Cancelled; succeeded - Succeeded; failed - Failed; expired - Expired |
| reason | string | false | read-only | Additional description of how the order was completed |
| order_type | string | false | none | Types of take-profit and stop-loss orders, including: - 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, used to close all long positions- close-short-position: Position take-profit/stop-loss, used to close all short positions- plan-close-long-position: Position plan take-profit/stop-loss, used to close all or partial long positions- plan-close-short-position: Position plan take-profit/stop-loss, used to close all or partial short positionsThe two types of order take-profit/stop-loss are read-only and cannot be passed in requests |
| me_order_id | integer(int64) | false | read-only | Corresponding order ID for order take-profit/stop-loss orders |
| 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 |
{
"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 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 | Contract type: inverse - inverse contract, direct - direct contract |
| 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 - internal trading price, index - 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, negative values indicate rebates |
| 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 allowed by the contract |
| order_size_max | integer(int64) | false | none | Maximum order size allowed by the contract |
| order_price_deviate | string | false | none | Maximum allowed deviation between order price and current mark price. The order price order_price must satisfy the following condition:abs(order_price - mark_price) <= mark_price * order_price_deviate |
| ref_discount_rate | string | false | none | Trading fee discount for referred users |
| ref_rebate_rate | string | false | none | Commission rate for referrers |
| orderbook_id | integer(int64) | false | none | Orderbook update ID |
| trade_id | integer(int64) | false | none | Current trade ID |
| trade_size | integer(int64) | false | none | Historical cumulative trading volume |
| position_size | integer(int64) | false | none | Current total long position size |
| config_change_time | number(double) | false | none | Last configuration update time |
| in_delisting | boolean | false | none | Contract is delisting |
| orders_limit | integer | false | none | Maximum number of pending orders |
| Property | Value |
|---|---|
| cycle | WEEKLY |
| cycle | BI-WEEKLY |
| cycle | QUARTERLY |
| cycle | BI-QUARTERLY |
| type | inverse |
| type | direct |
| mark_type | internal |
| mark_type | index |
{
"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
}