Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
Welcome to Gate 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.
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.105.32
Update POST /futures/{settle}/positions/{contract}/leverage endpoint description with detailed position mode switching rules, usage examples, and risk warnings for better clarity
v4.105.31
Add rpi_maker_fee field in GET /wallet/fee and GET /spot/fee endpoint responses to display RPI MM maker fee rate
Add futures_rpi_maker_fee field in GET /wallet/fee and GET /spot/fee endpoint responses to display futures RPI MM maker fee rate
Add rpi_mm field in GET /wallet/fee and GET /spot/fee endpoint responses to display RPI MM tier level
Update taker_fee and maker_fee field descriptions in TradeFee model to specify they are for spot trading
v4.105.29
deal field in GET /spot/my_trades endpoint response to display total deal amountoptions_order_loss field in GET /unified/accounts endpoint response to display options order loss in USDT, effective in portfolio margin modespot_order_loss field description in GET /unified/accounts endpoint response to clarify it represents spot order loss, effective in cross-currency margin mode and portfolio margin modecross_balance and iso_balance field descriptions in GET /unified/accounts endpoint response, now effective in both single-currency margin mode and cross-currency margin modev4.105.28
block_number field in DELETE /withdrawals/{withdrawal_id} endpoint response to display block numbercross_balance and iso_balance field descriptions in GET /unified/accounts endpoint response, now effective in both single-currency margin mode and cross-currency margin modev4.105.27
status field descriptions in DepositRecord, WithdrawalRecord, and WithdrawalsDel models for better clarityFINAL status from deposit status enum, optimize DONE status descriptionv4.105.24
GET /wallet/currency_chains endpoint description updated to indicate that currencies with extremely low liquidity or value are not supported via API and should be queried and processed through Web or AppGET /wallet/withdraw_status endpoint description updated to indicate that currencies with extremely low liquidity or value are not supported via API and should be queried and processed through Web or Appv4.105.20
DELETE /withdrawals/{withdrawal_id} endpoint response model updated to use WithdrawalsDel schemaBLOCKED, DEP_CREDITED, FINAL status values in GET /wallet/deposits endpoint responseis_deposit_disabled field in GET /wallet/currency_chains endpoint responsev4.105.19
GET /spot/currency_pairs and GET /spot/currency_pairs/{currency_pair} endpoints, fee field is now deprecatedPOST /earn/staking/eth2/swap endpoint summary updated from "ETH2 Swap" to "ETH Swap", ETH2 renamed to GTETHGET /earn/staking/eth2/rate_records endpoint summary updated to query historical rate of GTETHv4.105.18
PUT /futures/{settle}/price_orders endpoint to update a single price-triggered ordersettle, order_id, size, price, trigger_price, price_type, and auto_size parameters in update price-triggered order requestv4.105.11
GET /account/main_keys endpoint to query all main account API key informationGET /spot/currency_pairs and GET /spot/currency_pairs/{currency_pair} endpoints, fee field is now deprecatedv4.105.10
POST /futures/{settle}/price_orders endpoint, price and rule fields are now required in futures price trigger parametersv4.105.9
settlement_currency field in GET /futures/{settle}/positions response for multi-settlement supportauto_renew parameter in POST /earn/uni/lends request for automatic lending renewalGET /spot/trades endpoint with trade_type filter parameterv4.105.8
margin_mode field in GET /unified/accounts response to indicate account margin modeGET /futures/{settle}/position_close_history endpoint for position closing historyfee_currency field in GET /spot/my_trades responsev4.105.7
liquidation_price field in GET /futures/{settle}/positions response for better risk managementPOST /spot/orders with stop_loss and take_profit parameters for advanced order typestotal_balance field in GET /unified/accounts responsev4.105.6
GET /wallet/saved_address endpoint to query saved withdrawal addressesnetwork_fee field in GET /wallet/withdrawals responsemin_amount and max_amount fields in GET /spot/currency_pairs responsev4.105.5
order_type field in GET /futures/{settle}/orders response to distinguish order typesGET /spot/candlesticks with support for 30s intervalavailable_balance field in GET /margin/accounts responsev4.105.4
funding_rate_next field in GET /futures/{settle}/tickers responsePOST /unified/loans/repay endpoint for unified account loan repaymentcross_leverage field in GET /unified/accounts responsev4.105.3
position_side parameter in GET /futures/{settle}/positions query for hedge mode supportGET /earn/dual/orders with investment_type filter parameterunrealized_pnl field in GET /futures/{settle}/accounts responsev4.105.2
GET /spot/cross_margin/accounts endpoint for cross margin account informationmaker_fee_rate and taker_fee_rate fields in GET /spot/fee responsesettle_currency field in GET /futures/{settle}/contracts responsev4.105.1
time_in_force parameter in POST /futures/{settle}/orders requestGET /wallet/deposits with network filter parameterlast_update_time field in GET /spot/accounts responsev4.105.0
GET /unified/estimate_rate endpoint for unified account borrowing rate estimationportfolio_margin field in GET /unified/accounts responseposition_mode parameter in POST /futures/{settle}/positions/mode requestv4.104.9
reduce_only parameter in POST /futures/{settle}/orders request for position reduction ordersGET /spot/orders with account_type filter parameterfunding_balance field in GET /futures/{settle}/accounts responsev4.104.8
GET /earn/staking/products endpoint for staking product informationapr field in GET /earn/uni/currencies responselock_period field in GET /earn/dual/investment_plan responsev4.104.7
order_book_id field in GET /spot/order_book response for order book versioningPOST /wallet/transfers with client_order_id parametertrading_fee_rate field in GET /spot/accounts responsev4.104.6
mark_price field in GET /futures/{settle}/tickers responseGET /futures/{settle}/insurance endpoint for insurance fund informationisolated_margin field in GET /futures/{settle}/positions responsev4.104.5
order_id field in GET /spot/my_trades response for trade-order mappingGET /unified/loans with currency filter parameterborrow_amount field in GET /unified/accounts responsev4.104.4
POST /spot/price_orders/batch endpoint for batch price orderstrigger_price field in GET /spot/price_orders responsemaintenance_rate field in GET /futures/{settle}/contracts responsev4.104.3
hedge_mode parameter in GET /futures/{settle}/positions queryGET /earn/dual/orders with status filter parametercross_margin_leverage field in GET /unified/accounts responsev4.104.2
settlement_size field in GET /futures/{settle}/my_trades responseGET /wallet/total_balance endpoint for total account balanceavailable_margin field in GET /margin/accounts responsev4.104.1
post_only parameter in POST /spot/orders request for maker-only ordersGET /futures/{settle}/orders with contract filter parameterfunding_time field in GET /futures/{settle}/funding_rate responsev4.104.0
GET /unified/risk_units endpoint for unified account risk unit calculationrisk_level field in GET /unified/accounts responseauto_borrow parameter in POST /unified/orders request for automatic borrowingv4.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 GTETHv4.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 Limitingcopy_trading_role field in GET /account/detail responsev4.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 PUT /unified/unified_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
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/withdrawals'
query_param = ''
body='{"withdraw_order_id":"order_123456","currency":"USDT","address":"1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs","amount":"222.61","memo":"","chain":"TRX"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/withdrawals"
query_param=""
body_param='{"withdraw_order_id":"order_123456","currency":"USDT","address":"1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs","amount":"222.61","memo":"","chain":"TRX"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /withdrawals
Withdraw
If the recipient's on-chain address is also Gate, no transaction fee will be charged
Body parameter
{
"withdraw_order_id": "order_123456",
"currency": "USDT",
"address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
"amount": "222.61",
"memo": "",
"chain": "TRX"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » withdraw_order_id | body | string | false | 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
Example responses
200 Response
{
"id": "210496",
"timestamp": "1542000000",
"withdraw_order_id": "order_123456",
"currency": "USDT",
"address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
"txid": "128988928203223323290",
"amount": "222.61",
"memo": "",
"status": "DONE",
"chain": "TRX"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/push'
query_param = ''
body='{"receive_uid":12233,"currency":"USDT","amount":"1.1"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/withdrawals/push"
query_param=""
body_param='{"receive_uid":12233,"currency":"USDT","amount":"1.1"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /withdrawals/push
UID transfer
Transfers between main spot accounts. Both parties cannot be sub-accounts
Body parameter
{
"receive_uid": 12233,
"currency": "USDT",
"amount": "1.1"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » receive_uid | body | integer(int64) | true | Recipient UID |
| » currency | body | string | true | Currency name |
| » amount | body | string | true | Transfer amount |
Example responses
200 Response
{
"id": 111
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/210496'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/withdrawals/210496"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /withdrawals/{withdrawal_id}
Cancel withdrawal with specified ID
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| withdrawal_id | path | string | true | none |
Example responses
202 Response
{
"id": "210496",
"timestamp": "1542000000",
"currency": "USDT",
"address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
"txid": "128988928203223323290",
"amount": "222.61",
"memo": "",
"block_number": "18217349",
"status": "DONE",
"chain": "TRX"
}
| 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 |
| » 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 |
| » block_number | string | Block Number |
| » status | string | Transaction Status - BCODE: Deposit Code Operation - CANCEL: Cancelled - CANCELPEND: Withdrawal Cancellation Pending - DMOVE: Pending Manual Review - DONE: Completed (Only considered truly on-chain when block_number > 0) - EXTPEND: Sent and Waiting for Confirmation - FAIL: On-Chain Failure Pending Confirmation - FVERIFY: Facial Verification in Progress - LOCKED: Wallet-Side Order Locked - MANUAL: Pending Manual Review - REJECT: Rejected - REQUEST: Request in Progress - 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
Wallet API
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/currency_chains'
query_param = 'currency=GT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/wallet/currency_chains?currency=GT \
-H 'Accept: application/json'
GET /wallet/currency_chains
Query chains supported for specified currency
API operations are not supported for tokens with low liquidity or extremely low value. Please use the Web or App interface to query and process.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Currency name |
Example responses
200 Response
[
{
"chain": "ETH",
"name_cn": "以太坊ERC20",
"name_en": "ETH/ERC20",
"contract_address": "",
"is_disabled": 0,
"is_deposit_disabled": 0,
"is_withdraw_disabled": 0,
"is_tag": 0
}
]
| 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 |
| » is_tag | integer | Whether to Include Tag |
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/deposit_address'
query_param = 'currency=USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/deposit_address"
query_param="currency=USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /wallet/deposit_address
Generate currency deposit address
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Currency name |
Example responses
200 Response
{
"currency": "USDT",
"address": "LPXtk1kWHioP62SzfqwKbYE3Z7Wt2ujYEc",
"multichain_addresses": [
{
"chain": "TRX",
"address": "LPXtk1kWHioP62SzfqwKbYE3Z7Wt2ujYEc",
"payment_id": "",
"payment_name": "",
"obtain_failed": 0,
"min_confirms": 1
}
],
"min_deposit_amount": "0.000006"
}
| 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 |
| » min_deposit_amount | string | Minimum Deposit Amount |
| » 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 |
| »»» min_confirms | integer | Minimum Confirmation Count |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/withdrawals'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/withdrawals"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /wallet/withdrawals
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
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": ""
}
]
]
| 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 |
| » type | string | Business Type |
| » 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 - BCODE: Deposit Code Operation - CANCEL: Cancelled - CANCELPEND: Withdrawal Cancellation Pending - DONE: Completed (Only considered truly on-chain when block_number > 0) - EXTPEND: Sent and Waiting for Confirmation - FAIL: On-Chain Failure Pending Confirmation - FVERIFY: Facial Verification in Progress - LOCKED: Wallet-Side Order Locked - MANUAL: Pending Manual Review - REJECT: Rejected - REQUEST: Request in Progress - 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/deposits'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/deposits"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /wallet/deposits
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 |
Example responses
200 Response
[
{
"id": "210496",
"timestamp": "1542000000",
"currency": "USDT",
"address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
"txid": "128988928203223323290",
"amount": "222.61",
"memo": "",
"status": "DONE",
"chain": "TRX"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | string | Record ID |
| » txid | string | Hash record of the withdrawal |
| » 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 | Transaction Status - BLOCKED: Deposit Blocked - DEP_CREDITED: Deposit Credited, Withdrawal Pending Unlock - DONE: Funds Credited to Spot Account - INVALID: Invalid Transaction - MANUAL: Manual Review Required - PEND: Processing - REVIEW: Under Compliance Review - TRACK: Tracking Block Confirmations, Pending Spot Account Credit |
| » 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/transfers'
query_param = ''
body='{"currency":"BTC","from":"spot","to":"margin","amount":"1","currency_pair":"BTC_USDT","settle":""}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/wallet/transfers"
query_param=""
body_param='{"currency":"BTC","from":"spot","to":"margin","amount":"1","currency_pair":"BTC_USDT","settle":""}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /wallet/transfers
Transfer between trading accounts
Balance transfers between personal trading accounts. Currently supports the following transfer operations:
Body parameter
{
"currency": "BTC",
"from": "spot",
"to": "margin",
"amount": "1",
"currency_pair": "BTC_USDT",
"settle": ""
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Transfer currency 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 |
Example responses
200 Response
{
"tx_id": 59636381286
}
| 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/wallet/sub_account_transfers"
query_param=""
body_param='{"sub_account":"10002","sub_account_type":"spot","currency":"BTC","amount":"1","direction":"to","client_order_id":"da3ce7a088c8b0372b741419c7829033"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /wallet/sub_account_transfers
Transfer between main and sub accounts
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
Body parameter
{
"sub_account": "10002",
"sub_account_type": "spot",
"currency": "BTC",
"amount": "1",
"direction": "to",
"client_order_id": "da3ce7a088c8b0372b741419c7829033"
}
| 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 |
Example responses
200 Response
{
"tx_id": 59636381286
}
| 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/sub_account_transfers"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /wallet/sub_account_transfers
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 |
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"
}
]
| 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_to_sub_account'
query_param = ''
body='{"currency":"usdt","sub_account_from":"10001","sub_account_from_type":"spot","sub_account_to":"10002","sub_account_to_type":"spot","amount":"1"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/wallet/sub_account_to_sub_account"
query_param=""
body_param='{"currency":"usdt","sub_account_from":"10001","sub_account_from_type":"spot","sub_account_to":"10002","sub_account_to_type":"spot","amount":"1"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /wallet/sub_account_to_sub_account
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
Body parameter
{
"currency": "usdt",
"sub_account_from": "10001",
"sub_account_from_type": "spot",
"sub_account_to": "10002",
"sub_account_to_type": "spot",
"amount": "1"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Transfer currency name |
| » sub_account_type | body | string | false | Transfer from 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 |
Example responses
200 Response
{
"tx_id": 59636381286
}
| 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/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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/order_status"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /wallet/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 |
Example responses
200 Response
{
"tx_id": "59636381286",
"status": "SUCCESS"
}
| 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/withdraw_status'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/withdraw_status"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /wallet/withdraw_status
Query withdrawal status
API operations are not supported for tokens with low liquidity or extremely low value. Please use the Web or App interface to query and process.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
Example responses
200 Response
[
{
"currency": "GT",
"name": "GateToken",
"name_cn": "GateToken",
"deposit": "0",
"withdraw_percent": "0%",
"withdraw_fix": "0.01",
"withdraw_day_limit": "20000",
"withdraw_day_limit_remain": "20000",
"withdraw_amount_mini": "0.11",
"withdraw_eachtime_limit": "20000",
"withdraw_fix_on_chains": {
"BTC": "20",
"ETH": "15",
"TRX": "0",
"EOS": "2.5"
},
"withdraw_percent_on_chains": {
"ETH": "0%",
"GTEVM": "0%"
}
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/sub_account_balances'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/sub_account_balances"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /wallet/sub_account_balances
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 |
Example responses
200 Response
[
{
"uid": "10003",
"available": {
"BTC": "0.1",
"GT": "2000",
"USDT": "10"
}
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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_margin_balances'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/sub_account_margin_balances"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /wallet/sub_account_margin_balances
Query sub-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 |
Example responses
200 Response
[
{
"uid": "10000",
"available": [
{
"locked": false,
"currency_pair": "BTC_USDT",
"risk": "9999.99",
"base": {
"available": "0.1",
"borrowed": "0",
"interest": "0",
"currency": "BTC",
"locked": "0"
},
"quote": {
"available": "0",
"borrowed": "0",
"interest": "0",
"currency": "USDT",
"locked": "0"
}
}
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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 account information |
| »»»» currency | string | Currency name |
| »»»» available | string | Amount available for margin trading, available = margin + borrowed |
| »»»» locked | string | Frozen funds, such as amounts already placed in margin market for order trading |
| »»»» borrowed | string | Borrowed funds |
| »»»» interest | string | Unpaid interest |
| »»» quote | object | Currency account information |
| »»»» currency | string | Currency name |
| »»»» available | string | Amount available for margin trading, available = margin + borrowed |
| »»»» locked | string | Frozen funds, such as amounts already placed in margin market for order trading |
| »»»» borrowed | string | Borrowed funds |
| »»»» interest | string | Unpaid 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 = '/wallet/sub_account_futures_balances'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/sub_account_futures_balances"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /wallet/sub_account_futures_balances
Query sub-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 |
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"
}
]
]
| 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 | Refers to the available withdrawal or trading amount in per-position, specifically the per-position available balance under the unified account that includes the credit line (which incorporates trial funds; since trial funds cannot be withdrawn, the actual withdrawal amount needs to deduct the trial fund portion when processing withdrawals) |
| »»» point | string | Point card amount |
| »»» currency | string | Settlement currency |
| »»» in_dual_mode | boolean | Whether Hedge Mode is enabled |
| »»» position_mode | string | Position mode: single - one-way, dual - dual-side, split - sub-positions (in_dual_mode is deprecated) |
| »»» 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 |
| »»» history | object | Statistical data |
| »»»» dnw | string | total amount of deposit and withdraw |
| »»»» pnl | string | total amount of trading profit and loss |
| »»»» fee | string | total amount of fee |
| »»»» refr | string | total amount of referrer rebates |
| »»»» fund | string | total amount of funding costs |
| »»»» point_dnw | string | total amount of point deposit and withdraw |
| »»»» point_fee | string | total amount of point fee |
| »»»» point_refr | string | total amount of referrer rebates of point fee |
| »»»» bonus_dnw | string | total amount of perpetual contract bonus transfer |
| »»»» bonus_offset | string | total amount of perpetual contract bonus deduction |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/sub_account_cross_margin_balances'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/sub_account_cross_margin_balances"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /wallet/sub_account_cross_margin_balances
Query 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 |
Example responses
200 Response
[
{
"uid": "100000",
"available": {
"user_id": 100003,
"locked": false,
"total": "20.000000",
"borrowed": "0.000000",
"interest": "0",
"borrowed_net": "0",
"net": "20",
"leverage": "3",
"risk": "9999.99",
"total_initial_margin": "0.00",
"total_margin_balance": "20.00",
"total_maintenance_margin": "0.00",
"total_initial_margin_rate": "9999.9900",
"total_maintenance_margin_rate": "9999.9900",
"total_available_margin": "20.00",
"balances": {
"USDT": {
"available": "20.000000",
"freeze": "0.000000",
"borrowed": "0.000000",
"interest": "0.000000"
}
}
}
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » uid | string | User ID |
| » available | object | none |
| »» user_id | integer(int64) | Cross margin account user ID. 0 means this sub-account has not yet opened a cross margin account |
| »» locked | boolean | Whether the account is locked |
| »» balances | object | none |
| »»» CrossMarginBalance | object | none |
| »»»» available | string | Available balance |
| »»»» freeze | string | Locked balance |
| »»»» borrowed | string | Borrowed balance |
| »»»» interest | string | Unpaid interest |
| »»» total | string | Total account value in USDT, i.e., the sum of all currencies' (available+freeze)*price*discount |
| »»» borrowed | string | Total borrowed value in USDT, i.e., the sum of all currencies' borrowed*price*discount |
| »»» borrowed_net | string | Total borrowed value in USDT * leverage factor |
| »»» net | string | Total net assets in USDT |
| »»» leverage | string | Position leverage |
| »»» interest | string | Total unpaid interest in USDT, i.e., the sum of all currencies' interest*price*discount |
| »»» risk | string | Risk rate. When it falls below 110%, liquidation will be triggered. Calculation formula: total / (borrowed+interest) |
| »»» total_initial_margin | string | Total initial margin |
| »»» total_margin_balance | string | Total margin balance |
| »»» total_maintenance_margin | string | Total maintenance margin |
| »»» total_initial_margin_rate | string | Total initial margin rate |
| »»» total_maintenance_margin_rate | string | Total maintenance margin rate |
| »»» total_available_margin | string | Total available margin |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/saved_address'
query_param = 'currency=USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/saved_address"
query_param="currency=USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /wallet/saved_address
Query 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 |
Example responses
200 Response
[
{
"currency": "usdt",
"chain": "TRX",
"address": "TWYirLzw2RARB2jfeFcfRPmeuU3rC7rakT",
"name": "gate",
"tag": "",
"verified": "1"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/fee'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/fee"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /wallet/fee
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 |
Example responses
200 Response
{
"user_id": 10001,
"taker_fee": "0.002",
"maker_fee": "0.002",
"rpi_maker_fee": "-0.00175",
"futures_taker_fee": "-0.00025",
"futures_maker_fee": "0.00075",
"futures_rpi_maker_fee": "-0.00175",
"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,
"rpi_mm": 2
}
| 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 | spot taker fee rate |
| » maker_fee | string | spot maker fee rate |
| » rpi_maker_fee | string | spot RPI MM 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 |
| » futures_rpi_maker_fee | string | contract RPI MM 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 |
| » rpi_mm | integer | RPI MM Level |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/total_balance'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/total_balance"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /wallet/total_balance
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 |
Example responses
200 Response
{
"details": {
"cross_margin": {
"amount": "0",
"currency": "USDT"
},
"spot": {
"currency": "USDT",
"amount": "42264489969935775.5160259954878034182418"
},
"finance": {
"amount": "662714381.70310327810191647181",
"currency": "USDT"
},
"margin": {
"amount": "1259175.664137668554329559",
"currency": "USDT",
"borrowed": "0.00"
},
"quant": {
"amount": "591702859674467879.6488202650892478553852",
"currency": "USDT"
},
"futures": {
"amount": "2384175.5606114082065",
"currency": "USDT",
"unrealised_pnl": "0.00"
},
"delivery": {
"currency": "USDT",
"amount": "1519804.9756702",
"unrealised_pnl": "0.00"
},
"warrant": {
"amount": "0",
"currency": "USDT"
},
"cbbc": {
"currency": "USDT",
"amount": "0"
}
},
"total": {
"currency": "USDT",
"amount": "633967350312281193.068368815439797304437",
"unrealised_pnl": "0.00",
"borrowed": "0.00"
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request is valid and successfully returned | Inline |
Status Code 200
User's total balance information
| Name | Type | Description |
|---|---|---|
| » total | object | Total balances calculated with specified currency unit |
| »» amount | string | Account total balance amount |
| »» currency | string | Currency |
| »» unrealised_pnl | string | Unrealised_pnl, this field will only appear in futures, options, delivery, and total accounts |
| »» borrowed | string | Total borrowed amount, this field will only appear in margin and cross_margin accounts |
| » details | object | Total balances in different accounts - cross_margin: cross margin account - spot: spot account - finance: finance account - margin: margin account - quant: quant account - futures: perpetual contract account - delivery: delivery contract account - warrant: warrant account - cbbc: CBBC account |
| »» additionalProperties | object | Total balances calculated with specified currency unit |
| »»» amount | string | Account total balance amount |
| »»» currency | string | Currency |
| »»» unrealised_pnl | string | Unrealised_pnl, this field will only appear in futures, options, delivery, and total accounts |
| »»» borrowed | string | Total borrowed amount, this field will only appear in margin and cross_margin accounts |
| Property | Value |
|---|---|
| currency | BTC |
| currency | CNY |
| currency | USD |
| currency | USDT |
| currency | BTC |
| currency | CNY |
| currency | USD |
| currency | USDT |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/small_balance'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/small_balance"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /wallet/small_balance
Get list of convertible small balance currencies
Example responses
200 Response
[
[
{
"currency": "FLOKI",
"available_balance": "182.29400000",
"estimated_as_btc": "0.00000012",
"convertible_to_gt": "0.001080"
},
{
"currency": "MBLK",
"available_balance": "0.91723337",
"estimated_as_btc": "0.00000102",
"convertible_to_gt": "0.009188"
}
]
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | 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 = ''
body='{"currency":["FLOKI","MBLK"],"is_all":true}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/wallet/small_balance"
query_param=""
body_param='{"currency":["FLOKI","MBLK"],"is_all":true}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /wallet/small_balance
Convert small balance currency
Body parameter
{
"currency": [
"FLOKI",
"MBLK"
],
"is_all": true
}
| 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_history'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/small_balance_history"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /wallet/small_balance_history
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 |
Example responses
200 Response
[
[
{
"id": "28583810",
"create_time": 1706670777,
"currency": "FLOKI",
"amount": "182.29400000",
"gt_amount": "0.001079"
}
]
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | 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/push'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/wallet/push"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /wallet/push
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. |
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"
}
]
| 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
Sub-account management
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts'
query_param = ''
body='{"remark":"remark","login_name":"sub_account_for_trades"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/sub_accounts"
query_param=""
body_param='{"remark":"remark","login_name":"sub_account_for_trades"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /sub_accounts
Create a new sub-account
Body parameter
{
"remark": "remark",
"login_name": "sub_account_for_trades"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » remark | body | string | false | Remark |
| » login_name | body | string | true | Sub-account login name: Only letters, numbers and underscores are supported, cannot contain other invalid characters |
| » password | body | string | false | The sub-account's password. (Default: the same as main account's password) |
| body | string | false | The sub-account's email address. (Default: the same as main account's email address) |
Example responses
201 Response
{
"remark": "remark",
"login_name": "sub_account_for_trades",
"user_id": 10001,
"state": 1,
"create_time": 168888888
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Created successfully | Inline |
Status Code 201
| Name | Type | Description |
|---|---|---|
| » remark | string | Remark |
| » login_name | string | Sub-account login name: Only letters, numbers and underscores are supported, cannot contain other invalid characters |
| » password | string | The sub-account's password. (Default: the same as main account's password) |
| string | The sub-account's email address. (Default: the same as main account's email address) | |
| » state | integer(int32) | 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/sub_accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /sub_accounts
List sub-accounts
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| type | query | string | false | 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.
Example responses
200 Response
[
{
"remark": "remark",
"login_name": "sub_account_for_trades",
"user_id": 10001,
"state": 1,
"create_time": 168888888
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » remark | string | Remark |
| » login_name | string | Sub-account login name: Only letters, numbers and underscores are supported, cannot contain other invalid characters |
| » password | string | The sub-account's password. (Default: the same as main account's password) |
| string | The sub-account's email address. (Default: the same as main account's email address) | |
| » state | integer(int32) | 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/sub_accounts/0"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /sub_accounts/{user_id}
Get sub-account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer(int64) | true | Sub-account user ID |
Example responses
200 Response
{
"remark": "remark",
"login_name": "sub_account_for_trades",
"user_id": 10001,
"state": 1,
"create_time": 168888888
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » remark | string | Remark |
| » login_name | string | Sub-account login name: Only letters, numbers and underscores are supported, cannot contain other invalid characters |
| » password | string | The sub-account's password. (Default: the same as main account's password) |
| string | The sub-account's email address. (Default: the same as main account's email address) | |
| » state | integer(int32) | 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/keys'
query_param = ''
body='{"mode":1,"name":"spot","perms":[{"read_only":false,"name":"options"},{"read_only":false,"name":"spot"},{"read_only":false,"name":"delivery"},{"read_only":false,"name":"wallet"},{"read_only":false,"name":"futures"}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/sub_accounts/0/keys"
query_param=""
body_param='{"mode":1,"name":"spot","perms":[{"read_only":false,"name":"options"},{"read_only":false,"name":"spot"},{"read_only":false,"name":"delivery"},{"read_only":false,"name":"wallet"},{"read_only":false,"name":"futures"}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /sub_accounts/{user_id}/keys
Create new sub-account API key pair
Body parameter
{
"mode": 1,
"name": "spot",
"perms": [
{
"read_only": false,
"name": "options"
},
{
"read_only": false,
"name": "spot"
},
{
"read_only": false,
"name": "delivery"
},
{
"read_only": false,
"name": "wallet"
},
{
"read_only": false,
"name": "futures"
}
],
"ip_whitelist": [
"127.0.0.1",
"127.0.0.2"
]
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer(int64) | true | Sub-account user ID |
| body | body | SubAccountKey | true | none |
| » mode | body | integer(int32) | false | Mode: 1 - classic 2 - portfolio account |
| » name | body | string | false | API Key Name |
| » perms | body | array | false | none |
| »» name | body | string | false | Permission 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)
Example responses
200 Response
{
"state": 1,
"name": "spot",
"user_id": 100000,
"perms": [
{
"name": "options",
"read_only": false
},
{
"name": "spot",
"read_only": false
},
{
"name": "delivery",
"read_only": false
},
{
"name": "wallet",
"read_only": false
},
{
"name": "futures",
"read_only": false
}
],
"ip_whitelist": [
"127.0.0.1",
"127.0.0.2"
],
"mode": 1,
"secret": "cddcc6e5e78060e013860bdbe5e737830b96821c027664586fb38b411808f4fd",
"key": "eb8815bf99d7bb5f8ad6497bdc4774a8",
"created_at": 1663683330,
"updated_at": 1663683330
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Created successfully | 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/sub_accounts/0/keys"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /sub_accounts/{user_id}/keys
List all API key pairs of the sub-account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer | true | Sub-account user ID |
Example responses
200 Response
[
{
"state": 1,
"name": "spot",
"user_id": 1000000,
"perms": [
{
"name": "futures",
"read_only": false
},
{
"name": "wallet",
"read_only": false
},
{
"name": "delivery",
"read_only": false
},
{
"name": "options",
"read_only": false
},
{
"name": "spot",
"read_only": false
}
],
"mode": 1,
"ip_whitelist": [
"127.0.0.1",
"127.0.0.2"
],
"key": "75c3264105b74693d8cb5c7f1a8e2420",
"created_at": 1663642892,
"last_access": 1663642892,
"update_at": 1663642892
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/string'
query_param = ''
body='{"mode":1,"name":"spot","perms":[{"read_only":false,"name":"options"},{"read_only":false,"name":"spot"},{"read_only":false,"name":"delivery"},{"read_only":false,"name":"wallet"},{"read_only":false,"name":"futures"}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PUT', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="PUT"
url="/sub_accounts/0/keys/string"
query_param=""
body_param='{"mode":1,"name":"spot","perms":[{"read_only":false,"name":"options"},{"read_only":false,"name":"spot"},{"read_only":false,"name":"delivery"},{"read_only":false,"name":"wallet"},{"read_only":false,"name":"futures"}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
PUT /sub_accounts/{user_id}/keys/{key}
Update sub-account API key pair
Body parameter
{
"mode": 1,
"name": "spot",
"perms": [
{
"read_only": false,
"name": "options"
},
{
"read_only": false,
"name": "spot"
},
{
"read_only": false,
"name": "delivery"
},
{
"read_only": false,
"name": "wallet"
},
{
"read_only": false,
"name": "futures"
}
],
"ip_whitelist": [
"127.0.0.1",
"127.0.0.2"
]
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer | true | Sub-account user ID |
| key | path | string | true | 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/sub_accounts/0/keys/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /sub_accounts/{user_id}/keys/{key}
Delete 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('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/sub_accounts/0/keys/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /sub_accounts/{user_id}/keys/{key}
Get 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 |
Example responses
200 Response
{
"state": 1,
"name": "spot",
"user_id": 1000000,
"perms": [
{
"name": "futures",
"read_only": false
},
{
"name": "wallet",
"read_only": false
},
{
"name": "delivery",
"read_only": false
},
{
"name": "options",
"read_only": false
},
{
"name": "spot",
"read_only": false
}
],
"mode": 1,
"ip_whitelist": [
"127.0.0.1",
"127.0.0.2"
],
"key": "75c3264105b74693d8cb5c7f1a8e2420",
"created_at": 1663642892,
"last_access": 1663642892,
"update_at": 1663642892
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/lock'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/sub_accounts/0/lock"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /sub_accounts/{user_id}/lock
Lock 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/unlock'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/sub_accounts/0/unlock"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /sub_accounts/{user_id}/unlock
Unlock 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/unified_mode'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/sub_accounts/unified_mode"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /sub_accounts/unified_mode
Get sub-account mode
Unified account mode:
classic: Classic account modemulti_currency: Cross-currency margin modeportfolio: Portfolio margin modesingle_currency: Single-currency margin modeExample responses
200 Response
[
{
"user_id": 110285555,
"is_unified": true,
"mode": "multi_currency"
}
]
| 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: Cross-currency margin mode- portfolio: Portfolio margin mode- single_currency: Single-currency margin mode |
WARNING
To perform this operation, you must be authenticated by API key and secret
Unified account
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/unified/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /unified/accounts
Get unified account information
The assets of each currency in the account will be adjusted according to their liquidity, defined by corresponding adjustment coefficients, and then uniformly converted to USD to calculate the total asset value and position value of the account.
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 |
Example responses
200 Response
{
"user_id": 10001,
"locked": false,
"balances": {
"ETH": {
"available": "0",
"freeze": "0",
"borrowed": "0.075393666654",
"negative_liab": "0",
"futures_pos_liab": "0",
"equity": "1016.1",
"total_freeze": "0",
"total_liab": "0",
"spot_in_use": "1.111"
},
"POINT": {
"available": "9999999999.017023138734",
"freeze": "0",
"borrowed": "0",
"negative_liab": "0",
"futures_pos_liab": "0",
"equity": "12016.1",
"total_freeze": "0",
"total_liab": "0",
"spot_in_use": "12"
},
"USDT": {
"available": "0.00000062023",
"freeze": "0",
"borrowed": "0",
"negative_liab": "0",
"futures_pos_liab": "0",
"equity": "16.1",
"total_freeze": "0",
"total_liab": "0",
"spot_in_use": "12"
}
},
"total": "230.94621713",
"borrowed": "161.66395521",
"total_initial_margin": "1025.0524665088",
"total_margin_balance": "3382495.944473949183",
"total_maintenance_margin": "205.01049330176",
"total_initial_margin_rate": "3299.827135672679",
"total_maintenance_margin_rate": "16499.135678363399",
"total_available_margin": "3381470.892007440383",
"unified_account_total": "3381470.892007440383",
"unified_account_total_liab": "0",
"unified_account_total_equity": "100016.1",
"leverage": "2",
"spot_order_loss": "12",
"spot_hedge": false
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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 applies to Single-Currency Margin Mode and Cross-Currency Margin Mode, and is 0 in other modes such as Portfolio 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 | Spot Pending Order Loss, in USDT, effective only in Cross-Currency Margin Mode and Portfolio Margin Mode. |
| »» options_order_loss | string | Option Pending Order Loss, in USDT, effective only in Portfolio 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/borrowable'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/unified/borrowable"
query_param="currency=BTC"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /unified/borrowable
Query maximum borrowable amount for unified account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Query by specified currency name |
Example responses
200 Response
{
"currency": "ETH",
"amount": "10000"
}
| 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/transferable'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/unified/transferable"
query_param="currency=BTC"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /unified/transferable
Query maximum transferable amount for unified account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Query by specified currency name |
Example responses
200 Response
{
"currency": "ETH",
"amount": "10000"
}
| 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/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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/unified/transferables"
query_param="currencies=BTC,ETH"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /unified/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 |
Example responses
200 Response
[
{
"currency": "BTC",
"amount": "123456"
}
]
| 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/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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/unified/batch_borrowable"
query_param="currencies=BTC,GT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /unified/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 |
Example responses
200 Response
[
{
"currency": "BTC",
"amount": "123456"
}
]
| 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/loans'
query_param = ''
body='{"currency":"BTC","amount":"0.1","type":"borrow","repaid_all":false,"text":"t-test"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/unified/loans"
query_param=""
body_param='{"currency":"BTC","amount":"0.1","type":"borrow","repaid_all":false,"text":"t-test"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /unified/loans
Borrow or repay
When borrowing, 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
Body parameter
{
"currency": "BTC",
"amount": "0.1",
"type": "borrow",
"repaid_all": false,
"text": "t-test"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Currency |
| » type | body | string | true | Type: borrow - borrow, repay - repay |
| » amount | body | string | true | 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 |
Example responses
200 Response
{
"tran_id": 9527
}
| 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/unified/loans"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /unified/loans
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 |
Example responses
200 Response
[
{
"currency": "USDT",
"currency_pari": "GT_USDT",
"amount": "1",
"type": "margin",
"change_time": 1673247054000,
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/loan_records'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/unified/loan_records"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /unified/loan_records
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 |
Example responses
200 Response
[
{
"id": 16442,
"type": "borrow",
"margin_mode": "cross",
"currency_pair": "AE_USDT",
"currency": "USDT",
"amount": "1000",
"create_time": 1673247054000,
"repayment_type": "auto_repay"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/interest_records'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/unified/interest_records"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /unified/interest_records
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 |
Example responses
200 Response
[
{
"status": 1,
"currency_pair": "BTC_USDT",
"currency": "USDT",
"actual_rate": "0.00000236",
"interest": "0.00006136",
"type": "platform",
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/risk_units'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/unified/risk_units"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /unified/risk_units
Get user risk unit details
Get user risk unit details, only valid in portfolio margin mode
Example responses
200 Response
{
"user_id": 0,
"spot_hedge": true,
"risk_units": [
{
"symbol": "BTC",
"spot_in_use": "-13500.000001223",
"maintain_margin": "2334.002",
"initial_margin": "2334.002",
"delta": "0.22",
"gamma": "0.42",
"theta": "0.29",
"vega": "0.22"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/unified_mode'
query_param = ''
body='{"mode":"portfolio","settings":{"spot_hedge":true,"usdt_futures":true,"options":true}}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PUT', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="PUT"
url="/unified/unified_mode"
query_param=""
body_param='{"mode":"portfolio","settings":{"spot_hedge":true,"usdt_futures":true,"options":true}}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
PUT /unified/unified_mode
Set 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/unified/unified_mode"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /unified/unified_mode
Query mode of the unified account
Unified account mode:
classic: Classic account modemulti_currency: Cross-currency margin modeportfolio: Portfolio margin modesingle_currency: Single-currency margin modeExample responses
200 Response
{
"mode": "portfolio",
"settings": {
"spot_hedge": true,
"usdt_futures": true,
"options": true
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/estimate_rate'
query_param = 'currencies=BTC,GT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/unified/estimate_rate"
query_param="currencies=BTC,GT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /unified/estimate_rate
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 |
Example responses
200 Response
{
"BTC": "0.000002",
"GT": "0.000001",
"ETH": ""
}
| 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
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/currency_discount_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/unified/currency_discount_tiers \
-H 'Accept: application/json'
GET /unified/currency_discount_tiers
Query unified account tiered
Example responses
200 Response
[
[
{
"currency": "USDT",
"discount_tiers": [
{
"tier": "1",
"discount": "1",
"lower_limit": "0",
"leverage": "10",
"upper_limit": "+"
}
]
},
{
"currency": "USDC",
"discount_tiers": [
{
"tier": "1",
"discount": "1",
"lower_limit": "0",
"leverage": "10",
"upper_limit": "10000000"
},
{
"tier": "2",
"discount": "0.98",
"lower_limit": "10000000",
"leverage": "10",
"upper_limit": "15000000"
},
{
"tier": "3",
"discount": "0.95",
"lower_limit": "15000000",
"leverage": "10",
"upper_limit": "20000000"
},
{
"tier": "4",
"discount": "0.925",
"lower_limit": "20000000",
"leverage": "10",
"upper_limit": "50000000"
},
{
"tier": "5",
"discount": "0.9",
"lower_limit": "50000000",
"leverage": "10",
"upper_limit": "100000000"
},
{
"tier": "6",
"discount": "0",
"lower_limit": "100000000",
"leverage": "10",
"upper_limit": "+"
}
]
},
{
"currency": "BTC",
"discount_tiers": [
{
"tier": "1",
"discount": "0.98",
"lower_limit": "0",
"leverage": "10",
"upper_limit": "1000"
},
{
"tier": "2",
"discount": "0.95",
"lower_limit": "1000",
"leverage": "10",
"upper_limit": "10000"
},
{
"tier": "3",
"discount": "0.9",
"lower_limit": "10000",
"leverage": "10",
"upper_limit": "50000"
},
{
"tier": "4",
"discount": "0.85",
"lower_limit": "50000",
"leverage": "10",
"upper_limit": "+"
}
]
},
{
"currency": "ETH",
"discount_tiers": [
{
"tier": "1",
"discount": "0.98",
"lower_limit": "0",
"leverage": "10",
"upper_limit": "1000"
},
{
"tier": "2",
"discount": "0.95",
"lower_limit": "1000",
"leverage": "10",
"upper_limit": "10000"
},
{
"tier": "3",
"discount": "0.9",
"lower_limit": "10000",
"leverage": "10",
"upper_limit": "50000"
},
{
"tier": "4",
"discount": "0.85",
"lower_limit": "50000",
"leverage": "10",
"upper_limit": "+"
}
]
}
]
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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 | Tier |
| »»» discount | string | Discount |
| »»» lower_limit | string | Lower limit |
| »»» upper_limit | string | Upper limit, + indicates positive infinity |
| »»» leverage | string | Position leverage |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/loan_margin_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/unified/loan_margin_tiers \
-H 'Accept: application/json'
GET /unified/loan_margin_tiers
Query unified account tiered loan margin
Example responses
200 Response
[
{
"currency": "USDT",
"margin_tiers": [
{
"tier": "1",
"margin_rate": "0.02",
"lower_limit": "200000",
"upper_limit": "400000",
"leverage": "3"
}
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/portfolio_calculator'
query_param = ''
body='{"spot_balances":[{"currency":"BTC","equity":"-1","freeze":"10"}],"spot_orders":[{"currency_pairs":"BTC_USDT","order_price":"344","size":"100","left":"100","type":"sell"}],"futures_positions":[{"contract":"BTC_USDT","size":"100"}],"futures_orders":[{"contract":"BTC_USDT","size":"10","left":"8"}],"options_positions":[{"options_name":"BTC_USDT-20240329-32000-C","size":"10"}],"options_orders":[{"options_name":"BTC_USDT-20240329-32000-C","size":"100","left":"80"}],"spot_hedge":false}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST https://api.gateio.ws/api/v4/unified/portfolio_calculator \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /unified/portfolio_calculator
Portfolio margin calculator
Portfolio Margin Calculator
When inputting 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.
Body parameter
{
"spot_balances": [
{
"currency": "BTC",
"equity": "-1",
"freeze": "10"
}
],
"spot_orders": [
{
"currency_pairs": "BTC_USDT",
"order_price": "344",
"size": "100",
"left": "100",
"type": "sell"
}
],
"futures_positions": [
{
"contract": "BTC_USDT",
"size": "100"
}
],
"futures_orders": [
{
"contract": "BTC_USDT",
"size": "10",
"left": "8"
}
],
"options_positions": [
{
"options_name": "BTC_USDT-20240329-32000-C",
"size": "10"
}
],
"options_orders": [
{
"options_name": "BTC_USDT-20240329-32000-C",
"size": "100",
"left": "80"
}
],
"spot_hedge": false
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » spot_balances | body | array | false | Spot |
| »» None | body | object | false | Spot |
| »»» currency | body | string | true | Currency name |
| »»» equity | body | string | true | Currency equity, where equity = balance - borrowed, represents the net delta exposure of your spot positions, which can be negative. Currently only supports BTC and ETH |
| »» spot_orders | body | array | false | Spot orders |
| »»» None | body | object | false | Spot orders |
| »»»» currency_pairs | body | string | true | Market |
| »»»» order_price | body | string | true | Price |
| »»»» count | body | string | false | Initial order quantity for spot trading pairs, not involved in actual calculation. Currently only supports BTC and ETH Currently only supports three currencies: BTC, ETH |
| »»»» left | body | string | true | Unfilled quantity, involved in actual calculation |
| »»»» type | body | string | true | Order type, sell - sell order, buy - buy order |
| »»» futures_positions | body | array | false | Futures positions |
| »»»» None | body | object | false | Futures positions |
| »»»»» contract | body | string | true | Futures name, currently only supports USDT perpetual contracts for BTC and ETH |
| »»»»» size | body | string | true | Position size, measured in contract quantity |
| »»»» futures_orders | body | array | false | Futures order |
| »»»»» None | body | object | false | Futures order |
| »»»»»» contract | body | string | true | Futures name, currently only supports USDT perpetual contracts for BTC and ETH |
| »»»»»» size | body | string | true | Contract quantity, representing the initial order quantity, not involved in actual settlement |
| »»»»»» left | body | string | true | Unfilled contract quantity, involved in actual calculation |
| »»»»» options_positions | body | array | false | Options positions |
| »»»»»» None | body | object | false | Options positions |
| »»»»»»» options_name | body | string | true | Option name, currently only supports USDT options for BTC and ETH |
| »»»»»»» size | body | string | true | Position size, measured in contract quantity |
| »»»»»» options_orders | body | array | false | Option orders |
| »»»»»»» None | body | object | false | Option orders |
| »»»»»»»» options_name | body | string | true | Option name, currently only supports USDT options for BTC and ETH |
| »»»»»»»» size | body | string | true | Initial order quantity, not involved in actual calculation |
| »»»»»»»» left | body | string | true | Unfilled contract quantity, involved in actual calculation |
| »»»»»»» spot_hedge | body | boolean | false | Whether to enable spot hedging |
Example responses
200 Response
{
"maintain_margin_total": "0.000000000000",
"initial_margin_total": "0.000000000000",
"calculate_time": "1709014486",
"risk_unit": [
{
"symbol": "BTC",
"margin_result": [
{
"type": "original_position",
"profit_loss_ranges": [
{
"price_percentage": "-0.200000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "-0.160000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "-0.120000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "-0.080000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "-0.040000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.000000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.040000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.080000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.120000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.160000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.200000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
}
],
"max_loss": {
"price_percentage": "-0.200000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
"mr1": "0.000000000000",
"mr2": "0.000000000000",
"mr3": "0.000000000000",
"mr4": "0.000000000000"
}
],
"maintain_margin": "0.000000000000",
"initial_margin": "0.000000000000"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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 | Risk unit |
| »»» symbol | string | Risk unit name |
| »»» spot_in_use | string | Spot hedge usage |
| »»» maintain_margin | string | Maintenance margin |
| »»» initial_margin | string | Initial margin |
| »»» margin_result | array | Margin result |
| »»»» None | object | Margin result |
| »»»»» type | string | Position combination typeoriginal_position - Original positionlong_delta_original_position - Positive delta + Original positionshort_delta_original_position - Negative delta + Original position |
| »»»»» profit_loss_ranges | array | Results of 33 stress scenarios for MR1 |
| »»»»»» None | object | Profit and loss range |
| »»»»»»» price_percentage | string | Percentage change in price |
| »»»»»»» implied_volatility_percentage | string | Percentage change in implied volatility |
| »»»»»»» profit_loss | string | PnL |
| »»»»»» max_loss | object | Profit and loss range |
| »»»»»»» price_percentage | string | Percentage change in price |
| »»»»»»» implied_volatility_percentage | string | Percentage change in implied volatility |
| »»»»»»» profit_loss | string | PnL |
| »»»»»» mr1 | string | Stress testing |
| »»»»»» mr2 | string | Basis spread risk |
| »»»»»» mr3 | string | Volatility spread risk |
| »»»»»» mr4 | string | Option short risk |
| »»»»» delta | string | Total Delta of risk unit |
| »»»»» gamma | string | Total Gamma of risk unit |
| »»»»» theta | string | Total Theta of risk unit |
| »»»»» vega | string | Total Vega of risk unit |
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/leverage/user_currency_config'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/unified/leverage/user_currency_config"
query_param="currency=BTC"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /unified/leverage/user_currency_config
Maximum and minimum currency leverage that can be set
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Currency |
Example responses
200 Response
{
"current_leverage": "2",
"min_leverage": "0",
"max_leverage": "0",
"debit": "0",
"available_margin": "0",
"borrowable": "0",
"except_leverage_borrowable": "0"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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_setting'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/unified/leverage/user_currency_setting"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /unified/leverage/user_currency_setting
Get 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 |
Example responses
200 Response
[
{
"currency": "BTC",
"leverage": "3"
}
]
| 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 = ''
body='{"currency":"BTC","leverage":"3"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/unified/leverage/user_currency_setting"
query_param=""
body_param='{"currency":"BTC","leverage":"3"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /unified/leverage/user_currency_setting
Set loan currency leverage
Body parameter
{
"currency": "BTC",
"leverage": "3"
}
| 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
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())
curl -X GET https://api.gateio.ws/api/v4/unified/currencies \
-H 'Accept: application/json'
GET /unified/currencies
List of loan currencies supported by unified account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Currency |
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"
}
]
| 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/history_loan_rate'
query_param = 'currency=USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/unified/history_loan_rate?currency=USDT \
-H 'Accept: application/json'
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 |
Example responses
200 Response
{
"currency": "USDT",
"tier": "1",
"tier_up_rate": "1.18",
"rates": [
{
"time": 1729047616000,
"rate": "0.00010287"
}
]
}
| 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
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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/unified/collateral_currencies"
query_param=""
body_param='{"collateral_type":1,"enable_list":["BTC","ETH"],"disable_list":["SOL","GT"]}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /unified/collateral_currencies
Set collateral currency
Body parameter
{
"collateral_type": 1,
"enable_list": [
"BTC",
"ETH"
],
"disable_list": [
"SOL",
"GT"
]
}
| 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 |
Example responses
200 Response
{
"is_success": true
}
| 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
Isolated Margin
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/accounts
Margin account list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Currency pair |
Example responses
200 Response
[
{
"currency_pair": "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"
}
}
]
| 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 account information |
| »»» currency | string | Currency name |
| »»» available | string | Amount available for margin trading, available = margin + borrowed |
| »»» locked | string | Frozen funds, such as amounts already placed in margin market for order trading |
| »»» borrowed | string | Borrowed funds |
| »»» interest | string | Unpaid interest |
| »» quote | object | Currency account information |
| »»» currency | string | Currency name |
| »»» available | string | Amount available for margin trading, available = margin + borrowed |
| »»» locked | string | Frozen funds, such as amounts already placed in margin market for order trading |
| »»» borrowed | string | Borrowed funds |
| »»» interest | string | Unpaid interest |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/account_book"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/account_book
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
Example responses
200 Response
[
{
"id": "123456",
"time": "1547633726",
"time_ms": 1547633726123,
"currency": "BTC",
"currency_pair": "BTC_USDT",
"change": "1.03",
"balance": "4.59316525194"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/funding_accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/funding_accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/funding_accounts
Funding account list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
Example responses
200 Response
[
{
"currency": "BTC",
"available": "1.238",
"locked": "0",
"lent": "3.32",
"total_lent": "3.32"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/auto_repay'
query_param = 'status=on'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/margin/auto_repay"
query_param="status=on"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /margin/auto_repay
Update user auto repayment settings
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| status | query | string | true | Whether to enable auto repayment: on - enabled, off - disabled |
Example responses
200 Response
{
"status": "on"
}
| 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/auto_repay"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/auto_repay
Query user auto repayment settings
Example responses
200 Response
{
"status": "on"
}
| 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/transferable'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/transferable"
query_param="currency=BTC"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/transferable
Get 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 |
Example responses
200 Response
{
"currency": "ETH",
"currency_pair": "ETH_USDT",
"amount": "10000"
}
| 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
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/uni/currency_pairs'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/margin/uni/currency_pairs \
-H 'Accept: application/json'
GET /margin/uni/currency_pairs
List lending markets
Example responses
200 Response
[
{
"currency_pair": "AE_USDT",
"base_min_borrow_amount": "100",
"quote_min_borrow_amount": "100",
"leverage": "3"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/AE_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/margin/uni/currency_pairs/AE_USDT \
-H 'Accept: application/json'
GET /margin/uni/currency_pairs/{currency_pair}
Get lending market details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | path | string | true | Currency pair |
Example responses
200 Response
{
"currency_pair": "AE_USDT",
"base_min_borrow_amount": "100",
"quote_min_borrow_amount": "100",
"leverage": "3"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/uni/estimate_rate'
query_param = 'currencies=BTC,GT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/uni/estimate_rate"
query_param="currencies=BTC,GT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/uni/estimate_rate
Estimate interest rate 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 |
Example responses
200 Response
{
"BTC": "0.000002",
"GT": "0.000001"
}
| 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/loans'
query_param = ''
body='{"currency":"BTC","amount":"0.1","type":"borrow","currency_pair":"BTC_USDT","repaid_all":false}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/margin/uni/loans"
query_param=""
body_param='{"currency":"BTC","amount":"0.1","type":"borrow","currency_pair":"BTC_USDT","repaid_all":false}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /margin/uni/loans
Borrow or repay
Body parameter
{
"currency": "BTC",
"amount": "0.1",
"type": "borrow",
"currency_pair": "BTC_USDT",
"repaid_all": false
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Currency |
| » type | body | string | true | Type: borrow - borrow, repay - repay |
| » amount | body | string | true | 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/uni/loans"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/uni/loans
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 |
Example responses
200 Response
[
{
"currency": "USDT",
"currency_pari": "GT_USDT",
"amount": "1",
"type": "margin",
"change_time": 1673247054000,
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/loan_records'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/uni/loan_records"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/uni/loan_records
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 |
Example responses
200 Response
[
{
"type": "borrow",
"currency_pair": "AE_USDT",
"currency": "USDT",
"amount": "1000",
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/interest_records'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/uni/interest_records"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/uni/interest_records
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
Example responses
200 Response
[
{
"status": 1,
"currency_pair": "BTC_USDT",
"currency": "USDT",
"actual_rate": "0.00000236",
"interest": "0.00006136",
"type": "platform",
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/borrowable'
query_param = 'currency=BTC¤cy_pair=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/uni/borrowable"
query_param="currency=BTC¤cy_pair=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/uni/borrowable
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 |
Example responses
200 Response
{
"currency": "AE",
"borrowable": "1123.344",
"currency_pair": "AE_USDT"
}
| 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/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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/user/loan_margin_tiers"
query_param="currency_pair=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /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 |
Example responses
200 Response
[
{
"tier_amount": "100",
"mmr": "0.9",
"leverage": "1"
}
]
| 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
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())
curl -X GET https://api.gateio.ws/api/v4/margin/loan_margin_tiers?currency_pair=BTC_USDT \
-H 'Accept: application/json'
GET /margin/loan_margin_tiers
Query current market leverage lending tiers
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | true | Currency pair |
Example responses
200 Response
[
{
"tier_amount": "100",
"mmr": "0.9",
"leverage": "1"
}
]
| 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
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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/margin/leverage/user_market_setting"
query_param=""
body_param='{"currency_pair":"BTC_USDT","leverage":"10"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /margin/leverage/user_market_setting
Set user market leverage multiplier
Body parameter
{
"currency_pair": "BTC_USDT",
"leverage": "10"
}
| 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/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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/margin/user/account"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /margin/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 |
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"
}
}
]
| 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 account information |
| »»» currency | string | Currency name |
| »»» available | string | Amount available for margin trading, available = margin + borrowed |
| »»» locked | string | Frozen funds, such as amounts already placed in margin market for order trading |
| »»» borrowed | string | Borrowed funds |
| »»» interest | string | Unpaid interest |
| »» quote | object | Currency account information |
| »»» currency | string | Currency name |
| »»» available | string | Amount available for margin trading, available = margin + borrowed |
| »»» locked | string | Frozen funds, such as amounts already placed in margin market for order trading |
| »»» borrowed | string | Borrowed funds |
| »»» interest | string | Unpaid interest |
WARNING
To perform this operation, you must be authenticated by API key and secret
Spot trading
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/spot/currencies \
-H 'Accept: application/json'
GET /spot/currencies
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
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": ""
}
]
}
]
| 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 |
| » 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())
curl -X GET https://api.gateio.ws/api/v4/spot/currencies/GT \
-H 'Accept: application/json'
GET /spot/currencies/{currency}
Query single currency information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | true | Currency name |
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": ""
}
]
}
| 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 |
| » 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/currency_pairs'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/spot/currency_pairs \
-H 'Accept: application/json'
GET /spot/currency_pairs
Query all supported currency pairs
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
}
]
| 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(deprecated) |
| »» 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())
curl -X GET https://api.gateio.ws/api/v4/spot/currency_pairs/ETH_BTC \
-H 'Accept: application/json'
GET /spot/currency_pairs/{currency_pair}
Query single currency pair details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | path | string | true | Currency pair |
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
}
| 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(deprecated) |
| » 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/tickers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/spot/tickers \
-H 'Accept: application/json'
GET /spot/tickers
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 |
Example responses
200 Response
[
{
"currency_pair": "BTC3L_USDT",
"last": "2.46140352",
"lowest_ask": "2.477",
"highest_bid": "2.4606821",
"change_percentage": "-8.91",
"change_utc0": "-8.91",
"change_utc8": "-8.91",
"base_volume": "656614.0845820589",
"quote_volume": "1602221.66468375534639404191",
"high_24h": "2.7431",
"low_24h": "1.9863",
"etf_net_value": "2.46316141",
"etf_pre_net_value": "2.43201848",
"etf_pre_timestamp": 1611244800,
"etf_leverage": "2.2803019447281203"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/order_book'
query_param = 'currency_pair=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/spot/order_book?currency_pair=BTC_USDT \
-H 'Accept: application/json'
GET /spot/order_book
Get market depth information
Market depth buy orders are sorted by price from high to low, sell orders are reversed
| 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 |
Example responses
200 Response
{
"id": 123456,
"current": 1623898993123,
"update": 1623898993121,
"asks": [
[
"1.52",
"1.151"
],
[
"1.53",
"1.218"
]
],
"bids": [
[
"1.17",
"201.863"
],
[
"1.16",
"725.464"
]
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/trades'
query_param = 'currency_pair=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/spot/trades?currency_pair=BTC_USDT \
-H 'Accept: application/json'
GET /spot/trades
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 | Use the ID of the last record in the previous list as the starting point for the next list |
| 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 |
last_id: Use the ID of the last record in the previous list as the starting point for the next list
Operations based on custom IDs can only be checked when orders are pending. After orders are completed (filled/cancelled), they can be checked within 1 hour after completion. After expiration, only order IDs can be used
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.
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",
"deal": "0.0045"
}
]
| 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 |
| » deal | string | Total Executed Value |
| Property | Value |
|---|---|
| side | buy |
| side | sell |
| role | taker |
| role | maker |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/candlesticks'
query_param = 'currency_pair=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/spot/candlesticks?currency_pair=BTC_USDT \
-H 'Accept: application/json'
GET /spot/candlesticks
Market 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 |
Example responses
200 Response
[
[
"1539852480",
"971519.677",
"0.0021724",
"0.0021922",
"0.0021724",
"0.0021737",
"true"
]
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/fee'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/fee"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /spot/fee
Query 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.
Example responses
200 Response
{
"user_id": 10001,
"taker_fee": "0.002",
"maker_fee": "0.002",
"gt_discount": false,
"gt_taker_fee": "0",
"gt_maker_fee": "0",
"loan_fee": "0.18",
"point_type": "1",
"currency_pair": "BTC_USDT",
"debit_fee": 3
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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 |
| » rpi_maker_fee | string | RPI MM 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 |
| » rpi_mm | integer | RPI MM Level |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/batch_fee'
query_param = 'currency_pairs=BTC_USDT,ETH_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/batch_fee"
query_param="currency_pairs=BTC_USDT,ETH_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /spot/batch_fee
Batch query account fee rates
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pairs | query | string | true | Maximum 50 currency pairs per request |
Example responses
200 Response
{
"BTC_USDT": {
"user_id": 10001,
"taker_fee": "0.002",
"maker_fee": "0.002",
"rpi_maker_fee": "-0.00175",
"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,
"rpi_mm": 2
},
"GT_USDT": {
"user_id": 10001,
"taker_fee": "0.002",
"maker_fee": "0.002",
"rpi_maker_fee": "-0.00175",
"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,
"rpi_mm": 2
},
"ETH_USDT": {
"user_id": 10001,
"taker_fee": "0.002",
"maker_fee": "0.002",
"rpi_maker_fee": "-0.00175",
"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,
"rpi_mm": 2
}
}
| 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 |
| »» rpi_maker_fee | string | RPI MM 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 |
| »» rpi_mm | integer | RPI MM Level |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /spot/accounts
List spot trading accounts
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
Example responses
200 Response
[
{
"currency": "ETH",
"available": "968.8",
"locked": "0",
"update_id": 98
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/account_book"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /spot/account_book
Query 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 |
Example responses
200 Response
[
{
"id": "123456",
"time": 1547633726123,
"currency": "BTC",
"change": "1.03",
"balance": "4.59316525194",
"type": "margin_in",
"text": "3815099"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/batch_orders'
query_param = ''
body='[{"text":"t-abc123","currency_pair":"BTC_USDT","type":"limit","account":"unified","side":"buy","amount":"0.001","price":"65000","time_in_force":"gtc","iceberg":"0"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/batch_orders"
query_param=""
body_param='[{"text":"t-abc123","currency_pair":"BTC_USDT","type":"limit","account":"unified","side":"buy","amount":"0.001","price":"65000","time_in_force":"gtc","iceberg":"0"}]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /spot/batch_orders
Batch place orders
Batch order requirements:
text must be specifiedaccount fields in the same request must be identicalBody parameter
[
{
"text": "t-abc123",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0"
}
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | 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 |
Example responses
200 Response
[
{
"order_id": "12332324",
"amend_text": "t-123456",
"text": "t-123456",
"succeeded": true,
"label": "",
"message": "",
"id": "12332324",
"create_time": "1548000000",
"update_time": "1548000100",
"create_time_ms": 1548000000123,
"update_time_ms": 1548000100123,
"currency_pair": "ETC_BTC",
"status": "cancelled",
"type": "limit",
"account": "spot",
"side": "buy",
"amount": "1",
"price": "5.00032",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0.5",
"filled_amount": "1.242",
"filled_total": "2.50016",
"avg_deal_price": "5.00032",
"fee": "0.005",
"fee_currency": "ETH",
"point_fee": "0",
"gt_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "BTC",
"stp_act": "cn",
"finish_as": "stp",
"stp_id": 10240
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request 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/open_orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/open_orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /spot/open_orders
List all open orders
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 |
Example responses
200 Response
[
{
"currency_pair": "ETH_BTC",
"total": 1,
"orders": [
{
"id": "12332324",
"text": "t-123456",
"create_time": "1548000000",
"update_time": "1548000100",
"currency_pair": "ETH_BTC",
"status": "open",
"type": "limit",
"account": "spot",
"side": "buy",
"amount": "1",
"price": "5.00032",
"time_in_force": "gtc",
"left": "0.5",
"filled_total": "2.50016",
"fee": "0.005",
"fee_currency": "ETH",
"point_fee": "0",
"gt_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "BTC"
}
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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 |
| Property | Value |
|---|---|
| status | open |
| status | closed |
| status | cancelled |
| type | limit |
| type | market |
| side | buy |
| side | sell |
| time_in_force | gtc |
| time_in_force | ioc |
| time_in_force | poc |
| time_in_force | fok |
| stp_act | cn |
| stp_act | co |
| stp_act | cb |
| stp_act | - |
| finish_as | open |
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidate_cancelled |
| finish_as | depth_not_enough |
| finish_as | trader_not_enough |
| finish_as | small |
| finish_as | ioc |
| finish_as | poc |
| finish_as | fok |
| finish_as | stp |
| finish_as | unknown |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/cross_liquidate_orders'
query_param = ''
body='{"currency_pair":"GT_USDT","amount":"12","price":"10.15","text":"t-34535"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/cross_liquidate_orders"
query_param=""
body_param='{"currency_pair":"GT_USDT","amount":"12","price":"10.15","text":"t-34535"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /spot/cross_liquidate_orders
Close position when cross-currency is disabled
Currently, only cross-margin accounts are supported to 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
Body parameter
{
"currency_pair": "GT_USDT",
"amount": "12",
"price": "10.15",
"text": "t-34535"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » text | body | string | false | 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)
Example responses
201 Response
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order created 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 |
| 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/orders"
query_param=""
body_param='{"text":"t-abc123","currency_pair":"BTC_USDT","type":"limit","account":"unified","side":"buy","amount":"0.001","price":"65000","time_in_force":"gtc","iceberg":"0"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /spot/orders
Create an order
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
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"
}
| 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 |
| » 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 | - |
Example responses
ACK response body example
{
"id": "12332324",
"text": "t-123456",
"amend_text": "test2"
}
RESULT response body example
{
"id": "12332324",
"text": "t-123456",
"create_time": "1548000000",
"update_time": "1548000100",
"create_time_ms": 1548000000123,
"update_time_ms": 1548000100123,
"currency_pair": "ETH_BTC",
"status": "cancelled",
"type": "limit",
"account": "spot",
"side": "buy",
"iceberg": "0",
"amount": "1",
"price": "5.00032",
"time_in_force": "gtc",
"auto_borrow": false,
"left": "0.5",
"filled_total": "2.50016",
"avg_deal_price": "5.00032",
"stp_act": "cn",
"finish_as": "stp",
"stp_id": 10240
}
FULL response body example
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order created | 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 |
| » 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 = 'currency_pair=BTC_USDT&status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/orders"
query_param="currency_pair=BTC_USDT&status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /spot/orders
List orders
Note that query results default to spot order lists for spot, unified account, and isolated margin accounts.
When status is set to open (i.e., when querying pending order lists), only page and limit pagination controls are supported. limit can only be set to a maximum of 100.
The side parameter and time range query parameters from and to are not supported.
When status is set to finished (i.e., when querying historical orders), in addition to pagination queries, from and to time range queries are also supported.
Additionally, the side parameter can be set to filter one-sided history.
Time range filter parameters are processed according to the order end time.
| 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
Example responses
200 Response
[
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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 |
| 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
open orders in specified currency pairCode samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/spot/orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /spot/orders
Cancel all open orders in specified currency pair
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)Example responses
200 Response
[
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"succeeded": true,
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation request accepted 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 |
| Property | Value |
|---|---|
| status | open |
| status | closed |
| status | cancelled |
| type | limit |
| type | market |
| side | buy |
| side | sell |
| time_in_force | gtc |
| time_in_force | ioc |
| time_in_force | poc |
| time_in_force | fok |
| stp_act | cn |
| stp_act | co |
| stp_act | cb |
| stp_act | - |
| finish_as | open |
| finish_as | filled |
| finish_as | cancelled |
| finish_as | ioc |
| finish_as | stp |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/cancel_batch_orders'
query_param = ''
body='[{"currency_pair":"BTC_USDT","id":"123456"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/cancel_batch_orders"
query_param=""
body_param='[{"currency_pair":"BTC_USDT","id":"123456"}]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /spot/cancel_batch_orders
Cancel batch orders by specified ID list
Multiple currency pairs can be specified, but maximum 20 orders are allowed per request
Body parameter
[
{
"currency_pair": "BTC_USDT",
"id": "123456"
}
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | 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 |
Example responses
200 Response
[
{
"currency_pair": "BTC_USDT",
"id": "123456",
"text": "123456",
"succeeded": true,
"label": null,
"message": null
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation completed | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » CancelOrderResult | object | Order cancellation result |
| »» currency_pair | string | Order currency pair |
| »» id | string | Order ID |
| »» text | string | Custom order information |
| »» succeeded | boolean | Whether cancellation succeeded |
| »» label | string | Error label when failed to cancel the order; emtpy if succeeded |
| »» message | string | Error 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/orders/12345'
query_param = 'currency_pair=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/orders/12345"
query_param="currency_pair=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /spot/orders/{order_id}
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)
Example responses
200 Response
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Detail retrieved | 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 |
| 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="PATCH"
url="/spot/orders/12345"
query_param=""
body_param='{"currency_pair":"BTC_USDT","account":"spot","amount":"1"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
PATCH /spot/orders/{order_id}
Amend 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.
Body parameter
{
"currency_pair": "BTC_USDT",
"account": "spot",
"amount": "1"
}
| 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)
Example responses
200 Response
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Updated 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 |
| 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/spot/orders/12345"
query_param="currency_pair=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /spot/orders/{order_id}
Cancel 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)Example responses
200 Response
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order cancelled | 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 |
| 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/my_trades'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/my_trades"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /spot/my_trades
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 | The accountparameter has been deprecated. The interface supports querying all transaction records of the 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 |
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",
"deal": "0.0045"
}
]
| 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 |
| » deal | string | Total Executed Value |
| Property | Value |
|---|---|
| side | buy |
| side | sell |
| role | taker |
| role | maker |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/time'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/spot/time \
-H 'Accept: application/json'
GET /spot/time
Get server current time
Example responses
200 Response
{
"server_time": 1597026383085
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/countdown_cancel_all'
query_param = ''
body='{"timeout":30,"currency_pair":"BTC_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/countdown_cancel_all"
query_param=""
body_param='{"timeout":30,"currency_pair":"BTC_USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /spot/countdown_cancel_all
Countdown cancel orders
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.
Body parameter
{
"timeout": 30,
"currency_pair": "BTC_USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » timeout | body | integer(int32) | true | Countdown time in seconds |
| » currency_pair | body | string | false | Currency pair |
» timeout: Countdown time in seconds At least 5 seconds, 0 means cancel countdown
Example responses
200 Response
{
"triggerTime": "1660039145000"
}
| 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/amend_batch_orders'
query_param = ''
body='[{"order_id":"121212","currency_pair":"BTC_USDT","account":"spot","amount":"1","amend_text":"test"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/amend_batch_orders"
query_param=""
body_param='[{"order_id":"121212","currency_pair":"BTC_USDT","account":"spot","amount":"1","amend_text":"test"}]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /spot/amend_batch_orders
Batch modification of orders
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.
Body parameter
[
{
"order_id": "121212",
"currency_pair": "BTC_USDT",
"account": "spot",
"amount": "1",
"amend_text": "test"
}
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | 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 |
Example responses
200 Response
[
{
"order_id": "12332324",
"amend_text": "t-123456",
"text": "t-123456",
"succeeded": true,
"label": "",
"message": "",
"id": "12332324",
"create_time": "1548000000",
"update_time": "1548000100",
"create_time_ms": 1548000000123,
"update_time_ms": 1548000100123,
"currency_pair": "ETC_BTC",
"status": "cancelled",
"type": "limit",
"account": "spot",
"side": "buy",
"amount": "1",
"price": "5.00032",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0.5",
"filled_amount": "1.242",
"filled_total": "2.50016",
"avg_deal_price": "5.00032",
"fee": "0.005",
"fee_currency": "ETH",
"point_fee": "0",
"gt_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "BTC",
"stp_act": "cn",
"finish_as": "stp",
"stp_id": 10240
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order modification executed successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Batch order details] |
| » None | object | Batch order details |
| »» order_id | string | Order ID |
| »» amend_text | string | The custom data that the user remarked when amending the order |
| »» text | string | 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
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())
curl -X GET https://api.gateio.ws/api/v4/spot/insurance_history?business=margin¤cy=BTC&from=1547706332&to=1547706332 \
-H 'Accept: application/json'
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 |
Example responses
200 Response
[
{
"currency": "BTC",
"balance": "1021.21",
"time": 1727054547
}
]
| 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
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/price_orders'
query_param = ''
body='{"trigger":{"price":"100","rule":">=","expiration":3600},"put":{"type":"limit","side":"buy","price":"2.15","amount":"2.00000000","account":"normal","time_in_force":"gtc","text":"api"},"market":"GT_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/price_orders"
query_param=""
body_param='{"trigger":{"price":"100","rule":">=","expiration":3600},"put":{"type":"limit","side":"buy","price":"2.15","amount":"2.00000000","account":"normal","time_in_force":"gtc","text":"api"},"market":"GT_USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /spot/price_orders
Create price-triggered order
Body parameter
{
"trigger": {
"price": "100",
"rule": ">=",
"expiration": 3600
},
"put": {
"type": "limit",
"side": "buy",
"price": "2.15",
"amount": "2.00000000",
"account": "normal",
"time_in_force": "gtc",
"text": "api"
},
"market": "GT_USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | SpotPriceTriggeredOrder | true | none |
| » trigger | body | object | true | none |
| »» price | body | string | true | Trigger price |
| »» rule | body | string | true | Price trigger condition |
| »» expiration | body | integer | true | 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, refers to the trading quantity of the trading currency, i.e., the currency that needs to be traded, for example, the quantity of BTC in BTC_USDT. |
| »» 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
»» 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 |
Example responses
201 Response
{
"id": 1432329
}
| 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 = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/price_orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /spot/price_orders
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 |
Example responses
200 Response
[
{
"trigger": {
"price": "100",
"rule": ">=",
"expiration": 3600
},
"put": {
"type": "limit",
"side": "buy",
"price": "2.15",
"amount": "2.00000000",
"account": "normal",
"time_in_force": "gtc",
"text": "api"
},
"id": 1283293,
"user": 1234,
"market": "GT_USDT",
"ctime": 1616397800,
"ftime": 1616397801,
"fired_order_id": 0,
"status": "",
"reason": ""
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/spot/price_orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /spot/price_orders
Cancel all 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 |
Example responses
200 Response
[
{
"trigger": {
"price": "100",
"rule": ">=",
"expiration": 3600
},
"put": {
"type": "limit",
"side": "buy",
"price": "2.15",
"amount": "2.00000000",
"account": "normal",
"time_in_force": "gtc",
"text": "api"
},
"id": 1283293,
"user": 1234,
"market": "GT_USDT",
"ctime": 1616397800,
"ftime": 1616397801,
"fired_order_id": 0,
"status": "",
"reason": ""
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation request accepted 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/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/spot/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /spot/price_orders/{order_id}
Query single auto order details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | string | true | ID returned when order is successfully created |
Example responses
200 Response
{
"trigger": {
"price": "100",
"rule": ">=",
"expiration": 3600
},
"put": {
"type": "limit",
"side": "buy",
"price": "2.15",
"amount": "2.00000000",
"account": "normal",
"time_in_force": "gtc",
"text": "api"
},
"id": 1283293,
"user": 1234,
"market": "GT_USDT",
"ctime": 1616397800,
"ftime": 1616397801,
"fired_order_id": 0,
"status": "",
"reason": ""
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Auto order 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/spot/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /spot/price_orders/{order_id}
Cancel single auto order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | string | true | ID returned when order is successfully created |
Example responses
200 Response
{
"trigger": {
"price": "100",
"rule": ">=",
"expiration": 3600
},
"put": {
"type": "limit",
"side": "buy",
"price": "2.15",
"amount": "2.00000000",
"account": "normal",
"time_in_force": "gtc",
"text": "api"
},
"id": 1283293,
"user": 1234,
"market": "GT_USDT",
"ctime": 1616397800,
"ftime": 1616397801,
"fired_order_id": 0,
"status": "",
"reason": ""
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Auto order details | SpotPriceTriggeredOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Flash exchange
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/flash_swap/currency_pairs'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/flash_swap/currency_pairs \
-H 'Accept: application/json'
GET /flash_swap/currency_pairs
List All Supported Currency Pairs In Flash Swap
BTC_GT represents selling BTC and buying GT. The limits for each currency may vary across different currency pairs.
It is not necessary that two currencies that can be swapped instantaneously can be exchanged with each other. For example, it is possible to sell BTC and buy GT, but it does not necessarily mean that GT can be sold to buy BTC.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | 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 |
Example responses
200 Response
[
{
"currency_pair": "BTC_USDT",
"sell_currency": "BTC",
"buy_currency": "USDT",
"sell_min_amount": "0.00001",
"sell_max_amount": "100",
"buy_min_amount": "10",
"buy_max_amount": "10000000"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/flash_swap/orders'
query_param = ''
body='{"preview_id":"4564564","sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT","buy_amount":"10"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/flash_swap/orders"
query_param=""
body_param='{"preview_id":"4564564","sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT","buy_amount":"10"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /flash_swap/orders
Create a flash swap order
Initiate a flash swap preview in advance because order creation requires a preview result
Body parameter
{
"preview_id": "4564564",
"sell_currency": "BTC",
"sell_amount": "0.1",
"buy_currency": "USDT",
"buy_amount": "10"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » preview_id | body | string | true | Preview result ID |
| » sell_currency | body | string | true | 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) |
Example responses
201 Response
{
"id": 54646,
"create_time": 1651116876378,
"update_time": 1651116876378,
"user_id": 11135567,
"sell_currency": "BTC",
"sell_amount": "0.01",
"buy_currency": "USDT",
"buy_amount": "10",
"price": "100",
"status": 1
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/flash_swap/orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /flash_swap/orders
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)Example responses
200 Response
[
{
"id": 54646,
"create_time": 1651116876378,
"update_time": 1651116876378,
"user_id": 11135567,
"sell_currency": "BTC",
"sell_amount": "0.01",
"buy_currency": "USDT",
"buy_amount": "10",
"price": "100",
"status": 1
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/1'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/flash_swap/orders/1"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /flash_swap/orders/{order_id}
Query single flash swap order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | integer | true | Flash swap order ID |
Example responses
200 Response
{
"id": 54646,
"create_time": 1651116876378,
"update_time": 1651116876378,
"user_id": 11135567,
"sell_currency": "BTC",
"sell_amount": "0.01",
"buy_currency": "USDT",
"buy_amount": "10",
"price": "100",
"status": 1
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/preview'
query_param = ''
body='{"sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/flash_swap/orders/preview"
query_param=""
body_param='{"sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /flash_swap/orders/preview
Flash swap order preview
Body parameter
{
"sell_currency": "BTC",
"sell_amount": "0.1",
"buy_currency": "USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » sell_currency | body | string | true | The name of the asset being sold, as obtained from the "GET /flash_swap/currency_pairs" API, which retrieves a list of supported flash swap currency pairs |
| » sell_amount | body | string | false | Amount to sell. |
| » buy_currency | body | string | true | The name of the asset being purchased, as obtained from the "GET /flash_swap/currency_pairs" API, which provides a list of supported flash swap currency pairs |
| » buy_amount | body | string | false | Amount to buy. |
» sell_amount: Amount to sell.
It is required to choose one parameter between sell_amount and buy_amount
» buy_amount: Amount to buy.
It is required to choose one parameter between sell_amount and buy_amount
Example responses
200 Response
{
"preview_id": "3453434",
"sell_currency": "BTC",
"sell_amount": "0.1",
"buy_currency": "USDT",
"buy_amount": "10",
"price": "100"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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
Perpetual futures
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/contracts'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/contracts \
-H 'Accept: application/json'
GET /futures/{settle}/contracts
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 |
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,
"delisting_time": 1609899548,
"delisted_time": 1609899548
}
]
| 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/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/contracts/BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/contracts/{contract}
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 |
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,
"delisting_time": 1609899548,
"delisted_time": 1609899548
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Contract information | Contract |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/order_book'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/order_book?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/order_book
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 the depth changes |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"id": 123456,
"current": 1623898993.123,
"update": 1623898993.121,
"asks": [
{
"p": "1.52",
"s": 100
},
{
"p": "1.53",
"s": 40
}
],
"bids": [
{
"p": "1.17",
"s": 150
},
{
"p": "1.16",
"s": 203
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/trades'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/trades?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/trades
Futures 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 |
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800,
"contract": "BTC_USDT",
"size": -100,
"price": "100.123"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/candlesticks'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/candlesticks?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/candlesticks
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 |
| timezone | query | string | false | Time zone: all/utc0/utc8, default utc0 |
| 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 |
Example responses
200 Response
[
{
"t": 1539852480,
"v": 97151,
"c": "1.032",
"h": "1.032",
"l": "1.032",
"o": "1.032",
"sum": "3580"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/premium_index'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/premium_index?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/premium_index
Premium Index K-line 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 |
Example responses
200 Response
[
{
"t": 1539852480,
"c": "0",
"h": "0.00023",
"l": "0",
"o": "0"
}
]
| 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/tickers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/tickers \
-H 'Accept: application/json'
GET /futures/{settle}/tickers
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 |
Example responses
200 Response
[
{
"contract": "BTC_USDT",
"last": "6432",
"low_24h": "6278",
"high_24h": "6790",
"change_percentage": "4.43",
"total_size": "32323904",
"volume_24h": "184040233284",
"volume_24h_btc": "28613220",
"volume_24h_usd": "184040233284",
"volume_24h_base": "28613220",
"volume_24h_quote": "184040233284",
"volume_24h_settle": "28613220",
"mark_price": "6534",
"funding_rate": "0.0001",
"funding_rate_indicative": "0.0001",
"index_price": "6531",
"highest_bid": "34089.7",
"highest_size": "100",
"lowest_ask": "34217.9",
"lowest_size": "1000"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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 |
| » change_utc0 | string | Percentage change at utc0. Negative values indicate a drop, e.g., -7.45% |
| » change_utc8 | string | Percentage change at utc8. Negative values indicate a drop, e.g., -7.45% |
| » change_price | string | 24h change amount. Negative values indicate a drop, e.g., -7.45 |
| » change_utc0_price | string | Change amount at utc0. Negative values indicate a drop, e.g., -7.45 |
| » change_utc8_price | string | Change amount at utc8. Negative values indicate a drop, e.g., -7.45 |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/funding_rate'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/funding_rate?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/funding_rate
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 |
Example responses
200 Response
[
{
"t": 1543968000,
"r": "0.000157"
}
]
| 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/insurance'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/insurance \
-H 'Accept: application/json'
GET /futures/{settle}/insurance
Futures 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 |
Example responses
200 Response
[
{
"t": 1543968000,
"b": "83.0031"
}
]
| 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/contract_stats'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/contract_stats?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/contract_stats
Futures 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 |
Example responses
200 Response
[
{
"time": 1603865400,
"lsr_taker": 100,
"lsr_account": 0.5,
"long_liq_size": 0,
"short_liq_size": 0,
"open_interest": 124724,
"short_liq_usd": 0,
"mark_price": "8865",
"top_lsr_size": 1.02,
"short_liq_amount": 0,
"long_liq_amount": 0,
"open_interest_usd": 1511,
"top_lsr_account": 1.5,
"long_liq_usd": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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 |
| » mark_price | number(double) | Mark 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/index_constituents/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/index_constituents/BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/index_constituents/{index}
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 |
Example responses
200 Response
{
"index": "BTC_USDT",
"constituents": [
{
"exchange": "Binance",
"symbols": [
"BTC_USDT"
]
},
{
"exchange": "Gate.com",
"symbols": [
"BTC_USDT"
]
},
{
"exchange": "Huobi",
"symbols": [
"BTC_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/liq_orders'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/liq_orders \
-H 'Accept: application/json'
GET /futures/{settle}/liq_orders
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 |
Example responses
200 Response
[
{
"time": 1548654951,
"contract": "BTC_USDT",
"size": 600,
"order_size": -600,
"order_price": "3405",
"fill_price": "3424",
"left": 0
}
]
| 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/risk_limit_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/risk_limit_tiers \
-H 'Accept: application/json'
GET /futures/{settle}/risk_limit_tiers
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 when the contract parameter is empty.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"maintenance_rate": "0.01",
"tier": 1,
"initial_rate": "0.02",
"leverage_max": "50",
"risk_limit": "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"
}
]
| 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
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/accounts
Get futures account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 1666,
"currency": "USDT",
"total": "9707.803567115145",
"unrealised_pnl": "3371.248828",
"position_margin": "38.712189181",
"order_margin": "0",
"available": "9669.091377934145",
"point": "0",
"bonus": "0",
"in_dual_mode": false,
"enable_evolved_classic": false,
"cross_initial_margin": "61855.56788525",
"cross_maintenance_margin": "682.04678105",
"cross_order_margin": "0",
"cross_unrealised_pnl": "1501.178222634128",
"cross_available": "27549.406108813951",
"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
}
| 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 | Refers to the available withdrawal or trading amount in per-position, specifically the per-position available balance under the unified account that includes the credit line (which incorporates trial funds; since trial funds cannot be withdrawn, the actual withdrawal amount needs to deduct the trial fund portion when processing withdrawals) |
| » point | string | Point card amount |
| » currency | string | Settlement currency |
| » in_dual_mode | boolean | Whether Hedge Mode is enabled |
| » position_mode | string | Position mode: single - one-way, dual - dual-side, split - sub-positions (in_dual_mode is deprecated) |
| » 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 |
| » history | object | Statistical data |
| »» dnw | string | total amount of deposit and withdraw |
| »» pnl | string | total amount of trading profit and loss |
| »» fee | string | total amount of fee |
| »» refr | string | total amount of referrer rebates |
| »» fund | string | total amount of funding costs |
| »» point_dnw | string | total amount of point deposit and withdraw |
| »» point_fee | string | total amount of point fee |
| »» point_refr | string | total amount of referrer rebates of point fee |
| »» bonus_dnw | string | total amount of perpetual contract bonus transfer |
| »» bonus_offset | string | total amount of perpetual contract bonus deduction |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/account_book"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/account_book
Query 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 | 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 |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"time": 1682294400.123456,
"change": "0.000010152188",
"balance": "4.59316525194",
"text": "ETH_USD:6086261",
"type": "fee",
"contract": "ETH_USD",
"trade_id": "1",
"id": "1"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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 | Change types: - dnw: Deposit and withdrawal - pnl: Profit and loss from position reduction - fee: Trading fees - refr: Referrer rebates - fund: Funding fees - point_dnw: Point card deposit and withdrawal - point_fee: Point card trading fees - point_refr: Point card referrer rebates - bonus_offset: Trial fund 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/positions'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/positions"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/positions
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 |
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"
}
]
| 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/BTC_USDT'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/positions/BTC_USDT"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/positions/{contract}
Get single position information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions/BTC_USDT/margin'
query_param = 'change=0.01'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/positions/BTC_USDT/margin"
query_param="change=0.01"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/positions/{contract}/margin
Update position margin
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| change | query | string | true | Margin change amount, positive number increases, negative number decreases |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions/BTC_USDT/leverage'
query_param = 'leverage=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/positions/BTC_USDT/leverage"
query_param="leverage=10"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/positions/{contract}/leverage
Update position leverage
⚠️ Position Mode Switching Rules:
Examples:
⚠️ Warning: Incorrect settings may cause unexpected position mode switching, affecting risk management.
| 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) |
| pid | query | integer(int32) | false | Product ID |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
| 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/positions/cross_mode"
query_param=""
body_param='{"mode":"ISOLATED","contract":"BTC_USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/positions/cross_mode
Switch Position Margin Mode
Body parameter
{
"mode": "ISOLATED",
"contract": "BTC_USDT"
}
| 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 |
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"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_comp/positions/cross_mode"
query_param=""
body_param='{"mode":"ISOLATED","contract":"BTC_USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/dual_comp/positions/cross_mode
Switch Between Cross and Isolated Margin Modes Under Hedge Mode
Body parameter
{
"mode": "ISOLATED",
"contract": "BTC_USDT"
}
| 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 |
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"
}
]
| 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/positions/BTC_USDT/risk_limit'
query_param = 'risk_limit=1000000'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/positions/BTC_USDT/risk_limit"
query_param="risk_limit=1000000"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/positions/{contract}/risk_limit
Update position risk limit
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| risk_limit | query | string | true | New risk limit value |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_mode'
query_param = 'dual_mode=true'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_mode"
query_param="dual_mode=true"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/dual_mode
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 Hedge Mode |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 1666,
"currency": "USDT",
"total": "9707.803567115145",
"unrealised_pnl": "3371.248828",
"position_margin": "38.712189181",
"order_margin": "0",
"available": "9669.091377934145",
"point": "0",
"bonus": "0",
"in_dual_mode": false,
"enable_evolved_classic": false,
"cross_initial_margin": "61855.56788525",
"cross_maintenance_margin": "682.04678105",
"cross_order_margin": "0",
"cross_unrealised_pnl": "1501.178222634128",
"cross_available": "27549.406108813951",
"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
}
| 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 | Refers to the available withdrawal or trading amount in per-position, specifically the per-position available balance under the unified account that includes the credit line (which incorporates trial funds; since trial funds cannot be withdrawn, the actual withdrawal amount needs to deduct the trial fund portion when processing withdrawals) |
| » point | string | Point card amount |
| » currency | string | Settlement currency |
| » in_dual_mode | boolean | Whether Hedge Mode is enabled |
| » position_mode | string | Position mode: single - one-way, dual - dual-side, split - sub-positions (in_dual_mode is deprecated) |
| » 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 |
| » history | object | Statistical data |
| »» dnw | string | total amount of deposit and withdraw |
| »» pnl | string | total amount of trading profit and loss |
| »» fee | string | total amount of fee |
| »» refr | string | total amount of referrer rebates |
| »» fund | string | total amount of funding costs |
| »» point_dnw | string | total amount of point deposit and withdraw |
| »» point_fee | string | total amount of point fee |
| »» point_refr | string | total amount of referrer rebates of point fee |
| »» bonus_dnw | string | total amount of perpetual contract bonus transfer |
| »» bonus_offset | string | total amount of perpetual contract bonus deduction |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_comp/positions/BTC_USDT'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/dual_comp/positions/BTC_USDT"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/dual_comp/positions/{contract}
Get position information in Hedge Mode
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
| 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_comp/positions/BTC_USDT/margin"
query_param="change=0.01&dual_side=dual_long"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/dual_comp/positions/{contract}/margin
Update position margin in Hedge 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 |
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"
}
]
| 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_comp/positions/BTC_USDT/leverage"
query_param="leverage=10"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/dual_comp/positions/{contract}/leverage
Update position leverage in Hedge Mode
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| leverage | query | string | true | New position leverage |
| cross_leverage_limit | query | string | false | Cross margin leverage (valid only when leverage is 0) |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
| 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_comp/positions/BTC_USDT/risk_limit"
query_param="risk_limit=1000000"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/dual_comp/positions/{contract}/risk_limit
Update position risk limit in Hedge Mode
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| risk_limit | query | string | true | New risk limit value |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
| 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/orders'
query_param = ''
body='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/orders"
query_param=""
body_param='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/orders
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_actBody parameter
{
"contract": "BTC_USDT",
"size": 6024,
"iceberg": 0,
"price": "3765",
"tif": "gtc",
"text": "t-my-custom-id",
"stp_act": "-"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | 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 |
| » limit_vip | body | integer(int64) | false | Counterparty user's VIP level for limit order fills. Current order will only match with orders whose VIP level is less than or equal to the specified level. Only 11~16 are supported; default is 0 |
| » pid | body | integer(int64) | false | Position ID |
| 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 |
Example responses
201 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order details | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/orders
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 | Use the ID of the last record in the previous list as the starting point for the next list |
| settle | path | string | true | Settle currency |
last_id: Use the ID of the last record in the previous list as the starting point for the next list
Operations based on custom IDs can only be checked when orders are pending. After orders are completed (filled/cancelled), they can be checked within 1 hour after completion. After expiration, only order IDs can be used
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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 = 'contract=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/usdt/orders"
query_param="contract=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /futures/{settle}/orders
Cancel all 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 to cancel all buy orders, set to ask to cancel all sell orders |
| exclude_reduce_only | query | boolean | false | Whether to exclude reduce-only orders |
| text | query | string | false | Remark for order cancellation |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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_timerange'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/orders_timerange"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/orders_timerange
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 |
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/batch_orders'
query_param = ''
body='[{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/batch_orders"
query_param=""
body_param='[{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/batch_orders
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 errorBody parameter
[
{
"contract": "BTC_USDT",
"size": 6024,
"iceberg": 0,
"price": "3765",
"tif": "gtc",
"text": "t-my-custom-id",
"stp_act": "-"
}
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | 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 |
Example responses
200 Response
[
{
"succeeded": true,
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request 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/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/orders/{order_id}
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 |
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order details | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/usdt/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /futures/{settle}/orders/{order_id}
Cancel 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 |
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order details | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders/12345'
query_param = ''
body='{"size":100,"price":"54321"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PUT', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="PUT"
url="/futures/usdt/orders/12345"
query_param=""
body_param='{"size":100,"price":"54321"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
PUT /futures/{settle}/orders/{order_id}
Amend single order
Body parameter
{
"size": 100,
"price": "54321"
}
| 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 |
| » text | body | string | false | Internal users can modify information in the text field. |
| 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 |
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order details | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/my_trades'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/my_trades"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/my_trades
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 |
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800.123,
"contract": "BTC_USDT",
"order_id": "21893289839",
"size": 100,
"price": "100.123",
"text": "t-123456",
"fee": "0.01",
"point_fee": "0",
"role": "taker",
"close_size": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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_timerange'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/my_trades_timerange"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/my_trades_timerange
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 |
Example responses
200 Response
[
{
"trade_id": "121234231",
"create_time": 1514764800.123,
"contract": "BTC_USDT",
"order_id": "21893289839",
"size": 100,
"price": "100.123",
"text": "t-123456",
"fee": "0.01",
"point_fee": "0",
"role": "taker",
"close_size": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/position_close'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/position_close"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/position_close
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 |
Example responses
200 Response
[
{
"time": 1546487347,
"pnl": "0.00013",
"pnl_pnl": "0.00011",
"pnl_fund": "0.00001",
"pnl_fee": "0.00001",
"side": "long",
"contract": "BTC_USDT",
"text": "web",
"max_size": "100",
"accum_size": "100",
"first_open_time": 1546487347,
"long_price": "2026.87",
"short_price": "2544.4"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/liquidates'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/liquidates"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/liquidates
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 |
Example responses
200 Response
[
{
"time": 1548654951,
"contract": "BTC_USDT",
"size": 600,
"leverage": "25",
"margin": "0.006705256878",
"entry_price": "3536.123",
"liq_price": "3421.54",
"mark_price": "3420.27",
"order_id": 317393847,
"order_price": "3405",
"fill_price": "3424",
"left": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/auto_deleverages'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/auto_deleverages"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/auto_deleverages
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 |
Example responses
200 Response
[
{
"time": 1675841679,
"contract": "ACH_USDT",
"order_id": 73873128,
"user": 1666,
"cross_leverage_limit": "0",
"leverage": "0",
"entry_price": "2649.648633636364",
"fill_price": "2790.8082",
"position_size": 1,
"trade_size": -10
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/countdown_cancel_all'
query_param = ''
body='{"timeout":30,"contract":"BTC_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/countdown_cancel_all"
query_param=""
body_param='{"timeout":30,"contract":"BTC_USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/countdown_cancel_all
Countdown cancel orders
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.
Body parameter
{
"timeout": 30,
"contract": "BTC_USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » timeout | body | integer(int32) | true | Countdown time in seconds |
| » contract | body | string | false | Futures contract |
| settle | path | string | true | Settle currency |
» timeout: Countdown time in seconds At least 5 seconds, 0 means cancel countdown
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"triggerTime": "1660039145000"
}
| 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/fee'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/fee"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/fee
Query 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 |
Example responses
200 Response
{
"1INCH_USDT": {
"taker_fee": "0.00025",
"maker_fee": "-0.00010"
},
"AAVE_USDT": {
"taker_fee": "0.00025",
"maker_fee": "-0.00010"
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/batch_cancel_orders'
query_param = ''
body='["1","2","3"]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/batch_cancel_orders"
query_param=""
body_param='["1","2","3"]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/batch_cancel_orders
Cancel batch orders by specified ID list
Multiple different order IDs can be specified. A maximum of 20 records can be cancelled in one request
Body parameter
[
"1",
"2",
"3"
]
| 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 |
Example responses
200 Response
[
{
"user_id": 111,
"id": "123456",
"succeeded": true,
"message": ""
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order cancellation operation completed | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » FutureCancelOrderResult | object | Order cancellation result |
| »» id | string | Order ID |
| »» user_id | integer(int64) | User ID |
| »» succeeded | boolean | Whether cancellation succeeded |
| »» message | string | Error 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_amend_orders'
query_param = ''
body='[{"order_id":121212,"amend_text":"batch amend text","size":100,"price":"54321"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/batch_amend_orders"
query_param=""
body_param='[{"order_id":121212,"amend_text":"batch amend text","size":100,"price":"54321"}]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/batch_amend_orders
Batch modify orders by specified IDs
Multiple different order IDs can be specified. A maximum of 10 orders can be modified in one request
Body parameter
[
{
"order_id": 121212,
"amend_text": "batch amend text",
"size": 100,
"price": "54321"
}
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | 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 |
Example responses
200 Response
[
{
"succeeded": true,
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request 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
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())
curl -X GET https://api.gateio.ws/api/v4/futures/usdt/risk_limit_table?table_id=CYBER_USDT_20241122 \
-H 'Accept: application/json'
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 |
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"
}
]
| 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
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/bbo_orders'
query_param = ''
body='{"contract":"PI_USDT","level":8,"direction":"sell","size":1}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/bbo_orders"
query_param=""
body_param='{"contract":"PI_USDT","level":8,"direction":"sell","size":1}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/bbo_orders
Level-based BBO Contract Order Placement
Compared to the futures trading order placement interface (futures/{settle}/orders), it adds the level and direction parameters.
Body parameter
{
"contract": "PI_USDT",
"level": 8,
"direction": "sell",
"size": 1
}
| 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 | FuturesBBOOrder | 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. |
| » direction | body | string | true | Direction: 'sell' fetches the bid side, 'buy' fetches the ask side. |
| » iceberg | body | integer(int64) | false | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| » level | body | integer(int64) | true | Level: maximum 20 levels |
| » 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 |
| » limit_vip | body | integer(int64) | false | Counterparty user's VIP level for limit order fills. Current order will only match with orders whose VIP level is less than or equal to the specified level. Only 11~16 are supported; default is 0 |
| » pid | body | integer(int64) | false | Position ID |
| 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 |
Example responses
201 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order details | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/price_orders'
query_param = ''
body='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/price_orders"
query_param=""
body_param='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /futures/{settle}/price_orders
Create price-triggered order
Body parameter
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"order_type": "close-long-order"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | FuturesPriceTriggeredOrder | true | none |
| » initial | body | object | true | none |
| »» contract | body | string | true | Futures contract |
| »» size | body | integer(int64) | false | Represents the number of contracts that need to be closed, full closing: size=0 |
| »» price | body | string | true | Order price. Set to 0 to use market price |
| »» close | body | boolean | false | In One-way Mode, when closing all positions, this must be set to true to perform the closing operation |
| »» tif | body | string | false | Time in force strategy, default is gtc, market orders currently only support ioc mode |
| »» text | body | string | false | The source of the order, including: |
| »» reduce_only | body | boolean | false | When set to true, perform automatic position reduction operation. Set to true to ensure that the order will not open a new position, and is only used to close or reduce positions |
| »» auto_size | body | string | false | One-way Mode: auto_size is not required |
| » trigger | body | object | true | none |
| »» strategy_type | body | integer(int32) | false | Trigger Strategy |
| »» price_type | body | integer(int32) | false | Reference price type. 0 - Latest trade price, 1 - Mark price, 2 - Index price |
| »» price | body | string | true | Price value for price trigger, or spread value for spread trigger |
| »» rule | body | integer(int32) | true | Price Condition Type |
| »» expiration | body | integer | false | Maximum wait time for trigger condition (in seconds). Order will be cancelled if timeout |
| » order_type | body | string | false | Types of take-profit and stop-loss orders, including: |
| settle | path | string | true | Settle currency |
»» size: Represents the number of contracts that need to be closed, full closing: size=0 Partial closing: plan-close-short-position size>0 Partial closing: plan-close-long-position size<0
»» close: In One-way Mode, when closing all positions, this must be set to true to perform the closing operation When partially closing positions in One-way Mode or Hedge Mode, you can omit close or set close=false
»» tif: Time in force strategy, default is gtc, market orders currently only support ioc mode
»» text: The source of the order, including:
»» auto_size: One-way Mode: auto_size is not required Hedge Mode full closing (size=0): auto_size must be set, close_long for closing long positions, close_short for closing short positions Hedge Mode partial closing (size≠0): auto_size is not required
»» strategy_type: Trigger Strategy
price_type and the second-last price
Currently only supports 0 (latest transaction price)»» rule: Price Condition Type
strategy_type and price_type is greater than or equal to Trigger.Price, while Trigger.Price must > last_pricestrategy_type and price_type is less than or equal to Trigger.Price, and 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 |
Example responses
201 Response
{
"id": 1432329
}
| 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 = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/price_orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/price_orders
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 |
Example responses
200 Response
[
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/usdt/price_orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /futures/{settle}/price_orders
Cancel all 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 |
Example responses
200 Response
[
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation request accepted 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/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /futures/{settle}/price_orders/{order_id}
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 |
Example responses
200 Response
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Auto order 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/usdt/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /futures/{settle}/price_orders/{order_id}
Cancel 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 |
Example responses
200 Response
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Auto order 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 = ''
body='{"contract":"BTC_USDT","size":0,"price":"0","trigger_price":"988888","price_type":0,"auto_size":"close_long"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PUT', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="PUT"
url="/futures/usdt/price_orders/string"
query_param=""
body_param='{"contract":"BTC_USDT","size":0,"price":"0","trigger_price":"988888","price_type":0,"auto_size":"close_long"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
PUT /futures/{settle}/price_orders/{order_id}
Modify a Single Auto Order
Body parameter
{
"contract": "BTC_USDT",
"size": 0,
"price": "0",
"trigger_price": "988888",
"price_type": 0,
"auto_size": "close_long"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | FuturesUpdatePriceTriggeredOrder | true | none |
| » contact | body | string | false | The order ID of the modified price-triggered order. This ID is returned upon successful creation of the price-triggered order. Note: This ID must be passed in both the request path and request body. |
| » size | body | integer(int64) | false | Modified Contract Quantity. Full Close: 0; Partial Close: Positive/Negative values indicate direction (consistent with the creation interface logic). |
| » price | body | string | false | Represents the modified trading price. A value of 0 indicates a market order. |
| » trigger_price | body | string | false | Modified Trigger Price |
| » price_type | body | integer(int32) | false | Reference price type. 0 - Latest trade price, 1 - Mark price, 2 - Index price |
| » auto_size | body | string | false | One-way Mode: auto_size is not required |
| settle | path | string | true | Settle currency |
| order_id | path | string | true | ID returned when order is successfully created |
» auto_size: One-way Mode: auto_size is not required Hedge Mode partial closing (size≠0): auto_size is not required Hedge Mode full closing (size=0): auto_size must be set, close_long for closing long positions, close_short for closing short positions
| Parameter | Value |
|---|---|
| » price_type | 0 |
| » price_type | 1 |
| » price_type | 2 |
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"id": 1432329
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order created successfully | Inline |
Status Code 200
TriggerOrderResponse
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Auto order ID |
WARNING
To perform this operation, you must be authenticated by API key and secret
Delivery contract
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/contracts'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/contracts \
-H 'Accept: application/json'
GET /delivery/{settle}/contracts
Query all futures contracts
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
[
{
"name": "BTC_USDT_20200814",
"underlying": "BTC_USDT",
"cycle": "WEEKLY",
"type": "direct",
"quanto_multiplier": "0.0001",
"mark_type": "index",
"last_price": "9017",
"mark_price": "9019",
"index_price": "9005.3",
"basis_rate": "0.185095",
"basis_value": "13.7",
"basis_impact_value": "100000",
"settle_price": "0",
"settle_price_interval": 60,
"settle_price_duration": 1800,
"settle_fee_rate": "0.0015",
"expire_time": 1593763200,
"order_price_round": "0.1",
"mark_price_round": "0.1",
"leverage_min": "1",
"leverage_max": "100",
"maintenance_rate": "1000000",
"risk_limit_base": "140.726652109199",
"risk_limit_step": "1000000",
"risk_limit_max": "8000000",
"maker_fee_rate": "-0.00025",
"taker_fee_rate": "0.00075",
"ref_discount_rate": "0",
"ref_rebate_rate": "0.2",
"order_price_deviate": "0.5",
"order_size_min": 1,
"order_size_max": 1000000,
"orders_limit": 50,
"orderbook_id": 63,
"trade_id": 26,
"trade_size": 435,
"position_size": 130,
"config_change_time": 1593158867,
"in_delisting": false
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/BTC_USDT_20200814'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/contracts/BTC_USDT_20200814 \
-H 'Accept: application/json'
GET /delivery/{settle}/contracts/{contract}
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 |
Example responses
200 Response
{
"name": "BTC_USDT_20200814",
"underlying": "BTC_USDT",
"cycle": "WEEKLY",
"type": "direct",
"quanto_multiplier": "0.0001",
"mark_type": "index",
"last_price": "9017",
"mark_price": "9019",
"index_price": "9005.3",
"basis_rate": "0.185095",
"basis_value": "13.7",
"basis_impact_value": "100000",
"settle_price": "0",
"settle_price_interval": 60,
"settle_price_duration": 1800,
"settle_fee_rate": "0.0015",
"expire_time": 1593763200,
"order_price_round": "0.1",
"mark_price_round": "0.1",
"leverage_min": "1",
"leverage_max": "100",
"maintenance_rate": "1000000",
"risk_limit_base": "140.726652109199",
"risk_limit_step": "1000000",
"risk_limit_max": "8000000",
"maker_fee_rate": "-0.00025",
"taker_fee_rate": "0.00075",
"ref_discount_rate": "0",
"ref_rebate_rate": "0.2",
"order_price_deviate": "0.5",
"order_size_min": 1,
"order_size_max": 1000000,
"orders_limit": 50,
"orderbook_id": 63,
"trade_id": 26,
"trade_size": 435,
"position_size": 130,
"config_change_time": 1593158867,
"in_delisting": false
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Contract information | DeliveryContract |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/order_book'
query_param = 'contract=BTC_USDT_20200814'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/order_book?contract=BTC_USDT_20200814 \
-H 'Accept: application/json'
GET /delivery/{settle}/order_book
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 the depth changes |
| Parameter | Value |
|---|---|
| settle | usdt |
| interval | 0 |
| interval | 0.1 |
| interval | 0.01 |
Example responses
200 Response
{
"id": 123456,
"current": 1623898993.123,
"update": 1623898993.121,
"asks": [
{
"p": "1.52",
"s": 100
},
{
"p": "1.53",
"s": 40
}
],
"bids": [
{
"p": "1.17",
"s": 150
},
{
"p": "1.16",
"s": 203
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/trades'
query_param = 'contract=BTC_USDT_20200814'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/trades?contract=BTC_USDT_20200814 \
-H 'Accept: application/json'
GET /delivery/{settle}/trades
Futures 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 | Use the ID of the last record in the previous list as the starting point for the next list.This field is no longer supported. For new requests, please use the fromand tofields to specify the time rang |
| 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. |
from: Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items.
If items between from and to are more than limit, only limit number will be returned.
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800,
"contract": "BTC_USDT",
"size": -100,
"price": "100.123"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/candlesticks'
query_param = 'contract=BTC_USDT_20200814'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/candlesticks?contract=BTC_USDT_20200814 \
-H 'Accept: application/json'
GET /delivery/{settle}/candlesticks
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 |
Example responses
200 Response
[
{
"t": 1539852480,
"v": 97151,
"c": "1.032",
"h": "1.032",
"l": "1.032",
"o": "1.032"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/tickers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/tickers \
-H 'Accept: application/json'
GET /delivery/{settle}/tickers
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 |
Example responses
200 Response
[
{
"contract": "BTC_USDT",
"last": "6432",
"low_24h": "6278",
"high_24h": "6790",
"change_percentage": "4.43",
"total_size": "32323904",
"volume_24h": "184040233284",
"volume_24h_btc": "28613220",
"volume_24h_usd": "184040233284",
"volume_24h_base": "28613220",
"volume_24h_quote": "184040233284",
"volume_24h_settle": "28613220",
"mark_price": "6534",
"funding_rate": "0.0001",
"funding_rate_indicative": "0.0001",
"index_price": "6531",
"highest_bid": "34089.7",
"highest_size": "100",
"lowest_ask": "34217.9",
"lowest_size": "1000"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/insurance'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/insurance \
-H 'Accept: application/json'
GET /delivery/{settle}/insurance
Futures 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 |
Example responses
200 Response
[
{
"t": 1543968000,
"b": "83.0031"
}
]
| 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
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/accounts
Get futures account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
{
"user": 1666,
"currency": "USDT",
"total": "9707.803567115145",
"unrealised_pnl": "3371.248828",
"position_margin": "38.712189181",
"order_margin": "0",
"available": "9669.091377934145",
"point": "0",
"bonus": "0",
"in_dual_mode": false,
"enable_evolved_classic": false,
"cross_initial_margin": "61855.56788525",
"cross_maintenance_margin": "682.04678105",
"cross_order_margin": "0",
"cross_unrealised_pnl": "1501.178222634128",
"cross_available": "27549.406108813951",
"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
}
| 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 | Refers to the available withdrawal or trading amount in per-position, specifically the per-position available balance under the unified account that includes the credit line (which incorporates trial funds; since trial funds cannot be withdrawn, the actual withdrawal amount needs to deduct the trial fund portion when processing withdrawals) |
| » point | string | Point card amount |
| » currency | string | Settlement currency |
| » in_dual_mode | boolean | Whether Hedge Mode is enabled |
| » position_mode | string | Position mode: single - one-way, dual - dual-side, split - sub-positions (in_dual_mode is deprecated) |
| » 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 |
| » history | object | Statistical data |
| »» dnw | string | total amount of deposit and withdraw |
| »» pnl | string | total amount of trading profit and loss |
| »» fee | string | total amount of fee |
| »» refr | string | total amount of referrer rebates |
| »» fund | string | total amount of funding costs |
| »» point_dnw | string | total amount of point deposit and withdraw |
| »» point_fee | string | total amount of point fee |
| »» point_refr | string | total amount of referrer rebates of point fee |
| »» bonus_dnw | string | total amount of perpetual contract bonus transfer |
| »» bonus_offset | string | total amount of perpetual contract bonus deduction |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/account_book"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/account_book
Query 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 | 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 |
|---|---|
| settle | usdt |
| type | dnw |
| type | pnl |
| type | fee |
| type | refr |
| type | fund |
| type | point_dnw |
| type | point_fee |
| type | point_refr |
Example responses
200 Response
[
{
"time": 1682294400.123456,
"change": "0.000010152188",
"balance": "4.59316525194",
"text": "ETH_USD:6086261",
"type": "fee",
"contract": "ETH_USD",
"trade_id": "1",
"id": "1"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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 | Change types: - dnw: Deposit and withdrawal - pnl: Profit and loss from position reduction - fee: Trading fees - refr: Referrer rebates - fund: Funding fees - point_dnw: Point card deposit and withdrawal - point_fee: Point card trading fees - point_refr: Point card referrer rebates - bonus_offset: Trial fund 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/positions'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/positions"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/positions
Get user position list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
| 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/BTC_USDT_20200814'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/positions/BTC_USDT_20200814"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/positions/{contract}
Get single position information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/positions/BTC_USDT_20200814/margin'
query_param = 'change=0.01'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/positions/BTC_USDT_20200814/margin"
query_param="change=0.01"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /delivery/{settle}/positions/{contract}/margin
Update position margin
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| change | query | string | true | Margin change amount, positive number increases, negative number decreases |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/positions/BTC_USDT_20200814/leverage'
query_param = 'leverage=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/positions/BTC_USDT_20200814/leverage"
query_param="leverage=10"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /delivery/{settle}/positions/{contract}/leverage
Update position leverage
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| leverage | query | string | true | New position leverage |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/positions/BTC_USDT_20200814/risk_limit'
query_param = 'risk_limit=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/positions/BTC_USDT_20200814/risk_limit"
query_param="risk_limit=10"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /delivery/{settle}/positions/{contract}/risk_limit
Update position risk limit
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| risk_limit | query | string | true | New position risk limit |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/orders'
query_param = ''
body='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/orders"
query_param=""
body_param='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /delivery/{settle}/orders
Place futures order
Zero-fill orders cannot be retrieved 10 minutes after order cancellation
Body parameter
{
"contract": "BTC_USDT",
"size": 6024,
"iceberg": 0,
"price": "3765",
"tif": "gtc",
"text": "t-my-custom-id",
"stp_act": "-"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | FuturesOrder | true | none |
| » contract | body | string | true | Futures contract |
| » size | body | integer(int64) | true | 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 |
| » limit_vip | body | integer(int64) | false | Counterparty user's VIP level for limit order fills. Current order will only match with orders whose VIP level is less than or equal to the specified level. Only 11~16 are supported; default is 0 |
| » pid | body | integer(int64) | false | Position ID |
| 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 |
Example responses
201 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order details | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/orders
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 | Use the ID of the last record in the previous list as the starting point for the next list |
| count_total | query | integer | false | Whether to return total number matched, defaults to 0 (no return) |
| settle | path | string | true | Settle currency |
last_id: Use the ID of the last record in the previous list as the starting point for the next list
Operations based on custom IDs can only be checked when orders are pending. After orders are completed (filled/cancelled), they can be checked within 1 hour after completion. After expiration, only order IDs can be used
| Parameter | Value |
|---|---|
| status | open |
| status | finished |
| count_total | 0 |
| count_total | 1 |
| settle | usdt |
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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 = 'contract=BTC_USDT_20200814'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/delivery/usdt/orders"
query_param="contract=BTC_USDT_20200814"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /delivery/{settle}/orders
Cancel all 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 |
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/orders/{order_id}
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 |
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order details | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/delivery/usdt/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /delivery/{settle}/orders/{order_id}
Cancel 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 |
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order details | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/my_trades'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/my_trades"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/my_trades
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 | Use the ID of the last record in the previous list as the starting point for the next list |
| count_total | query | integer | false | Whether to return total number matched, defaults to 0 (no return) |
last_id: Use the ID of the last record in the previous list as the starting point for the next list
Operations based on custom IDs can only be checked when orders are pending. After orders are completed (filled/cancelled), they can be checked within 1 hour after completion. After expiration, only order IDs can be used
| Parameter | Value |
|---|---|
| settle | usdt |
| count_total | 0 |
| count_total | 1 |
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800.123,
"contract": "BTC_USDT",
"order_id": "21893289839",
"size": 100,
"price": "100.123",
"text": "t-123456",
"fee": "0.01",
"point_fee": "0",
"role": "taker",
"close_size": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/position_close'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/position_close"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/position_close
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 |
Example responses
200 Response
[
{
"time": 1546487347,
"pnl": "0.00013",
"pnl_pnl": "0.00011",
"pnl_fund": "0.00001",
"pnl_fee": "0.00001",
"side": "long",
"contract": "BTC_USDT",
"text": "web",
"max_size": "100",
"accum_size": "100",
"first_open_time": 1546487347,
"long_price": "2026.87",
"short_price": "2544.4"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/liquidates'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/liquidates"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/liquidates
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 |
Example responses
200 Response
[
{
"time": 1548654951,
"contract": "BTC_USDT",
"size": 600,
"leverage": "25",
"margin": "0.006705256878",
"entry_price": "3536.123",
"liq_price": "3421.54",
"mark_price": "3420.27",
"order_id": 317393847,
"order_price": "3405",
"fill_price": "3424",
"left": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/settlements'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/settlements"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/settlements
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 |
Example responses
200 Response
[
{
"time": 1548654951,
"contract": "BTC_USDT",
"size": 600,
"leverage": "25",
"margin": "0.006705256878",
"entry_price": "3536.123",
"settle_price": "3421.54",
"profit": "-6.87498",
"fee": "0.03079386"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/risk_limit_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/risk_limit_tiers \
-H 'Accept: application/json'
GET /delivery/{settle}/risk_limit_tiers
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 when the contract parameter is empty.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
[
{
"maintenance_rate": "0.01",
"tier": 1,
"initial_rate": "0.02",
"leverage_max": "50",
"risk_limit": "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"
}
]
| 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
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/price_orders'
query_param = ''
body='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/delivery/usdt/price_orders"
query_param=""
body_param='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /delivery/{settle}/price_orders
Create price-triggered order
Body parameter
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"order_type": "close-long-order"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | FuturesPriceTriggeredOrder | true | none |
| » initial | body | object | true | none |
| »» contract | body | string | true | Futures contract |
| »» size | body | integer(int64) | false | Represents the number of contracts that need to be closed, full closing: size=0 |
| »» price | body | string | true | Order price. Set to 0 to use market price |
| »» close | body | boolean | false | In One-way Mode, when closing all positions, this must be set to true to perform the closing operation |
| »» tif | body | string | false | Time in force strategy, default is gtc, market orders currently only support ioc mode |
| »» text | body | string | false | The source of the order, including: |
| »» reduce_only | body | boolean | false | When set to true, perform automatic position reduction operation. Set to true to ensure that the order will not open a new position, and is only used to close or reduce positions |
| »» auto_size | body | string | false | One-way Mode: auto_size is not required |
| » trigger | body | object | true | none |
| »» strategy_type | body | integer(int32) | false | Trigger Strategy |
| »» price_type | body | integer(int32) | false | Reference price type. 0 - Latest trade price, 1 - Mark price, 2 - Index price |
| »» price | body | string | true | Price value for price trigger, or spread value for spread trigger |
| »» rule | body | integer(int32) | true | Price Condition Type |
| »» expiration | body | integer | false | Maximum wait time for trigger condition (in seconds). Order will be cancelled if timeout |
| » order_type | body | string | false | Types of take-profit and stop-loss orders, including: |
| settle | path | string | true | Settle currency |
»» size: Represents the number of contracts that need to be closed, full closing: size=0 Partial closing: plan-close-short-position size>0 Partial closing: plan-close-long-position size<0
»» close: In One-way Mode, when closing all positions, this must be set to true to perform the closing operation When partially closing positions in One-way Mode or Hedge Mode, you can omit close or set close=false
»» tif: Time in force strategy, default is gtc, market orders currently only support ioc mode
»» text: The source of the order, including:
»» auto_size: One-way Mode: auto_size is not required Hedge Mode full closing (size=0): auto_size must be set, close_long for closing long positions, close_short for closing short positions Hedge Mode partial closing (size≠0): auto_size is not required
»» strategy_type: Trigger Strategy
price_type and the second-last price
Currently only supports 0 (latest transaction price)»» rule: Price Condition Type
strategy_type and price_type is greater than or equal to Trigger.Price, while Trigger.Price must > last_pricestrategy_type and price_type is less than or equal to Trigger.Price, and 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 |
Example responses
201 Response
{
"id": 1432329
}
| 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 = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/price_orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/price_orders
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 |
Example responses
200 Response
[
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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 = 'contract=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/delivery/usdt/price_orders"
query_param="contract=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /delivery/{settle}/price_orders
Cancel all auto orders
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | true | Futures contract |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | usdt |
Example responses
200 Response
[
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation request accepted 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/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/delivery/usdt/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /delivery/{settle}/price_orders/{order_id}
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 |
Example responses
200 Response
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Auto order 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/delivery/usdt/price_orders/string"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /delivery/{settle}/price_orders/{order_id}
Cancel 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 |
Example responses
200 Response
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Auto order details | FuturesPriceTriggeredOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Options API
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/underlyings'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/underlyings \
-H 'Accept: application/json'
GET /options/underlyings
List all underlying assets
Example responses
200 Response
[
{
"name": "BTC_USDT",
"index_price": "70000"
}
]
| 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/expirations'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/expirations?underlying=BTC_USDT \
-H 'Accept: application/json'
GET /options/expirations
List all expiration dates
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | true | Underlying (Obtained by listing underlying endpoint) |
Example responses
200 Response
[
1637913600
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List expiration 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/contracts'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/contracts?underlying=BTC_USDT \
-H 'Accept: application/json'
GET /options/contracts
List all 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 |
Example responses
200 Response
[
{
"name": "BTC_USDT-20211130-65000-C",
"tag": "WEEK",
"create_time": 1636702700,
"expiration_time": 1637913600,
"is_call": true,
"strike_price": "65000",
"last_price": "13000",
"mark_price": "14010",
"orderbook_id": 9,
"trade_id": 1,
"trade_size": 10,
"position_size": 10,
"underlying": "BTC_USDT",
"underlying_price": "70000",
"multiplier": "0.0001",
"order_price_round": "0.1",
"mark_price_round": "0.1",
"maker_fee_rate": "0.0004",
"taker_fee_rate": "0.0004",
"price_limit_fee_rate": "0.1",
"ref_discount_rate": "0",
"ref_rebate_rate": "0",
"order_price_deviate": "0.5",
"order_size_min": 1,
"order_size_max": 100000,
"orders_limit": 50
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/BTC_USDT-20211130-65000-C'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/contracts/BTC_USDT-20211130-65000-C \
-H 'Accept: application/json'
GET /options/contracts/{contract}
Query specified contract details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | path | string | true | none |
Example responses
200 Response
{
"name": "BTC_USDT-20211130-65000-C",
"tag": "WEEK",
"create_time": 1636702700,
"expiration_time": 1637913600,
"is_call": true,
"strike_price": "65000",
"last_price": "13000",
"mark_price": "14010",
"orderbook_id": 9,
"trade_id": 1,
"trade_size": 10,
"position_size": 10,
"underlying": "BTC_USDT",
"underlying_price": "70000",
"multiplier": "0.0001",
"order_price_round": "0.1",
"mark_price_round": "0.1",
"maker_fee_rate": "0.0004",
"taker_fee_rate": "0.0004",
"price_limit_fee_rate": "0.1",
"ref_discount_rate": "0",
"ref_rebate_rate": "0",
"order_price_deviate": "0.5",
"order_size_min": 1,
"order_size_max": 100000,
"orders_limit": 50
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/settlements'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/settlements?underlying=BTC_USDT \
-H 'Accept: application/json'
GET /options/settlements
List settlement history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | true | Underlying (Obtained by listing underlying endpoint) |
| limit | query | integer | false | Maximum number of records 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
Example responses
200 Response
[
{
"time": 1598839200,
"profit": "312.35",
"fee": "0.3284",
"settle_price": "11687.65",
"contract": "BTC-WEEKLY-200824-11000-P",
"strike_price": "12000"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/BTC_USDT-20211130-65000-C'
query_param = 'underlying=BTC_USDT&at=0'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/settlements/BTC_USDT-20211130-65000-C?underlying=BTC_USDT&at=0 \
-H 'Accept: application/json'
GET /options/settlements/{contract}
Get specified contract 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 |
Example responses
200 Response
{
"time": 1598839200,
"profit": "312.35",
"fee": "0.3284",
"settle_price": "11687.65",
"contract": "BTC-WEEKLY-200824-11000-P",
"strike_price": "12000"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/my_settlements'
query_param = 'underlying=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/my_settlements"
query_param="underlying=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/my_settlements
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
Example responses
200 Response
[
{
"size": -1,
"settle_profit": "0",
"contract": "BTC_USDT-20220624-26000-C",
"strike_price": "26000",
"time": 1656057600,
"settle_price": "20917.461281337048",
"underlying": "BTC_USDT",
"realised_pnl": "-0.00116042",
"fee": "0"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/order_book'
query_param = 'contract=BTC_USDT-20210916-5000-C'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/order_book?contract=BTC_USDT-20210916-5000-C \
-H 'Accept: application/json'
GET /options/order_book
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 the depth changes |
| Parameter | Value |
|---|---|
| interval | 0 |
| interval | 0.1 |
| interval | 0.01 |
Example responses
200 Response
{
"id": 123456,
"current": 1623898993.123,
"update": 1623898993.121,
"asks": [
{
"p": "1.52",
"s": 100
},
{
"p": "1.53",
"s": 40
}
],
"bids": [
{
"p": "1.17",
"s": 150
},
{
"p": "1.16",
"s": 203
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/tickers'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/tickers?underlying=BTC_USDT \
-H 'Accept: application/json'
GET /options/tickers
Query options market ticker information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | true | Underlying (Obtained by listing underlying endpoint) |
Example responses
200 Response
[
{
"name": "BTC_USDT-20211130-65000-C",
"last_price": "13000",
"mark_price": "14010",
"position_size": 10,
"ask1_size": 0,
"ask1_price": "0",
"bid1_size": 1,
"bid1_price": "11",
"vega": "41.41202",
"theta": "-120.1506",
"rho": "6.52485",
"gamma": "0.00004",
"delta": "0.33505",
"mark_iv": "0.123",
"bid_iv": "0.023",
"ask_iv": "0.342",
"leverage": "13"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/underlying/tickers/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/underlying/tickers/BTC_USDT \
-H 'Accept: application/json'
GET /options/underlying/tickers/{underlying}
Query underlying ticker information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | path | string | true | Underlying |
Example responses
200 Response
{
"trade_put": 33505,
"trade_call": 123,
"index_price": "76543.3"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/candlesticks'
query_param = 'contract=BTC_USDT-20210916-5000-C'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/candlesticks?contract=BTC_USDT-20210916-5000-C \
-H 'Accept: application/json'
GET /options/candlesticks
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 |
Example responses
200 Response
[
{
"t": 1539852480,
"v": 97151,
"c": "1.032",
"h": "1.032",
"l": "1.032",
"o": "1.032"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/underlying/candlesticks'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/underlying/candlesticks?underlying=BTC_USDT \
-H 'Accept: application/json'
GET /options/underlying/candlesticks
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 |
Example responses
200 Response
[
{
"t": 1539852480,
"v": 97151,
"c": "1.032",
"h": "1.032",
"l": "1.032",
"o": "1.032",
"sum": "3580"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/trades'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/options/trades \
-H 'Accept: application/json'
GET /options/trades
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
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800,
"contract": "BTC_USDT",
"size": -100,
"price": "100.123"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/accounts
Query account information
Example responses
200 Response
{
"user": 666,
"currency": "USDT",
"short_enabled": true,
"mmp_enabled": false,
"liq_triggered": false,
"margin_mode": 0,
"total": "1650.443022",
"position_value": "-40.1136",
"equity": "1610.329422",
"unrealised_pnl": "-0.7811",
"init_margin": "0",
"maint_margin": "135.541485",
"order_margin": "139.74496",
"ask_order_margin": "139.74496",
"bid_order_margin": "0",
"available": "1514.901537",
"point": "0",
"orders_limit": 10,
"position_notional_limit": 1000000
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/account_book"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/account_book
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 |
Example responses
200 Response
[
{
"time": 1636426005,
"change": "-0.16",
"balance": "7378.189",
"text": "BTC_USDT-20211216-5000-P:25",
"type": "fee"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/positions'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/positions"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/positions
List user's positions of specified underlying
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | false | Underlying |
Example responses
200 Response
[
{
"user": 11027586,
"underlying": "BTC_USDT",
"underlying_price": "70000",
"contract": "BTC_USDT-20211216-5000-P",
"size": 10,
"entry_price": "1234",
"realised_pnl": "120",
"mark_price": "6000",
"mark_iv": "0.9638",
"unrealised_pnl": "-320",
"pending_orders": 1,
"close_order": {
"id": 232323,
"price": "5779",
"is_liq": false
},
"delta": "-0.0046",
"gamma": "0",
"vega": "2.87656",
"theta": "-1.00247"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/BTC_USDT-20211130-65000-C'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/positions/BTC_USDT-20211130-65000-C"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/positions/{contract}
Get specified contract position
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | path | string | true | none |
Example responses
200 Response
{
"user": 11027586,
"underlying": "BTC_USDT",
"underlying_price": "70000",
"contract": "BTC_USDT-20211216-5000-P",
"size": 10,
"entry_price": "1234",
"realised_pnl": "120",
"mark_price": "6000",
"mark_iv": "0.9638",
"unrealised_pnl": "-320",
"pending_orders": 1,
"close_order": {
"id": 232323,
"price": "5779",
"is_liq": false
},
"delta": "-0.0046",
"gamma": "0",
"vega": "2.87656",
"theta": "-1.00247"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/position_close'
query_param = 'underlying=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/position_close"
query_param="underlying=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/position_close
List user's liquidation history of specified underlying
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | true | Underlying (Obtained by listing underlying endpoint) |
| contract | query | string | false | Options contract name |
Example responses
200 Response
[
{
"time": 1631764800,
"pnl": "-42914.291",
"settle_size": "-10001",
"side": "short",
"contract": "BTC_USDT-20210916-5000-C",
"text": "settled"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/orders'
query_param = ''
body='{"size":-1,"iceberg":0,"contract":"BTC_USDT-20210916-5000-C","text":"-","tif":"gtc","price":"100"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/options/orders"
query_param=""
body_param='{"size":-1,"iceberg":0,"contract":"BTC_USDT-20210916-5000-C","text":"-","tif":"gtc","price":"100"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /options/orders
Create an options order
Body parameter
{
"size": -1,
"iceberg": 0,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"tif": "gtc",
"price": "100"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » contract | body | string | true | 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 |
Example responses
201 Response
{
"status": "finished",
"size": -1,
"id": 2,
"iceberg": 0,
"is_liq": false,
"is_close": false,
"is_mmp": false,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"fill_price": "100",
"finish_as": "filled",
"left": 0,
"tif": "gtc",
"is_reduce_only": false,
"create_time": 1631763361,
"finish_time": 1631763397,
"price": "100"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order detail | Inline |
Status Code 201
Options order 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 = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/orders
List options orders
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | false | Options contract name |
| underlying | query | string | false | Underlying |
| status | query | string | true | 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 |
Example responses
200 Response
[
{
"status": "finished",
"size": -1,
"id": 2,
"iceberg": 0,
"is_liq": false,
"is_close": false,
"is_mmp": false,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"fill_price": "100",
"finish_as": "filled",
"left": 0,
"tif": "gtc",
"is_reduce_only": false,
"create_time": 1631763361,
"finish_time": 1631763397,
"price": "100"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/options/orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /options/orders
Cancel all 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 |
Example responses
200 Response
[
{
"status": "finished",
"size": -1,
"id": 2,
"iceberg": 0,
"is_liq": false,
"is_close": false,
"is_mmp": false,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"fill_price": "100",
"finish_as": "filled",
"left": 0,
"tif": "gtc",
"is_reduce_only": false,
"create_time": 1631763361,
"finish_time": 1631763397,
"price": "100"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/orders/{order_id}
Query single order details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | integer(int64) | true | Order ID returned when order is successfully created |
Example responses
200 Response
{
"status": "finished",
"size": -1,
"id": 2,
"iceberg": 0,
"is_liq": false,
"is_close": false,
"is_mmp": false,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"fill_price": "100",
"finish_as": "filled",
"left": 0,
"tif": "gtc",
"is_reduce_only": false,
"create_time": 1631763361,
"finish_time": 1631763397,
"price": "100"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order detail | Inline |
Status Code 200
Options order 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/options/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /options/orders/{order_id}
Cancel single order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | integer(int64) | true | Order ID returned when order is successfully created |
Example responses
200 Response
{
"status": "finished",
"size": -1,
"id": 2,
"iceberg": 0,
"is_liq": false,
"is_close": false,
"is_mmp": false,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"fill_price": "100",
"finish_as": "filled",
"left": 0,
"tif": "gtc",
"is_reduce_only": false,
"create_time": 1631763361,
"finish_time": 1631763397,
"price": "100"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order detail | Inline |
Status Code 200
Options order 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/countdown_cancel_all'
query_param = ''
body='{"timeout":30,"contract":"BTC_USDT-20241001-46000-C","underlying":"BTC_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/options/countdown_cancel_all"
query_param=""
body_param='{"timeout":30,"contract":"BTC_USDT-20241001-46000-C","underlying":"BTC_USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /options/countdown_cancel_all
Countdown cancel orders
Option order heartbeat detection, when the timeout time set by the user is reached, if the existing countdown is not canceled or a new countdown is set, the related option pending order will be automatically canceled.
This interface can be called repeatedly to set a new countdown or cancel the countdown.
Usage example: Repeat this interface at intervals of 30 seconds, with each countdown timeout set to 30 (seconds).
If this interface is not called again within 30 seconds, all pending orders on the underlying contract you specified will be automatically cancelled. If underlying contract is not specified, user will be automatically cancelled
If timeout is set to 0 within 30 seconds, the countdown timer will expire and the automatic order cancellation function will be cancelled.
Body parameter
{
"timeout": 30,
"contract": "BTC_USDT-20241001-46000-C",
"underlying": "BTC_USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » timeout | body | integer(int32) | true | Countdown time in seconds |
| » contract | body | string | false | Options contract name |
| » underlying | body | string | false | Underlying |
» timeout: Countdown time in seconds At least 5 seconds, 0 means cancel countdown
Example responses
200 Response
{
"triggerTime": "1660039145000"
}
| 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/my_trades'
query_param = 'underlying=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/my_trades"
query_param="underlying=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/my_trades
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
Example responses
200 Response
[
{
"underlying_price": "48000",
"size": 1,
"contract": "BTC_USDT-20210916-5000-C",
"id": 1,
"role": "taker",
"create_time": 1631763397,
"order_id": 4,
"price": "100"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/mmp'
query_param = ''
body='{"underlying":"BTC_USDT","window":5000,"frozen_period":200,"qty_limit":"10","delta_limit":"10"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/options/mmp"
query_param=""
body_param='{"underlying":"BTC_USDT","window":5000,"frozen_period":200,"qty_limit":"10","delta_limit":"10"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /options/mmp
MMP Settings
Body parameter
{
"underlying": "BTC_USDT",
"window": 5000,
"frozen_period": 200,
"qty_limit": "10",
"delta_limit": "10"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » underlying | body | string | true | Underlying |
| » window | body | integer(int32) | true | 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) |
Example responses
200 Response
{
"underlying": "BTC_USDT",
"window": 5000,
"frozen_period": 200,
"qty_limit": "10",
"delta_limit": "10",
"trigger_time_ms": 0,
"frozen_until_ms": 0
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | MMP Information | Inline |
Status Code 200
MMP Settings
| Name | Type | Description |
|---|---|---|
| » underlying | string | Underlying |
| » window | integer(int32) | 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/options/mmp"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /options/mmp
MMP Query.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| underlying | query | string | false | Underlying |
Example responses
200 Response
[
{
"underlying": "BTC_USDT",
"window": 5000,
"frozen_period": 200,
"qty_limit": "10",
"delta_limit": "10",
"trigger_time_ms": 0,
"frozen_until_ms": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/reset'
query_param = ''
body='{"underlying":"BTC_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/options/mmp/reset"
query_param=""
body_param='{"underlying":"BTC_USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /options/mmp/reset
MMP Reset
Body parameter
{
"underlying": "BTC_USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » underlying | body | string | true | Underlying |
Example responses
200 Response
{
"underlying": "BTC_USDT",
"window": 5000,
"frozen_period": 200,
"qty_limit": "10",
"delta_limit": "10",
"trigger_time_ms": 0,
"frozen_until_ms": 0
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | MMP Information | Inline |
Status Code 200
MMP Settings
| Name | Type | Description |
|---|---|---|
| » underlying | string | Underlying |
| » window | integer(int32) | 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
Lend & Earn
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/earn/uni/currencies \
-H 'Accept: application/json'
GET /earn/uni/currencies
Query lending currency list
Example responses
200 Response
[
{
"currency": "AE",
"min_lend_amount": "100",
"max_lend_amount": "200000000",
"max_rate": "0.00057",
"min_rate": "0.000001"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/btc'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/earn/uni/currencies/btc \
-H 'Accept: application/json'
GET /earn/uni/currencies/{currency}
Query single lending currency details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | true | Currency |
Example responses
200 Response
{
"currency": "AE",
"min_lend_amount": "100",
"max_lend_amount": "200000000",
"max_rate": "0.00057",
"min_rate": "0.000001"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/lends'
query_param = ''
body='{"currency":"AE","amount":"100","min_rate":"0.00001","type":"lend"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/earn/uni/lends"
query_param=""
body_param='{"currency":"AE","amount":"100","min_rate":"0.00001","type":"lend"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /earn/uni/lends
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.
Body parameter
{
"currency": "AE",
"amount": "100",
"min_rate": "0.00001",
"type": "lend"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Currency name |
| » amount | body | string | true | 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/earn/uni/lends"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /earn/uni/lends
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 |
Example responses
200 Response
[
{
"currency": "BTC",
"current_amount": "20.999992",
"amount": "20.999992",
"lent_amount": "0",
"frozen_amount": "0",
"min_rate": "0.1",
"interest_status": "interest_dividend",
"reinvest_left_amount": 0,
"create_time": 1673247054000,
"update_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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 = ''
body='{"currency":"AE","min_rate":"0.0001"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PATCH', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="PATCH"
url="/earn/uni/lends"
query_param=""
body_param='{"currency":"AE","min_rate":"0.0001"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
PATCH /earn/uni/lends
Amend user lending information
Currently only supports amending minimum interest rate (hourly)
Body parameter
{
"currency": "AE",
"min_rate": "0.0001"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | false | Currency name |
| » min_rate | body | string | false | Minimum interest rate |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Updated 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/lend_records'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/earn/uni/lend_records"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /earn/uni/lend_records
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 |
Example responses
200 Response
[
{
"type": "lend",
"currency": "BTC",
"amount": "1",
"last_wallet_amount": "0.2",
"last_lent_amount": "0",
"last_frozen_amount": "0",
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/interests/btc'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/earn/uni/interests/btc"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /earn/uni/interests/{currency}
Query user's total interest income for specified currency
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | true | Currency |
Example responses
200 Response
{
"currency": "AE",
"interest": "123.345"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/interest_records'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/earn/uni/interest_records"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /earn/uni/interest_records
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
Example responses
200 Response
[
{
"status": 1,
"currency": "AE",
"actual_rate": "0.0005",
"interest": "0.05",
"interest_status": "interest_dividend",
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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_status/btc'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/earn/uni/interest_status/btc"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /earn/uni/interest_status/{currency}
Query currency interest compounding status
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | true | Currency |
Example responses
200 Response
{
"currency": "BTC",
"interest_status": "interest_dividend"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/earn/uni/chart"
query_param="from=1719763200&to=1722441600&asset=BTC"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /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 |
Example responses
200 Response
[
{
"time": 1719705600,
"value": "0.01"
}
]
| 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/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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/earn/uni/rate"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /earn/uni/rate
Currency estimated annualized interest rate
Example responses
200 Response
[
{
"currency": "USDT",
"est_rate": "0.0226"
}
]
| 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
Collateral loan, only for single currency collateral
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/orders'
query_param = ''
body='{"collateral_amount":"1","collateral_currency":"BTC","borrow_amount":"49","borrow_currency":"USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/loan/collateral/orders"
query_param=""
body_param='{"collateral_amount":"1","collateral_currency":"BTC","borrow_amount":"49","borrow_currency":"USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /loan/collateral/orders
Place collateral loan order
Body parameter
{
"collateral_amount": "1",
"collateral_currency": "BTC",
"borrow_amount": "49",
"borrow_currency": "USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » collateral_amount | body | string | true | Collateral amount |
| » collateral_currency | body | string | true | Collateral currency |
| » borrow_amount | body | string | true | Borrowed amount |
| » borrow_currency | body | string | true | Borrowed currency |
Example responses
200 Response
{
"order_id": 10005578
}
| 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/loan/collateral/orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /loan/collateral/orders
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 |
Example responses
200 Response
[
{
"order_id": 10000421,
"collateral_currency": "BTC",
"borrow_currency": "USDT",
"collateral_amount": "1",
"borrow_amount": "1000",
"repaid_amount": "10",
"repaid_principal": "10",
"repaid_interest": "0",
"init_ltv": "0.0003934533764831",
"current_ltv": "0.0004521768651985",
"liquidate_ltv": "0.9",
"status": "initial_status",
"borrow_time": 1688462668,
"left_repay_total": "990.0219384",
"left_repay_interest": "0.0219384"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/100001'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/loan/collateral/orders/100001"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /loan/collateral/orders/{order_id}
Query single order details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | integer(int64) | true | Order ID returned when order is successfully created |
Example responses
200 Response
{
"order_id": 10000421,
"collateral_currency": "BTC",
"borrow_currency": "USDT",
"collateral_amount": "1",
"borrow_amount": "1000",
"repaid_amount": "10",
"repaid_principal": "10",
"repaid_interest": "0",
"init_ltv": "0.0003934533764831",
"current_ltv": "0.0004521768651985",
"liquidate_ltv": "0.9",
"status": "initial_status",
"borrow_time": 1688462668,
"left_repay_total": "990.0219384",
"left_repay_interest": "0.0219384"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/repay'
query_param = ''
body='{"order_id":37438962,"repay_amount":"1000","repaid_all":false}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/loan/collateral/repay"
query_param=""
body_param='{"order_id":37438962,"repay_amount":"1000","repaid_all":false}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /loan/collateral/repay
Collateral loan repayment
Body parameter
{
"order_id": 37438962,
"repay_amount": "1000",
"repaid_all": false
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » order_id | body | integer(int64) | true | Order ID |
| » repay_amount | body | string | true | Repayment amount, it is mandatory when making partial repayments |
| » repaid_all | body | boolean | true | Repayment method, set to true for full repayment, and false for partial repayment; |
» repaid_all: Repayment method, set to true for full repayment, and false for partial repayment;
When partial repayment, the repay_amount parameter cannot be greater than the remaining amount to be repaid by the user.
Example responses
200 Response
{
"repaid_principal": "11",
"repaid_interest": "111"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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_records'
query_param = 'source=repay'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/loan/collateral/repay_records"
query_param="source=repay"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /loan/collateral/repay_records
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 |
Example responses
200 Response
[
{
"order_id": 10000425,
"record_id": 181,
"repaid_amount": "10.00000000000000000000",
"borrow_currency": "USDT",
"collateral_currency": "BTC",
"collateral_amount": "1.00000000000000000000",
"init_ltv": "0.00039345337648310000",
"borrow_time": 1688471851,
"repay_time": 1688526310,
"total_interest": "0.25446901544300000000",
"before_left_principal": "11.00000000",
"pre_left_principal": "990.00000000000000000000",
"after_left_principal": "990.00000000000000000000",
"before_left_collateral": "1.00000000000000000000",
"after_left_collateral": "1.00000000000000000000"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/collaterals'
query_param = ''
body='{"collateral_amount":"1212","collateral_currency":"BTC","order_id":1130,"type":"append"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/loan/collateral/collaterals"
query_param=""
body_param='{"collateral_amount":"1212","collateral_currency":"BTC","order_id":1130,"type":"append"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /loan/collateral/collaterals
Increase or redeem collateral
Body parameter
{
"collateral_amount": "1212",
"collateral_currency": "BTC",
"order_id": 1130,
"type": "append"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » order_id | body | integer(int64) | true | Order ID |
| » collateral_currency | body | string | true | Collateral 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/loan/collateral/collaterals"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /loan/collateral/collaterals
Query collateral adjustment records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records 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 |
Example responses
200 Response
[
{
"order_id": 10000417,
"record_id": 10000452,
"borrow_currency": "USDT",
"borrow_amount": "1000.00000000000000000000",
"collateral_currency": "BTC",
"pre_collateral": "1.00000000000000000000",
"after_collateral": "2.00000000000000000000",
"pre_ltv": "0.00039345555621480000",
"after_ltv": "0.00019672777810740000",
"operate_time": 1688461924
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/total_amount'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/loan/collateral/total_amount"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /loan/collateral/total_amount
Query user's total borrowing and collateral amount
Example responses
200 Response
{
"borrow_amount": "11",
"collateral_amount": "111"
}
| 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/ltv'
query_param = 'collateral_currency=BTC&borrow_currency=USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/loan/collateral/ltv"
query_param="collateral_currency=BTC&borrow_currency=USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /loan/collateral/ltv
Query user's collateralization ratio and remaining borrowable currencies
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| collateral_currency | query | string | true | Collateral currency |
| borrow_currency | query | string | true | Borrowed currency |
Example responses
200 Response
{
"collateral_currency": "BTC",
"borrow_currency": "USDT",
"init_ltv": "0.7",
"alert_ltv": "0.8",
"liquidate_ltv": "0.9",
"min_borrow_amount": "3",
"left_borrowable_amount": "4233030.635065916703"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/loan/collateral/currencies \
-H 'Accept: application/json'
GET /loan/collateral/currencies
Query supported borrowing and collateral currencies
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| loan_currency | query | string | false | Parameter loan_currency. If omitted, returns all supported borrowing currencies; if provided, returns the array of collateral currencies supported for that borrowing currency |
Example responses
200 Response
[
{
"loan_currency": "BTC",
"collateral_currency": [
"BTC",
"ETH",
"GT"
]
}
]
| 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 |
Multi-currency collateral
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/orders'
query_param = ''
body='{"order_id":1721387470,"order_type":"fixed","fixed_type":"7d","fixed_rate":0.00001,"auto_renew":true,"auto_repay":true,"borrow_currency":"BTC","borrow_amount":"1","collateral_currencies":[{"currency":"USDT","amount":"1000"}]}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/loan/multi_collateral/orders"
query_param=""
body_param='{"order_id":1721387470,"order_type":"fixed","fixed_type":"7d","fixed_rate":0.00001,"auto_renew":true,"auto_repay":true,"borrow_currency":"BTC","borrow_amount":"1","collateral_currencies":[{"currency":"USDT","amount":"1000"}]}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /loan/multi_collateral/orders
Place multi-currency collateral order
Body parameter
{
"order_id": 1721387470,
"order_type": "fixed",
"fixed_type": "7d",
"fixed_rate": 0.00001,
"auto_renew": true,
"auto_repay": true,
"borrow_currency": "BTC",
"borrow_amount": "1",
"collateral_currencies": [
{
"currency": "USDT",
"amount": "1000"
}
]
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » order_id | body | string | false | Order ID |
| » order_type | body | string | false | current - current 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 |
Example responses
200 Response
{
"order_id": 10005578
}
| 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/loan/multi_collateral/orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /loan/multi_collateral/orders
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 - Default descending by creation time, ltv_asc - Ascending by LTV ratio, ltv_desc - Descending by LTV ratio |
| order_type | query | string | false | Order type: current - Query current orders, fixed - Query fixed orders, defaults to current orders if not specified |
Example responses
200 Response
[
{
"order_id": "10005578",
"order_type": "fixed",
"fixed_type": "7d",
"fixed_rate": 0.00001,
"expire_time": 1703820105,
"auto_renew": true,
"auto_repay": true,
"current_ltv": "0.0001004349664281",
"status": "lent",
"borrow_time": 1702615021,
"total_left_repay_usdt": "106.491212982",
"total_left_collateral_usdt": "1060300.18",
"borrow_currencies": [
{
"currency": "GT",
"index_price": "10.6491",
"left_repay_principal": "10",
"left_repay_interest": "0.00002",
"left_repay_usdt": "106.491212982"
}
],
"collateral_currencies": [
{
"currency": "BTC",
"index_price": "112794.7",
"left_collateral": "9.4",
"left_collateral_usdt": "1060270.18"
},
{
"currency": "USDT",
"index_price": "1",
"left_collateral": "30",
"left_collateral_usdt": "30"
}
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/loan/multi_collateral/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /loan/multi_collateral/orders/{order_id}
Query order details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | string | true | Order ID returned when order is successfully created |
Example responses
200 Response
{
"order_id": "10005578",
"order_type": "fixed",
"fixed_type": "7d",
"fixed_rate": 0.00001,
"expire_time": 1703820105,
"auto_renew": true,
"auto_repay": true,
"current_ltv": "0.0001004349664281",
"status": "lent",
"borrow_time": 1702615021,
"total_left_repay_usdt": "106.491212982",
"total_left_collateral_usdt": "1060300.18",
"borrow_currencies": [
{
"currency": "GT",
"index_price": "10.6491",
"left_repay_principal": "10",
"left_repay_interest": "0.00002",
"left_repay_usdt": "106.491212982"
}
],
"collateral_currencies": [
{
"currency": "BTC",
"index_price": "112794.7",
"left_collateral": "9.4",
"left_collateral_usdt": "1060270.18"
},
{
"currency": "USDT",
"index_price": "1",
"left_collateral": "30",
"left_collateral_usdt": "30"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/repay'
query_param = ''
body='{"order_id":10005578,"repay_items":[{"currency":"btc","amount":"1","repaid_all":false}]}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/loan/multi_collateral/repay"
query_param=""
body_param='{"order_id":10005578,"repay_items":[{"currency":"btc","amount":"1","repaid_all":false}]}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /loan/multi_collateral/repay
Multi-currency collateral repayment
Body parameter
{
"order_id": 10005578,
"repay_items": [
{
"currency": "btc",
"amount": "1",
"repaid_all": false
}
]
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » order_id | body | integer(int64) | true | Order ID |
| » repay_items | body | array | true | Repay Currency Item |
| »» MultiLoanRepayItem | body | object | false | none |
| »»» currency | body | string | false | Repayment currency |
| »»» amount | body | string | false | Size |
| »»» repaid_all | body | boolean | true | Repayment method, set to true for full repayment, false for partial repayment |
Example responses
200 Response
{
"order_id": 10005679,
"repaid_currencies": [
{
"succeeded": false,
"label": "INVALID_PARAM_VALUE",
"message": "Invalid parameter value",
"currency": "BTC",
"repaid_principal": "1",
"repaid_interest": "0.0001"
},
{
"succeeded": true,
"currency": "BTC",
"repaid_principal": "1",
"repaid_interest": "0.0001"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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 = 'type=repay'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/loan/multi_collateral/repay"
query_param="type=repay"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /loan/multi_collateral/repay
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 |
Example responses
200 Response
[
{
"order_id": 10005679,
"record_id": 1348,
"init_ltv": "0.2141",
"before_ltv": "0.215",
"after_ltv": "0.312",
"borrow_time": 1702995889,
"repay_time": 1703053927,
"borrow_currencies": [
{
"currency": "BAT",
"index_price": "103.02",
"before_amount": "1",
"before_amount_usdt": "103.02",
"after_amount": "0.999017",
"after_amount_usdt": "102.91873134"
}
],
"collateral_currencies": [
{
"currency": "ETC",
"index_price": "0.6014228107",
"before_amount": "1000",
"before_amount_usdt": "601.4228107",
"after_amount": "1000",
"after_amount_usdt": "601.4228107"
}
],
"repaid_currencies": [
{
"currency": "BAT",
"index_price": "103.02",
"repaid_amount": "0.001",
"repaid_principal": "0.000983",
"repaid_interest": "0.000017",
"repaid_amount_usdt": "0.10302"
}
],
"total_interest_list": [
{
"currency": "BAT",
"index_price": "103.02",
"amount": "0.000017",
"amount_usdt": "0.00175134"
}
],
"left_repay_interest_list": [
{
"currency": "BAT",
"index_price": "103.02",
"before_amount": "0.000017",
"before_amount_usdt": "0.00175134",
"after_amount": "0",
"after_amount_usdt": "0"
}
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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 | Currency |
| »»» index_price | string | Currency Index Price |
| »»» before_amount | string | Amount before the operation |
| »»» before_amount_usdt | string | USDT Amount before the operation |
| »»» after_amount | string | Amount after the operation |
| »»» after_amount_usdt | string | USDT Amount after the operation |
| »» collateral_currencies | array | List of collateral information |
| »»» currency | string | Currency |
| »»» index_price | string | Currency Index Price |
| »»» before_amount | string | Amount before the operation |
| »»» before_amount_usdt | string | USDT Amount before the operation |
| »»» after_amount | string | Amount after the operation |
| »»» after_amount_usdt | string | USDT Amount after the operation |
| »» repaid_currencies | array | Repay Currency List |
| »»» RepayRecordRepaidCurrency | object | none |
| »»»» currency | string | Repayment currency |
| »»»» index_price | string | Currency Index Price |
| »»»» repaid_amount | string | Repayment amount |
| »»»» repaid_principal | string | Principal |
| »»»» repaid_interest | string | Interest |
| »»»» repaid_amount_usdt | string | 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/mortgage'
query_param = ''
body='{"order_id":10005578,"type":"append","collaterals":[{"currency":"btc","amount":"0.5"}]}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/loan/multi_collateral/mortgage"
query_param=""
body_param='{"order_id":10005578,"type":"append","collaterals":[{"currency":"btc","amount":"0.5"}]}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /loan/multi_collateral/mortgage
Add or withdraw collateral
Body parameter
{
"order_id": 10005578,
"type": "append",
"collaterals": [
{
"currency": "btc",
"amount": "0.5"
}
]
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » order_id | body | integer(int64) | true | Order ID |
| » type | body | string | true | Operation type: append - add collateral, redeem - withdraw collateral |
| » collaterals | body | array | false | Collateral currency list |
| »» currency | body | string | false | Currency |
| »» amount | body | string | false | Size |
Example responses
200 Response
{
"order_id": 10005679,
"collateral_currencies": [
{
"succeeded": true,
"currency": "btc",
"amount": "0.5"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/loan/multi_collateral/mortgage"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /loan/multi_collateral/mortgage
Query collateral adjustment records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer | false | Page number |
| limit | query | integer | false | Maximum number of records 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 |
Example responses
200 Response
[
{
"order_id": 10000417,
"record_id": 10000452,
"before_ltv": "0.00039345555621480000",
"after_ltv": "0.00019672777810740000",
"operate_time": 1688461924,
"borrow_currencies": [
{
"currency": "BTC",
"index_price": "30000",
"before_amount": "0.1",
"before_amount_usdt": "1000",
"after_amount": "0.6",
"after_amount_usdt": "1006"
}
],
"collateral_currencies": [
{
"currency": "BTC",
"index_price": "30000",
"before_amount": "0.1",
"before_amount_usdt": "1000",
"after_amount": "0.6",
"after_amount_usdt": "1006"
}
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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 | Currency |
| »»» index_price | string | Currency Index Price |
| »»» before_amount | string | Amount before the operation |
| »»» before_amount_usdt | string | USDT Amount before the operation |
| »»» after_amount | string | Amount after the operation |
| »»» after_amount_usdt | string | USDT Amount after the operation |
| »» collateral_currencies | array | Collateral Currency List |
| »»» currency | string | Currency |
| »»» index_price | string | Currency Index Price |
| »»» before_amount | string | Amount before the operation |
| »»» before_amount_usdt | string | USDT Amount before the operation |
| »»» after_amount | string | Amount after the operation |
| »»» after_amount_usdt | string | USDT Amount after the operation |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/currency_quota'
query_param = 'type=collateral¤cy=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/loan/multi_collateral/currency_quota"
query_param="type=collateral¤cy=BTC"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /loan/multi_collateral/currency_quota
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 passed separated by commas; when it is a borrowing currency, only one currency can be passed |
Example responses
200 Response
[
{
"currency": "BTC",
"index_price": "35306.1",
"min_quota": "0",
"left_quota": "2768152.4958445218723677",
"left_quote_usdt": "97732668833.536273678"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/loan/multi_collateral/currencies \
-H 'Accept: application/json'
GET /loan/multi_collateral/currencies
Query supported borrowing and collateral currencies for multi-currency collateral
Example responses
200 Response
{
"loan_currencies": [
{
"currency": "BTC",
"price": "1212"
},
{
"currency": "GT",
"price": "12"
}
],
"collateral_currencies": [
{
"currency": "BTC",
"index_price": "1212",
"discount": "0.7"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/ltv'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/loan/multi_collateral/ltv \
-H 'Accept: application/json'
GET /loan/multi_collateral/ltv
Query collateralization ratio information
Multi-currency collateral ratio is fixed, independent of currency
Example responses
200 Response
{
"init_ltv": "0.7",
"alert_ltv": "0.8",
"liquidate_ltv": "0.9"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/fixed_rate'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/loan/multi_collateral/fixed_rate \
-H 'Accept: application/json'
GET /loan/multi_collateral/fixed_rate
Query currency's 7-day and 30-day fixed interest rates
Example responses
200 Response
[
{
"currency": "BTC",
"rate_7d": "0.000023",
"rate_30d": "0.1",
"update_time": 1703820105
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/current_rate'
query_param = 'currencies=BTC,GT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/loan/multi_collateral/current_rate?currencies=BTC,GT \
-H 'Accept: application/json'
GET /loan/multi_collateral/current_rate
Query currency's current interest rate
Query the current interest rate of the currency in the previous hour, the current interest rate is updated every hour
| 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 |
Example responses
200 Response
[
{
"currency": "BTC",
"current_rate": "0.000023"
}
]
| 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 |
Earn service
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/staking/eth2/swap'
query_param = ''
body='{"side":"1","amount":"1.5"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/earn/staking/eth2/swap"
query_param=""
body_param='{"side":"1","amount":"1.5"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /earn/staking/eth2/swap
ETH swap
Body parameter
{
"side": "1",
"amount": "1.5"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » side | body | string | true | 1-Forward Swap (ETH -> GTETH), 2-Reverse Swap (GTETH -> 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/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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/earn/staking/eth2/rate_records"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /earn/staking/eth2/rate_records
GTETH historical return rate query
Query ETH earnings rate records for the last 31 days
Example responses
200 Response
[
{
"date_time": 1690348815,
"date": "2023-07-26",
"rate": "60.00"
},
{
"date_time": 1690435215,
"date": "2023-07-27",
"rate": "20.00"
}
]
| 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
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/dual/investment_plan'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/earn/dual/investment_plan \
-H 'Accept: application/json'
GET /earn/dual/investment_plan
Dual Investment product list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| plan_id | query | integer(int64) | false | Financial project ID |
Example responses
200 Response
[
{
"id": 272,
"instrument_name": "DOGE-17NOV23-0.067-P",
"type": "put",
"invest_currency": "USDT",
"exercise_currency": "DOGE",
"exercise_price": 0.067,
"delivery_time": 1700208000,
"min_copies": 1,
"max_copies": 1000,
"start_time": 1697685172,
"end_time": 1697685172,
"status": "ONGOING",
"apy_display": "0.0114000000",
"per_value": "1"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/dual/orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/earn/dual/orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /earn/dual/orders
Dual Investment order list
| 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 |
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"
}
]
| 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 = ''
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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/earn/dual/orders"
query_param=""
body_param='{"plan_id":"176","amount":"1","text":"t-custom-text"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /earn/dual/orders
Place Dual Investment order
Body parameter
{
"plan_id": "176",
"amount": "1",
"text": "t-custom-text"
}
| 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
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/structured/products'
query_param = 'status=in_process'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET https://api.gateio.ws/api/v4/earn/structured/products?status=in_process \
-H 'Accept: application/json'
GET /earn/structured/products
Structured Product List
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| type | query | string | false | Product Type (Default 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
Example responses
200 Response
[
{
"id": 3700,
"type": "BullishSharkFin",
"name_en": "Bullish Sharkfin_USDT",
"investment_period": 7,
"min_annual_rate": "0.50",
"mid_annual_rate": "7.50",
"max_annual_rate": "13.00",
"watch_market": "BTC_USDT",
"investment_coin": "USDT",
"start_time": 1698224400,
"end_time": 1700902800,
"status": "in_process"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/structured/orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/earn/structured/orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /earn/structured/orders
Structured Product Order List
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | 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
Example responses
200 Response
[
{
"id": 35,
"pid": "3691",
"lock_coin": "ETH",
"amount": "20",
"status": "SUCCESS",
"income": "0.000000",
"create_time": 1697685172
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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 = ''
body='{"pid":"1","amount":"0.5"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/earn/structured/orders"
query_param=""
body_param='{"pid":"1","amount":"0.5"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /earn/structured/orders
Place Structured Product Order
Body parameter
{
"pid": "1",
"amount": "0.5"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » pid | body | string | false | 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/staking/coins'
query_param = ''
body='{"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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/earn/staking/coins"
query_param=""
body_param='{"cointype":"string"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /earn/staking/coins
Staking coins
Body parameter
{
"cointype": "string"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » cointype | body | string | false | Currency type: swap - voucher; lock - locked position; debt - US Treasury bond. |
Example responses
200 Response
[
{
"pid": 1,
"productType": 0,
"isDefi": 0,
"currency": "GT",
"estimateApr": "36.00",
"minStakeAmount": "1",
"maxStakeAmount": 700,
"protocolName": "Gatechain",
"redeemPeriod": 0,
"exchangeRate": "1.00000000",
"exchangeRateReserve": "1.00000000",
"extraInterest": [
{
"start_time": 1749427201,
"end_time": 1765497600,
"reward_coin": "GT",
"segment_interest": [
{
"money_min": "0",
"money_max": "1000",
"money_rate": "10.00"
},
{
"money_min": "1000",
"money_max": "2000",
"money_rate": "15.00"
},
{
"money_min": "2000",
"money_max": "3000",
"money_rate": "30.00"
}
]
}
],
"currencyRewards": [
{
"apr": "6.00",
"reward_coin": "GT2",
"reward_delay_days": 1,
"interest_delay_days": 1
}
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » pid | integer | Product ID |
| » productType | integer | Project type 0-voucher 1-locked position 2-US Treasury bond |
| » isDefi | integer | Is DEFI protocol 0-no 1-yes |
| » currency | string | Staked currencies (multiple entries separated by commas) |
| » estimateApr | string | Estimated yield rate |
| » minStakeAmount | string | Minimum staked amount |
| » maxStakeAmount | string | Maximum staked amount |
| » protocolName | string | Protocol name |
| » redeemPeriod | string | Redemption period (days) |
| » exchangeRate | string | Exchange rate |
| » exchangeRateReserve | string | Reverse exchange rate |
| » extraInterest | array | Additional rewards |
| »» start_time | string | Start timestamp |
| »» end_time | string | End Timestamp |
| »» reward_coin | string | Additional reward currency |
| »» segment_interest | array | Tiered reward information |
| »»» money_min | string | Tiered lower value |
| »»» money_max | string | Tiered upper value |
| »»» money_rate | string | Tiered interest rate |
| »» currencyRewards | array | Reward currency information |
| »»» apr | string | Base interest rate |
| »»» reward_coin | string | Reward currency |
| »»» reward_delay_days | string | Dividend day -1 indicates dividends are distributed upon redemption |
| »»» interest_delay_days | string | Interest accrual day |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/earn/staking/swap"
query_param=""
body_param='{"coin":"GT","side":"0","amount":"1.5"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /earn/staking/swap
On-chain token swap for earned coins
Body parameter
{
"coin": "GT",
"side": "0",
"amount": "1.5"
}
| 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 |
Example responses
200 Response
{
"id": 21000,
"uid": 12345,
"coin": "GT",
"type": 0,
"exchange_rate": "1.00000000",
"amount": "2",
"pid": 1,
"status": 1,
"createStamp": 1752200661
}
| 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 | SubType |
| » amount | string | Amount |
| » exchange_rate | string | Exchange ratio |
| » exchange_amount | string | Redemption Amount |
| » updateStamp | integer | UpdateTimestamp |
| » 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/order_list'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/earn/staking/order_list"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /earn/staking/order_list
List of on-chain coin-earning orders
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| pid | query | integer | false | Product ID |
| coin | query | string | false | Currency name |
| type | query | integer | false | Type 0-staking 1-redemption |
| page | query | integer(int32) | false | Page number |
Example responses
200 Response
{
"page": 1,
"pageSize": 20,
"pageCount": 5,
"totalCount": 90,
"list": [
{
"pid": 2,
"coin": "SOL",
"amount": "1.00000000",
"type": 0,
"status": 1,
"redeem_stamp": 0,
"createStamp": 1756105456,
"exchange_amount": "1.00000000",
"fee": "0.0000000000"
},
{
"pid": 2,
"coin": "SOL",
"amount": "1.00000000",
"type": 0,
"status": 1,
"redeem_stamp": 0,
"createStamp": 1755588122,
"exchange_amount": "0.80000000",
"fee": "0.0000000000"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » page | integer | Page |
| » pageSize | integer | Items per page |
| » pageCount | integer | Total pages |
| » totalCount | integer | Total entries |
| » list | array | none |
| »» pid | integer | Product ID |
| »» coin | string | Staked and redeemed currencies |
| »» amount | string | Amount |
| »» type | integer | Type 0-Staking 1-Redemption |
| »» status | integer | Status |
| »» redeem_stamp | integer | Redemption credit time |
| »» createStamp | integer | Order time |
| »» exchange_amount | string | Exchange rate |
| »» fee | string | 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 = '/earn/staking/award_list'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/earn/staking/award_list"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /earn/staking/award_list
On-chain coin-earning dividend records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| pid | query | integer | false | Product ID |
| coin | query | string | false | Currency name |
| page | query | integer(int32) | false | Page number |
Example responses
200 Response
{
"page": 1,
"pageSize": 20,
"pageCount": 2,
"totalCount": 33,
"list": [
{
"pid": 64,
"mortgage_coin": "USDT",
"amount": "0.0000019100",
"reward_coin": "COMP",
"interest": "0.0000019100",
"fee": "0.0000000700",
"status": 4,
"bonus_date": "2025-08-08 00:00:00",
"should_bonus_stamp": 1755907200
},
{
"pid": 27,
"mortgage_coin": "DOT",
"amount": "0.0023424700",
"reward_coin": "DOT",
"interest": "0.0023424700",
"fee": "0.0001232800",
"status": 4,
"bonus_date": "2025-08-11 00:00:00",
"should_bonus_stamp": 1755043200
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » page | integer | Page |
| » pageSize | integer | Items per page |
| » pageCount | integer | Total pages |
| » totalCount | integer | Total entries |
| » list | array | none |
| »» pid | integer | Product ID |
| »» mortgage_coin | string | Collateral currency |
| »» amount | string | Amount |
| »» reward_coin | string | Reward currency |
| »» interest | string | Interest amount |
| »» fee | string | fee |
| »» status | integer | Status |
| »» bonus_date | string | Date |
| »» should_bonus_stamp | integer | Scheduled distribution timestamp |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import 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/assets'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/earn/staking/assets"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /earn/staking/assets
On-chain coin-earning assets
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| coin | query | string | false | Currency name |
Example responses
200 Response
[
{
"pid": 1,
"mortgage_coin": "GT",
"mortgage_amount": "111.60000000",
"createStamp": 1728530266,
"extra_income": "0",
"freeze_amount": "0.0000000000",
"move_income": "0.0000000000",
"type": 0,
"status": 1,
"income_total": "0",
"yesterday_income_multi": [],
"reward_coins": [
{
"reward_coin": "GT2",
"interest_delay_days": 1,
"reward_delay_days": 1
}
]
},
{
"pid": 64,
"mortgage_coin": "USDT",
"mortgage_amount": "1.0000000000",
"createStamp": 1750764156,
"extra_income": "0",
"freeze_amount": "0.0000000000",
"move_income": "0.0000000000",
"type": 1,
"status": 1,
"income_total": "0",
"yesterday_income_multi": [],
"defi_income": {
"total": [
{
"coin": "COMP",
"amount": "0.0000076200"
}
]
},
"reward_coins": [
{
"reward_coin": "USDT",
"interest_delay_days": 1,
"reward_delay_days": -1
},
{
"reward_coin": "COMP",
"interest_delay_days": 1,
"reward_delay_days": 15
}
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » pid | integer | Product ID |
| » mortgage_coin | string | Staked currencies (multiple entries separated by commas) |
| » mortgage_amount | string | Position amount |
| » createStamp | integer | First timestamp |
| » extra_income | string | Additional rewards converted to USDT amount |
| » freeze_amount | string | Locked amount, used in trading |
| » move_income | string | none |
| » type | integer | Type 0-voucher 1-locked position 2-US Treasury bond |
| » status | integer | Status |
| » income_total | string | Total earnings by currency |
| » yesterday_income_multi | array | Yesterday's earnings |
| » reward_coins | array | Currency-specific reward earnings |
| »» reward_coin | string | Reward currency |
| »» interest_delay_days | integer | Interest accrual day |
| »» reward_delay_days | integer | Dividend day -1 indicates dividends are distributed upon redemption |
| » defi_income | object | DEIF earnings |
| »» total | array | none |
| »»» coin | string | none |
| »»» amount | string | none |
WARNING
To perform this operation, you must be authenticated by API key and secret
Retrieve user account information
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/detail'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/account/detail"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /account/detail
Retrieve user account information
Example responses
200 Response
{
"user_id": 1667201533,
"ip_whitelist": [
"127.0.0.1"
],
"currency_pairs": [
"USDT_BTC"
],
"key": {
"mode": 1
},
"tier": 2,
"copy_trading_role": 1
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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 - Copy trading 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/main_keys'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/account/main_keys"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /account/main_keys
Query All Main Account Key Information
Example responses
200 Response
[
{
"state": 1,
"mode": 1,
"name": "test1",
"user_id": 1,
"perms": [
{
"name": "account",
"read_only": false
},
{
"name": "spot",
"read_only": false
}
],
"ip_whitelist": [],
"currency_pairs": [
"BTC_USD",
"ETH_USD"
],
"key": "c5dcfbf1f3a7*****",
"created_at": 1753030929,
"update_at": 1756300567,
"last_access": 1753030929
},
{
"state": 1,
"mode": 1,
"name": "test2",
"user_id": 1,
"perms": [
{
"name": "spot",
"read_only": false
},
{
"name": "account",
"read_only": false
}
],
"ip_whitelist": [],
"currency_pairs": [
"BTC_USD",
"ETH_USD"
],
"key": "52fd0035f665*****",
"created_at": 1753897991,
"update_at": 1756300567,
"last_access": 1753897991
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
AccountKeyInfo
| Name | Type | Description |
|---|---|---|
| » state | integer(int32) | API Key Status: 1 - Normal, 2 - Locked, 3 - Frozen (can only be modified; default is 1 upon creation) |
| » mode | integer(int32) | User Mode: 1 - Classic, 2 - Legacy Unified (can only be specified during creation, non-modifiable afterwards) |
| » name | string | API Key Remark |
| » currency_pairs | array | Trading Pair Whitelist, Maximum 30 Pairs |
| » user_id | integer(int64) | User ID |
| » ip_whitelist | array | IP Whitelist |
| » perms | array | none |
| »» name | string | 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- pilot: pilot- otc: otc- alpha: alpha- crossx: cross-exchange |
| »» read_only | boolean | Read Only |
| » key | object | API Key details |
| »» mode | integer(int32) | Mode: 1 - Classic mode, 2 - Legacy unified mode |
| » created_at | string | Created time |
| » updated_at | string | Last Update Time |
| » last_access | string | Last Access Time |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/rate_limit'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/account/rate_limit"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /account/rate_limit
Get user transaction rate limit information
Example responses
200 Response
[
{
"type": "spot",
"tier": "1",
"ratio": "0",
"main_ratio": "0",
"updated_at": "1728230400"
},
{
"type": "futures",
"tier": "1",
"ratio": "0",
"main_ratio": "0",
"updated_at": "1728230400"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | 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/stp_groups'
query_param = ''
body='{"name":"stp_name"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/account/stp_groups"
query_param=""
body_param='{"name":"stp_name"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /account/stp_groups
Create STP user group
Only the main account is allowed to create a new STP user group
Body parameter
{
"name": "stp_name"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » id | body | integer(int64) | false | STP Group ID |
| » name | body | string | true | STP Group name |
| » creator_id | body | integer(int64) | false | Creator ID |
| » create_time | body | integer(int64) | false | Created time |
Example responses
200 Response
{
"id": 123435,
"name": "group",
"create_time": 1548000000,
"creator_id": 10000
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | User added successfully, returning 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/account/stp_groups"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /account/stp_groups
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 |
Example responses
200 Response
[
{
"id": 123435,
"name": "group",
"create_time": 1548000000,
"creator_id": 10000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/1/users'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/account/stp_groups/1/users"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /account/stp_groups/{stp_id}/users
Query users in the STP user group
Only the main account that created this STP group can query the account ID list of the current STP group
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| stp_id | path | integer(int64) | true | STP Group ID |
Example responses
200 Response
[
{
"user_id": 10000,
"stp_id": 1,
"create_time": 1548000000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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 = ''
body='[1,2,3]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/account/stp_groups/1/users"
query_param=""
body_param='[1,2,3]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /account/stp_groups/{stp_id}/users
Add users to the STP user group
Body parameter
[
1,
2,
3
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| stp_id | path | integer(int64) | true | STP Group ID |
| body | body | array[integer] | true | User ID |
Example responses
200 Response
[
{
"user_id": 10000,
"stp_id": 1,
"create_time": 1548000000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | User added successfully, returning 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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/account/stp_groups/1/users"
query_param="user_id=1"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
DELETE /account/stp_groups/{stp_id}/users
Delete 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 |
Example responses
200 Response
[
{
"user_id": 10000,
"stp_id": 1,
"create_time": 1548000000
}
]
| 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/debit_fee'
query_param = ''
body='{"enabled":true}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/account/debit_fee"
query_param=""
body_param='{"enabled":true}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
POST /account/debit_fee
Configure GT fee deduction
Enable or disable GT fee deduction for the current account
Body parameter
{
"enabled": true
}
| 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 = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/account/debit_fee"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /account/debit_fee
Query GT fee deduction configuration
Query the GT fee deduction configuration for the current account
Example responses
200 Response
{
"enabled": true
}
| 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
Broker rebate endpoints
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/agency/transaction_history'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/rebate/agency/transaction_history"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /rebate/agency/transaction_history
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 |
Example responses
200 Response
{
"total": 100,
"list": [
{
"transaction_time": 1539852480,
"user_id": 10000,
"group_name": "gateio",
"fee": "1",
"fee_asset": "GT",
"currency_pair": "GT_USDT",
"amount": "1000",
"source": "SPOT",
"amount_asset": "GT"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/commission_history'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/rebate/agency/commission_history"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /rebate/agency/commission_history
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 |
| commission_type | query | integer | false | Rebate type: 1 - Direct rebate, 2 - Indirect rebate, 3 - Self rebate |
| 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 |
Example responses
200 Response
{
"total": 100,
"list": [
{
"commission_time": 1539852480,
"user_id": 10000,
"group_name": "gateio",
"commission_amount": "1000",
"source": "SPOT",
"commission_asset": "GT"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/partner/transaction_history'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/rebate/partner/transaction_history"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /rebate/partner/transaction_history
Partner obtains transaction 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 |
Example responses
200 Response
{
"total": 15,
"list": [
{
"user_id": 1879032535,
"group_name": "test",
"fee": "0.00044800",
"transaction_time": 1718615824,
"amount": "29.98688000USDT",
"amount_asset": "USDT",
"currency_pair": "BCH_USDT",
"source": "SPOT",
"fee_asset": "BCH"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/commission_history'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/rebate/partner/commission_history"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /rebate/partner/commission_history
Partner obtains 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 |
Example responses
200 Response
{
"total": 52,
"list": [
{
"user_id": 1879043947,
"commission_time": 1718616728,
"commission_amount": "0.2216934846",
"commission_asset": "USDT",
"source": "SPOT",
"group_name": "test"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/sub_list'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/rebate/partner/sub_list"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /rebate/partner/sub_list
Partner subordinate list
Including sub-agents, direct customers, 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 |
Example responses
200 Response
{
"total": 3,
"list": [
{
"user_id": 1,
"user_join_time": 1666255731,
"type": 1
},
{
"user_id": 2,
"user_join_time": 1666271213,
"type": 2
},
{
"user_id": 3,
"user_join_time": 1666422143,
"type": 3
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved 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/broker/commission_history'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/rebate/broker/commission_history"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /rebate/broker/commission_history
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 |
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
}
| 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/transaction_history'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/rebate/broker/transaction_history"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /rebate/broker/transaction_history
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 |
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
}
| 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/user/info'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/rebate/user/info"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /rebate/user/info
User obtains rebate information
Example responses
200 Response
{
"invite_uid": 987
}
| 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/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())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/rebate/user/sub_relation"
query_param="user_id_list=1, 2, 3"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
-H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
GET /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 |
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
}
]
}
| 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
{
"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
}
| 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 |
{
"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"
}
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, refers to the trading quantity of the trading currency, i.e., the currency that needs to be traded, for example, the quantity of BTC in BTC_USDT. |
| » 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 |
{
"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,
"delisting_time": 0,
"delisted_time": 0
}
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), circuit_breaker (circuit breaker) |
| launch_time | integer(int64) | false | none | Contract expiry timestamp |
| delisting_time | integer(int64) | false | none | Timestamp when contract enters reduce-only state |
| delisted_time | integer(int64) | false | none | Contract delisting time |
| Property | Value |
|---|---|
| type | inverse |
| type | direct |
| mark_type | internal |
| mark_type | index |
{
"user": 0,
"contract": "string",
"size": 0,
"leverage": "string",
"risk_limit": "string",
"leverage_max": "string",
"maintenance_rate": "string",
"value": "string",
"margin": "string",
"entry_price": "string",
"liq_price": "string",
"mark_price": "string",
"initial_margin": "string",
"maintenance_margin": "string",
"unrealised_pnl": "string",
"realised_pnl": "string",
"pnl_pnl": "string",
"pnl_fund": "string",
"pnl_fee": "string",
"history_pnl": "string",
"last_close_pnl": "string",
"realised_point": "string",
"history_point": "string",
"adl_ranking": 0,
"pending_orders": 0,
"close_order": {
"id": 0,
"price": "string",
"is_liq": true
},
"mode": "single",
"cross_leverage_limit": "string",
"update_time": 0,
"update_id": 0,
"open_time": 0,
"risk_limit_table": "string",
"average_maintenance_rate": "string",
"pid": 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: One-way Mode- dual_long: Long position in Hedge Mode- dual_short: Short position in Hedge 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 |
| 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 |
| pid | integer(int64) | false | read-only | Sub-account position ID |
| Property | Value |
|---|---|
| mode | single |
| mode | dual_long |
| mode | dual_short |
{
"id": 0,
"user": 0,
"create_time": 0.1,
"update_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",
"limit_vip": 0,
"pid": 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 |
| update_time | number(double) | false | read-only | OrderUpdateTime |
| 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 |
| limit_vip | integer(int64) | false | write-only | Counterparty user's VIP level for limit order fills. Current order will only match with orders whose VIP level is less than or equal to the specified level. Only 11~16 are supported; default is 0 |
| pid | integer(int64) | false | write-only | Position ID |
| 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 | - |
{
"contract": "string",
"size": 0,
"direction": "string",
"iceberg": 0,
"level": 0,
"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",
"limit_vip": 0,
"pid": 0
}
contractBBOorderdetails
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| 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. |
| direction | string | true | none | Direction: 'sell' fetches the bid side, 'buy' fetches the ask side. |
| iceberg | integer(int64) | false | none | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| level | integer(int64) | true | write-only | Level: maximum 20 levels |
| 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 |
| limit_vip | integer(int64) | false | write-only | Counterparty user's VIP level for limit order fills. Current order will only match with orders whose VIP level is less than or equal to the specified level. Only 11~16 are supported; default is 0 |
| pid | integer(int64) | false | write-only | Position ID |
| Property | 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 | - |
{
"order_id": 0,
"text": "string",
"size": 0,
"price": "string",
"amend_text": "string"
}
Modify contract order parameters
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| order_id | integer(int64) | false | none | Order id, order_id and text must contain at least one |
| text | string | false | none | User-defined order text, at least one of order_id and text must be passed |
| size | integer(int64) | false | none | 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 |
{
"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 price-triggered order details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| initial | object | true | none | none |
| » contract | string | true | none | Futures contract |
| » size | integer(int64) | false | none | Represents the number of contracts that need to be closed, full closing: size=0 Partial closing: plan-close-short-position size>0 Partial closing: plan-close-long-position size<0 |
| » price | string | true | none | Order price. Set to 0 to use market price |
| » close | boolean | false | write-only | In One-way Mode, when closing all positions, this must be set to true to perform the closing operation When partially closing positions in One-way Mode or Hedge Mode, you can omit close or set close=false |
| » tif | string | false | none | Time in force strategy, default is gtc, market orders currently only support ioc mode - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled |
| » text | string | false | none | The source of the order, including: - web: Web - api: API call - app: Mobile app |
| » reduce_only | boolean | false | none | When set to true, perform automatic position reduction operation. Set to true to ensure that the order will not open a new position, and is only used to close or reduce positions |
| » auto_size | string | false | write-only | One-way Mode: auto_size is not required Hedge Mode full closing (size=0): auto_size must be set, close_long for closing long positions, close_short for closing short positions Hedge Mode partial closing (size≠0): auto_size is not required |
| » is_reduce_only | boolean | false | read-only | Is the order reduce-only |
| » is_close | boolean | false | read-only | Is the order to close position |
| trigger | object | true | none | none |
| » strategy_type | integer(int32) | false | none | Trigger Strategy - 0: Price trigger, triggered when price meets conditions - 1: Price spread trigger, i.e. the difference between the latest price specified in price_type and the second-last priceCurrently only supports 0 (latest transaction price) |
| » price_type | integer(int32) | false | none | Reference price type. 0 - Latest trade price, 1 - Mark price, 2 - Index price |
| » price | string | true | none | Price value for price trigger, or spread value for spread trigger |
| » rule | integer(int32) | true | none | Price Condition Type - 1: Trigger when the price calculated based on strategy_type and price_type is greater than or equal to Trigger.Price, while Trigger.Price must > last_price- 2: Trigger when the price calculated based on strategy_type and price_type is less than or equal to Trigger.Price, and Trigger.Price must < last_price |
| » expiration | integer | false | none | Maximum wait time for trigger condition (in seconds). Order will be cancelled if timeout |
| 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 |
{
"settle": "string",
"order_id": 0,
"contact": "string",
"size": 0,
"price": "string",
"trigger_price": "string",
"price_type": 0,
"auto_size": "string"
}
Modify Price Order Details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| settle | string | false | read-only | Settlement Currency (e.g., USDT, BTC) |
| order_id | integer | false | read-only | ID of the Pending Take-Profit/Stop-Loss Trigger Order |
| contact | string | false | none | The order ID of the modified price-triggered order. This ID is returned upon successful creation of the price-triggered order. Note: This ID must be passed in both the request path and request body. |
| size | integer(int64) | false | none | Modified Contract Quantity. Full Close: 0; Partial Close: Positive/Negative values indicate direction (consistent with the creation interface logic). |
| price | string | false | none | Represents the modified trading price. A value of 0 indicates a market order. |
| trigger_price | string | false | none | Modified Trigger Price |
| price_type | integer(int32) | false | none | Reference price type. 0 - Latest trade price, 1 - Mark price, 2 - Index price |
| auto_size | string | false | none | One-way Mode: auto_size is not required Hedge Mode partial closing (size≠0): auto_size is not required Hedge Mode full closing (size=0): auto_size must be set, close_long for closing long positions, close_short for closing short positions |
| Property | Value |
|---|---|
| price_type | 0 |
| price_type | 1 |
| price_type | 2 |
{
"name": "string",
"underlying": "string",
"cycle": "WEEKLY",
"type": "inverse",
"quanto_multiplier": "string",
"leverage_min": "string",
"leverage_max": "string",
"maintenance_rate": "string",
"mark_type": "internal",
"mark_price": "string",
"index_price": "string",
"last_price": "string",
"maker_fee_rate": "string",
"taker_fee_rate": "string",
"order_price_round": "string",
"mark_price_round": "string",
"basis_rate": "string",
"basis_value": "string",
"basis_impact_value": "string",
"settle_price": "string",
"settle_price_interval": 0,
"settle_price_duration": 0,
"expire_time": 0,
"risk_limit_base": "string",
"risk_limit_step": "string",
"risk_limit_max": "string",
"order_size_min": 0,
"order_size_max": 0,
"order_price_deviate": "string",
"ref_discount_rate": "string",
"ref_rebate_rate": "string",
"orderbook_id": 0,
"trade_id": 0,
"trade_size": 0,
"position_size": 0,
"config_change_time": 0.1,
"in_delisting": true,
"orders_limit": 0
}
Futures contract details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| name | string | false | none | Futures contract |
| underlying | string | false | none | Underlying |
| cycle | string | false | none | Cycle type, e.g. WEEKLY, QUARTERLY |
| type | string | false | none | 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 |