Welcome to Gate API APIv4 provides operations related to spot, margin, and contract trading, including public interfaces for querying market data and authenticated private interfaces for implementing API-based automated trading.
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
REST API BaseURL:
https://api.gateio.ws/api/v4
https://api-testnet.gateapi.io/api/v4
https://fx-api.gateio.ws/api/v4
Available SDK:
Besides API examples, some SDK provides an additional demo application. The demo application is a relatively complete example demonstrating how to use the SDK. It can be built and run separately. Refer to corresponding repository for details.
Previously(before April 2020) futures APIv4 key are separated from spot one, but this is no longer the case anymore. You can create multiple keys with each key having multiple permissions now. e.g. you can create one key with spot read/write and futures read/write permission which can be used in both spot and futures trading.
History API keys will not be affected by this improvement. Previous spot key and futures key are now one key with only spot permissions enabled, another only futures permission enabled. You can reconfigure their permissions after migration.
APIv4 is a standalone brand-new HTTP REST API, currently used in parallel with APIv2. APIv4 provides complete trading operations, with more highly secured authentication method. What's more, APIv4 specification is written following OpenAPI Specification (opens new window). SDKs and documents are all generated from the same spec, which ensures consistency between documents and implementation.
The ways APIv4 and APIv2 differ are:
Which one to choose:
In order to further improve the platform's opening depth and trading liquidity, we will recruit institutional market makers in an open and transparent way, and provide a professional market maker's service rate scheme for professional institutional market makers according to their contribution to the platform's liquidity.
Provide the above content and submit to mm@gate.com , we will accept within 3 working days.
TIP
Vip11 and above need to open GT deduction in the personal center to enjoy the professional market rate.
If you have any questions or suggestions during the use, you can contact us in any of the following ways:
If you encounter API errors, it is recommended that you sort out the following content, so that we can quickly analyze the problem for you:
DANGER
Even if you submit a problem, you should not submit the API key information to customer service or others, otherwise there will be serious asset risk. If it has been accidentally leaked, please delete the existing API and rebuild it.
v4.103.0
code
field in GET /spot/account_book
query parameter and response to filter account book entries by specific codethreshold
parameter to enable_evolved_classic
configuration for setting position upgrade threshold in classic account margin modetext
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
, source
v4.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
voucher_size
, voucher_margin
, voucher_id
GET /futures/{settle}/risk_limit_table
endpoint, Query risk limit tier table by table_idGET /futures/{settle}/risk_limit_table/list
endpoint, Query all risk limit tier tablesenable_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
、GET /spot/real_accounts
endpoint responsePUT /earn/uni/interest_reinvest
endpointv4.98.0
/earn/uni/rate
endpoint, Currency estimate annualized interest ratedelisting_time
、trade_url
field in GET /spot/currency_pairs
、GET /spot/currency_pairs/{currency_pair}
endpointv4.97.0
GET /unified/batch_borrowable
endpoint, Batch query unified account can be borrowed up to a maximumGET /spot/candlesticks
endpoint, interval
supports 1s
granularityGET /earn/uni/chart
endpoint, UniLoan currency annualized trend chartPOST /futures/{settle}/positions/cross_mode
endpoint, Switch to the full position-by-store modev4.96.0
cross_margin_balance
,cross_mmr
,cross_imr
field in GET /futures/{settle}/accounts
responsev4.95.0
code
field in GET /spot/account_book
query & responseGET /unified/transferables
endpoint, Batch query unified account can be transferred up to a maximum ofGET /margin/user/loan_margin_tiers
endpoint, Check the user's own leverage lending gradient in the
current marketGET /margin/loan_margin_tiers
endpoint, Query the current market leverage lending gradientPOST /margin/leverage/user_market_setting
endpoint, Set the user market leverage multipleGET /margin/user/account
endpoint, Query the user's leverage account listv4.94.0
GET /unified/currencies
endpoint, List of loan currencies supported by unified accountsub_uid
field in GET /unified/accounts
queryv4.93.0
plan_id
field in GET /earn/dual/investment_plan
queryfrom
、to
、page
、limit
field in GET /earn/dual/orders
querytext
field in GET /earn/dual/orders
responsetext
field in POST /earn/dual/orders
responseGET /earn/staking/eth2/rate_records
endpoint, Query historical rate of ETH2v4.92.0
2025-02-24
name
field in GET /spot/currencies
querybase_name
、quote_name
field in GET /spot/currency_pairs
responseunified
field in GET /spot/price_orders
querysub_uid
field in GET /unified/accounts
queryv4.91.0
2025-02-10
2025-04-01
After that, we will remove the following interface, please migrate to the new interface as soon as possible
GET /margin/cross/borrowable
endpoint, deprecatedGET /margin/cross/estimate_rate
endpoint, deprecatedGET /margin/cross/transferable
endpoint, deprecatedGET /margin/cross/interest_records
endpoint, deprecatedGET /margin/cross/repayments
endpoint, deprecatedPOST /margin/cross/repayments
endpoint, deprecatedGET /margin/cross/loans/{loan_id}
endpoint, deprecatedPOST /margin/cross/loans
endpoint, deprecatedGET /margin/cross/account_book
endpoint, deprecatedGET /margin/cross/accounts
endpoint, deprecatedGET /margin/cross/currencies/{currency}
endpoint, deprecatedGET /margin/cross/currencies
endpoint, deprecatedv4.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.89.0
2025-01-08
text
field in DELETE /futures/{settle}/close_all_positions
query stringv4.88.0
2024-12-24
GET /spot/insurance_history
endpoint, Query spot insurance fund historical datacross_balance
、iso_balance
、im
、mm
、imr
、mmr
、margin_balance
、available_margin
field
in GET /unified/accounts
responsePUT /unified/unified_mode
endpoint, Added single-currency margin modev4.87.0
GET /unified/history_loan_rate
endpoint, Get historical lending ratesv4.86.0
2024-12-02
GET /wallet/order_status
endpoint. Transfer status queryupdate_id
field in GET /futures/{settle}/positions
responsev4.85.0
2024-11-11
x-gate-exptime
field in POST /futures/{settle}/orders
、POST /spot/batch_order
header.Add cross_order_margin
、cross_initial_margin
、cross_maintenance_margin
、cross_unrealised_pnl
、cross_available
、isolated_position_margin
field in POST /futures/{settle}/dual_mode
response.
v4.84.0
2024-11-04
GET /loan/multi_collateral/current_rate
endpoint, Query the current interest rate of the currencylowest_size
、highest_size
field in GET /spot/tickers
responseamount
field in POST /earn/dual/orders
request bodyv4.83.0
2024-10-28
GET /unified/leverage/user_currency_config
endpoint, Query the maximum and minimum leverage multiples
that users can set for a currencyGET /unified/leverage/user_currency_setting
endpoint, Get the user's currency leveragePOST /unified/leverage/user_currency_setting
endpoint, Set the currency leverage ratioid
field in GET /futures/{settle}/account_book
responseleverage
field in GET /unified/currency_discount_tiers
responsev4.82.0
2024-10-14
GET /account/rate_limit
endpoint, Get user flow limit information. For details, please refer
to Trade Ratio Rate LimitingGET /account/detail
接口, 返回值增加 copy_trading_role
fieldv4.81.0
2024-09-30
POST /options/countdown_cancel_all
endpoint, Countdown to cancel ordermessage
field in GET /wallet/push
responselowest_size
、highest_size
in GET /futures/{settle}/tickers
responsefrom
、to
in GET /futures/{settle}/funding_rate
queryis_max
field in POST /earn/dual/orders
responsev4.80.0
2024-09-09
GET /options/mmp
endpoint, MMP QueryPOST /options/mmp
endpoint, MMP SettingsPOST /options/mmp/reset
endpoint, MMP Resetblock_number
field in GET /wallet/withdrawals
responsev4.79.0
2024-09-02
from
、to
field in GET /unified/interest_records
queryoptions
field in GET /unified/unified_mode
responseoptions
field in PUT /unified/unified_mode
request bodyv4.78.0
2024-08-19
GET /wallet/push
endpoint, Get RecordsPOST /withdrawals/push
endpoint, Transfer between spot main accounts. Both parties cannot be
sub-accounts.GET /futures/{settle}/batch_amend_orders
endpoint, Batch modify orders with specified IDsclose_size
field in GET /futures/{settle}/my_trades
responsetx_id
field in POST /wallet/transfers
responsev4.77.0
2024-08-05
GET /sub_accounts/unified_mode
endpoint, Get sub-account modefrom
、to
field in GET /rebate/broker/commission_history
queryfrom
、to
field in GET /rebate/broker/transaction_history
queryv4.76.0
2024-07-22
GET /rebate/partner/sub_list
endpoint, Partner subordinate listpage
、limit
field in GET /flash_swap/currency_pairs
queryorder_id
、currency_pair
、account
field in PATCH /spot/orders/{order_id}
order_id
、currency_pair
、account
field in DELETE /spot/orders/{order_id}
v4.75.1
2024-07-08
GET /delivery/{settle}/risk_limit_tiers
endpoint, querying risk limit levelsGET /rebate/partner/transaction_history
endpoint, partners to get the transaction history of
recommended usersborrow_type
field in GET /unified/loan_records
responseaccum_size
field in GET /futures/{settle}/position_close
responsev4.75.0
2024-06-24
GET /account/debit_fee
endpoint, query GT deduction configuration.POST /account/debit_fee
endpoint, to enable or disable GT deduction for the current account.v4.74.1
2024-06-11
v4.74.0
2024-05-29
GET /unified/loan_margin_tiers
endpoint, list loan margin tiersv4.73.0
2024-05-27
is_all
parameter in POST /wallet/small_balance
endpointtext
field in POST /spot/cancel_batch_orders
responsefunding
、funding_version
、use_funding
field in GET /unified/accounts
responsev4.72.0
2024-05-13
last_access
field in GET /sub_accounts/{user_id}/keys
responsecontract
field in GET /futures/{settle}/risk_limit_tiers
responsev4.71.0
2024-04-23
page
parameter in GET /wallet/saved_address
endpointGET /api/v4/rebate/user/info
endpoint, retrieve user rebate informationPOST /unified/portfolio_calculator
endpoint, portfolio margin calculatorGET /unified/risk_units
endpoint, retrieve user risk unitPUT /unified/unified_mode
endpoint, set unified account modeGET /unified/unified_mode
endpoint, retrieve unified account modev4.70.0
2024-04-08
pnl_pnl
、pnl_fund
、pnl_fee
field in GET /futures/{settle}/positions
responsepnl_pnl
、pnl_fund
、pnl_fee
field in GET /futures/{settle}/position_close
responsev4.69.0
2024-03-25
text
field in POST /delivery/{settle}/price_orders
responsev4.68.0
2024-03-18
GET /unified/currency_discount_tiers
endpoint, list currency discount tierstype
parameter in GET /unified/loans
endpointtype
parameter in GET /unified/interest_records
endpointv4.67.0
2024-03-11
filled_amount
field in POST /spot/orders
,POST /spot/batch_orders
response10r/10s
to 1r/3s
(No modification to the original rate limiting behavior)v4.66.1
2024-02-19
GET /wallet/small_balance
endpoint, list small balance.GET /wallet/small_balance_history
endpoint, list small balance history.GET /unified/estimate_rate
endpoint, get unified estimate rate.v4.65.0
2024-01-29
debit_fee
field in GET /spot/batch_fee
responseuser_id
parameter in DELETE /account/stp_groups/{stp_id}/users
endpointACK
, RESULT
, FULL
. For details, please refer
to SPOT APIv4.64.0
2024-01-22
order_type
parameter in GET /loan/multi_collateral/orders
endpointorder_type
,fixed_type
,fixed_rate
,expire_time
,auto_renew
,auto_repay
field
in GET /loan/multi_collateral/orders
responsebefore_ltv
,after_ltv
field in GET /loan/multi_collateral/repay
responseGET /loan/multi_collateral/fixed_rate
endpoint, query multi-collateral fix rate.unrealised_pnl
,borrowed
field in GET /wallet/total_balance
responsev4.63.0
2024-01-15
decimal
field in GET /wallet/currency_chains
responseGET /futures/{settle}/risk_limit_tiers
endpoint, list risk limit tiers.v4.62.0
2024-01-02
POST /futures/{settle}/batch_cancel_orders
endpoint, users have the ability to batch cancel orders./loan/multi_collateral/**
)v4.61.0
2023-12-18
GET /rebate/broker/commission_history
and GET /rebate/broker/commission_history
endpointsv4.60.0
2023-12-01
/portfoli/*
endpoints are deprecated./earn/**
)trade_id
field in GET /futures/{settle}/account_book
responsev4.59.0
2023-11-22
funding_cap_ratio
field in GET /futures/{settle}/contracts
responsecontract
field in GET /delivery/{settle}/account_book
responsewithdraw_percent_on_chains
field in GET /wallet/withdraw_status
responseleverage
field in GET /portfolio/accounts
responsev4.58.0
2023-11-03
Add loanable
field in GET /margin/cross/currencies
response
Add tier
field in GET /account/detail
response
Add max_base_amount
、max_quote_amount
field in GET /spot/currency_pairs
response
v4.57.0
2023-10-20
POST /spot/orders
endpointPUT /earn/uni/interest_reinvest
endpoint, users have the option to enable or disable interest
reinvestment.POST /spot/amend_batch_orders
endpoint, users have the ability to batch modify orders.sequence_id
field in GET /spot/trades
responsetext
field in GET /spot/account_book
responsetext
field in GET /spot/my_trades
responseGET /portfolio/spot/orders
、 GET /portfolio/spot/orders
、GET /portfolio/spot/orders/{order_id}
、DELETE /portfolio/spot/orders/{order_id}
and PATCH /portfolio/spot/orders/{order_id}
have been deprecated. We will remove the endpoints by the end of October
2023. Please use /spot/orders
instead.v4.56.0
2023-09-25
repayment_type
field in GET /margin/cross/repayments
and GET /portfolio/loan_records
endpoints.holding
in GET /futures/{settle}/positions
endpointrole
in GET /futures/{settle}/my_trades_timerange
endpointside
and pnl
in GET /futures/{settle}/position_close
endpointv4.55.0
2023-09-12
POST /portfolio/account_mode
endpoint, allow to change the mode.v4.54.0
2023-08-28
contract_address
field in GET /wallet/currency_chains
endpoint.GET /portfolio/spot/currency_pairs
and GET /portfolio/spot/currency_pairs/{currency_pair}
endpoints, list
portfolio spot's currency pairs.v4.53.0
2023-08-14
DELETE /account/stp_groups/{stp_id}/users
endpointv4.52.0
2023-08-07
v4.51.0
2023-07-29
mode
field in GET /account/detail
edpoint.v4.50.0
2023-07-14
GET /flash_swap/currency_pairs
, list all flash swap currency pairv4.49.0
2023-07-03
GET /futures/{settle}/orders
API endpoint, the request field contract
has been modified to be optional
instead of mandatory.v4.48.0
2023-06-16
client_order_id
fields in GET /wallet/sub_account_transfers
edpoint.v4.47.0
2023-05-23
GET /margin/uni/estimate_rate
and GET /margin/cross/estimate_rate
endpoints.GET /futures/{settle}/orders_timerange
endpointunderlying
、underlying_price
、mark_iv
、delta
、gamma
、vega
、theta
fields
in GET /options/positions/{contract}
endpoint.v4.46.0
2023-05-08
GET /spot/account_book
endpointGET /futures/{settle}/fee
endpointis_internal
field in GET /futures/{settle}/trades
endpointv4.45.0
2023-04-21
Lend & Earn
. For more information, please refer to
the Margin Migration InstructionsGET /margin/cross/interest_records
endpoint.Self-Trade Prevention
feature in the POST /futures/{settle}/batch_orders
endpoint.futures_in
、futures_out
two fields in GET /margin/cross/account_book
endpoint.v4.44.0
2023-04-07
ORDER_BOOK_NOT_FOUND
and FAILED_RETRIEVE_ASSETS
error messages.v4.43.0
2023-03-27
Self-Trade Prevention
feature in the POST /spot/orders
endpoint. Fore more detail, please refer
to STP overviewGET /account/detail
endpoint.amend_text
in PATCH /spot/orders/{order_id}
endpoint.lowest_ask
and highest_bid
fields in GET /futures/{settle}/tickers
endpointv4.42.0
2023-03-13
Lend & Earn
APISelf-Trade Prevention
feature in the POST /futures/{settle}/orders
endpoint. Fore more detail,
please refer to STP overviewdelivery
account type in POST /wallet/sub_account_transfers
endpointamend_text
field in PUT /futures/{settle}/orders/{order_id}
endpointv4.41.0
2023-03-03
Add negative_liab
, futures_pos_liab
, equity
, total_freeze
, total_liab
, portfolio_margin_total_liab
, portfolio_margin_total_equity
fields in GET /margin/cross/accounts
endpoint
v4.40.0
2023-02-24
Get /futures/{settle}/auto_deleverages
sum
field in GET /futures/{settle}/candlesticks
endpointv4.39.0
2023-02-09
GET /spot/batch_fee
enable_bonus
、enable_credit
fields in GET /futures/{settle}/contracts
endpointv4.38.0
2023-02-04
GET /futures/{settle}/my_trades_timerange
withdraw_order_id
field in POST /withdrawals
endpointv4.37.0
2023-01-20
v4.36.0
2022-12-23
iceberg
in POST /spot/orders
and POST /spot/batch_orders
endpointsv4.35.0
2022-12-09
/spot/orders/{order_id}
avg_deal_price
field in GET /spot/orders
responseportfolio_margin_total
field in ``GET /margin/cross/accounts` responsePOST /spot/batch_orders
endpointv4.34.0
2022-11-25
POST /spot/orders
endpointv4.33.0
2022-11-11
GET /futures/{settle}/premium_index
v4.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}/trades
v4.27.0
2022-07-29
basis_rate
、basis_value
fields in GET /delivery/{settle}/tickers
responseX-Client-Request-Id
http header for tracking requestPOST /futures/{settle}/batch_orders
FOK
tif type for futures orderv4.26.0
2022-07-15
GET /wallet/saved_address
to list saved addressPOST /wallet/transfers
returns tx_id
fieldGET /wallet/sub_account_cross_margin_balances
to query subaccount's cross_margin
accountstatus
field in GET /margin/currency_pairs
responsev4.25.1
2022-07-06
GET /spot/time
endpoint which get system's time info.GET /options/my_settlements
endpoint which list my selttlements.change_utc0
, change_utc8
fields in GET /spot/tickers
endpointv4.25.0
2022-06-24
status
field in GET /margin/cross/currencies
endpoint, determine whether the cross
currency is disabled 0
-disable 1
-enablePOST /spot/cross_liquidate_orders
spot trading endpoint that close position when the
cross-currency is disabledbouns
and history
fields in GET /futures/{settle}/accounts
endpointtext
、fee
and point_fee
fields in GET /futures/{settle}/my_trades
endpointcancel a price-triggered order
endpointsPOST /wallet/sub_account_transfers
supports transferring to cross_margin
v4.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 FuturesPriceTriggeredOrder
v4.23.4
2022-04-25
PUT /futures/{settle}/orders/{order_id}
to amend perpetual futures orders30d
intervalv4.23.3
2022-04-01
chain
field.GET /wallet/currency_chains
responsecross_leverage_limit
in perpetual contract's dual mode position leverage update APIv4.23.2
2022-01-21
fee
in withdrawal and deposit historyCurrency
v4.23.1
2021-12-23
time_in_force
FOK
FOK_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 int64
v4.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_address
v4.21.5
2021-06-30
GET /spot/orders
, GET /spot/orders/{order_id}
and GET /spot/my_trades
allow empty
currency_pair
if operated against finished ordersGET /wallet/withdraw_status
responseGET /margin/transferable
and GET /margin/cross/transferable
to retrieve
maximum transferable amount from margin and cross margin accountfrom
and to
parameter to specify time range for futures position closes history APIv4.21.4
2021-06-23
GET /margin/cross/account_book
GET /margin/account_book
responsev4.21.3
2021-06-17
v4.21.2
2021-06-07
/margin/cross
create_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_orders
v4.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_repay
multichain_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_stats
v4.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_orders
reverse
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
/delivery
v4.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_delisting
v4.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_IMMEDIATELY
v4.11.1
2020-03-23
role
in GET /spot/my_trades
responseGET /margin/funding_accounts
v4.11.0
2020-03-20
poc
v4.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 BatchOrder
GET /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
volume_24h_base
, volume_24h_quote
and volume_24h_settle
in /futures/{settle}/tickers
response to replace volume_24h_btc
and volume_24h_usd
. The latter two are still
preserved for compatibility usage, but are NOT recommended for any futures operations.To use USDT futures, just replace /futures
with /futures/usdt
, e.g.
use GET /futures/usdt/accounts
to retrieve futures accounts settled in USDT,
while GET /futures/btc/accounts
returns accounts in BTC.
For compatibility, GET /futures/xxx
defaults to GET /futures/btc/xxx
, e.g.
GET /futures/accounts
will be treated as GET /futures/btc/accounts
v4.7.3
2019-07-18
text
in /spot/orders
and /futures/orders
to support user defined order informationv4.6.3
2019-06-11
v4.7.2
2019-05-29
rate
in Loan
as non-required for lending side.v4.7.1
2019-04-17
GET /margin/loans
can sort by rate
and support an optional parameter currency_pair
v4.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/v4
v1.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
, FuturesOrder
GET /futures/position_close
to retrieve position close historyorder_id
support for API GET /futures/my_trades
DELETE /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 DELETE
s 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-limit
limit-offset
In both method, limit
limits the maximum number of records returned in one request. If no
additional explanation, it defaults to 100
if not provided and its maximum value is limited
to 1000
.
page
starts from 1
, mimicking common paging used in web pages. To iterate the whole list, use
the same limit
and increment page
by 1
until the records' length is shorter than the
limit
offset
starts from 0
, behaving like common DB search. To iterate the whole list, increment
offset
by limit
until the records' length is shorter than the limit
.
For example, if the total number of orders is 201. Using page-limit method, send request parameters like the following:
page=1&limit=100
page=2&limit=100
page=3&limit=100
Using limit-offset method, send request parameters like:
limit=100&offset=0
limit=100&offset=100
limit=100&offset=200
Some endpoints may return additional pagination metadata. If present, they are sent back through the
response header. Take GET /futures/{settle}/orders
as an example, following headers will be
returned
X-Pagination-Limit
: request limitX-Pagination-Offset
: request offsetX-Pagination-Total
: total record number satisfying the requestMarkets | Endpoints | Limits | Based On | Include |
---|---|---|---|---|
All public endpoints | Public endpoints | 200r/10s per endpoint | IP | Orderbook, Candlestick, Ticker, etc. |
Wallet | Private endpoints |
Withdrawal(POST /withdrawals) : 1r/3s Transfer between trading accounts (POST /wallet/transfers) 80r/10s Transfer between main and sub accounts (POST /wallet/sub_account_transfers) 80r/10s Transfer from a sub-account to another sub-account (POST /wallet/sub_account_to_sub_account) 80r/10s Retrieve user's total balances (GET /wallet/total_balance) 80r/10s Retrieve sub account balances (GET /wallet/sub_account_balances) 80r/10s Query sub accounts' margin balances (GET /wallet/sub_account_margin_balances) 80r/10s Query sub accounts' futures account balances (GET /wallet/sub_account_futures_balances) 80r/10s Query subaccount's cross_margin account info(GET /wallet/sub_account_cross_margin_balances) 80r/10s The Others: 200r/10s per endpoint | UID |
Withdrawal. Query personal account balance. Query subaccount balance. |
Spot | Private endpoints |
The rate limit for batch/single order placement and amend an order are total of 10r/s (UID+Market) The rate limit for batch/single order cancellation is total of 200r/s The Others: 200r/10s per endpoint | UID |
Spot order placement and cancellation. Trade history and fee rates. |
Perpetual Futures | Private endpoints |
The rate limit for batch/single order placement and amend an order are total of 100r/s The maximum rate limit for the order cancellation (bulk/single) is 200r/s The Others: 200r/10s per endpoint | UID |
Futures order placement and cancellation Trade history and fee rates |
Delivery | Private endpoints |
The maximum rate limit for the order placement (bulk/single) is 500r/10s The maximum rate limit for the order cancellation (bulk/single) is 500r/10s The Others: 200r/10s per endpoint | UID |
Order placement and cancellation |
Options | Private endpoints |
The maximum rate limit for the order placement (bulk/single) is 200r/s The maximum rate limit for the order cancellation (bulk/single) is 200r/s The Others: 200r/10s per endpoint | UID |
Order placement and cancellation |
Subaccount | Private endpoints | 80r/10s per endpoint | UID |
Create a sub-account. Retrieve the list of sub-accounts. Disable or enable API key for a sub-account. |
Unified | Private endpoints | Borrow or repay 15/10s | UID |
Borrow or repay(POST /unified/loans) |
Other Private endpoints | Private endpoints | 150r/10s per endpoint | UID | Earning, collateral etc |
The rate limit is counted against each sub-account or main account.
Rate Limit
Each request to the API response header will contain the following fields::
WebSocket:
In order to enhance trading efficiency, we have decided to implement more favorable sub-account rate limits for clients with a higher fill ratio. This assessment will be based on trading data from the past seven days and will be calculated daily at 00:00 UTC. Please note that this rule applies only to clients at VIP level 14 and above.
To facilitate a more refined management of the impact of different trading products on the fill ratio, we have introduced the concept of the symbol multiplier. This multiplier allows us to adjust the influence of each product on the overall trading volume based on its characteristics. For products with a multiplier of less than 1, they typically involve smaller contract sizes and therefore require more trading orders to achieve the same trading volume. Generally, all trading products come with a default multiplier; however, certain products are assigned independent multipliers based on their specific characteristics. For detailed information regarding the multipliers of relevant products, please refer to the provided table.
Product Typee | Based On | Independnet Symbol Multiplier | Default Symbol Multiplier |
---|---|---|---|
USDT-Margined Perpetural Futures | Contract Symbol |
1 Contract Symbol: BTC-USDT ETH-USDT | 0.4 |
Spot | Currency Pairst |
1 Currency Pairs: BTC-USDT ETH-USDT | 0.4 |
Please note: The spot trading rate limits will not be launched this time.
We will assess the behavior patterns of makers and takers based on market fluctuations and design the trading volume weight ratios accordingly. Additionally, we will regularly evaluate these weights and make synchronized adjustments when necessary.
Current weight of the maker trading volume: 100%, current weight of the taker trading volume: 90%.
The system will take a snapshot of the data at 00:00 UTC daily and, based on this information, will select the higher value between the fill ratio of the sub-account and the overall fill ratio of the main account to determine the future trading rate limit for the sub-account. For exchange brokers, the system will only consider the fill ratio of their sub-accounts. It is important to note that the main account is also considered a "sub-account."
Contract Frequency Limitation Rules | ||
---|---|---|
Tier | Ratio | Rate Limit (uid) |
Tier 1 | [0,1) | 100r/s |
Tier 2 | [1,3) | 150r/s |
Tier 3 | [3,5) | 200r/s |
Tier 4 | [5,10) | 250r/s |
Tier 5 | [10,20) | 300r/s |
Tier 6 | [20,50) | 350r/s |
Tier 7 | >= 50 | 400r/s |
Please stay tuned for the rate limits for spot trading.
Assuming the client has three accounts, with the symbol multipliers for trading perpetual contract products BTC-USDT and SOL-USDT being 1 and 0.4, respectively.
All API responses are in JSON format, and users need to transform and extract data by themselves.
The HTTP status code 2XX will be returned when all operations are successful. 401 indicates that there is a problem with the certification. Other 4xx status codes indicate that the request is invalid. If it is a 5xx error, the server has encountered an unknown serious error when processing the request. Please give feedback as soon as possible.
Return Status
Status Code | Description |
---|---|
200/201 | Request succeeded |
202 | Request accepted by the server, but processing is not done yet |
204 | Request succeeded, but the server doesn't return body |
400 | Invalid request |
401 | Authentication failed |
404 | Not found |
429 | Too many requests |
5xx | Server error |
Type | Description |
---|---|
string | String type, in double quotation marks. Price and amount are also formatted in string format |
integer | 32-bit integer, Mainly related to status codes, size, times, etc. |
integer(int64) | 64-bit integer, Mainly involves ID and higher precision timestamp |
float | Floating point number. Some time and stat fields use float. |
object | Object, Contains a child object{} |
array | List, Includes multiple groups of content |
boolean | true is true, false is false |
TIP
The Portfolio Margin Account is no longer maintained, please refer to the new version of the Unified Account
Since version 4.25.0
, we start supporting portfolio margin account. Gate's Portfolio Margin
Account is a new feature of Gate's trading system. Its main function is to break the capital
isolation between cross-margin leverage account and USD cross-margin perpetual contract account
inside a Classic Account and achieve the multi-currency margin sharing among multi-product lines.
Thanks to the margin sharing, users don't need to transfer funds between the two accounts, and the
profit and loss of positions among different trading products can offset each other and effectively
improve the capital utilization rate. See more details in the
Help Center
Before using the portfolio margin account's API key, you should create the API key on the API management page. The API key supports spot and perpetual contracts trading only.
If permissions of the API key can't be checked, ensure your cross-margin account has available balance first.
The classic account and portfolio margin account are two different capital isolation accounts. If you want to achieve multi-currency margin sharing among multi-product lines, use the portfolio margin account please.
The funds of the portfolio margin account come from the classic account. Due to the change of funds in the classic account, the transfer of funds can only be performed using the API Key of the classic account.
The portfolio margin account is upgraded based on the cross-margin account of the original classic account, so the classic account only needs to transfer its spot funds to the cross-margin account to deposit the portfolio margin account. Similarly, withdrawals from portfolio margin account can be achieved by the classic account performing transferals from the cross margin to its spot account.
The API Key of the portfolio margin account can only perform transferals among its own multiple accounts. Due to the sharing of margin, the portfolio margin account does not need to transfer funds to its futures account (we also restrict doing so). If the futures account has PNL funds that need to be withdrawn, it must be transferred by the portfolio margin account's API key to its cross-margin account first, so that the classic account can perform withdrawals from portfolio margin account.
The spot trading of the portfolio margin account is almost the same as the classic account, except
that cross_margin
must be specified in the account
parameter when placing orders. For example,
if you want to place a buy order for the BTC_USDT
currency pair, the order request will be similar
to
POST /spot/orders
{
"currency_pair": "BTC_USDT",
"account": "cross_margin",
"side": "buy",
...
}
For other related restrictions, please refer to the document of the API endpoint directly.
TIP
It should be noted that the portfolio margin account is upgraded from the classic account's cross-margin account. The API Key of the classic account originally supports the operation of the cross-margin account. In order not to affect the existing operations of the classic account, we still retain this function of the classic account. So whether it is the API Key of the classic account or the portfolio margin account, both can operate the same the cross margin account (note that the futures accounts are separate)
The API operation of the perpetual contract of the portfolio margin account is exactly the same as that of the classic account, but currently only supports USD settlement
TIP
In the futures trading, it should be noted that there is no compatibility for cross-margin accounts
like using the API Key of the classic account in spot trading. Therefore, when using the API Key of
the classic account for futures trading, assets are kept under classic account-futures
, and when
using portfolio margin account API Key for futures trading, assets are kept
under portfolio margin account-futures
. These two are different futures accounts. In addition,
funds under classic account-spot
cannot share margin with classic account-futures
.
The API response will carry the header: X-Gate-Trace-ID . This header is used for tracking.
Self-Trade Prevention: STP will prevent any user's orders from being matched with each other.
CN: Cancel new, Cancel new orders and keep old ones.
CO: Cancel old, Cancel old orders and keep new ones.
CB: Cancel both, Both old and new orders will be cancelled.
We support three STP strategies, which are CN
, CO
and CB
.
STP is achieved by adding users to one STP trading group.
When a user in a STP group place orders, and trading could happen with existing orders of users in the same group, orders will be cancelled.
The prevention strategy depends on the stp_act
parameter specified when placing the order as taker.
If not specified, the CN
strategy will be used by default.
A user has to be added to a STP trading group before using STP.
When a user does not belong to any STP trading group, and place orders with the stp_act
parameter, the orders will be rejected.
Take placing futures order as an example:
POST /futures/{settle}/orders
New request body parameter:
Name | Position | Type | Required | Description |
---|---|---|---|---|
stp_act | body | string | No | STP Strategies, including: - cn - co - cb |
New response fields:
Name | Type | Required | Restriction | Description |
---|---|---|---|---|
stp_act | string | No | none | STP Strategies, including: - cn - co - cb |
stp_id | integer(int64) | No | readonly | The ID of the STP trading group to which user belongs. |
finish_as | string | No | readonly | order finish type: - stp: The order has been canceled due to the STP |
There are multiple accounts under Organization A
, and the IDs of several accounts are 101
, 102
, and 103
In order to prevent self-trading of orders placed by internal accounts of the organization, the administrator created a STP trading group with group ID 100
,
and added accounts 101
and 102
to the STP trading group.
In this case, the members in the group are [101,102]
.
T1: The STP
strategy version released.
T2: After the organization A
account 101
places a short order, there is no matching order in the market order book to match the transaction.
At this time, the role of the order is maker
, and the order status is open
.
The key response fields returned are:
{
"status":"open",
"stp_act":"cn",
"stp_id":100
}
T3: Organization A
account 101
/102
places a long order, and it can reach a trade with account 101’s short order.
The match engine finds both two orders' stp_id are 100, so it applies the STP strategy of the taker order, which defaults to cn
, and cancels the long order.
Order's finish_as
will be set to stp
.
The key response fields returned are:
{
"status":"finished",
"stp_act":"cn",
"stp_id":100,
"finish_as":"stp"
}
If stp_act
is co
, the order placed by taker
will be retained, the order status will be open
,
and the system will cancel the order of maker
.
If stp_act
is cb
, both the long and short orders will be cancelled. Orders' finish_as
will be set to stp
.
The key response fields returned are:
{
"status":"finished",
"stp_act":"cb",
"stp_id":100,
"finish_as":"stp"
}
T3': If account 103 places a long order, and it can reach a trade with account 101’s short order, the transaction will be made since account 103 has not been added to account 101’s STP group. The key response fields returned are:
{
"status":"finished",
"stp_id":0,
"finish_as":"filled"
}
Once a user upgrades their account to the unified account, they can utilize the assets from their spot account as collateral for trading. The assets in the account, denominated in various currencies, will be adjusted based on their liquidity and converted to USD for consistent calculation of the account's assets and position value.
The maximum borrowing limit for margin trading represents the maximum amount that a user can borrow for a given trading market. The platform calculates the user's maximum borrowing limit based on factors such as available margin and platform risk control rules. Once the margin trading generates automatic borrowing, the platform immediately starts accruing interest on the borrowed digital assets.
Currently, the ability to switch to cross_margin
orusdt_futures
mode is available. In the future, we will gradually introduce support for various combination margin accounts, including Futures
, Delivery
, Options
and more. Stay tuned for further updates.
Please refer to the documentation for unified API. Once you have upgraded your account, you will be able to make use of these endpoints.
Related endpoint can be found in the Unified Account API doc. After enabling the Unified Account, you can proceed to call them. For more detailed information, please refer to here
API KEY
or update the permissions of an existing API KEY
, checking the unified
permissionAPI KEY
to call the POST /api/v4/unified/account_mode
endpoint, or upgrade from the WEB page to the Unified Account/api/v4/spot/**
API for spot-related operations (ordering, modifying orders, querying orders), with the account=unified
option/api/v4/futures/**
API for perpetual futures-related operations (ordering, modifying orders, querying orders)/api/v4/unified/**
API for Unified Account-related operations (account querying, loan querying)The spot trading in the Unified Account is consistent with that in the classical account. In order operations, specify account=unified
, or specify account=spot
and the system will automatically handle the order as a unified account order when detecting the account as a unified account. For example, to place a buy order for the BTC_USDT
currency pair, the order creation request would be similar to
POST /spot/orders
{
"currency_pair": "BTC_USDT",
"account": "unified",
"side": "buy",
...
}
For other related restrictions, please refer to the document of the API endpoint directly.
Name | Cross Margin |
---|---|
portfolio_margin_total_equity | Account Equity = ∑(Equity * Index Price) |
total_margin_balance | Account Margin Balance = ∑(Positive Equity x Index Price x Adjustment Factor) + ∑(Negative Equity x Index Price) - Haircut Loss |
total_initial_margin_rate | Account Initial Margin Level = Account Margin Balance / Account Initial Margin |
total_maintenance_margin_rate | Account Maintenance Margin Level = Account Margin Balance / Account Maintenance Margin |
total_initial_margin | Account Initial Margin = Total Liabilities x Spot Initial Margin Rate |
total_maintenance_margin | Account Maintenance Margin = Total Liabilities x Spot Maintenance Margin Rate |
equity | Equity = Coin Balance - Borrowed |
available | Available Balance = Principal + Borrowed |
freeze | Occupied = Assets Occupied by Spot Open Orders |
For all abnormal requests, APIv4 will return non-2xx status code, with a response body in JSON format to explain the error.
The error response body follows a format like:
{
"label": "INVALID_PARAM_VALUE",
"message": "Invalid parameter `text` with value: abc"
}
label
: denotes error type in string
format. Its value are chosen from a certain list(see
below).
Programs can use label
to identify and catch a specific error.message
(or detail
): detailed error message. A longer explanation showing why the error is
generated
or how to avoid it. Its purpose is helping to better understand the API. Error handling
mechanism with this field is highly NOT recommended.Take Python requests (opens new window) for example, error handling can be written like:
Following examples only deal with business-related errors. Network timeout or other common errors need to be handled separately:
import requests
r = requests.get("https://api.gateio.ws/api/v4/futures/btc/contracts/BTC_USD")
try:
r.raise_for_status()
except requests.HTTPError:
# catch 2xx errors, parse error message in body, and do something based on `label`
if r.json()['label'] == 'xxx':
print(r.json())
or with Python SDK (opens new window):
import json
from gate_api import FuturesApi
from gate_api.rest import ApiException
api = FuturesApi()
try:
api.get_futures_contract(settle='btc', contract="BTC_USD")
except ApiException as e: # ApiException wraps whole error information, see implementation for details
detail = json.loads(e.value.body)
if detail['label'] == 'xxx':
print(detail)
label
listlabel | Meaning |
---|---|
INVALID_PARAM_VALUE | Invalid parameter value |
INVALID_PROTOCOL | Invalid parameter value |
INVALID_ARGUMENT | Invalid argument |
INVALID_REQUEST_BODY | Invalid request body |
MISSING_REQUIRED_PARAM | Missing required parameter |
BAD_REQUEST | Invalid request |
INVALID_CONTENT_TYPE | Invalid Content-Type header |
NOT_ACCEPTABLE | Invalid Accept- Header |
METHOD_NOT_ALLOWED | Request method is not allowed |
NOT_FOUND | Request URL not exists |
label | Meaning |
---|---|
INVALID_CREDENTIALS | Invalid credentials provided |
INVALID_KEY | Invalid API Key |
IP_FORBIDDEN | Request IP not in whitelist |
READ_ONLY | API key is read-only |
INVALID_SIGNATURE | Invalid signature |
MISSING_REQUIRED_HEADER | Missing required authentication header |
REQUEST_EXPIRED | Request Timestamp is far from the server time |
ACCOUNT_LOCKED | Account is locked |
FORBIDDEN | Account has no permission to request operation |
label | Meaning |
---|---|
SUB_ACCOUNT_NOT_FOUND | Sub account not found |
SUB_ACCOUNT_LOCKED | Sub account is locked |
MARGIN_BALANCE_EXCEPTION | Abnormal margin account |
MARGIN_TRANSFER_FAILED | Failed to transfer with margin account |
TOO_MUCH_FUTURES_AVAILABLE | Futures balance exceeds max allowed |
FUTURES_BALANCE_NOT_ENOUGH | Futures balance not enough |
ACCOUNT_EXCEPTION | Abnormal account |
SUB_ACCOUNT_TRANSFER_FAILED | Failed to transfer with sub account |
ADDRESS_NOT_USED | Address never being used in web console |
TOO_FAST | Withdrawing request exceeds frequency limit |
WITHDRAWAL_OVER_LIMIT | Withdrawal limit exceeded |
API_WITHDRAW_DISABLED | API withdrawal operation is disabled temporarily |
INVALID_WITHDRAW_ID | Invalid withdraw ID |
INVALID_WITHDRAW_CANCEL_STATUS | Cancelling withdrawal not allowed with current status |
DUPLICATE_REQUEST | Duplicate request |
ORDER_EXISTS | Order already exists, do not resubmit |
INVALID_CLIENT_ORDER_ID | The client_order_id is invalid |
label | Meaning |
---|---|
INVALID_PRECISION | Invalid precision |
INVALID_CURRENCY | Invalid currency |
INVALID_CURRENCY_PAIR | Invalid currency pair |
POC_FILL_IMMEDIATELY | Order would match and take immediately so it's cancelled |
ORDER_NOT_FOUND | Order not found |
ORDER_CLOSED | Order already closed |
ORDER_CANCELLED | Order already cancelled |
QUANTITY_NOT_ENOUGH | Amount is not enough |
BALANCE_NOT_ENOUGH | Balance is not enough |
MARGIN_NOT_SUPPORTED | Request currency pair doesn't provide margin trading |
MARGIN_BALANCE_NOT_ENOUGH | Margin balance is not enough |
AMOUNT_TOO_LITTLE | Amount does not reach minimum required |
AMOUNT_TOO_MUCH | Amount exceeds maximum allowed |
REPEATED_CREATION | Repeated creation |
LOAN_NOT_FOUND | Margin loan is not found |
LOAN_RECORD_NOT_FOUND | Margin loan record is not found |
NO_MATCHED_LOAN | No loan can match request borrow requirement |
NOT_MERGEABLE | Request loans cannot be merged |
NO_CHANGE | No change is made |
REPAY_TOO_MUCH | Repay more than required |
TOO_MANY_CURRENCY_PAIRS | Too many currency pairs in batch orders creation |
TOO_MANY_ORDERS | Too many orders in one currency pair in batch orders creation |
MIXED_ACCOUNT_TYPE | More than one account type is used in batch orders creation |
AUTO_BORROW_TOO_MUCH | Auto borrow exceeds maximum allowed |
TRADE_RESTRICTED | Trading is restricted due to high debt ratio |
FOK_NOT_FILL | FOK order cannot be filled completely |
INITIAL_MARGIN_TOO_LOW | User's total initial margin rate is too low |
NO_MERGEABLE_ORDERS | Orders can be merged not found |
ORDER_BOOK_NOT_FOUND | Insufficient liquidity |
FAILED_RETRIEVE_ASSETS | Failed to retrieve account assets |
CANCEL_FAIL | Order cancel failed |
label | Meaning |
---|---|
USER_NOT_FOUND | User has no futures account |
CONTRACT_NO_COUNTER | No counter order found |
CONTRACT_NOT_FOUND | Contract not found |
RISK_LIMIT_EXCEEDED | Risk limit exceeded |
INSUFFICIENT_AVAILABLE | Balance is not enough |
LIQUIDATE_IMMEDIATELY | Operation may cause liquidation |
LEVERAGE_TOO_HIGH | leverage too high |
LEVERAGE_TOO_LOW | leverage too low |
ORDER_NOT_FOUND | Order not found |
ORDER_NOT_OWNED | Order not owned |
ORDER_FINISHED | Order already finished |
TOO_MANY_ORDERS | Too many open orders |
POSITION_CROSS_MARGIN | margin updating is not allowed in cross margin |
POSITION_IN_LIQUIDATION | Position is being liquidated |
POSITION_IN_CLOSE | Position is closing |
POSITION_EMPTY | Position is empty |
REMOVE_TOO_MUCH | Changed margin exceeds allowed |
RISK_LIMIT_NOT_MULTIPLE | Risk limit is not a multiple of step |
RISK_LIMIT_TOO_HIGH | Risk limit too high |
RISK_LIMIT_TOO_lOW | Risk limit too low |
PRICE_TOO_DEVIATED | Order price deviates too much from mark price |
SIZE_TOO_LARGE | Order size exceeds maximum |
SIZE_TOO_SMALL | Order size does not reach minimum |
PRICE_OVER_LIQUIDATION | Price to increase position can not exceeds liquidation price |
PRICE_OVER_BANKRUPT | Price to decrease position cannot exceeds bankrupting price |
ORDER_POC_IMMEDIATE | POC order will be finished immediately |
INCREASE_POSITION | POC order will increase position |
CONTRACT_IN_DELISTING | Contract is delisting, only reduce-only order or close order is allowed |
POSITION_NOT_FOUND | Position not found |
POSITION_DUAL_MODE | Operation forbidden in dual-mode |
ORDER_PENDING | Operation forbidden with pending orders |
POSITION_HOLDING | Operation forbidden with holding position |
REDUCE_EXCEEDED | Reduce order would exceed position in dual-mode |
NO_CHANGE | No change is made |
AMEND_WITH_STOP | Amend forbidden with stop order |
ORDER_FOK | Killed for FOK |
label | Meaning |
---|---|
COL_NOT_ENOUGH | Collateral balance not enough |
COL_TOO_MUCH | Exceed collateral currency quota |
INIT_LTV_TOO_HIGH | Init ltv too high |
REDEEMED_LTV_TOO_HIGH | Ltv too high after redeem |
BORROWABLE_NOT_ENOUGH | Left borrowable not enough |
ORDER_TOO_MANY_TOTAL | Exceed platform order count one day |
ORDER_TOO_MANY_DAILY | Exceed single user order count one day |
ORDER_TOO_MANY_USER | Exceed single user order count total |
ORDER_NOT_EXIST | Order id not exist |
ORDER_FINISHED | Order id finished |
ORDER_NO_PAY | Order unpaid amount is zero |
ORDER_EXIST | Order exist |
ORDER_HISTORY_EXIST | Order history exist |
ORDER_REPAYING | Order is repaying |
ORDER_LIQUIDATING | Order is liquidating |
BORROW_TOO_LITTLE | Less than currency min borrow amount |
BORROW_TOO_LARGE | Greater than total max borrow amount quantity |
REPAY_AMOUNT_INVALID | Repay request amount invalid |
REPAY_GREATER_THAN_AVAILABLE | Repay greater than available |
POOL_BALANCE_NOT_ENOUGH | Pool balance not enough |
CURRENCY_SETTLING | Currency settlement in progress |
RISK_REJECT | Risk reject, please try again later |
LOAN_FAILED | Loan failed, you can borrow again |
label | Meaning |
---|---|
USER_LIAB | User has liab |
USER_PENDING_ORDERS | User has pending orders |
MODE_SET | already set portfolio_margin mode |
label | Meaning |
---|---|
ERR_BALANCE_NOT_ENOUGH | balance not enough |
ERR_PRODUCT_SELL_OUT | Target quota reached |
ERR_PRODUCT_BUY | The project is not yet open for purchase |
ERR_CREATE_ORDER | Put order fail |
ERR_QUOTA_LOWER_LIMIT | Not meeting the minimum order amount |
ERR_QUOTA_SUPERIOR_LIMIT | The maximum order limit has been reached |
ERR_ORDER_NUMBER_LIMIT | The maximum order quantity has been reached |
ERR_PRODUCT_CLOSE | Project closed |
COPIES_NOT_ENOUGH | Not enough shares available to subscribe |
COPIES_TOO_SMALL | Investment share is too small |
COPIES_TOO_BIG | The number of investment shares exceeds the upper limit |
TOTAL_AMOUNT_24 | The total amount of pledge and redemption within 24 hours exceeds the limit |
TOTAL_BUYCOUNT_24 | Pledge and redemption times exceeding the limit within 24 hours |
REDEEM_24_LIMIT | Redemption are allowed 24 hours after the last staking |
label | Meaning |
---|---|
INTERNAL | Internal server error |
SERVER_ERROR | Internal server error |
TOO_BUSY | Server is too busy at the moment |
Before calling the private API interface, the API key of the account needs to be generated to verify the identity. You can log in on the website and generate it in [account management] - > [APIv4 keys], or click here to generate API keys.
Each account can create 20 API keys, and the permission configuration of each key is independent of each other. It is recommended to set a note name for each key to indicate its purpose.
Key
Access Key
Secret Key
The key used for signature authentication encryption
Besides, you can attach an IP whitelist, which requires the server only accept requests from specified IPs. Each key can have at most 20 IPs formatted in IPv4(not supporting IP range though). If IP whitelist is not set, the server will skip client IP validation.
Each user can create at most 5 keys with separate permissions. It is recommended to set a name for key denoting how the key will be used.
TIP
Note: If the key is named with spot
or futures
, then it could be the default name after
APIv4 migration. For details refer to About APIv4 key improvement section
Created key can also be updated or deleted, but any modification(s) can take up to 5 minutes to take effect.
Please note that futures TestNet trading is a separate environment from futures real trading. Real trading API keys cannot be used in TestNet. If you want to test futures API with TestNet, you need to log into the console to generate TestNet API keys(in "Futures TestNet APIKeys" tab on " APIv4Keys" page). Making futures requests are identical between real and TestNet trading, with the only exceptions are different base URLs and different API keys.
When creating a Key, you can configure whether to enable spot, margin, contract, wallet, or withdrawal permissions for the Key, and whether to enable read-write or read-only permissions.
Products | Permissions |
---|---|
spot/margin | Read-only query orders Read-write query orders & place orders |
perpetual contract | Read-only query orders Read-write query orders & place orders |
delivery contract | Read-only query orders Read-write query orders & place orders |
wallet | Read-only Query for withdrawal transfer records Read-write Query for account records & fund transfers |
withdrawal | Read-only Query cash withdrawal records Read-write Query cash withdrawal records & withdrawals |
All GET
operations are read requests, while others are write requests. Each permission group can
be set to disabled, read-only or read-write.
Please note that even though withdrawal API has only one operation(i.e.
POST /withdrawals
), for general concern, it is still separated from wallet API into a standalone
permission group, while withdrawal history retrieving API stays inside wallet operations(
i.e., GET /wallet/withdrawals
).
KEY
to the key.Timestamp
to current time formatted in Unix time in seconds. Pay
attention that the gap between its value and current time cannot exceed 60 seconds.SIGN
to encrypted request signature. Refer to next section for how signature
string is generated. Signature generation method is
HexEncode(HMAC_SHA512(secret, signature_string))
, i.e., the hexadecimal digest output of
HMAC-SHA512 with APIv4 secret as secret and signature string as message,In APIv4, signature string is concatenated as the following way:
Request Method + "\n" + Request URL + "\n" + Query String + "\n" + HexEncode(SHA512(Request Payload)) + "\n" + Timestamp
Request method in UPPERCASE, e.g. POST
, GET
Request url. Protocol, host and port are not included, e.g. /api/v4/futures/orders
Request query string without URL encode. query parameters order should be the
same as how they are concatenated in the request URL, e.g. status=finished&limit=50
. Use empty string("") if no query parameters.
Hash the request body with SHA512 and output its Hex encoded form. If no request body, use empty string's hashed result, i.e.
cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
Timestamp
request header value.
Examples
Note: all example signature string are broken into multiple lines for displaying purpose only.
Only the \n
character in signature string is reserved in reality.
Suppose the key we used is key
, while the secret is secret
.
GET /api/v4/futures/orders?contract=BTC_USD&status=finished&limit=50 HTTP/1.1
Signature string:
GET\n
/api/v4/futures/orders\n
contract=BTC_USD&status=finished&limit=50\n
cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e\n
1541993715
Explanation:
/api/v4/futures/orders
: request urlcontract=BTC_USD&status=finished&limit=50
: keep the query string as it is in the request url1541993715
: Unix timestamp in secondsSignature generated
55f84ea195d6fe57ce62464daaa7c3c02fa9d1dde954e4c898289c9a2407a3d6fb3faf24deff16790d726b66ac9f74526668b13bd01029199cc4fcc522418b8a
POST /api/v4/futures/orders HTTP/1.1
{"contract":"BTC_USD","type":"limit","size":100,"price":6800,"time_in_force":"gtc"}
Signature string:
POST\n
/api/v4/futures/orders\n
\n
ad3c169203dc3026558f01b4df307641fa1fa361f086b2306658886d5708767b1854797c68d9e62fef2f991645aa82673622ebf417e091d0bd22bafe5d956cca\n
1541993715
Explanation:
Signature generated
eae42da914a590ddf727473aff25fc87d50b64783941061f47a3fdb92742541fc4c2c14017581b4199a1418d54471c269c03a38d788d802e2c306c37636389f0
# example authentication implementation in Python
"""
Python SDK is recommended as it has already implemented the authentication process for every API:
"""
import time
import hashlib
import hmac
import requests
import json
def gen_sign(method, url, query_string=None, payload_string=None):
key = '' # api_key
secret = '' # api_secret
t = time.time()
m = hashlib.sha512()
m.update((payload_string or "").encode('utf-8'))
hashed_payload = m.hexdigest()
s = '%s\n%s\n%s\n%s\n%s' % (method, url, query_string or "", hashed_payload, t)
sign = hmac.new(secret.encode('utf-8'), s.encode('utf-8'), hashlib.sha512).hexdigest()
return {'KEY': key, 'Timestamp': str(t), 'SIGN': sign}
if __name__ == "__main__":
host = "https://api.gateio.ws"
prefix = "/api/v4"
common_headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/orders'
body = {"contract": "BTC_USD", "size": 100, "price": "30", "tif": "gtc"}
request_content = json.dumps(body)
sign_headers = gen_sign('POST', prefix + url, "", request_content)
sign_headers.update(common_headers)
print('signature headers: %s' % sign_headers)
res = requests.post(host + prefix + url, headers=sign_headers, data=request_content)
print(res.status_code)
print(res.content)
How to retrieve POST /wallet/transfers
history?
Records of transfers generated through POST /wallet/transfers
has multiple methods to be
retrieved based on account, including:
GET /margin/account_book
to retrieve transferals from or to margin account.GET /futures/{settle}/account_book?type=dnw
to retrieve perpetual contract account historyGET /delivery/{settle}/account_book?type=dnw
to retrieve delivery contract account historyHow to create margin orders?
Margin order creation has been merged into spot order APIs. In POST /spot/orders
or
POST /spot/batch_orders
, set account
to margin
to create margin orders.
Futures operation returns error USER_NOT_FOUND
Futures account is not initialized yet. Making a deposit to your futures account will help. Note that each settle currency is associated with an independent futures account.
Futures operation returns error CONTRACT_NOT_FOUND
Every settle currency has its own contract list. Make sure the contract you specified is supported by the settle currency. You can query the list with
GET /futures/{settle}/contracts
or GET /delivery/{settle}/contracts
Difference between sub account and main account
POST /wallet/sub_account_transfers
POST /withdrawals
I have other question(s) not covered above
Contact support for the issue. If the problem is related to one of the SDKs, you can also open an issue in the corresponding GitHub repository.
When submitting an issue, please include the following information to help identify the problem:
Withdrawal operations.
POST /withdrawals
Withdraw.
Withdrawals to Gate addresses do not incur transaction fees.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» withdraw_order_id | body | string | false | User-defined order number when withdrawing. Default is empty. When not empty, the specified user-defined order number record will be queried |
» amount | body | string | true | Currency amount. |
» currency | body | string | true | Currency name. |
» address | body | string | false | Withdrawal address. Required for withdrawals. |
» memo | body | string | false | Additional remarks with regards to the withdrawal. |
» withdraw_id | body | string | false | The withdrawal record id starts with w, such as: w1879219868. When withdraw_id is not empty, the value querys this withdrawal record and no longer querys according to time |
» asset_class | body | string | false | The currency type of withdrawal record is empty by default. It supports users to query the withdrawal records in the main and innovation areas on demand. |
» chain | body | string | true | Name of the chain used in withdrawals. |
» asset_class: The currency type of withdrawal record is empty by default. It supports users to query the withdrawal records in the main and innovation areas on demand. Value range: SPOT, PILOT
SPOT: Main Zone PILOT: Innovation Zone
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Withdraw request is accepted. Refer to withdrawal records for status. | 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 when withdrawing. Default is empty. When not empty, the specified user-defined order number record will be queried |
» timestamp | string | Operation time. |
» amount | string | Currency amount. |
» currency | string | Currency name. |
» address | string | Withdrawal address. Required for withdrawals. |
» memo | string | Additional remarks with regards to the withdrawal. |
» withdraw_id | string | The withdrawal record id starts with w, such as: w1879219868. When withdraw_id is not empty, the value querys this withdrawal record and no longer querys according to time |
» asset_class | string | The currency type of withdrawal record is empty by default. It supports users to query the withdrawal records in the main and innovation areas on demand. Value range: SPOT, PILOT SPOT: Main Zone PILOT: Innovation Zone |
» status | string | Record status. - DONE: done - CANCEL: cancelled - REQUEST: requesting - MANUAL: pending manual approval - BCODE: GateCode operation - EXTPEND: pending confirm after sending - FAIL: pending confirm when fail - INVALID: invalid order - VERIFY: verifying - PROCES: processing - PEND: pending - DMOVE: required manual approval - REVIEW: Under review |
» chain | string | Name of the chain used in withdrawals. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/withdrawals'
query_param = ''
body='{"withdraw_order_id":"order_123456","currency":"USDT","address":"1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs","amount":"222.61","memo":"","chain":"TRX"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"withdraw_order_id": "order_123456",
"currency": "USDT",
"address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
"amount": "222.61",
"memo": "",
"chain": "TRX"
}
Example responses
200 Response
{
"id": "210496",
"timestamp": "1542000000",
"withdraw_order_id": "order_123456",
"currency": "USDT",
"address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
"txid": "128988928203223323290",
"amount": "222.61",
"memo": "",
"status": "DONE",
"chain": "TRX"
}
POST /withdrawals/push
UID transfer.
Transfers between main spot accounts are allowed; however, both parties cannot be sub-accounts
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» receive_uid | body | integer(int64) | true | Recipient UID. |
» currency | body | string | true | Currency name. |
» amount | body | string | true | Transfer amount. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | The request has been accepted. Check the withdrawal record status for the processing result. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» id | integer(int64) | Order ID. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/withdrawals/push'
query_param = ''
body='{"receive_uid":12233,"currency":"USDT","amount":"1.1"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"receive_uid": 12233,
"currency": "USDT",
"amount": "1.1"
}
Example responses
200 Response
{
"id": 111
}
DELETE /withdrawals/{withdrawal_id}
Cancel withdrawal with specified ID.
Name | In | Type | Required | Description |
---|---|---|---|---|
withdrawal_id | path | string | true | none |
Status | Meaning | Description | Schema |
---|---|---|---|
202 | Accepted (opens new window) | Cancellation accepted. Refer to record status for the cancellation result. | Inline |
Status Code 202
Name | Type | Description |
---|---|---|
» id | string | Record ID. |
» txid | string | Hash record of the withdrawal. |
» withdraw_order_id | string | User-defined order number when withdrawing. Default is empty. When not empty, the specified user-defined order number record will be queried |
» timestamp | string | Operation time. |
» amount | string | Currency amount. |
» currency | string | Currency name. |
» address | string | Withdrawal address. Required for withdrawals. |
» memo | string | Additional remarks with regards to the withdrawal. |
» withdraw_id | string | The withdrawal record id starts with w, such as: w1879219868. When withdraw_id is not empty, the value querys this withdrawal record and no longer querys according to time |
» asset_class | string | The currency type of withdrawal record is empty by default. It supports users to query the withdrawal records in the main and innovation areas on demand. Value range: SPOT, PILOT SPOT: Main Zone PILOT: Innovation Zone |
» status | string | Record status. - DONE: done - CANCEL: cancelled - REQUEST: requesting - MANUAL: pending manual approval - BCODE: GateCode operation - EXTPEND: pending confirm after sending - FAIL: pending confirm when fail - INVALID: invalid order - VERIFY: verifying - PROCES: processing - PEND: pending - DMOVE: required manual approval - REVIEW: Under review |
» chain | string | Name of the chain used in withdrawals. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/withdrawals/210496'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
Example responses
202 Response
{
"id": "210496",
"timestamp": "1542000000",
"withdraw_order_id": "order_123456",
"currency": "USDT",
"address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
"txid": "128988928203223323290",
"amount": "222.61",
"memo": "",
"status": "DONE",
"chain": "TRX"
}
Wallet.
GET /wallet/currency_chains
List chains supported for specified currency.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | true | Currency name. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» chain | string | Chain name. |
» name_cn | string | Chain name in Chinese. |
» name_en | string | Chain name in English. |
» contract_address | string | Smart contract address for the currency; if no address is available, it will be an empty string |
» is_disabled | integer(int32) | If it is disabled. 0 means NOT being disabled. |
» is_deposit_disabled | integer(int32) | Is deposit disabled. 0 means not. |
» is_withdraw_disabled | integer(int32) | Is withdrawal disabled. 0 means not. |
» decimal | string | Withdrawal precision. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/currency_chains'
query_param = 'currency=GT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"chain": "ETH",
"name_cn": "以太坊ERC20",
"name_en": "ETH/ERC20",
"contract_address": "",
"is_disabled": 0,
"is_deposit_disabled": 0,
"is_withdraw_disabled": 0
}
]
GET /wallet/deposit_address
Generate currency deposit address.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | true | Currency name. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Address successfully generated. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» currency | string | Currency detail. |
» address | string | Deposit address. |
» multichain_addresses | array | none |
»» MultiChainAddressItem | object | none |
»»» chain | string | Name of the chain. |
»»» address | string | Deposit address. |
»»» payment_id | string | Notes that some currencies required(e.g., Tag, Memo) when depositing. |
»»» payment_name | string | Note type, Tag or Memo . |
»»» obtain_failed | integer | The obtain failed status- 0: address successfully obtained- 1: failed to obtain address |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/deposit_address'
query_param = 'currency=USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"currency": "USDT",
"address": "LPXtk1kWHioP62SzfqwKbYE3Z7Wt2ujYEc",
"multichain_addresses": [
{
"chain": "TRX",
"address": "LPXtk1kWHioP62SzfqwKbYE3Z7Wt2ujYEc",
"payment_id": "",
"payment_name": "",
"obtain_failed": 0
}
]
}
GET /wallet/withdrawals
Retrieve withdrawal records.
Record time range cannot exceed 30 days.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Filter by currency. Return all currency records if not specified. |
withdraw_id | query | string | false | The withdrawal record id starts with w, such as: w1879219868. When withdraw_id is not empty, the value querys this withdrawal record and no longer querys according to time |
asset_class | query | string | false | The currency type of withdrawal record is empty by default. It supports users to query the withdrawal records in the main and innovation areas on demand. |
withdraw_order_id | query | string | false | User-defined order number when withdrawing. Default is empty. When not empty, the specified user-defined order number record will be queried |
from | query | integer(int64) | false | Time range beginning, default to 7 days before current time. |
to | query | integer(int64) | false | Time range ending, default to current time. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
asset_class: The currency type of withdrawal record is empty by default. It supports users to query the withdrawal records in the main and innovation areas on demand. Value range: SPOT, PILOT
SPOT: Main Zone PILOT: Innovation Zone
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» id | string | Record ID. |
» txid | string | Hash record of the withdrawal. |
» block_number | string | 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 | Currency amount. |
» fee | string | fee. |
» currency | string | Currency name. |
» address | string | Withdrawal address. |
» fail_reason | string | The reason for withdrawal failure is that there is a value when status = CANCEL, and the rest of the state is empty |
» timestamp2 | string | The withdrawal end time, i.e.: withdrawal cancel time or withdrawal success time When status = CANCEL, the corresponding cancel time When status = DONE and block_number > 0, it is the |
» memo | string | Additional remarks with regards to the withdrawal. |
» status | string | Transaction status - DONE: Completed (block_number > 0 is considered to be truly completed) - CANCEL: Canceled - REQUEST: Requesting - MANUAL: Pending manual review - BCODE: Recharge code operation - EXTPEND: Sent awaiting confirmation - FAIL: Failure on the chain awaiting confirmation - INVALID: Invalid order - VERIFY: Verifying - PROCES: Processing - PEND: Processing - DMOVE: pending manual review - REVIEW: Under review |
» chain | string | Name of the chain used in withdrawals. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/withdrawals'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
[
{
"id": "w1879219868",
"currency": "USDT",
"address": "THISISTESTADDRESSFORGATEPAY",
"amount": "4.023",
"fee": "0",
"txid": "Internal transaction 260594131",
"chain": "BSC",
"timestamp": "1745220149",
"status": "DONE",
"withdraw_order_id": "202504211521368538928",
"block_number": "1000",
"fail_reason": "",
"type": "appbankgp",
"timestamp2": "1745220149",
"memo": ""
}
]
]
GET /wallet/deposits
Retrieve deposit records.
Record time range cannot exceed 30 days.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Filter by currency. Return all currency records if not specified. |
from | query | integer(int64) | false | Time range beginning, default to 7 days before current time. |
to | query | integer(int64) | false | Time range ending, default to current time. |
limit | query | integer | false | The maximum number of entries returned in the list is limited to 500 transactions. |
offset | query | integer | false | List offset, starting from 0. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» id | string | Record ID. |
» txid | string | Hash record of the withdrawal. |
» withdraw_order_id | string | Client order id, up to 32 length and can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) |
» timestamp | string | Operation time. |
» amount | string | Currency amount. |
» currency | string | Currency name. |
» address | string | Withdrawal address. Required for withdrawals. |
» memo | string | Additional remarks with regards to the withdrawal. |
» status | string | Trading Status - REVIEW: Recharge review (compliance review) - PEND: Processing - DONE: Waiting for funds to be unlocked - INVALID: Invalid data - TRACK: Track the number of confirmations, waiting to add funds to the user (spot) - BLOCKED: Rejected Recharge - DEP_CREDITED: Recharge to account, withdrawal is not unlocked |
» chain | string | Name of the chain used in withdrawals. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/deposits'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": "210496",
"timestamp": "1542000000",
"withdraw_order_id": "order_123456",
"currency": "USDT",
"address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
"txid": "128988928203223323290",
"amount": "222.61",
"memo": "",
"status": "DONE",
"chain": "TRX"
}
]
POST /wallet/transfers
Transfer between trading accounts.
Transfer between different accounts. Currently support transfers between the following:
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» currency | body | string | true | Transfer currency. For futures account, currency can be set to POINT or settle currency |
» from | body | string | true | Account to transfer from. |
» to | body | string | true | Account to transfer to. |
» amount | body | string | true | Transfer amount. |
» currency_pair | body | string | false | Margin currency pair. Required if transfer from or to margin account. |
» settle | body | string | false | Futures settle currency. Required if transferring from or to futures account |
Parameter | Value |
---|---|
» from | spot |
» from | margin |
» from | futures |
» from | delivery |
» from | options |
» to | spot |
» to | margin |
» to | futures |
» to | delivery |
» to | options |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Balance transferred. | Inline |
Status Code 200
TransactionID
Name | Type | Description |
---|---|---|
» tx_id | integer(int64) | Order id. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/transfers'
query_param = ''
body='{"currency":"BTC","from":"spot","to":"margin","amount":"1","currency_pair":"BTC_USDT","settle":""}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"currency": "BTC",
"from": "spot",
"to": "margin",
"amount": "1",
"currency_pair": "BTC_USDT",
"settle": ""
}
Example responses
200 Response
{
"tx_id": 59636381286
}
POST /wallet/sub_account_transfers
Transfer between main and sub accounts.
Support transferring with sub user's spot or futures account. Note that only main user's spot account is used no matter which sub user's account is operated.
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 user's account. spot - spot account, futures - perpetual contract account, delivery - delivery 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 | The custom ID provided by the customer serves as a safeguard against duplicate transfers. It can be a combination of letters (case-sensitive), numbers, hyphens '-', and underscores '_', with a length ranging from 1 to 64 characters. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Balance transferred. | Inline |
Status Code 200
TransactionID
Name | Type | Description |
---|---|---|
» tx_id | integer(int64) | Order id. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/sub_account_transfers'
query_param = ''
body='{"sub_account":"10002","sub_account_type":"spot","currency":"BTC","amount":"1","direction":"to","client_order_id":"da3ce7a088c8b0372b741419c7829033"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"sub_account": "10002",
"sub_account_type": "spot",
"currency": "BTC",
"amount": "1",
"direction": "to",
"client_order_id": "da3ce7a088c8b0372b741419c7829033"
}
Example responses
200 Response
{
"tx_id": 59636381286
}
GET /wallet/sub_account_transfers
Retrieve transfer records between main and sub accounts.
Record time range cannot exceed 30 days
Note: only records after 20-04-10can be retrieved
Name | In | Type | Required | Description |
---|---|---|---|---|
sub_uid | query | string | false | User ID of sub-account, you can query multiple records separated by , . If not specified, it will return the records of all sub accounts |
from | query | integer(int64) | false | Time range beginning, default to 7 days before current time. |
to | query | integer(int64) | false | Time range ending, default to current time. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [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 user's account. spot - spot account, futures - perpetual contract account, delivery - delivery 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 | Where the operation is initiated from. |
» client_order_id | string | The custom ID provided by the customer serves as a safeguard against duplicate transfers. It can be a combination of letters (case-sensitive), numbers, hyphens '-', and underscores '_', with a length ranging from 1 to 64 characters. |
» status | string | Sub-account transfer record status, currently only success. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/sub_account_transfers'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"timest": "1592809000",
"uid": "10001",
"sub_account": "10002",
"sub_account_type": "spot",
"currency": "BTC",
"amount": "1",
"direction": "to",
"source": "web",
"client_order_id": "da3ce7a088c8b0372b741419c7829033",
"status": "success"
}
]
POST /wallet/sub_account_to_sub_account
Sub-account transfers to sub-account.
It is possible to perform balance transfers between two sub-accounts under the same main account. You can use either the API Key of the main account sub-account to initiate the transfer.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» currency | body | string | true | Transfer currency name. |
» sub_account_type | body | string | false | Transfer from the account. (deprecate, use sub_account_from_type and sub_account_to_type instead) |
» sub_account_from | body | string | true | Transfer from the user id of the sub-account. |
» sub_account_from_type | body | string | true | The sub-account's outgoing trading account, spot - spot account, futures - perpetual contract account, delivery - delivery contract account. |
» sub_account_to | body | string | true | Transfer to the user id of the sub-account. |
» sub_account_to_type | body | string | true | Transferred sub-account trading account: spot - spot account, futures - perpetual contract account, delivery - delivery contract account |
» amount | body | string | true | Transfer amount. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Balance transferred. | Inline |
Status Code 200
TransactionID
Name | Type | Description |
---|---|---|
» tx_id | integer(int64) | Order id. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/sub_account_to_sub_account'
query_param = ''
body='{"currency":"usdt","sub_account_from":"10001","sub_account_from_type":"spot","sub_account_to":"10002","sub_account_to_type":"spot","amount":"1"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"currency": "usdt",
"sub_account_from": "10001",
"sub_account_from_type": "spot",
"sub_account_to": "10002",
"sub_account_to_type": "spot",
"amount": "1"
}
Example responses
200 Response
{
"tx_id": 59636381286
}
GET /wallet/order_status
Transfer status query.
Support 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 | The custom ID provided by the customer serves as a safeguard against duplicate transfers. It can be a combination of letters (case-sensitive), numbers, hyphens '-', and underscores '_', with a length ranging from 1 to 64 characters. |
tx_id | query | string | false | The transfer operation number and client_order_id cannot be empty at the same time |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Transfer status obtained successfully. | Inline |
Status Code 200
TransferOrderStatus
Name | Type | Description |
---|---|---|
» tx_id | string | Order id. |
» status | string | Transfer status, PENDING - in process, SUCCESS - successful transfer, FAIL - failed transfer, PARTIAL_SUCCESS - Partially successful (this status will appear when transferring between sub-subs) |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/order_status'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"tx_id": "59636381286",
"status": "SUCCESS"
}
GET /wallet/withdraw_status
Retrieve withdrawal status.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Retrieve data of the specified currency. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» currency | string | Currency. |
» name | string | Currency name. |
» name_cn | string | Currency Chinese name. |
» deposit | string | Deposits fee. |
» withdraw_percent | string | Withdrawal fee rate percentage. |
» withdraw_fix | string | Fixed withdrawal fee. |
» withdraw_day_limit | string | Daily allowed withdrawal amount. |
» withdraw_amount_mini | string | Minimum withdrawal amount. |
» withdraw_day_limit_remain | string | Daily withdrawal amount left. |
» withdraw_eachtime_limit | string | Maximum amount for each withdrawal. |
» withdraw_fix_on_chains | object | Fixed withdrawal fee on multiple chains. |
»» additionalProperties | string | none |
» withdraw_percent_on_chains | object | Percentage withdrawal fee on multiple chains. |
»» additionalProperties | string | none |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/withdraw_status'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "GT",
"name": "GateToken",
"name_cn": "GateToken",
"deposit": "0",
"withdraw_percent": "0%",
"withdraw_fix": "0.01",
"withdraw_day_limit": "20000",
"withdraw_day_limit_remain": "20000",
"withdraw_amount_mini": "0.11",
"withdraw_eachtime_limit": "20000",
"withdraw_fix_on_chains": {
"BTC": "20",
"ETH": "15",
"TRX": "0",
"EOS": "2.5"
},
"withdraw_percent_on_chains": {
"ETH": "0%",
"GTEVM": "0%"
}
}
]
GET /wallet/sub_account_balances
Retrieve sub account balances.
Name | In | Type | Required | Description |
---|---|---|---|---|
sub_uid | query | string | false | User ID of sub-account, you can query multiple records separated by , . If not specified, it will return the records of all sub accounts |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» uid | string | User ID. |
» available | object | Available balances of currencies. |
»» additionalProperties | string | none |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/sub_account_balances'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"uid": "10003",
"available": {
"BTC": "0.1",
"GT": "2000",
"USDT": "10"
}
}
]
GET /wallet/sub_account_margin_balances
Query sub accounts' margin balances.
Name | In | Type | Required | Description |
---|---|---|---|---|
sub_uid | query | string | false | User ID of sub-account, you can query multiple records separated by , . If not specified, it will return the records of all sub accounts |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» uid | string | User ID. |
» available | array | Margin account balances. |
»» None | object | Margin account detail. base refers to base currency, while `quotes to quote currency |
»»» currency_pair | string | Currency pair. |
»»» account_type | string | Account type, risk - risk rate account, mmr - maintenance margin market not activated |
»»» leverage | string | User current market leverage multiple. |
»»» locked | boolean | Whether account is locked. |
»»» risk | string | Leveraged Account Current Risk Rate (Returned when the Account is a Risk Rate Account) |
»»» mmr | string | Leveraged Account Current Maintenance Margin Rate (returned when the Account is Account) |
»»» base | object | 货币账户信息 |
»»»» currency | string | 货币名称 |
»»»» available | string | 可用于杠杆交易的额度, available = 保证金 + borrowed |
»»»» locked | string | 冻结资金, 如已经放在杠杆市场里挂单交易的数额 |
»»»» borrowed | string | 借入资金 |
»»»» interest | string | 未还利息 |
»»» quote | object | 货币账户信息 |
»»»» currency | string | 货币名称 |
»»»» available | string | 可用于杠杆交易的额度, available = 保证金 + borrowed |
»»»» locked | string | 冻结资金, 如已经放在杠杆市场里挂单交易的数额 |
»»»» borrowed | string | 借入资金 |
»»»» interest | string | 未还利息 |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/sub_account_margin_balances'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"uid": "10000",
"available": [
{
"locked": false,
"currency_pair": "BTC_USDT",
"risk": "9999.99",
"base": {
"available": "0.1",
"borrowed": "0",
"interest": "0",
"currency": "BTC",
"locked": "0"
},
"quote": {
"available": "0",
"borrowed": "0",
"interest": "0",
"currency": "USDT",
"locked": "0"
}
}
]
}
]
GET /wallet/sub_account_futures_balances
Query sub accounts' futures account balances.
Name | In | Type | Required | Description |
---|---|---|---|---|
sub_uid | query | string | false | User ID of sub-account, you can query multiple records separated by , . If not specified, it will return the records of all sub accounts |
settle | query | string | false | Query only balances of specified settle currency. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» uid | string | User ID. |
» available | object | Futures account balances. |
»» additionalProperties | object | none |
»»» total | string | total is the balance after the user's accumulated deposit, withdraw, profit and loss (including realized profit and loss, fund, fee and referral rebate), excluding unrealized profit and loss. total = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund) |
»»» unrealised_pnl | string | Unrealized PNL. |
»»» position_margin | string | Position margin. |
»»» order_margin | string | Order margin of unfinished orders. |
»»» available | string | The available balance for transferring or trading(including bonus. Bonus can't be withdrawn. The transfer amount needs to deduct the bonus) |
»»» point | string | POINT amount. |
»»» currency | string | Settle currency. |
»»» in_dual_mode | boolean | Whether dual mode is enabled. |
»»» enable_credit | boolean | Whether portfolio margin account mode is enabled. |
»»» position_initial_margin | string | Initial margin position, applicable to the portfolio margin account model. |
»»» maintenance_margin | string | The maintenance deposit occupied by the position is suitable for the new classic account margin model and unified account model |
»»» bonus | string | Perpetual Contract Bonus. |
»»» enable_evolved_classic | boolean | Classic account margin mode, true-new mode, false-old mode. |
»»» cross_order_margin | string | Full -warehouse hanging order deposit, suitable for the new classic account margin model |
»»» cross_initial_margin | string | The initial security deposit of the full warehouse is suitable for the new classic account margin model |
»»» cross_maintenance_margin | string | Maintain deposit in full warehouse, suitable for new classic account margin models |
»»» cross_unrealised_pnl | string | The full warehouse does not achieve profit and loss, suitable for the new classic account margin model |
»»» cross_available | string | Full warehouse available amount, suitable for the new classic account margin model |
»»» cross_margin_balance | string | Full margin balance, suitable for the new classic account margin model. |
»»» cross_mmr | string | Maintain margin ratio for the full position, suitable for the new classic account margin model |
»»» cross_imr | string | The initial margin rate of the full position is suitable for the new classic account margin model |
»»» isolated_position_margin | string | Ware -position margin, suitable for the new classic account margin model. |
»»» enable_new_dual_mode | boolean | Whether to open a new two-way position mode. |
»»» margin_mode | integer | Margin mode, 0-classic margin mode, 1-cross-currency margin mode, 2-combined margin mode |
»»» enable_tiered_mm | boolean | Whether to enable tiered maintenance margin calculation. |
»»» position_voucher_total | string | Total Position Experience Coupon Amount in Account. |
»»» history | object | Statistical data. |
»»»» dnw | string | total amount of deposit and withdraw. |
»»»» pnl | string | total amount of trading profit and loss. |
»»»» fee | string | total amount of fee. |
»»»» refr | string | total amount of referrer rebates. |
»»»» fund | string | total amount of funding costs. |
»»»» point_dnw | string | total amount of point deposit and withdraw. |
»»»» point_fee | string | total amount of point fee. |
»»»» point_refr | string | total amount of referrer rebates of point fee. |
»»»» bonus_dnw | string | total amount of perpetual contract bonus transfer. |
»»»» bonus_offset | string | total amount of perpetual contract bonus deduction. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/sub_account_futures_balances'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
[
{
"available": {
"btc": {
"available": "0.0009",
"bonus": "0",
"cross_available": "0.0009",
"cross_initial_margin": "0",
"cross_maintenance_margin": "0",
"cross_order_margin": "0",
"cross_unrealised_pnl": "0",
"currency": "BTC",
"enable_credit": false,
"enable_evolved_classic": true,
"enable_new_dual_mode": false,
"history": {
"bonus_dnw": "0",
"bonus_offset": "0",
"cross_settle": "0",
"dnw": "0.0009",
"fee": "0",
"fund": "0",
"pnl": "0",
"point_dnw": "0",
"point_fee": "0",
"point_refr": "0",
"refr": "0"
},
"in_dual_mode": false,
"isolated_position_margin": "0",
"maintenance_margin": "0",
"margin_mode": 0,
"margin_mode_name": "classic",
"order_margin": "0",
"point": "0",
"position_initial_margin": "0",
"position_margin": "0",
"total": "0.0009",
"unrealised_pnl": "0",
"update_id": 11,
"update_time": 1741766400,
"user": 10003
},
"usd": {},
"usdt": {
"available": "500.7",
"bonus": "0",
"cross_available": "500.7",
"cross_initial_margin": "0",
"cross_maintenance_margin": "0",
"cross_order_margin": "0",
"cross_unrealised_pnl": "0",
"currency": "USDT",
"enable_credit": true,
"enable_evolved_classic": true,
"enable_new_dual_mode": true,
"history": {
"bonus_dnw": "0",
"bonus_offset": "0",
"cross_settle": "-1.854650083",
"dnw": "1.89047097",
"fee": "-0.141010882",
"fund": "0",
"pnl": "0.10519",
"point_dnw": "0",
"point_fee": "0",
"point_refr": "0",
"refr": "0"
},
"in_dual_mode": true,
"isolated_position_margin": "0",
"maintenance_margin": "0",
"margin_mode": 1,
"margin_mode_name": "multi_currency",
"order_margin": "0",
"point": "0",
"position_initial_margin": "0",
"position_margin": "0",
"total": "0.000000005",
"unrealised_pnl": "0",
"update_id": 37,
"update_time": 1741766400,
"user": 10003
}
},
"uid": "10003"
}
]
]
GET /wallet/sub_account_cross_margin_balances
Query subaccount's cross_margin account info.
Name | In | Type | Required | Description |
---|---|---|---|---|
sub_uid | query | string | false | User ID of sub-account, you can query multiple records separated by , . If not specified, it will return the records of all sub accounts |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» uid | string | User ID. |
» available | object | none |
»» user_id | integer(int64) | 全仓帐户用户ID, 如果 0 代表这个子帐号尚未开通全仓帐户 |
»» locked | boolean | 账户是否被锁定 |
»» balances | object | none |
»»» CrossMarginBalance | object | none |
»»»» available | string | 可用额度 |
»»»» freeze | string | 被锁定的额度 |
»»»» borrowed | string | 借入额度 |
»»»» interest | string | 未还利息 |
»»» total | string | 折算成 USDT 的账户总资产, 即所有币种(不包括点卡)的 (available+freeze)*price*discount 之和 |
»»» borrowed | string | 折算成 USDT 的账户总借入数量, 即所有币种(不包括点卡)的 borrowed*price*discount 之和 |
»»» borrowed_net | string | 折算成 USDT 的账户总借入数量 * 放大系数 |
»»» net | string | 折算成 USDT 的净资产 |
»»» leverage | string | Leverage multiplier |
»»» interest | string | 折算成 USDT 的账户未接利息的总和, 即所有币种(不包括点卡)的 interest*price*discount 之和 |
»»» risk | string | 风险率, 风险率小于 110% 会被爆仓, 计算方式 total / (borrowed+interest) |
»»» total_initial_margin | string | 总初始保证金 |
»»» total_margin_balance | string | 总保证金余额 |
»»» total_maintenance_margin | string | 总维持保证金 |
»»» total_initial_margin_rate | string | 总初始保证金率 |
»»» total_maintenance_margin_rate | string | 总维持保证金率 |
»»» total_available_margin | string | 可用的保证金额度 |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/sub_account_cross_margin_balances'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"uid": "100000",
"available": {
"user_id": 100003,
"locked": false,
"total": "20.000000",
"borrowed": "0.000000",
"interest": "0",
"borrowed_net": "0",
"net": "20",
"leverage": "3",
"risk": "9999.99",
"total_initial_margin": "0.00",
"total_margin_balance": "20.00",
"total_maintenance_margin": "0.00",
"total_initial_margin_rate": "9999.9900",
"total_maintenance_margin_rate": "9999.9900",
"total_available_margin": "20.00",
"balances": {
"USDT": {
"available": "20.000000",
"freeze": "0.000000",
"borrowed": "0.000000",
"interest": "0.000000"
}
}
}
}
]
GET /wallet/saved_address
Query saved address.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | true | Currency. |
chain | query | string | false | Chain name. |
limit | query | string | false | Maximum number returned, 100 at most. |
page | query | integer | false | Page number |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» currency | string | Currency. |
» chain | string | Chain name. |
» address | string | Address. |
» name | string | Name. |
» tag | string | Tag. |
» verified | string | Whether to pass the verification 0-unverified, 1-verified. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/saved_address'
query_param = 'currency=USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "usdt",
"chain": "TRX",
"address": "TWYirLzw2RARB2jfeFcfRPmeuU3rC7rakT",
"name": "gate",
"tag": "",
"verified": "1"
}
]
GET /wallet/fee
Retrieve personal trading fee.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency_pair | query | string | false | Specify a currency pair to retrieve precise fee rate |
settle | query | string | false | Specify the settlement currency of the contract to get more accurate rate settings |
currency_pair: Specify a currency pair to retrieve precise fee rate
This field is optional. In most cases, the fee rate is identical among all currency pairs
settle: Specify the settlement currency of the contract to get more accurate rate settings
This field is optional. Generally, the rate settings for all settlement currencies are the same.
Parameter | Value |
---|---|
settle | BTC |
settle | USDT |
settle | USD |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» user_id | integer(int64) | User ID. |
» taker_fee | string | taker fee rate. |
» maker_fee | string | maker fee rate. |
» gt_discount | boolean | If GT deduction is enabled. |
» gt_taker_fee | string | Taker fee rate if using GT deduction. It will be 0 if GT deduction is disabled |
» gt_maker_fee | string | Maker fee rate if using GT deduction. It will be 0 if GT deduction is disabled |
» loan_fee | string | Loan fee rate of margin lending. |
» point_type | string | Point type. 0 - Initial version. 1 - new version since 202009. |
» futures_taker_fee | string | Futures trading taker fee. |
» futures_maker_fee | string | Future trading maker fee. |
» delivery_taker_fee | string | Delivery trading taker fee. |
» delivery_maker_fee | string | Delivery trading maker fee. |
» debit_fee | integer | Deduction types for rates, 1 - GT deduction, 2 - Point card deduction, 3 - VIP rates |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/fee'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"user_id": 10001,
"taker_fee": "0.002",
"maker_fee": "0.002",
"futures_taker_fee": "-0.00025",
"futures_maker_fee": "0.00075",
"gt_discount": false,
"gt_taker_fee": "0",
"gt_maker_fee": "0",
"loan_fee": "0.18",
"point_type": "1",
"delivery_taker_fee": "0.00016",
"delivery_maker_fee": "-0.00015",
"debit_fee": 3
}
GET /wallet/total_balance
Retrieve user's total balances.
This endpoint returns an approximate sum of exchanged amount from all currencies to input currency for each account.The exchange rate and account balance could have been cached for at most 1 minute. It is not recommended to use its result for any trading calculation.
For trading calculation, use the corresponding account query endpoint for each account type. For example:
GET /spot/accounts
to query spot account balanceGET /margin/accounts
/futures/{settle}/accounts` to query futures account balanceName | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Currency unit used to calculate the balance amount. BTC, CNY, USD and USDT are allowed. USDT is the default. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Request is valid and is successfully responded. | Inline |
Status Code 200
User's balance in all accounts.
Name | Type | Description |
---|---|---|
» total | object | 换算成目标币种的账户总额 |
»» amount | string | 账户总额数字 |
»» currency | string | 币种 |
»» unrealised_pnl | string | 未实现盈亏总和,这个 field只会在futures,options,delivery,total 账户中出现 |
»» borrowed | string | 杠杆借贷总和,这个 field只会在margin,cross_margin账户中出现 |
» details | object | Total balances in different accounts - cross_margin: cross margin account - spot: spot account - finance: finance account - margin: margin account - quant: quant account - futures: futures account - delivery: delivery account - warrant: warrant account - cbbc: cbbc account |
»» additionalProperties | object | 换算成目标币种的账户总额 |
»»» amount | string | 账户总额数字 |
»»» currency | string | 币种 |
»»» unrealised_pnl | string | 未实现盈亏总和,这个 field只会在futures,options,delivery,total 账户中出现 |
»»» borrowed | string | 杠杆借贷总和,这个 field只会在margin,cross_margin账户中出现 |
Property | Value |
---|---|
currency | BTC |
currency | CNY |
currency | USD |
currency | USDT |
currency | BTC |
currency | CNY |
currency | USD |
currency | USDT |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/total_balance'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"details": {
"cross_margin": {
"amount": "0",
"currency": "USDT"
},
"spot": {
"currency": "USDT",
"amount": "42264489969935775.5160259954878034182418"
},
"finance": {
"amount": "662714381.70310327810191647181",
"currency": "USDT"
},
"margin": {
"amount": "1259175.664137668554329559",
"currency": "USDT",
"borrowed": "0.00"
},
"quant": {
"amount": "591702859674467879.6488202650892478553852",
"currency": "USDT"
},
"futures": {
"amount": "2384175.5606114082065",
"currency": "USDT",
"unrealised_pnl": "0.00"
},
"delivery": {
"currency": "USDT",
"amount": "1519804.9756702",
"unrealised_pnl": "0.00"
},
"warrant": {
"amount": "0",
"currency": "USDT"
},
"cbbc": {
"currency": "USDT",
"amount": "0"
}
},
"total": {
"currency": "USDT",
"amount": "633967350312281193.068368815439797304437",
"unrealised_pnl": "0.00",
"borrowed": "0.00"
}
}
GET /wallet/small_balance
List small balance.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Success. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Convert Small Balance. |
»» currency | string | Currency. |
»» available_balance | string | Available balance. |
»» estimated_as_btc | string | Estimated as BTC. |
»» convertible_to_gt | string | Estimated conversion to GT. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/small_balance'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
[
{
"currency": "FLOKI",
"available_balance": "182.29400000",
"estimated_as_btc": "0.00000012",
"convertible_to_gt": "0.001080"
},
{
"currency": "MBLK",
"available_balance": "0.91723337",
"estimated_as_btc": "0.00000102",
"convertible_to_gt": "0.009188"
}
]
]
POST /wallet/small_balance
Convert small balance.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» currency | body | array | false | Currency. |
» is_all | body | boolean | false | Whether to exchange all. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Success. | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/small_balance'
query_param = ''
body='{"currency":["FLOKI","MBLK"],"is_all":true}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"currency": [
"FLOKI",
"MBLK"
],
"is_all": true
}
GET /wallet/small_balance_history
List small balance history.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Currency. |
page | query | integer(int32) | false | Page number. |
limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Success. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Convert Small Balance. |
»» id | string | Order ID. |
»» currency | string | Currency. |
»» amount | string | amount. |
»» gt_amount | string | GT amount. |
»» create_time | integer(int64) | Exchange time (in seconds). |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/small_balance_history'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
[
{
"id": "28583810",
"create_time": 1706670777,
"currency": "FLOKI",
"amount": "182.29400000",
"gt_amount": "0.001079"
}
]
]
GET /wallet/push
Retrieve the UID transfer history.
Name | In | Type | Required | Description |
---|---|---|---|---|
id | query | integer(int32) | false | Order ID. |
from | query | integer(int32) | false | The start time of the query record. If not specified, it defaults to 7 days forward from the current time, in seconds Unix timestamp |
to | query | integer(int32) | false | The end time of the query record. If not specified, the default is the current time, which is a Unix timestamp in seconds. |
limit | query | integer(int32) | false | The maximum number of items returned in the list, the default value is 100. |
offset | query | integer(int32) | false | List offset, starting from 0. |
transaction_type | query | string | false | The list returns the order type withdraw , deposit , the default is withdraw . |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Success. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» id | integer(int64) | Order ID. |
» push_uid | integer(int64) | Initiator User ID. |
» receive_uid | integer(int64) | Recipient User ID. |
» currency | string | Currency name. |
» amount | string | Transfer amount. |
» create_time | integer(int64) | Creation time. |
» status | string | Withdrawal Status - CREATING: Creating - PENDING: Waiting for receiving(Please contact the other party to accept the transfer on the Gate official website) - CANCELLING: Cancelling - CANCELLED: Revoked - REFUSING: Rejection - REFUSED: Rejected - RECEIVING: Receiving - RECEIVED: Success |
» message | string | PENDING Reason Tips. |
» transaction_type | string | Order Type. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/push'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 111,
"push_uid": 1132,
"receive_uid": 12324,
"currency": "BTC",
"amount": "1.2",
"status": "PENDING",
"create_time": 1706670777,
"message": "The other party has not completed KYC,There is a security risk in your account, please contact customer service",
"transaction_type": "withdraw"
}
]
Sub-accounts management.
POST /sub_accounts
Create a new sub-account.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» remark | body | string | false | custom text. |
» login_name | body | string | true | Sub-account login name: Only letters, numbers and underscores are supported, and cannot contain other illegal characters |
» password | body | string | false | The sub-account's password. (Default: the same as main account's password). |
body | string | false | The sub-account's email address. (Default: the same as main account's email address) |
Status | Meaning | Description | Schema |
---|---|---|---|
201 | Created (opens new window) | Created Successfully. | Inline |
Status Code 201
Name | Type | Description |
---|---|---|
» remark | string | custom text. |
» login_name | string | Sub-account login name: Only letters, numbers and underscores are supported, and cannot contain other illegal characters |
» password | string | The sub-account's password. (Default: the same as main account's password). |
string | The sub-account's email address. (Default: the same as main account's email address) | |
» state | integer(int32) | State: 1-normal, 2-locked". |
» type | integer(int32) | "Sub-account type: 1 - sub-account, 3 - cross margin account. |
» user_id | integer(int64) | The user id of the sub-account. |
» create_time | integer(int64) | Created time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts'
query_param = ''
body='{"remark":"remark","login_name":"sub_account_for_trades"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"remark": "remark",
"login_name": "sub_account_for_trades"
}
Example responses
201 Response
{
"remark": "remark",
"login_name": "sub_account_for_trades",
"user_id": 10001,
"state": 1,
"create_time": 168888888
}
GET /sub_accounts
List sub-accounts.
Name | In | Type | Required | Description |
---|---|---|---|---|
type | query | string | false | 0 to list all types of sub-accounts (currently supporting cross margin accounts and sub-accounts). |
type: 0
to list all types of sub-accounts (currently supporting cross margin accounts and sub-accounts).
1
to list sub-accounts only. If no parameter is passed, only sub-accounts will be listed by default.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» remark | string | custom text. |
» login_name | string | Sub-account login name: Only letters, numbers and underscores are supported, and cannot contain other illegal characters |
» password | string | The sub-account's password. (Default: the same as main account's password). |
string | The sub-account's email address. (Default: the same as main account's email address) | |
» state | integer(int32) | State: 1-normal, 2-locked". |
» type | integer(int32) | "Sub-account type: 1 - sub-account, 3 - cross margin account. |
» user_id | integer(int64) | The user id of the sub-account. |
» create_time | integer(int64) | Created time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"remark": "remark",
"login_name": "sub_account_for_trades",
"user_id": 10001,
"state": 1,
"create_time": 168888888
}
]
GET /sub_accounts/{user_id}
Get the sub-account.
Name | In | Type | Required | Description |
---|---|---|---|---|
user_id | path | integer(int64) | true | Sub-account user id. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successful. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» remark | string | custom text. |
» login_name | string | Sub-account login name: Only letters, numbers and underscores are supported, and cannot contain other illegal characters |
» password | string | The sub-account's password. (Default: the same as main account's password). |
string | The sub-account's email address. (Default: the same as main account's email address) | |
» state | integer(int32) | State: 1-normal, 2-locked". |
» type | integer(int32) | "Sub-account type: 1 - sub-account, 3 - cross margin account. |
» user_id | integer(int64) | The user id of the sub-account. |
» create_time | integer(int64) | Created time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts/0'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"remark": "remark",
"login_name": "sub_account_for_trades",
"user_id": 10001,
"state": 1,
"create_time": 168888888
}
POST /sub_accounts/{user_id}/keys
Create API Key of the sub-account.
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 white list (list will be removed if no value is passed). |
»» name: Permission function name (no value will be cleared)
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Created Successfully. | SubAccountKey |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts/0/keys'
query_param = ''
body='{"mode":1,"name":"spot","perms":[{"read_only":false,"name":"options"},{"read_only":false,"name":"spot"},{"read_only":false,"name":"delivery"},{"read_only":false,"name":"wallet"},{"read_only":false,"name":"futures"}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"mode": 1,
"name": "spot",
"perms": [
{
"read_only": false,
"name": "options"
},
{
"read_only": false,
"name": "spot"
},
{
"read_only": false,
"name": "delivery"
},
{
"read_only": false,
"name": "wallet"
},
{
"read_only": false,
"name": "futures"
}
],
"ip_whitelist": [
"127.0.0.1",
"127.0.0.2"
]
}
Example responses
200 Response
{
"state": 1,
"name": "spot",
"user_id": 100000,
"perms": [
{
"name": "options",
"read_only": false
},
{
"name": "spot",
"read_only": false
},
{
"name": "delivery",
"read_only": false
},
{
"name": "wallet",
"read_only": false
},
{
"name": "futures",
"read_only": false
}
],
"ip_whitelist": [
"127.0.0.1",
"127.0.0.2"
],
"mode": 1,
"secret": "cddcc6e5e78060e013860bdbe5e737830b96821c027664586fb38b411808f4fd",
"key": "eb8815bf99d7bb5f8ad6497bdc4774a8",
"created_at": 1663683330,
"updated_at": 1663683330
}
GET /sub_accounts/{user_id}/keys
List all API Key of the sub-account.
Name | In | Type | Required | Description |
---|---|---|---|---|
user_id | path | integer | true | Sub-account user id. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [SubAccountKey] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts/0/keys'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"state": 1,
"name": "spot",
"user_id": 1000000,
"perms": [
{
"name": "futures",
"read_only": false
},
{
"name": "wallet",
"read_only": false
},
{
"name": "delivery",
"read_only": false
},
{
"name": "options",
"read_only": false
},
{
"name": "spot",
"read_only": false
}
],
"mode": 1,
"ip_whitelist": [
"127.0.0.1",
"127.0.0.2"
],
"key": "75c3264105b74693d8cb5c7f1a8e2420",
"created_at": 1663642892,
"last_access": 1663642892,
"update_at": 1663642892
}
]
PUT /sub_accounts/{user_id}/keys/{key}
Update API key of the sub-account.
Name | In | Type | Required | Description |
---|---|---|---|---|
user_id | path | integer | true | Sub-account user id. |
key | path | string | true | The API Key of the sub-account. |
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 white list (list will be removed 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. | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts/0/keys/string'
query_param = ''
body='{"mode":1,"name":"spot","perms":[{"read_only":false,"name":"options"},{"read_only":false,"name":"spot"},{"read_only":false,"name":"delivery"},{"read_only":false,"name":"wallet"},{"read_only":false,"name":"futures"}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PUT', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"mode": 1,
"name": "spot",
"perms": [
{
"read_only": false,
"name": "options"
},
{
"read_only": false,
"name": "spot"
},
{
"read_only": false,
"name": "delivery"
},
{
"read_only": false,
"name": "wallet"
},
{
"read_only": false,
"name": "futures"
}
],
"ip_whitelist": [
"127.0.0.1",
"127.0.0.2"
]
}
DELETE /sub_accounts/{user_id}/keys/{key}
Delete API key of the sub-account.
Name | In | Type | Required | Description |
---|---|---|---|---|
user_id | path | integer | true | Sub-account user id. |
key | path | string | true | The API Key of the sub-account. |
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content (opens new window) | Delete successfully. | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts/0/keys/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
GET /sub_accounts/{user_id}/keys/{key}
Get the API Key of the sub-account.
Name | In | Type | Required | Description |
---|---|---|---|---|
user_id | path | integer | true | Sub-account user id. |
key | path | string | true | The API Key of the sub-account. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successful. | SubAccountKey |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts/0/keys/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"state": 1,
"name": "spot",
"user_id": 1000000,
"perms": [
{
"name": "futures",
"read_only": false
},
{
"name": "wallet",
"read_only": false
},
{
"name": "delivery",
"read_only": false
},
{
"name": "options",
"read_only": false
},
{
"name": "spot",
"read_only": false
}
],
"mode": 1,
"ip_whitelist": [
"127.0.0.1",
"127.0.0.2"
],
"key": "75c3264105b74693d8cb5c7f1a8e2420",
"created_at": 1663642892,
"last_access": 1663642892,
"update_at": 1663642892
}
POST /sub_accounts/{user_id}/lock
Lock the sub-account.
Name | In | Type | Required | Description |
---|---|---|---|---|
user_id | path | integer(int64) | true | The user id of the sub-account. |
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content (opens new window) | Lock successfully. | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts/0/lock'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers)
print(r.json())
POST /sub_accounts/{user_id}/unlock
Unlock the sub-account.
Name | In | Type | Required | Description |
---|---|---|---|---|
user_id | path | integer(int64) | true | The user id of the sub-account. |
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content (opens new window) | Unlock successfully. | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts/0/unlock'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers)
print(r.json())
GET /sub_accounts/unified_mode
Get sub-account mode.
Unified account mode:
classic
: Classic account modemulti_currency
: Multi-currency margin modeportfolio
: Portfolio margin modeStatus | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» user_id | integer(int64) | User ID. |
» is_unified | boolean | Is it a unified account?. |
» mode | string | Unified account mode: - classic : Classic account mode- multi_currency : Multi-currency margin mode- portfolio : Portfolio margin mode |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts/unified_mode'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"user_id": 110285555,
"is_unified": true,
"mode": "multi_currency"
}
]
Unified account.
GET /unified/accounts
Get unified account information.
The assets of each currency in the account will be adjusted according to their liquidity, defined by corresponding adjustment coefficients, and then uniformly converted to USD to calculate the total asset value and position value of the account.
You can refer to the Formula in the documentation
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Retrieve data of the specified currency. |
sub_uid | query | string | false | Sub account user ID. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» user_id | integer(int64) | User ID. |
» refresh_time | integer(int64) | Time of the most recent refresh. |
» locked | boolean | Whether 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 amount is valid in single currency margin/cross-currency margin/combined margin mode, and the calculation is different in different modes |
»»» freeze | string | The locked amount is valid in single currency margin/cross-currency margin/combined margin mode |
»»» borrowed | string | Borrow limit, valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
»»» negative_liab | string | Negative balance loan is valid in cross-currency margin/combined margin mode, and is 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 occupancy (discarded, to be offline field). |
»»» total_liab | string | Total borrowing, valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
»»» spot_in_use | string | The amount of spot hedging is valid in the combined margin mode, and is 0 in other margin modes such as single currency and cross-currency margin modes |
»»» funding | string | Uniloan financial management amount, effective when turned on as a unified account margin switch |
»»» funding_version | string | Funding version. |
»»» cross_balance | string | Full margin balance is valid in single currency margin mode, and is 0 in other modes such as cross currency margin/combined margin mode |
»»» iso_balance | string | Isolated margin balance is valid in single-currency margin mode and is 0 in other modes such as cross-currency margin/combined margin mode |
»»» im | string | Full-position initial margin is valid in single-currency margin mode and is 0 in other modes such as cross-currency margin/combined margin mode |
»»» mm | string | The full position maintains margin, which is valid in the single currency margin mode, and other cross-currency margin combination margin mode is 0. |
»»» 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 | Full margin available for full position is valid in single currency margin mode, and is 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 deprecated, replaced by unified_account_total) |
»» borrowed | string | The total borrowed amount of the account converted into USD, i.e. the sum of borrowed * price of all currencies (excluding Point Cards). It is valid in cross-currency margin/combined margin mode, and is 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 | Unify the total account assets, valid in single currency margin/cross-currency margin/combined margin mode |
»» unified_account_total_liab | string | Unify the total loan of the account, valid in the cross-currency margin/combined margin mode, and 0 in other modes such as single-currency margin mode |
»» unified_account_total_equity | string | Unify the total account equity, valid in single currency margin/cross-currency margin/combined margin mode |
»» leverage | string | Actual leverage, valid in cross-currency margin/combined margin mode. |
»» spot_order_loss | string | Total pending order loss, in USDT, valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
»» spot_hedge | boolean | Spot hedging status, true - enabled, false - not enabled. |
»» use_funding | boolean | Whether to use funds as margin. |
»» is_all_collateral | boolean | Whether all currencies are used as margin, true - false - No |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"user_id": 10001,
"locked": false,
"balances": {
"ETH": {
"available": "0",
"freeze": "0",
"borrowed": "0.075393666654",
"negative_liab": "0",
"futures_pos_liab": "0",
"equity": "1016.1",
"total_freeze": "0",
"total_liab": "0",
"spot_in_use": "1.111"
},
"POINT": {
"available": "9999999999.017023138734",
"freeze": "0",
"borrowed": "0",
"negative_liab": "0",
"futures_pos_liab": "0",
"equity": "12016.1",
"total_freeze": "0",
"total_liab": "0",
"spot_in_use": "12"
},
"USDT": {
"available": "0.00000062023",
"freeze": "0",
"borrowed": "0",
"negative_liab": "0",
"futures_pos_liab": "0",
"equity": "16.1",
"total_freeze": "0",
"total_liab": "0",
"spot_in_use": "12"
}
},
"total": "230.94621713",
"borrowed": "161.66395521",
"total_initial_margin": "1025.0524665088",
"total_margin_balance": "3382495.944473949183",
"total_maintenance_margin": "205.01049330176",
"total_initial_margin_rate": "3299.827135672679",
"total_maintenance_margin_rate": "16499.135678363399",
"total_available_margin": "3381470.892007440383",
"unified_account_total": "3381470.892007440383",
"unified_account_total_liab": "0",
"unified_account_total_equity": "100016.1",
"leverage": "2",
"spot_order_loss": "12",
"spot_hedge": false
}
GET /unified/borrowable
Query about the maximum borrowing for the unified account.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | true | Retrieve data of the specified currency. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
UnifiedBorrowable
Name | Type | Description |
---|---|---|
» currency | string | Currency detail. |
» amount | string | Max borrowable amount. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/borrowable'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"currency": "ETH",
"amount": "10000"
}
GET /unified/transferable
Query about the maximum transferable for the unified account.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | true | Retrieve data of the specified currency. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
UnifiedTransferable
Name | Type | Description |
---|---|---|
» currency | string | Currency detail. |
» amount | string | The maximum amount that can be transferred out. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/transferable'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"currency": "ETH",
"amount": "10000"
}
GET /unified/transferables
Batch query can be transferred out at most for unified accounts; each currency is the maximum value. After the user withdraws the currency, the amount of transferable currency will be changed.
Name | In | Type | Required | Description |
---|---|---|---|---|
currencies | query | string | true | Specify the currency name to query in batches, and support up to 100 pass parameters at a time. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» TransferablesResult | object | Batch query unified account can be transferred up to a maximum of results. |
»» currency | string | Currency detail. |
»» amount | string | The maximum amount that can be transferred out. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/transferables'
query_param = 'currencies=BTC,ETH'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "BTC",
"amount": "123456"
}
]
GET /unified/batch_borrowable
Batch query unified account can be borrowed up to a maximum.
Name | In | Type | Required | Description |
---|---|---|---|---|
currencies | query | array[string] | true | Specify the currency names for querying in an array, separated by commas, with a maximum of 10 currencies. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» UnifiedBorrowable | object | Batch query unified account can be borrowed up to a maximum of results. |
»» currency | string | Currency detail. |
»» amount | string | The maximum amount to borrow. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/batch_borrowable'
query_param = 'currencies=BTC,GT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "BTC",
"amount": "123456"
}
]
POST /unified/loans
Borrow or repay.
When borrowing, it is essential to ensure that the borrowed amount is not below the minimum borrowing threshold for the specific cryptocurrency and does not exceed the maximum borrowing limit set by the platform and the user.
The interest on the loan will be automatically deducted from the account at regular intervals. It is the user's responsibility to manage the repayment of the borrowed amount.
For repayment, the option to repay the available by setting the parameter repaid_all=true
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» currency | body | string | true | Currency. |
» type | body | string | true | type: borrow - borrow, repay - repay. |
» amount | body | string | true | The amount of lending or repaying. |
» repaid_all | body | boolean | false | Full repayment is solely for repayment operations. When set to 'true,' it overrides the 'amount,' allowing for direct full repayment. |
» text | body | string | false | User defined custom ID. |
Parameter | Value |
---|---|
» type | borrow |
» type | repay |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Operated successfully. | Inline |
Status Code 200
Unified account loan and repayment response results.
Name | Type | Description |
---|---|---|
» tran_id | integer(int64) | Transaction id. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/loans'
query_param = ''
body='{"currency":"BTC","amount":"0.1","type":"borrow","repaid_all":false,"text":"t-test"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"currency": "BTC",
"amount": "0.1",
"type": "borrow",
"repaid_all": false,
"text": "t-test"
}
Example responses
200 Response
{
"tran_id": 9527
}
GET /unified/loans
List loans.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Retrieve data of the specified currency. |
page | query | integer(int32) | false | Page number. |
limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100. |
type | query | string | false | Loan type, platform - platform, margin - margin. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Loan.] |
» None | object | Loan. |
»» currency | string | Currency. |
»» currency_pair | string | Currency pair. |
»» amount | string | amount. |
»» type | string | Loan type, platform - platform, margin - margin. |
»» create_time | integer(int64) | Created time. |
»» update_time | integer(int64) | Updated time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/loans'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "USDT",
"currency_pari": "GT_USDT",
"amount": "1",
"type": "margin",
"change_time": 1673247054000,
"create_time": 1673247054000
}
]
GET /unified/loan_records
Get load records.
Name | In | Type | Required | Description |
---|---|---|---|---|
type | query | string | false | The types of lending records, borrow - indicates the action of borrowing funds, repaying the borrowed funds |
currency | query | string | false | Retrieve data of the specified currency. |
page | query | integer(int32) | false | Page number. |
limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Loan records. |
»» id | integer(int64) | id |
»» type | string | type: borrow - borrow, repay - repay. |
»» repayment_type | string | Repayment type, none - No repayment type, manual_repay - Manual repayment, auto_repay - Automatic repayment after withdrawal, different_currencies_repayment - Different currency repayment |
»» borrow_type | string | Loan type, returned when querying loan records. manual_borrow - Manual repayment , auto_borrow - Automatic repayment |
»» currency_pair | string | Currency pair. |
»» currency | string | Currency. |
»» amount | string | The amount of lending or repaying. |
»» create_time | integer(int64) | Created time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/loan_records'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 16442,
"type": "borrow",
"margin_mode": "cross",
"currency_pair": "AE_USDT",
"currency": "USDT",
"amount": "1000",
"create_time": 1673247054000,
"repayment_type": "auto_repay"
}
]
GET /unified/interest_records
List interest records.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Retrieve data of the specified currency. |
page | query | integer(int32) | false | Page number. |
limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100. |
from | query | integer(int64) | false | Start timestamp of the query. |
to | query | integer(int64) | false | Time range ending, default to current time. |
type | query | string | false | Loan type, platform loan - platform, leverage loan - margin, if not passed, defaults to margin |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Interest record.] |
» None | object | Interest record. |
»» currency | string | Currency name. |
»» currency_pair | string | Currency pair. |
»» actual_rate | string | Actual rate. |
»» interest | string | Interest. |
»» status | integer | Status: 0 - fail, 1 - success. |
»» type | string | Type, platform - platform, margin - margin. |
»» create_time | integer(int64) | Created time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/interest_records'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"status": 1,
"currency_pair": "BTC_USDT",
"currency": "USDT",
"actual_rate": "0.00000236",
"interest": "0.00006136",
"type": "platform",
"create_time": 1673247054000
}
]
GET /unified/risk_units
Get user risk unit details.
Retrieve user risk unit details, only valid in portfolio margin mode.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» user_id | integer(int64) | User ID. |
» spot_hedge | boolean | Spot hedging status, true - enabled, false - not enabled. |
» risk_units | array | Risk unit. |
»» RiskUnits | object | none |
»»» symbol | string | Risk unit flag. |
»»» spot_in_use | string | Spot hedging utilization. |
»»» maintain_margin | string | Maintenance margin for risk unit. |
»»» initial_margin | string | Initial margin for risk unit. |
»»» delta | string | Total Delta of risk unit. |
»»» gamma | string | Total Gamma of risk unit. |
»»» theta | string | Total Theta of risk unit. |
»»» vega | string | Total Vega of risk unit. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/risk_units'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"user_id": 0,
"spot_hedge": true,
"risk_units": [
{
"symbol": "BTC",
"spot_in_use": "-13500.000001223",
"maintain_margin": "2334.002",
"initial_margin": "2334.002",
"delta": "0.22",
"gamma": "0.42",
"theta": "0.29",
"vega": "0.22"
}
]
}
PUT /unified/unified_mode
Set mode of the unified account.
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 contract switch. In cross-currency margin mode, it can only be turned on and not off |
»» spot_hedge | body | boolean | false | Spot hedging switch. |
»» use_funding | body | boolean | false | switch, when the mode is cross-currency margin mode, whether to use Uniloan financial funds as margin |
»» options | body | boolean | false | Option switch. In cross-currency margin mode, it can only be turned on and not off |
» mode: Unified account mode:
classic
: Classic account modemulti_currency
: Multi-currency margin modeportfolio
: Portfolio margin modesingle_currency
: Single Currency Margin ModelStatus | Meaning | Description | Schema |
---|---|---|---|
204 | No Content (opens new window) | Success. | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/unified_mode'
query_param = ''
body='{"mode":"portfolio","settings":{"spot_hedge":true,"usdt_futures":true,"options":true}}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PUT', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
print(r.json())
GET /unified/unified_mode
Query mode of the unified account.
Unified account mode:
classic
: Classic account modemulti_currency
: Cross-currency margin modeportfolio
: Portfolio margin modesingle_currency
: Single-currency margin modeStatus | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» mode | string | Unified account mode: - classic : Classic account mode- multi_currency : Multi-currency margin mode- portfolio : Portfolio margin mode- single_currency : Single Currency Margin Model |
» settings | object | none |
»» usdt_futures | boolean | USDT contract switch. In cross-currency margin mode, it can only be turned on and not off |
»» spot_hedge | boolean | Spot hedging switch. |
»» use_funding | boolean | switch, when the mode is cross-currency margin mode, whether to use Uniloan financial funds as margin |
»» options | boolean | Option switch. In cross-currency margin mode, it can only be turned on and not off |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/unified_mode'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"mode": "portfolio",
"settings": {
"spot_hedge": true,
"usdt_futures": true,
"options": true
}
}
GET /unified/estimate_rate
Get unified estimate rate.
Due to fluctuations in lending depth, hourly interest rates may vary, and thus, I cannot provide exact rates. When a currency is not supported, the interest rate returned will be an empty string.
Name | In | Type | Required | Description |
---|---|---|---|---|
currencies | query | array[string] | true | Specify the currency names for querying in an array, separated by commas, with a maximum of 10 currencies. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Estimate the current hourly lending rates, categorized by currency.
Name | Type | Description |
---|---|---|
» additionalProperties | string | none |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/estimate_rate'
query_param = 'currencies=BTC,GT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"BTC": "0.000002",
"GT": "0.000001",
"ETH": ""
}
GET /unified/currency_discount_tiers
List currency discount tiers.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Currency discount tiers. |
»» currency | string | Currency name. |
»» discount_tiers | array | Tiered discount. |
»»» tier | string | 档位 |
»»» discount | string | 保证金折扣系数 |
»»» lower_limit | string | 下限 |
»»» upper_limit | string | 上限, +表示正无穷 |
»»» leverage | string | Leverage multiplier |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/currency_discount_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
[
{
"currency": "USDT",
"discount_tiers": [
{
"tier": "1",
"discount": "1",
"lower_limit": "0",
"leverage": "10",
"upper_limit": "+"
}
]
},
{
"currency": "USDC",
"discount_tiers": [
{
"tier": "1",
"discount": "1",
"lower_limit": "0",
"leverage": "10",
"upper_limit": "10000000"
},
{
"tier": "2",
"discount": "0.98",
"lower_limit": "10000000",
"leverage": "10",
"upper_limit": "15000000"
},
{
"tier": "3",
"discount": "0.95",
"lower_limit": "15000000",
"leverage": "10",
"upper_limit": "20000000"
},
{
"tier": "4",
"discount": "0.925",
"lower_limit": "20000000",
"leverage": "10",
"upper_limit": "50000000"
},
{
"tier": "5",
"discount": "0.9",
"lower_limit": "50000000",
"leverage": "10",
"upper_limit": "100000000"
},
{
"tier": "6",
"discount": "0",
"lower_limit": "100000000",
"leverage": "10",
"upper_limit": "+"
}
]
},
{
"currency": "BTC",
"discount_tiers": [
{
"tier": "1",
"discount": "0.98",
"lower_limit": "0",
"leverage": "10",
"upper_limit": "1000"
},
{
"tier": "2",
"discount": "0.95",
"lower_limit": "1000",
"leverage": "10",
"upper_limit": "10000"
},
{
"tier": "3",
"discount": "0.9",
"lower_limit": "10000",
"leverage": "10",
"upper_limit": "50000"
},
{
"tier": "4",
"discount": "0.85",
"lower_limit": "50000",
"leverage": "10",
"upper_limit": "+"
}
]
},
{
"currency": "ETH",
"discount_tiers": [
{
"tier": "1",
"discount": "0.98",
"lower_limit": "0",
"leverage": "10",
"upper_limit": "1000"
},
{
"tier": "2",
"discount": "0.95",
"lower_limit": "1000",
"leverage": "10",
"upper_limit": "10000"
},
{
"tier": "3",
"discount": "0.9",
"lower_limit": "10000",
"leverage": "10",
"upper_limit": "50000"
},
{
"tier": "4",
"discount": "0.85",
"lower_limit": "50000",
"leverage": "10",
"upper_limit": "+"
}
]
}
]
]
GET /unified/loan_margin_tiers
List loan margin tiers.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Unified margin tiers. |
»» currency | string | Currency name. |
»» margin_tiers | array | Margin tiers. |
»»» MarginTiers | object | none |
»»»» tier | string | Tier. |
»»»» margin_rate | string | Discount. |
»»»» lower_limit | string | Lower limit. |
»»»» upper_limit | string | Upper limit, "" indicates greater than (the last tier). |
»»»» leverage | string | Position leverage. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/loan_margin_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "USDT",
"margin_tiers": [
{
"tier": "1",
"margin_rate": "0.02",
"lower_limit": "200000",
"upper_limit": "400000",
"leverage": "3"
}
]
}
]
POST /unified/portfolio_calculator
Portfolio margin calculator.
Portfolio Margin Calculator When inputting a simulated position portfolio, each position includes the position name and quantity held, supporting markets within the range of BTC and ETH perpetual contracts, options, and spot markets. When inputting simulated orders, each order includes the market identifier, order price, and order of BTC and ETH perpetual contracts, options, and spot markets. Market orders are not included.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» spot_balances | body | array | false | Spot. |
»» None | body | object | false | 现货 |
»»» currency | body | string | true | 币种名称 |
»»» equity | body | string | true | 币种权益, 权益 = 余额 - 已借, 表示您在现货部位的净delta敞口, 可以为负数. 目前仅支持BTC、ETH三个币种 |
»» spot_orders | body | array | false | Spot orders. |
»»» None | body | object | false | 现货订单 |
»»»» currency_pairs | body | string | true | 市场 |
»»»» order_price | body | string | true | 价格 |
»»»» count | body | string | false | 现货交易对初始挂单数量, 不参与实际计算. 目前仅支持BTC、ETH三个币种 |
»»»» left | body | string | true | 未成交数量, 参与实际计算 |
»»»» type | body | string | true | 订单Type, sell - 卖出单, buy - 买入单 |
»»» futures_positions | body | array | false | Futures positions. |
»»»» None | body | object | false | 合约仓位 |
»»»»» contract | body | string | true | 合约名, 目前仅支持BTC、ETH的USDT永续合约 |
»»»»» size | body | string | true | 仓位大小, 单位是张数 |
»»»» futures_orders | body | array | false | Futures order. |
»»»»» None | body | object | false | 合约订单 |
»»»»»» contract | body | string | true | 合约名, 目前仅支持BTC、ETH的USDT永续合约 |
»»»»»» size | body | string | true | 合约张数, 为初始挂单数量, 不参与实际结算 |
»»»»»» left | body | string | true | 未成交张数, 参与实际计算 |
»»»»» options_positions | body | array | false | Options positions. |
»»»»»» None | body | object | false | 期权仓位 |
»»»»»»» options_name | body | string | true | 期权名称, 目前只支持BTC、ETH的USDT期权 |
»»»»»»» size | body | string | true | 仓位大小, 单位是张数 |
»»»»»» options_orders | body | array | false | Option orders. |
»»»»»»» None | body | object | false | 期权订单 |
»»»»»»»» options_name | body | string | true | 期权名称, 目前只支持BTC、ETH的USDT期权 |
»»»»»»»» size | body | string | true | 初始挂单张数, 不参与实际计算 |
»»»»»»»» left | body | string | true | 未成交张数, 参与实际计算 |
»»»»»»» spot_hedge | body | boolean | false | Whether to enable spot hedging. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
The output of the portfolio margin calculator.
Name | Type | Description |
---|---|---|
» maintain_margin_total | string | Total maintenance margin, including only the portfolio margin calculation results for positions in the risk unit, excluding borrowed margin. If borrowing exists, conventional borrowing margin requirements will still apply. |
» initial_margin_total | string | Total initial margin, calculated as the maximum of the following three combinations: position, position + positive delta orders, orders. |
» calculate_time | integer(int64) | Calculate time. |
» risk_unit | array | Risk unit. |
»» None | object | 风险单元 |
»»» symbol | string | 风险单元名称 |
»»» spot_in_use | string | 现货对冲使用量 |
»»» maintain_margin | string | 维持保证金 |
»»» initial_margin | string | 起始保证金 |
»»» margin_result | array | 保证金结果 |
»»»» None | object | 保证金结果 |
»»»»» type | string | 仓位组合Typeoriginal_position - 原始仓位long_delta_original_position - 正向delta+原始仓位short_delta_original_position - 负向delta+原始仓位 |
»»»»» profit_loss_ranges | array | mr1的33个压力场景测试结果 |
»»»»»» None | object | 盈亏范围 |
»»»»»»» price_percentage | string | 价格变动百分比 |
»»»»»»» implied_volatility_percentage | string | 隐含波动率变动百分比 |
»»»»»»» profit_loss | string | 盈亏 |
»»»»»» max_loss | object | 盈亏范围 |
»»»»»»» price_percentage | string | 价格变动百分比 |
»»»»»»» implied_volatility_percentage | string | 隐含波动率变动百分比 |
»»»»»»» profit_loss | string | 盈亏 |
»»»»»» mr1 | string | 压力测试 |
»»»»»» mr2 | string | 基差跨期风险 |
»»»»»» mr3 | string | 波动率跨期风险 |
»»»»»» mr4 | string | 期权空头风险 |
»»»»» delta | string | 风险单元的 总 delta |
»»»»» gamma | string | 风险单元的 总 gamma |
»»»»» theta | string | 风险单元的 总 theta |
»»»»» vega | string | 风险单元的 总 vega |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/portfolio_calculator'
query_param = ''
body='{"spot_balances":[{"currency":"BTC","equity":"-1","freeze":"10"}],"spot_orders":[{"currency_pairs":"BTC_USDT","order_price":"344","size":"100","left":"100","type":"sell"}],"futures_positions":[{"contract":"BTC_USDT","size":"100"}],"futures_orders":[{"contract":"BTC_USDT","size":"10","left":"8"}],"options_positions":[{"options_name":"BTC_USDT-20240329-32000-C","size":"10"}],"options_orders":[{"options_name":"BTC_USDT-20240329-32000-C","size":"100","left":"80"}],"spot_hedge":false}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"spot_balances": [
{
"currency": "BTC",
"equity": "-1",
"freeze": "10"
}
],
"spot_orders": [
{
"currency_pairs": "BTC_USDT",
"order_price": "344",
"size": "100",
"left": "100",
"type": "sell"
}
],
"futures_positions": [
{
"contract": "BTC_USDT",
"size": "100"
}
],
"futures_orders": [
{
"contract": "BTC_USDT",
"size": "10",
"left": "8"
}
],
"options_positions": [
{
"options_name": "BTC_USDT-20240329-32000-C",
"size": "10"
}
],
"options_orders": [
{
"options_name": "BTC_USDT-20240329-32000-C",
"size": "100",
"left": "80"
}
],
"spot_hedge": false
}
Example responses
200 Response
{
"maintain_margin_total": "0.000000000000",
"initial_margin_total": "0.000000000000",
"calculate_time": "1709014486",
"risk_unit": [
{
"symbol": "BTC",
"margin_result": [
{
"type": "original_position",
"profit_loss_ranges": [
{
"price_percentage": "-0.200000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "-0.160000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "-0.120000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "-0.080000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "-0.040000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.000000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.040000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.080000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.120000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.160000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.200000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
}
],
"max_loss": {
"price_percentage": "-0.200000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
"mr1": "0.000000000000",
"mr2": "0.000000000000",
"mr3": "0.000000000000",
"mr4": "0.000000000000"
}
],
"maintain_margin": "0.000000000000",
"initial_margin": "0.000000000000"
}
]
}
GET /unified/leverage/user_currency_config
Minimum currency leverage that can be set.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | true | Currency. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» current_leverage | string | Current leverage ratio. |
» min_leverage | string | Minimum adjustable leverage ratio. |
» max_leverage | string | Maximum adjustable leverage ratio. |
» debit | string | Current liabilities. |
» available_margin | string | Available Margin. |
» borrowable | string | The current leverage you can choose is. |
» except_leverage_borrowable | string | The maximum amount of margin that can be borrowed and the be borrowed, whichever is smaller |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/leverage/user_currency_config'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"current_leverage": "2",
"min_leverage": "0",
"max_leverage": "0",
"debit": "0",
"available_margin": "0",
"borrowable": "0",
"except_leverage_borrowable": "0"
}
GET /unified/leverage/user_currency_setting
Get the leverage multiple of the user currency.
Get the user's currency leverage. If currency is not passed, query all currencies.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Currency. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Loan currency leverage.
Name | Type | Description |
---|---|---|
» currency | string | Currency name. |
» leverage | string | multiple. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/leverage/user_currency_setting'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"currency": "BTC",
"leverage": "3"
}
POST /unified/leverage/user_currency_setting
Set the loan currency leverage.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» currency | body | string | true | Currency name. |
» leverage | body | string | true | multiple. |
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content (opens new window) | Success. | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/leverage/user_currency_setting'
query_param = ''
body='{"currency":"BTC","leverage":"3"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"currency": "BTC",
"leverage": "3"
}
GET /unified/currencies
List of loan currencies supported by unified account.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Currency. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» name | string | Currency name. |
» prec | string | Currency precision. |
» min_borrow_amount | string | The minimum debit limit is the unit of currency. |
» user_max_borrow_amount | string | The minimum debit limit is the unit of currency. |
» total_max_borrow_amount | string | The maximum debit limit for the platform is USDT. |
» loan_status | string | Does the lending status - disable : Loans are prohibited- enable : Support lending |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"name": "BTC",
"prec": "0.000001",
"min_borrow_amount": "0.01",
"user_max_borrow_amount": "1000000",
"total_max_borrow_amount": "1000000",
"loan_status": "enable"
}
]
GET /unified/history_loan_rate
get historical lending rates.
Name | In | Type | Required | Description |
---|---|---|---|---|
tier | query | string | false | The VIP level of the floating rate that needs to be queried. |
currency | query | string | true | Currency. |
page | query | integer(int32) | false | Page number. |
limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» currency | string | Currency name. |
» tier | string | The VIP level of the floating rate required. |
» tier_up_rate | string | VIP level corresponding floating rate. |
» rates | array | Historical interest rate information, one data per hour, the array size is determined by the page and limit parameters provided by the interface request parameters, sorted from recent to far in time |
»» time | integer(int64) | The hourly timestamp corresponding to the interest rate, in milliseconds. |
»» rate | string | Historical interest rates for this hour. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/history_loan_rate'
query_param = 'currency=USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"currency": "USDT",
"tier": "1",
"tier_up_rate": "1.18",
"rates": [
{
"time": 1729047616000,
"rate": "0.00010287"
}
]
}
POST /unified/collateral_currencies
Set Collateral Currency.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» collateral_type | body | integer | false | User-set collateral mode0(all)-All currencies used as collateral, collateral; when collateral_type is 0(all), the enable_list and disable_list parameters are invalid |
» enable_list | body | array | false | Currency list, where collateral_type=1(custom) indicates the logic of addition |
» disable_list | body | array | false | Cancellation list, indicating the logic of cancellation. |
Parameter | Value |
---|---|
» collateral_type | 0 |
» collateral_type | 1 |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | UpdateSuccess. | Inline |
Status Code 200
Return of unified account collateral mode settings.
Name | Type | Description |
---|---|---|
» is_success | boolean | Whether the setting was successful. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/collateral_currencies'
query_param = ''
body='{"collateral_type":1,"enable_list":["BTC","ETH"],"disable_list":["SOL","GT"]}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"collateral_type": 1,
"enable_list": [
"BTC",
"ETH"
],
"disable_list": [
"SOL",
"GT"
]
}
Example responses
200 Response
{
"is_success": true
}
Margin.
GET /margin/accounts
Margin account list.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency_pair | query | string | false | Currency pair. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Margin account detail. base refers to base currency, while `quotes to quote currency] |
» None | object | Margin account detail. base refers to base currency, while `quotes to quote currency |
»» currency_pair | string | Currency pair. |
»» account_type | string | Account type, risk - risk rate account, mmr - maintenance margin market not activated |
»» leverage | string | User current market leverage multiple. |
»» locked | boolean | Whether account is locked. |
»» risk | string | Leveraged Account Current Risk Rate (Returned when the Account is a Risk Rate Account) |
»» mmr | string | Leveraged Account Current Maintenance Margin Rate (returned when the Account is Account) |
»» base | object | 货币账户信息 |
»»» currency | string | 货币名称 |
»»» available | string | 可用于杠杆交易的额度, available = 保证金 + borrowed |
»»» locked | string | 冻结资金, 如已经放在杠杆市场里挂单交易的数额 |
»»» borrowed | string | 借入资金 |
»»» interest | string | 未还利息 |
»» quote | object | 货币账户信息 |
»»» currency | string | 货币名称 |
»»» available | string | 可用于杠杆交易的额度, available = 保证金 + borrowed |
»»» locked | string | 冻结资金, 如已经放在杠杆市场里挂单交易的数额 |
»»» borrowed | string | 借入资金 |
»»» interest | string | 未还利息 |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency_pair": "BTC_USDT",
"account_type": "mmr",
"leverage": "20",
"locked": false,
"risk": "1.3318",
"mmr": "16.5949188975473644",
"base": {
"currency": "BTC",
"available": "0.047060413211",
"locked": "0",
"borrowed": "0.047233",
"interest": "0"
},
"quote": {
"currency": "USDT",
"available": "1234",
"locked": "0",
"borrowed": "0",
"interest": "0"
}
}
]
GET /margin/account_book
List margin account balance change history.
Only transferals from and to margin account are provided for now. Time range allows 30 days at most
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | List records related to specified currency only. If specified, currency_pair is also required. |
currency_pair | query | string | false | List records related to specified currency pair. Used in combination with currency . Ignored if currency is not provided |
type | query | string | false | Only retrieve changes of the specified type. All types will be returned if not specified. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
page | query | integer(int32) | false | Page number. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» id | string | Balance change record ID. |
» time | string | Balance changed timestamp. |
» time_ms | integer(int64) | The timestamp of the change (in milliseconds). |
» currency | string | Currency changed. |
» currency_pair | string | Account currency pair. |
» change | string | Amount changed. Positive value means transferring in, while negative out. |
» balance | string | Balance after change. |
» type | string | Account book type. Please refer to account book type for more detail |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": "123456",
"time": "1547633726",
"time_ms": 1547633726123,
"currency": "BTC",
"currency_pair": "BTC_USDT",
"change": "1.03",
"balance": "4.59316525194"
}
]
GET /margin/funding_accounts
Funding account list.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Retrieve data of the specified currency. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» currency | string | Currency name. |
» available | string | Available assets to lend, which is identical to spot account available . |
» locked | string | Locked amount. i.e. amount in open loans. |
» lent | string | Outstanding loan amount yet to be repaid. |
» total_lent | string | Amount used for lending. total_lent = lent + locked. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/funding_accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "BTC",
"available": "1.238",
"locked": "0",
"lent": "3.32",
"total_lent": "3.32"
}
]
POST /margin/auto_repay
Update user's auto repayment setting.
Name | In | Type | Required | Description |
---|---|---|---|---|
status | query | string | true | New auto repayment status. on - enabled, off - disabled. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Current auto repayment setting. | Inline |
Status Code 200
AutoRepaySetting
Name | Type | Description |
---|---|---|
» status | string | Auto repayment status. on - enabled, off - disabled. |
Property | Value |
---|---|
status | on |
status | off |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/auto_repay'
query_param = 'status=on'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"status": "on"
}
GET /margin/auto_repay
Retrieve user auto repayment setting.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Current auto repayment setting. | Inline |
Status Code 200
AutoRepaySetting
Name | Type | Description |
---|---|---|
» status | string | Auto repayment status. on - enabled, off - disabled. |
Property | Value |
---|---|
status | on |
status | off |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/auto_repay'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"status": "on"
}
GET /margin/transferable
Get the max transferable amount for a specific margin currency.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | true | Retrieve data of the specified currency. |
currency_pair | query | string | false | Currency pair. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
MarginTransferable
Name | Type | Description |
---|---|---|
» currency | string | Currency detail. |
» currency_pair | string | Currency pair. |
» amount | string | Max transferable amount. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/transferable'
query_param = 'currency=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"currency": "ETH",
"currency_pair": "ETH_USDT",
"amount": "10000"
}
GET /margin/uni/currency_pairs
List lending markets.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Currency pair of the loan.] |
» None | object | Currency pair of the loan. |
»» currency_pair | string | Currency pair. |
»» base_min_borrow_amount | string | Minimum borrow amount of base currency. |
»» quote_min_borrow_amount | string | Minimum borrow amount of quote currency. |
»» leverage | string | Position leverage. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/uni/currency_pairs'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency_pair": "AE_USDT",
"base_min_borrow_amount": "100",
"quote_min_borrow_amount": "100",
"leverage": "3"
}
]
GET /margin/uni/currency_pairs/{currency_pair}
Get detail of lending market.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency_pair | path | string | true | Currency pair. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Currency pair of the loan.
Name | Type | Description |
---|---|---|
» currency_pair | string | Currency pair. |
» base_min_borrow_amount | string | Minimum borrow amount of base currency. |
» quote_min_borrow_amount | string | Minimum borrow amount of quote currency. |
» leverage | string | Position leverage. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/uni/currency_pairs/AE_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"currency_pair": "AE_USDT",
"base_min_borrow_amount": "100",
"quote_min_borrow_amount": "100",
"leverage": "3"
}
GET /margin/uni/estimate_rate
Estimate interest Rate.
Please note that the interest rates are subject to change based on the borrowing and lending demand, and therefore, the provided rates may not be entirely accurate.
Name | In | Type | Required | Description |
---|---|---|---|---|
currencies | query | array[string] | true | An array of up to 10 specifying the currency name. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Estimate the current hourly lending rates, categorized by currency.
Name | Type | Description |
---|---|---|
» additionalProperties | string | none |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/uni/estimate_rate'
query_param = 'currencies=BTC,GT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"BTC": "0.000002",
"GT": "0.000001"
}
POST /margin/uni/loans
Borrow or repay.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» currency | body | string | true | Currency. |
» type | body | string | true | type: borrow - borrow, repay - repay. |
» amount | body | string | true | The amount of lending or repaying. |
» repaid_all | body | boolean | false | Full repayment. Repay operation only. If the value is true , the amount will be ignored and repaid in full. |
» currency_pair | body | string | true | Currency pair. |
Parameter | Value |
---|---|
» type | borrow |
» type | repay |
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content (opens new window) | Operated successfully. | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/uni/loans'
query_param = ''
body='{"currency":"BTC","amount":"0.1","type":"borrow","currency_pair":"BTC_USDT","repaid_all":false}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"currency": "BTC",
"amount": "0.1",
"type": "borrow",
"currency_pair": "BTC_USDT",
"repaid_all": false
}
GET /margin/uni/loans
List loans.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency_pair | query | string | false | Currency pair. |
currency | query | string | false | Retrieve data of the specified currency. |
page | query | integer(int32) | false | Page number. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Loan.] |
» None | object | Loan. |
»» currency | string | Currency. |
»» currency_pair | string | Currency pair. |
»» amount | string | amount. |
»» type | string | Loan type, platform - platform, margin - margin. |
»» create_time | integer(int64) | Created time. |
»» update_time | integer(int64) | Updated time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/uni/loans'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "USDT",
"currency_pari": "GT_USDT",
"amount": "1",
"type": "margin",
"change_time": 1673247054000,
"create_time": 1673247054000
}
]
GET /margin/uni/loan_records
Get load records.
Name | In | Type | Required | Description |
---|---|---|---|---|
type | query | string | false | type: borrow - borrow, repay - repay. |
currency | query | string | false | Retrieve data of the specified currency. |
currency_pair | query | string | false | Currency pair. |
page | query | integer(int32) | false | Page number. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
Parameter | Value |
---|---|
type | borrow |
type | repay |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Loan records. |
»» type | string | type: borrow - borrow, repay - repay. |
»» currency_pair | string | Currency pair. |
»» currency | string | Currency. |
»» amount | string | The amount of lending or repaying. |
»» create_time | integer(int64) | Created time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/uni/loan_records'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"type": "borrow",
"currency_pair": "AE_USDT",
"currency": "USDT",
"amount": "1000",
"create_time": 1673247054000
}
]
GET /margin/uni/interest_records
List interest records.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency_pair | query | string | false | Currency pair. |
currency | query | string | false | Retrieve data of the specified currency. |
page | query | integer(int32) | false | Page number. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Interest record.] |
» None | object | Interest record. |
»» currency | string | Currency name. |
»» currency_pair | string | Currency pair. |
»» actual_rate | string | Actual rate. |
»» interest | string | Interest. |
»» status | integer | Status: 0 - fail, 1 - success. |
»» type | string | Type, platform - platform, margin - margin. |
»» create_time | integer(int64) | Created time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/uni/interest_records'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"status": 1,
"currency_pair": "BTC_USDT",
"currency": "USDT",
"actual_rate": "0.00000236",
"interest": "0.00006136",
"type": "platform",
"create_time": 1673247054000
}
]
GET /margin/uni/borrowable
Get maximum borrowable.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | true | Retrieve data of the specified currency. |
currency_pair | query | string | true | Currency pair. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
MaxUniBorrowable
Name | Type | Description |
---|---|---|
» currency | string | Currency. |
» currency_pair | string | Currency pair. |
» borrowable | string | Maximum borrowable. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/uni/borrowable'
query_param = 'currency=BTC¤cy_pair=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"currency": "AE",
"borrowable": "1123.344",
"currency_pair": "AE_USDT"
}
GET /margin/user/loan_margin_tiers
Check the user's own leverage lending gradient in the current market.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency_pair | query | string | true | Currency pair. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Market gradient information.] |
» None | object | Market gradient information. |
»» upper_limit | string | Maximum loan limit. |
»» mmr | string | Maintenance margin rate. |
»» leverage | string | Maximum leverage multiple. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/user/loan_margin_tiers'
query_param = 'currency_pair=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"tier_amount": "100",
"mmr": "0.9",
"leverage": "1"
}
]
GET /margin/loan_margin_tiers
Query the current market leverage lending gradient.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency_pair | query | string | true | Currency pair. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Market gradient information.] |
» None | object | Market gradient information. |
»» upper_limit | string | Maximum loan limit. |
»» mmr | string | Maintenance margin rate. |
»» leverage | string | Maximum leverage multiple. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/loan_margin_tiers'
query_param = 'currency_pair=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"tier_amount": "100",
"mmr": "0.9",
"leverage": "1"
}
]
POST /margin/leverage/user_market_setting
Set the user market leverage multiple.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» currency_pair | body | string | false | Currency pair. |
» leverage | body | string | true | Position leverage. |
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content (opens new window) | Success. | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/leverage/user_market_setting'
query_param = ''
body='{"currency_pair":"BTC_USDT","leverage":"10"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"currency_pair": "BTC_USDT",
"leverage": "10"
}
GET /margin/user/account
Query the user's leverage account list.
Support querying risk rate per position account and margin rate per position account
Name | In | Type | Required | Description |
---|---|---|---|---|
currency_pair | query | string | false | Currency pair. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Margin account detail. base refers to base currency, while `quotes to quote currency] |
» None | object | Margin account detail. base refers to base currency, while `quotes to quote currency |
»» currency_pair | string | Currency pair. |
»» account_type | string | Account type, risk - risk rate account, mmr - maintenance margin market not activated |
»» leverage | string | User current market leverage multiple. |
»» locked | boolean | Whether account is locked. |
»» risk | string | Leveraged Account Current Risk Rate (Returned when the Account is a Risk Rate Account) |
»» mmr | string | Leveraged Account Current Maintenance Margin Rate (returned when the Account is Account) |
»» base | object | 货币账户信息 |
»»» currency | string | 货币名称 |
»»» available | string | 可用于杠杆交易的额度, available = 保证金 + borrowed |
»»» locked | string | 冻结资金, 如已经放在杠杆市场里挂单交易的数额 |
»»» borrowed | string | 借入资金 |
»»» interest | string | 未还利息 |
»» quote | object | 货币账户信息 |
»»» currency | string | 货币名称 |
»»» available | string | 可用于杠杆交易的额度, available = 保证金 + borrowed |
»»» locked | string | 冻结资金, 如已经放在杠杆市场里挂单交易的数额 |
»»» borrowed | string | 借入资金 |
»»» interest | string | 未还利息 |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/user/account'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency_pair": "BTC_USDT",
"account_type": "mmr",
"leverage": "20",
"locked": false,
"risk": "1.3318",
"mmr": "16.5949188975473644",
"base": {
"currency": "BTC",
"available": "0.047060413211",
"locked": "0",
"borrowed": "0.047233",
"interest": "0"
},
"quote": {
"currency": "USDT",
"available": "1234",
"locked": "0",
"borrowed": "0",
"interest": "0"
}
}
]
Spot trading.
GET /spot/currencies
List all currencies' details.
When a currency corresponds to multiple chains, you can query the information of multiple chains through the chains
field, such as the charging and recharge status, identification, etc. of the chain.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» currency | string | Currency symbol. |
» name | string | Currency name. |
» delisted | boolean | Whether currency is de-listed. |
» withdraw_disabled | boolean | Whether currency's withdrawal is disabled (deprecated). |
» withdraw_delayed | boolean | Whether currency's withdrawal is delayed (deprecated). |
» deposit_disabled | boolean | Whether currency's deposit is disabled (deprecated). |
» trade_disabled | boolean | Whether currency's trading is disabled. |
» fixed_rate | string | Fixed fee rate. Only for fixed rate currencies, not valid for normal currencies |
» chain | string | The main chain corresponding to the coin. |
» is_private | boolean | Is it a privacy currency?. |
» chains | array | All links corresponding to coins. |
»» SpotCurrencyChain | object | none |
»»» name | string | Chain name. |
»»» addr | string | token address. |
»»» withdraw_disabled | boolean | Whether currency's withdrawal is disabled. |
»»» withdraw_delayed | boolean | Whether currency's withdrawal is delayed. |
»»» deposit_disabled | boolean | Whether currency's deposit is disabled. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "GT",
"name": "GateToken",
"delisted": false,
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"trade_disabled": false,
"chain": "GT",
"chains": [
{
"name": "GT",
"addr": "",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false
},
{
"name": "ETH",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"addr": "0xE66747a101bFF2dBA3697199DCcE5b743b454759"
},
{
"name": "GTEVM",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"addr": ""
}
]
}
]
GET /spot/currencies/{currency}
Get details of a specific currency.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | path | string | true | Currency name. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» currency | string | Currency symbol. |
» name | string | Currency name. |
» delisted | boolean | Whether currency is de-listed. |
» withdraw_disabled | boolean | Whether currency's withdrawal is disabled (deprecated). |
» withdraw_delayed | boolean | Whether currency's withdrawal is delayed (deprecated). |
» deposit_disabled | boolean | Whether currency's deposit is disabled (deprecated). |
» trade_disabled | boolean | Whether currency's trading is disabled. |
» fixed_rate | string | Fixed fee rate. Only for fixed rate currencies, not valid for normal currencies |
» chain | string | The main chain corresponding to the coin. |
» is_private | boolean | Is it a privacy currency?. |
» chains | array | All links corresponding to coins. |
»» SpotCurrencyChain | object | none |
»»» name | string | Chain name. |
»»» addr | string | token address. |
»»» withdraw_disabled | boolean | Whether currency's withdrawal is disabled. |
»»» withdraw_delayed | boolean | Whether currency's withdrawal is delayed. |
»»» deposit_disabled | boolean | Whether currency's deposit is disabled. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/currencies/GT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"currency": "GT",
"name": "GateToken",
"delisted": false,
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"trade_disabled": false,
"chain": "GT",
"chains": [
{
"name": "GT",
"addr": "",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false
},
{
"name": "ETH",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"addr": "0xE66747a101bFF2dBA3697199DCcE5b743b454759"
},
{
"name": "GTEVM",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"addr": ""
}
]
}
GET /spot/currency_pairs
List all currency pairs supported.
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 | Transaction currency name. |
»» quote | string | Quote currency. |
»» quote_name | string | Name of the denominated currency. |
»» fee | string | Trading fee. |
»» 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 | How currency pair can be traded - untradable: cannot be bought or sold - buyable: can be bought - sellable: can be sold - tradable: sold |
»» sell_start | integer(int64) | Sell start unix timestamp in seconds. |
»» buy_start | integer(int64) | Buy start unix timestamp in seconds. |
»» delisting_time | integer(int64) | Expected time to remove the shelves, Unix timestamp in seconds. |
»» type | string | Trading pair type, normal: normal, premarket: pre-market. |
»» trade_url | string | Transaction link. |
»» st_tag | boolean | Whether the trading pair is in ST risk assessment, false - No, true - Yes. |
Property | Value |
---|---|
trade_status | untradable |
trade_status | buyable |
trade_status | sellable |
trade_status | tradable |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/currency_pairs'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": "ETH_USDT",
"base": "ETH",
"base_name": "Ethereum",
"quote": "USDT",
"quote_name": "Tether",
"fee": "0.2",
"min_base_amount": "0.001",
"min_quote_amount": "1.0",
"max_base_amount": "10000",
"max_quote_amount": "10000000",
"amount_precision": 3,
"precision": 6,
"trade_status": "tradable",
"sell_start": 1516378650,
"buy_start": 1516378650,
"delisting_time": 0,
"trade_url": "https://www.gate.io/trade/ETH_USDT",
"st_tag": false
}
]
GET /spot/currency_pairs/{currency_pair}
Get details of a specifc currency pair.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency_pair | path | string | true | Currency pair. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Spot currency pair.
Name | Type | Description |
---|---|---|
» id | string | Currency pair. |
» base | string | Base currency. |
» base_name | string | Transaction currency name. |
» quote | string | Quote currency. |
» quote_name | string | Name of the denominated currency. |
» fee | string | Trading fee. |
» 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 | How currency pair can be traded - untradable: cannot be bought or sold - buyable: can be bought - sellable: can be sold - tradable: sold |
» sell_start | integer(int64) | Sell start unix timestamp in seconds. |
» buy_start | integer(int64) | Buy start unix timestamp in seconds. |
» delisting_time | integer(int64) | Expected time to remove the shelves, Unix timestamp in seconds. |
» type | string | Trading pair type, normal: normal, premarket: pre-market. |
» trade_url | string | Transaction link. |
» st_tag | boolean | Whether the trading pair is in ST risk assessment, false - No, true - Yes. |
Property | Value |
---|---|
trade_status | untradable |
trade_status | buyable |
trade_status | sellable |
trade_status | tradable |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/currency_pairs/ETH_BTC'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"id": "ETH_USDT",
"base": "ETH",
"base_name": "Ethereum",
"quote": "USDT",
"quote_name": "Tether",
"fee": "0.2",
"min_base_amount": "0.001",
"min_quote_amount": "1.0",
"max_base_amount": "10000",
"max_quote_amount": "10000000",
"amount_precision": 3,
"precision": 6,
"trade_status": "tradable",
"sell_start": 1516378650,
"buy_start": 1516378650,
"delisting_time": 0,
"trade_url": "https://www.gate.io/trade/ETH_USDT",
"st_tag": false
}
GET /spot/tickers
Retrieve ticker information.
Return only related data if currency_pair
is specified; otherwise return all of them
Name | In | Type | Required | Description |
---|---|---|---|---|
currency_pair | query | string | false | Currency pair. |
timezone | query | string | false | Timezone. |
Parameter | Value |
---|---|
timezone | utc0 |
timezone | utc8 |
timezone | all |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» currency_pair | string | Currency pair. |
» last | string | Last trading price. |
» lowest_ask | string | Recent lowest ask. |
» lowest_size | string | The latest seller's lowest price quantity; does not exist for batch query; exists for single query, and is empty if there is no data |
» highest_bid | string | Recent highest bid. |
» highest_size | string | The latest buyer's highest price quantity; does not exist for batch query; exists for single query, and is empty if there is no data |
» change_percentage | string | Change percentage in the last 24h. |
» change_utc0 | string | utc0 timezone, the percentage change in the last 24 hours. |
» change_utc8 | string | utc8 timezone, the percentage change in the last 24 hours. |
» base_volume | string | Base currency trade volume in the last 24h. |
» quote_volume | string | Quote currency trade volume in the last 24h. |
» high_24h | string | Highest price in 24h. |
» low_24h | string | Lowest price in 24h. |
» etf_net_value | string | ETF net value. |
» etf_pre_net_value | string|null | ETF previous net value at re-balancing time. |
» etf_pre_timestamp | integer(int64)|null | ETF previous re-balancing time. |
» etf_leverage | string|null | ETF current leverage. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/tickers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency_pair": "BTC3L_USDT",
"last": "2.46140352",
"lowest_ask": "2.477",
"highest_bid": "2.4606821",
"change_percentage": "-8.91",
"change_utc0": "-8.91",
"change_utc8": "-8.91",
"base_volume": "656614.0845820589",
"quote_volume": "1602221.66468375534639404191",
"high_24h": "2.7431",
"low_24h": "1.9863",
"etf_net_value": "2.46316141",
"etf_pre_net_value": "2.43201848",
"etf_pre_timestamp": 1611244800,
"etf_leverage": "2.2803019447281203"
}
]
GET /spot/order_book
Retrieve order book.
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 | Order depth. 0 means no aggregation is applied. default to 0. |
limit | query | integer | false | Maximum number of order depth data in asks or bids. |
with_id | query | boolean | false | Return order book ID. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» id | integer(int64) | Order book ID, which is updated whenever the order book is changed. Valid only when with_id is set to true |
» current | integer(int64) | The timestamp of the response data being generated (in milliseconds). |
» update | integer(int64) | The timestamp of when the orderbook last changed (in milliseconds). |
» asks | array | Asks order depth. |
»» None | array | price and amount. |
» bids | array | Bids order depth. |
»» None | array | price and amount. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/order_book'
query_param = 'currency_pair=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"id": 123456,
"current": 1623898993123,
"update": 1623898993121,
"asks": [
[
"1.52",
"1.151"
],
[
"1.53",
"1.218"
]
],
"bids": [
[
"1.17",
"201.863"
],
[
"1.16",
"725.464"
]
]
}
GET /spot/trades
Retrieve market trades.
Supports from
and to
by time range query or page-turn query based on last_id
. By default, is the last 30 days.
The query method based on last_id
page turn is no longer recommended. If last_id
is specified, the time range query parameters will be ignored.
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 | true | Currency pair. |
limit | query | integer(int32) | false | Maximum number of records to be returned in a single list. Default: 100, Minimum: 1, Maximum: 1000 |
last_id | query | string | false | Specify the currency name to query in batches, and support up to 100 pass parameters at a time. |
reverse | query | boolean | false | Whether the id of records to be retrieved should be less than the last_id specified. Default to false. |
from | query | integer(int64) | false | Start timestamp of the query. |
to | query | integer(int64) | false | Time range ending, default to current time. |
page | query | integer(int32) | false | Page number. |
reverse: Whether the id of records to be retrieved should be less than the last_id specified. Default to false.
When last_id
is specified. Set reverse
to true
to trace back trading history; false
to retrieve latest tradings.
No effect if last_id
is not specified.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» id | string | Trade ID. |
» create_time | string | Trading time. |
» create_time_ms | string | Trading time, with millisecond precision. |
» currency_pair | string | Currency pair. |
» side | string | Buy or sell order. |
» role | string | Trade role. No value in public endpoints. |
» amount | string | Trade amount. |
» price | string | Order price. |
» order_id | string | Related order ID. No value in public endpoints. |
» fee | string | Fee deducted. No value in public endpoints. |
» fee_currency | string | Fee currency unit. No value in public endpoints. |
» point_fee | string | Points used to deduct fee. No value in public endpoints. |
» gt_fee | string | GT used to deduct fee. No value in public endpoints. |
» amend_text | string | The custom data that the user remarked when amending the order. |
» sequence_id | string | Represents a unique and consecutive trade ID within a single market. It is used to track and identify trades in the specific market |
» text | string | User defined information. No value in public endpoints. |
Property | Value |
---|---|
side | buy |
side | sell |
role | taker |
role | maker |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/trades'
query_param = 'currency_pair=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": "1232893232",
"create_time": "1548000000",
"create_time_ms": "1548000000123.456",
"order_id": "4128442423",
"side": "buy",
"role": "maker",
"amount": "0.15",
"price": "0.03",
"fee": "0.0005",
"fee_currency": "ETH",
"point_fee": "0",
"gt_fee": "0",
"sequence_id": "588018",
"text": "t-test"
}
]
GET /spot/candlesticks
Market candlesticks.
Maximum of 1000 points can be returned in a query. Be sure not to exceed the limit when specifying from, to and interval
Name | In | Type | Required | Description |
---|---|---|---|---|
currency_pair | query | string | true | Currency pair. |
limit | query | integer | false | Maximum recent data points to return. limit is conflicted with from and to . If either from or to is specified, request will be rejected. |
from | query | integer(int64) | false | Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified |
to | query | integer(int64) | false | 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 specified |
interval | query | string | false | Interval time between data points. Note that 30d means 1 natual month, not 30 days |
Parameter | Value |
---|---|
interval | 1s |
interval | 10s |
interval | 1m |
interval | 5m |
interval | 15m |
interval | 30m |
interval | 1h |
interval | 4h |
interval | 8h |
interval | 1d |
interval | 7d |
interval | 30d |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [[string]] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | array | K-line data for each time granularity, arranged from left to right: - Unix timestamp with second precision - Trading volume in quote currency - Closing price - Highest price - Lowest price - Opening price - Trading volume in base currency - Whether the window is closed; true indicates the end of this segment of candlestick chart data, false indicates data is not yet complete |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/candlesticks'
query_param = 'currency_pair=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
[
"1539852480",
"971519.677",
"0.0021724",
"0.0021922",
"0.0021724",
"0.0021737",
"true"
]
]
GET /spot/fee
Query user trading fee rates.
This API is deprecated in favour of new fee retrieving API /wallet/fee
.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency_pair | query | string | false | Specify a currency pair to retrieve precise fee rate |
currency_pair: Specify a currency pair to retrieve precise fee rate
This field is optional. In most cases, the fee rate is identical among all currency pairs
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» user_id | integer(int64) | User ID. |
» taker_fee | string | taker fee rate. |
» maker_fee | string | maker fee rate. |
» gt_discount | boolean | If GT deduction is enabled. |
» gt_taker_fee | string | Taker fee rate if using GT deduction. It will be 0 if GT deduction is disabled |
» gt_maker_fee | string | Maker fee rate if using GT deduction. It will be 0 if GT deduction is disabled |
» loan_fee | string | Loan fee rate of margin lending. |
» point_type | string | Point type. 0 - Initial version. 1 - new version since 202009. |
» currency_pair | string | Currency pair. |
» debit_fee | integer | Deduction types for rates, 1 - GT deduction, 2 - Point card deduction, 3 - VIP rates |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/fee'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"user_id": 10001,
"taker_fee": "0.002",
"maker_fee": "0.002",
"gt_discount": false,
"gt_taker_fee": "0",
"gt_maker_fee": "0",
"loan_fee": "0.18",
"point_type": "1",
"currency_pair": "BTC_USDT",
"debit_fee": 3
}
GET /spot/batch_fee
Query a batch of user trading fee rates.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency_pairs | query | string | true | A request can only query up to 50 currency pairs. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» additionalProperties | object | none |
»» user_id | integer(int64) | User ID. |
»» taker_fee | string | taker fee rate. |
»» maker_fee | string | maker fee rate. |
»» gt_discount | boolean | If GT deduction is enabled. |
»» gt_taker_fee | string | Taker fee rate if using GT deduction. It will be 0 if GT deduction is disabled |
»» gt_maker_fee | string | Maker fee rate if using GT deduction. It will be 0 if GT deduction is disabled |
»» loan_fee | string | Loan fee rate of margin lending. |
»» point_type | string | Point type. 0 - Initial version. 1 - new version since 202009. |
»» currency_pair | string | Currency pair. |
»» debit_fee | integer | Deduction types for rates, 1 - GT deduction, 2 - Point card deduction, 3 - VIP rates |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/batch_fee'
query_param = 'currency_pairs=BTC_USDT,ETH_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"BTC_USDT": {
"user_id": 10001,
"taker_fee": "0.002",
"maker_fee": "0.002",
"gt_discount": false,
"gt_taker_fee": "0",
"gt_maker_fee": "0",
"loan_fee": "0.18",
"point_type": "1",
"currency_pair": "BTC_USDT",
"debit_fee": 3
},
"GT_USDT": {
"user_id": 10001,
"taker_fee": "0.002",
"maker_fee": "0.002",
"gt_discount": false,
"gt_taker_fee": "0",
"gt_maker_fee": "0",
"loan_fee": "0.18",
"point_type": "1",
"currency_pair": "GT_USDT",
"debit_fee": 3
},
"ETH_USDT": {
"user_id": 10001,
"taker_fee": "0.002",
"maker_fee": "0.002",
"gt_discount": false,
"gt_taker_fee": "0",
"gt_maker_fee": "0",
"loan_fee": "0.18",
"point_type": "1",
"currency_pair": "ETH_USDT",
"debit_fee": 3
}
}
GET /spot/accounts
List spot accounts.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Retrieve data of the specified currency. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» currency | string | Currency detail. |
» available | string | Available amount. |
» locked | string | Locked amount, used in trading. |
» update_id | integer(int64) | Version number. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "ETH",
"available": "968.8",
"locked": "0",
"update_id": 98
}
]
GET /spot/account_book
Query account book.
Record query time range is not allowed to exceed 30 days.
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 | query | string | false | Retrieve data of the specified currency. |
from | query | integer(int64) | false | Start timestamp of the query. |
to | query | integer(int64) | false | Time range ending, default to current time. |
page | query | integer(int32) | false | Page number. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
type | query | string | false | Only retrieve changes of the specified type. All types will be returned if not specified. |
code | query | string | false | Specify account change code query, if not specified, all change types are included, and the priority is higher than type |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» id | string | Balance change record ID. |
» time | integer(int64) | The timestamp of the change (in milliseconds). |
» currency | string | Currency changed. |
» change | string | Amount changed. Positive value means transferring in, while negative out. |
» balance | string | Balance after change. |
» type | string | Account book type. Please refer to account book type for more detail |
» code | string | Account change code, see [Asset Record Code] (Asset Record Code). |
» text | string | Additional information. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": "123456",
"time": 1547633726123,
"currency": "BTC",
"change": "1.03",
"balance": "4.59316525194",
"type": "margin_in",
"text": "3815099"
}
]
POST /spot/batch_orders
Create a batch of orders.
Batch orders requirements:
text
is requiredaccount
must be identical for all ordersName | In | Type | Required | Description |
---|---|---|---|---|
x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
body | body | array | true | none |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Request is completed. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Batch order details.] |
» None | object | Batch order details. |
»» order_id | string | Order ID. |
»» amend_text | string | The custom data that the user remarked when amending the order. |
»» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) |
»» succeeded | boolean | Whether the batch of orders succeeded. |
»» label | string | Error label, if any, otherwise an empty string. |
»» message | string | Detailed error message, if any, otherwise an empty string. |
»» id | string | Order ID. |
»» create_time | string | Creation time of order. |
»» update_time | string | Last modification time of order. |
»» create_time_ms | integer(int64) | Creation time of order (in milliseconds). |
»» update_time_ms | integer(int64) | Last modification time of order (in milliseconds). |
»» status | string | Order status - open : to be filled- closed : filled- cancelled : cancelled |
»» currency_pair | string | Currency pair. |
»» type | string | Order Type - limit : Limit Order - market : Market Order |
»» account | string | Account type, spot - 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 traded to fill. |
»» fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total . |
»» filled_total | string | Total filled in quote currency. |
»» avg_deal_price | string | Average fill price. |
»» fee | string | Fee deducted. |
»» fee_currency | string | Fee currency unit. |
»» point_fee | string | Points used to deduct fee. |
»» gt_fee | string | GT used to deduct fee. |
»» gt_discount | boolean | Whether GT fee discount is used. |
»» rebated_fee | string | Rebated fee. |
»» rebated_fee_currency | string | Rebated fee currency unit. |
»» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
»» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group , he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group , an error will be returned when passing the stp_act parameter. 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled |
»» finish_as | string | How the order was finished. - open: processing - filled: filled totally - cancelled: manually cancelled - ioc: time in force is IOC , finish immediately- stp: cancelled because self trade prevention |
Property | Value |
---|---|
status | open |
status | closed |
status | cancelled |
type | limit |
type | market |
account | spot |
account | margin |
account | cross_margin |
account | unified |
side | buy |
side | sell |
time_in_force | gtc |
time_in_force | ioc |
time_in_force | poc |
time_in_force | fok |
stp_act | cn |
stp_act | co |
stp_act | cb |
stp_act | - |
finish_as | open |
finish_as | filled |
finish_as | cancelled |
finish_as | ioc |
finish_as | stp |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/batch_orders'
query_param = ''
body='[{"text":"t-abc123","currency_pair":"BTC_USDT","type":"limit","account":"unified","side":"buy","amount":"0.001","price":"65000","time_in_force":"gtc","iceberg":"0"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
[
{
"text": "t-abc123",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0"
}
]
Example responses
200 Response
[
{
"order_id": "12332324",
"amend_text": "t-123456",
"text": "t-123456",
"succeeded": true,
"label": "",
"message": "",
"id": "12332324",
"create_time": "1548000000",
"update_time": "1548000100",
"create_time_ms": 1548000000123,
"update_time_ms": 1548000100123,
"currency_pair": "ETC_BTC",
"status": "cancelled",
"type": "limit",
"account": "spot",
"side": "buy",
"amount": "1",
"price": "5.00032",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0.5",
"filled_amount": "1.242",
"filled_total": "2.50016",
"avg_deal_price": "5.00032",
"fee": "0.005",
"fee_currency": "ETH",
"point_fee": "0",
"gt_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "BTC",
"stp_act": "cn",
"finish_as": "stp",
"stp_id": 10240
}
]
GET /spot/open_orders
List all open orders.
Query the current order list of all trading pairs. Please note that the paging parameter controls the number of pending orders in each trading pair. There is no paging control trading pairs. All trading pairs with pending orders will be returned.
Name | In | Type | Required | Description |
---|---|---|---|---|
page | query | integer(int32) | false | Page number. |
limit | query | integer | false | Maximum number of records returned in one page in each currency pair. |
account | query | string | false | Specify query account. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» currency_pair | string | Currency pair. |
» total | integer | The total number of pending orders for this trading pair on the current page |
» orders | array | none |
»» None | object | Spot order details. |
»»» id | string | Order ID. |
»»» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 |
»»» amend_text | string | The custom data that the user remarked when amending the order. |
»»» create_time | string | Creation time of order. |
»»» update_time | string | Last modification time of order. |
»»» create_time_ms | integer(int64) | Creation time of order (in milliseconds). |
»»» update_time_ms | integer(int64) | Last modification time of order (in milliseconds). |
»»» status | string | Order status - open : to be filled- closed : filled- cancelled : cancelled |
»»» currency_pair | string | Currency pair. |
»»» type | string | Order Type - limit : Limit Order - market : Market Order |
»»» account | string | Account type, spot - spot account, margin - leveraged account, unified - unified account |
»»» side | string | Buy or sell order. |
»»» amount | string | When type is limit, it refers to base currency. For instance, BTC_USDT means BTC When different currency according to side - side : buy means quote currency, BTC_USDT means USDT - side : sell means base currency, BTC_USDT means BTC |
»»» price | string | Price can't be empty when type = limit . |
»»» time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type =market |
»»» iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported. |
»»» auto_repay | boolean | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order. |
»»» left | string | Amount left to fill. |
»»» filled_amount | string | Amount traded to fill. |
»»» fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total . |
»»» filled_total | string | Total filled in quote currency. |
»»» avg_deal_price | string | Average fill price. |
»»» fee | string | Fee deducted. |
»»» fee_currency | string | Fee currency unit. |
»»» point_fee | string | Points used to deduct fee. |
»»» gt_fee | string | GT used to deduct fee. |
»»» gt_maker_fee | string | GT used to deduct maker fee. |
»»» gt_taker_fee | string | GT used to deduct taker fee. |
»»» gt_discount | boolean | Whether GT fee discount is used. |
»»» rebated_fee | string | Rebated fee. |
»»» rebated_fee_currency | string | Rebated fee currency unit. |
»»» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
»»» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group , he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group , an error will be returned when passing the stp_act parameter. 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled |
»»» finish_as | string | Order completion statuses include: - open: Awaiting processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled due to liquidation - small: Order quantity too small - depth_not_enough: Cancelled due to insufficient market depth - trader_not_enough: Cancelled due to insufficient counterparty - ioc: Not immediately filled because tif is set to ioc - poc: Not met the order poc - fok: Not fully filled immediately because tif is set to fok - stp: Cancelled due to self-trade prevention - unknown: Unknown |
»»» fee_discount | string | rate discount. |
Property | Value |
---|---|
status | open |
status | closed |
status | cancelled |
type | limit |
type | market |
side | buy |
side | sell |
time_in_force | gtc |
time_in_force | ioc |
time_in_force | poc |
time_in_force | fok |
stp_act | cn |
stp_act | co |
stp_act | cb |
stp_act | - |
finish_as | open |
finish_as | filled |
finish_as | cancelled |
finish_as | liquidate_cancelled |
finish_as | depth_not_enough |
finish_as | trader_not_enough |
finish_as | small |
finish_as | ioc |
finish_as | poc |
finish_as | fok |
finish_as | stp |
finish_as | unknown |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/open_orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency_pair": "ETH_BTC",
"total": 1,
"orders": [
{
"id": "12332324",
"text": "t-123456",
"create_time": "1548000000",
"update_time": "1548000100",
"currency_pair": "ETH_BTC",
"status": "open",
"type": "limit",
"account": "spot",
"side": "buy",
"amount": "1",
"price": "5.00032",
"time_in_force": "gtc",
"left": "0.5",
"filled_total": "2.50016",
"fee": "0.005",
"fee_currency": "ETH",
"point_fee": "0",
"gt_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "BTC"
}
]
}
]
POST /spot/cross_liquidate_orders
close position when cross-currency is disabled.
Currently, only cross-margin accounts are supported to close position when cross currencies are disabled. Maximum buy quantity = (unpaid principal and interest - currency balance - the amount of the currency in the order book) / 0.998
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» text | body | string | false | User defined information. If not empty, must follow the rules below: |
» currency_pair | body | string | true | Currency pair. |
» amount | body | string | true | Trade amount. |
» price | body | string | true | Order price. |
» action_mode | body | string | false | Processing Mode: |
» text: User defined information. If not empty, must follow the rules below:
t-
t-
prefix» action_mode: Processing Mode:
Different fields are returned when placing an order based on action_mode. This field is only valid during the request, and it is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)
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 | When type is limit, it refers to base currency. For instance, BTC_USDT means BTC When different currency according to side - side : buy means quote currency, BTC_USDT means USDT - side : sell means base currency, BTC_USDT means BTC |
» price | string | Price can't be empty when type = limit . |
» time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type =market |
» iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported. |
» auto_repay | boolean | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order. |
» left | string | Amount left to fill. |
» filled_amount | string | Amount traded to fill. |
» fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total . |
» filled_total | string | Total filled in quote currency. |
» avg_deal_price | string | Average fill price. |
» fee | string | Fee deducted. |
» fee_currency | string | Fee currency unit. |
» point_fee | string | Points used to deduct fee. |
» gt_fee | string | GT used to deduct fee. |
» gt_maker_fee | string | GT used to deduct maker fee. |
» gt_taker_fee | string | GT used to deduct taker fee. |
» gt_discount | boolean | Whether GT fee discount is used. |
» rebated_fee | string | Rebated fee. |
» rebated_fee_currency | string | Rebated fee currency unit. |
» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group , he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group , an error will be returned when passing the stp_act parameter. 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled |
» finish_as | string | Order completion statuses include: - open: Awaiting processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled due to liquidation - small: Order quantity too small - depth_not_enough: Cancelled due to insufficient market depth - trader_not_enough: Cancelled due to insufficient counterparty - ioc: Not immediately filled because tif is set to ioc - poc: Not met the order poc - fok: Not fully filled immediately because tif is set to fok - stp: Cancelled due to self-trade prevention - unknown: Unknown |
» fee_discount | string | rate discount. |
Property | Value |
---|---|
status | open |
status | closed |
status | cancelled |
type | limit |
type | market |
side | buy |
side | sell |
time_in_force | gtc |
time_in_force | ioc |
time_in_force | poc |
time_in_force | fok |
stp_act | cn |
stp_act | co |
stp_act | cb |
stp_act | - |
finish_as | open |
finish_as | filled |
finish_as | cancelled |
finish_as | liquidate_cancelled |
finish_as | depth_not_enough |
finish_as | trader_not_enough |
finish_as | small |
finish_as | ioc |
finish_as | poc |
finish_as | fok |
finish_as | stp |
finish_as | unknown |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/cross_liquidate_orders'
query_param = ''
body='{"currency_pair":"GT_USDT","amount":"12","price":"10.15","text":"t-34535"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"currency_pair": "GT_USDT",
"amount": "12",
"price": "10.15",
"text": "t-34535"
}
Example responses
201 Response
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
POST /spot/orders
Create an order.
Support spot, margin, leverage, and full-position leverage orders. Use different accounts through the account
field, default is spot
, that is, use the spot account to place an order if the user is unified
account, default is to place an order with a unified account
When using leveraged account trading, that is, when account
is set to margin
, you can set auto_borrow
to true
,
In the case of insufficient account balance, the system will automatically execute the POST /margin/uni/loans
to borrow the insufficient part.
Whether the assets obtained after the leveraged order is automatically used to return the borrowing orders of the leveraged account in a position-by-store leverage account depends on the automatic repayment settings of the user's position-by-store leverage account**,
The account automatic repayment settings can be queried and set through /margin/auto_repay
.
Use unified is set to unified
, auto_borrow
" can also be enableTo realize the insufficient part of automatic borrowing, but unlike the leverage account, whether the entrustment of a unified account is automatically repayable depends on the
when placing an orderauto_repay
setting, this setting is only effective for the current entrustment, that is, only the assets obtained after the entrustment transaction will be used to repay the borrowing orders of the full-position leverage account.
Unified account ordering currently supports auto_borrow
and auto_repay
at the same time.
Auto repayment will be triggered at the end of the order, i.e. status
is cancelled
or closed
.
Delegation Status
The entrustment status in the pending order is open
, which remains at open
until all the quantity is traded. If it is eaten, the order ends and the status becomes closed
.
If the order is cancelled before all transactions are completed, regardless of whether there are partial transactions, the status will become cancelled
Iceberg Entrustment
iceberg
is used to set the number of iceberg delegations displayed, and does not support complete hiding. Note that when hidden part of the transaction is charged according to the taker's handling rate.
Restrict user transactions
Set stp_act
to decide to use strategies that limit user transactions
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 | When type is limit, it refers to base currency. For instance, BTC_USDT means BTC |
» price | body | string | false | Price can't be empty when type = limit . |
» time_in_force | body | string | false | Time in force |
» iceberg | body | string | false | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported. |
» auto_borrow | body | boolean | false | Used in margin or cross margin trading to allow automatic loan of insufficient amount if balance is not enough. |
» auto_repay | body | boolean | false | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: |
» stp_act | body | string | false | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies |
» fee_discount | body | string | false | rate discount. |
» action_mode | body | string | false | Processing Mode: |
» text: User defined information. If not empty, must follow the rules below:
t-
t-
prefixBesides user defined information, reserved contents are listed below, denoting how the order is created:
» type: Order Type
» amount: When type
is limit, it refers to base currency. For instance, BTC_USDT
means BTC
When different currency according to side
side
: buy
means quote currency, BTC_USDT
means USDT
side
: sell
means base currency, BTC_USDT
means BTC
» time_in_force: Time in force
ioc
and fok
are supported when type
=market
» auto_repay: Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that:
auto_borrow
and auto_repay
can be both set to true in one order.» stp_act: Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies
STP Group
, he can pass stp_act
to limit the user's self-trade prevetion strategy. If stp_act
is not passed, the default is cn
strategy.STP group
, an error will be returned when passing the stp_act
parameter.» action_mode: Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)
Parameter | Value |
---|---|
» type | limit |
» type | market |
» side | buy |
» side | sell |
» time_in_force | gtc |
» time_in_force | ioc |
» time_in_force | poc |
» time_in_force | fok |
» stp_act | cn |
» stp_act | co |
» stp_act | cb |
» stp_act | - |
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 | When type is limit, it refers to base currency. For instance, BTC_USDT means BTC When different currency according to side - side : buy means quote currency, BTC_USDT means USDT - side : sell means base currency, BTC_USDT means BTC |
» price | string | Price can't be empty when type = limit . |
» time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type =market |
» iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported. |
» auto_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 traded to fill. |
» fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total . |
» filled_total | string | Total filled in quote currency. |
» avg_deal_price | string | Average fill price. |
» fee | string | Fee deducted. |
» fee_currency | string | Fee currency unit. |
» point_fee | string | Points used to deduct fee. |
» gt_fee | string | GT used to deduct fee. |
» gt_maker_fee | string | GT used to deduct maker fee. |
» gt_taker_fee | string | GT used to deduct taker fee. |
» gt_discount | boolean | Whether GT fee discount is used. |
» rebated_fee | string | Rebated fee. |
» rebated_fee_currency | string | Rebated fee currency unit. |
» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group , he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group , an error will be returned when passing the stp_act parameter. 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled |
» finish_as | string | Order completion statuses include: - open: Awaiting processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled due to liquidation - small: Order quantity too small - depth_not_enough: Cancelled due to insufficient market depth - trader_not_enough: Cancelled due to insufficient counterparty - ioc: Not immediately filled because tif is set to ioc - poc: Not met the order poc - fok: Not fully filled immediately because tif is set to fok - stp: Cancelled due to self-trade prevention - unknown: Unknown |
» fee_discount | string | rate discount. |
» action_mode | string | Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default) |
Property | Value |
---|---|
status | open |
status | closed |
status | cancelled |
type | limit |
type | market |
side | buy |
side | sell |
time_in_force | gtc |
time_in_force | ioc |
time_in_force | poc |
time_in_force | fok |
stp_act | cn |
stp_act | co |
stp_act | cb |
stp_act | - |
finish_as | open |
finish_as | filled |
finish_as | cancelled |
finish_as | liquidate_cancelled |
finish_as | depth_not_enough |
finish_as | trader_not_enough |
finish_as | small |
finish_as | ioc |
finish_as | poc |
finish_as | fok |
finish_as | stp |
finish_as | unknown |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/orders'
query_param = ''
body='{"text":"t-abc123","currency_pair":"BTC_USDT","type":"limit","account":"unified","side":"buy","amount":"0.001","price":"65000","time_in_force":"gtc","iceberg":"0"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"text": "t-abc123",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0"
}
Example responses
ACK response body example
{
"id": "12332324",
"text": "t-123456",
"amend_text": "test2"
}
RESULT response body example
{
"id": "12332324",
"text": "t-123456",
"create_time": "1548000000",
"update_time": "1548000100",
"create_time_ms": 1548000000123,
"update_time_ms": 1548000100123,
"currency_pair": "ETH_BTC",
"status": "cancelled",
"type": "limit",
"account": "spot",
"side": "buy",
"iceberg": "0",
"amount": "1",
"price": "5.00032",
"time_in_force": "gtc",
"auto_borrow": false,
"left": "0.5",
"filled_total": "2.50016",
"avg_deal_price": "5.00032",
"stp_act": "cn",
"finish_as": "stp",
"stp_id": 10240
}
FULL response body example
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
GET /spot/orders
List orders.
status
is set to open
, that is, when querying the pending order list, only page
and limit
paging control are supported. limit
The maximum setting is only 100.
Does not support side
and from
, to
parameters for querying by time range.
status
when querying historical orders, in addition to paging query, it also supports from
and to
query by time range.
In addition, it also supports setting the side
parameter to filter unilateral history.
The parameters for time range filtering are all processed according to the end time of the order.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency_pair | query | string | true | Retrieve results with specified currency pair. It is required for open orders, but optional for finished ones. |
status | query | string | true | List orders based on status |
page | query | integer(int32) | false | Page number. |
limit | query | integer | false | Maximum number of records to be returned. If status is open , maximum of limit is 100 |
account | query | string | false | Specify query account. |
from | query | integer(int64) | false | Start timestamp of the query. |
to | query | integer(int64) | false | Time range ending, default to current time. |
side | query | string | false | All bids or asks. Both included if not specified. |
status: List orders based on status
open
- order is waiting to be filled
finished
- order has been filled or cancelled
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [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 | When type is limit, it refers to base currency. For instance, BTC_USDT means BTC When different currency according to side - side : buy means quote currency, BTC_USDT means USDT - side : sell means base currency, BTC_USDT means BTC |
»» price | string | Price can't be empty when type = limit . |
»» time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type =market |
»» iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported. |
»» auto_repay | boolean | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order. |
»» left | string | Amount left to fill. |
»» filled_amount | string | Amount traded to fill. |
»» fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total . |
»» filled_total | string | Total filled in quote currency. |
»» avg_deal_price | string | Average fill price. |
»» fee | string | Fee deducted. |
»» fee_currency | string | Fee currency unit. |
»» point_fee | string | Points used to deduct fee. |
»» gt_fee | string | GT used to deduct fee. |
»» gt_maker_fee | string | GT used to deduct maker fee. |
»» gt_taker_fee | string | GT used to deduct taker fee. |
»» gt_discount | boolean | Whether GT fee discount is used. |
»» rebated_fee | string | Rebated fee. |
»» rebated_fee_currency | string | Rebated fee currency unit. |
»» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
»» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group , he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group , an error will be returned when passing the stp_act parameter. 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled |
»» finish_as | string | Order completion statuses include: - open: Awaiting processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled due to liquidation - small: Order quantity too small - depth_not_enough: Cancelled due to insufficient market depth - trader_not_enough: Cancelled due to insufficient counterparty - ioc: Not immediately filled because tif is set to ioc - poc: Not met the order poc - fok: Not fully filled immediately because tif is set to fok - stp: Cancelled due to self-trade prevention - unknown: Unknown |
»» fee_discount | string | rate discount. |
Property | Value |
---|---|
status | open |
status | closed |
status | cancelled |
type | limit |
type | market |
side | buy |
side | sell |
time_in_force | gtc |
time_in_force | ioc |
time_in_force | poc |
time_in_force | fok |
stp_act | cn |
stp_act | co |
stp_act | cb |
stp_act | - |
finish_as | open |
finish_as | filled |
finish_as | cancelled |
finish_as | liquidate_cancelled |
finish_as | depth_not_enough |
finish_as | trader_not_enough |
finish_as | small |
finish_as | ioc |
finish_as | poc |
finish_as | fok |
finish_as | stp |
finish_as | unknown |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/orders'
query_param = 'currency_pair=BTC_USDT&status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
]
open
orders in specified currency pair.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 position-by-position leverage will be cancelled.
When transaction pairs are revoked
You can specify a certain account separately to cancel all orders under the specified account
Name | In | Type | Required | Description |
---|---|---|---|---|
currency_pair | query | string | false | Currency pair. |
side | query | string | false | All bids or asks. Both included if not specified. |
account | query | string | false | Specify account type |
action_mode | query | string | false | Processing Mode |
x-gate-exptime | header | 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
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Batch cancellation request accepted. Query order status by listing orders. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Spot order details. |
»» id | string | Order ID. |
»» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 |
»» amend_text | string | The custom data that the user remarked when amending the order. |
»» succeeded | boolean | Whether the batch of orders succeeded. |
»» label | string | Error label, if any, otherwise an empty string. |
»» message | string | Detailed error message, if any, otherwise an empty string. |
»» create_time | string | Creation time of order. |
»» update_time | string | Last modification time of order. |
»» create_time_ms | integer(int64) | Creation time of order (in milliseconds). |
»» update_time_ms | integer(int64) | Last modification time of order (in milliseconds). |
»» status | string | Order status - open : to be filled- closed : filled- cancelled : cancelled |
»» currency_pair | string | Currency pair. |
»» type | string | Order Type - limit : Limit Order - market : Market Order |
»» account | string | Account type, spot - spot account, margin - leveraged account, unified - unified account |
»» side | string | Buy or sell order. |
»» amount | string | When type is limit, it refers to base currency. For instance, BTC_USDT means BTC When different currency according to side - side : buy means quote currency, BTC_USDT means USDT - side : sell means base currency, BTC_USDT means BTC |
»» price | string | Price can't be empty when type = limit . |
»» time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type =market |
»» iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported. |
»» auto_repay | boolean | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order. |
»» left | string | Amount left to fill. |
»» filled_amount | string | Amount traded to fill. |
»» fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total . |
»» filled_total | string | Total filled in quote currency. |
»» avg_deal_price | string | Average fill price. |
»» fee | string | Fee deducted. |
»» fee_currency | string | Fee currency unit. |
»» point_fee | string | Points used to deduct fee. |
»» gt_fee | string | GT used to deduct fee. |
»» gt_maker_fee | string | GT used to deduct maker fee. |
»» gt_taker_fee | string | GT used to deduct taker fee. |
»» gt_discount | boolean | Whether GT fee discount is used. |
»» rebated_fee | string | Rebated fee. |
»» rebated_fee_currency | string | Rebated fee currency unit. |
»» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
»» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group , he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group , an error will be returned when passing the stp_act parameter. 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled |
»» finish_as | string | How the order was finished. - open: processing - filled: filled totally - cancelled: manually cancelled - ioc: time in force is IOC , finish immediately- stp: cancelled because self trade prevention |
»» fee_discount | string | rate discount. |
Property | Value |
---|---|
status | open |
status | closed |
status | cancelled |
type | limit |
type | market |
side | buy |
side | sell |
time_in_force | gtc |
time_in_force | ioc |
time_in_force | poc |
time_in_force | fok |
stp_act | cn |
stp_act | co |
stp_act | cb |
stp_act | - |
finish_as | open |
finish_as | filled |
finish_as | cancelled |
finish_as | ioc |
finish_as | stp |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"succeeded": true,
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
]
POST /spot/cancel_batch_orders
Cancel a batch of orders with an ID list.
Multiple currency pairs can be specified, but maximum 20 orders are allowed per request
Name | In | Type | Required | Description |
---|---|---|---|---|
x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
body | body | array[object] | true | none |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Batch cancellation completed. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» CancelOrderResult | object | Order cancellation result. |
»» currency_pair | string | Order currency pair. |
»» id | string | Order ID. |
»» text | string | Custom order information. |
»» succeeded | boolean | Whether cancellation succeeded. |
»» label | string | Error label when failed to cancel the order; emtpy if succeeded. |
»» message | string | Error message when failed to cancel the order; empty if succeeded. |
»» account | string | Default is empty (deprecated). |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/cancel_batch_orders'
query_param = ''
body='[{"currency_pair":"BTC_USDT","id":"123456"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
[
{
"currency_pair": "BTC_USDT",
"id": "123456"
}
]
Example responses
200 Response
[
{
"currency_pair": "BTC_USDT",
"id": "123456",
"text": "123456",
"succeeded": true,
"label": null,
"message": null
}
]
GET /spot/orders/{order_id}
Get a single order.
By default, orders for spot, unified account and warehouse-by-site leverage account are checked.
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 transaction pair to query. If you are querying pending order records, this field is traded records, this field can be left blank. |
account | query | string | false | Specify query account. |
order_id: The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text
field).
Operations based on custom IDs can only be checked in pending orders. Only order ID can be used after the order is finished (transaction/cancel)
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Detail retrieved. | Inline |
Status Code 200
Spot order details.
Name | Type | Description |
---|---|---|
» id | string | Order ID. |
» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 |
» amend_text | string | The custom data that the user remarked when amending the order. |
» create_time | string | Creation time of order. |
» update_time | string | Last modification time of order. |
» create_time_ms | integer(int64) | Creation time of order (in milliseconds). |
» update_time_ms | integer(int64) | Last modification time of order (in milliseconds). |
» status | string | Order status - open : to be filled- closed : filled- cancelled : cancelled |
» currency_pair | string | Currency pair. |
» type | string | Order Type - limit : Limit Order - market : Market Order |
» account | string | Account type, spot - spot account, margin - leveraged account, unified - unified account |
» side | string | Buy or sell order. |
» amount | string | When type is limit, it refers to base currency. For instance, BTC_USDT means BTC When different currency according to side - side : buy means quote currency, BTC_USDT means USDT - side : sell means base currency, BTC_USDT means BTC |
» price | string | Price can't be empty when type = limit . |
» time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type =market |
» iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported. |
» auto_repay | boolean | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order. |
» left | string | Amount left to fill. |
» filled_amount | string | Amount traded to fill. |
» fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total . |
» filled_total | string | Total filled in quote currency. |
» avg_deal_price | string | Average fill price. |
» fee | string | Fee deducted. |
» fee_currency | string | Fee currency unit. |
» point_fee | string | Points used to deduct fee. |
» gt_fee | string | GT used to deduct fee. |
» gt_maker_fee | string | GT used to deduct maker fee. |
» gt_taker_fee | string | GT used to deduct taker fee. |
» gt_discount | boolean | Whether GT fee discount is used. |
» rebated_fee | string | Rebated fee. |
» rebated_fee_currency | string | Rebated fee currency unit. |
» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group , he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group , an error will be returned when passing the stp_act parameter. 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled |
» finish_as | string | Order completion statuses include: - open: Awaiting processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled due to liquidation - small: Order quantity too small - depth_not_enough: Cancelled due to insufficient market depth - trader_not_enough: Cancelled due to insufficient counterparty - ioc: Not immediately filled because tif is set to ioc - poc: Not met the order poc - fok: Not fully filled immediately because tif is set to fok - stp: Cancelled due to self-trade prevention - unknown: Unknown |
» fee_discount | string | rate discount. |
Property | Value |
---|---|
status | open |
status | closed |
status | cancelled |
type | limit |
type | market |
side | buy |
side | sell |
time_in_force | gtc |
time_in_force | ioc |
time_in_force | poc |
time_in_force | fok |
stp_act | cn |
stp_act | co |
stp_act | cb |
stp_act | - |
finish_as | open |
finish_as | filled |
finish_as | cancelled |
finish_as | liquidate_cancelled |
finish_as | depth_not_enough |
finish_as | trader_not_enough |
finish_as | small |
finish_as | ioc |
finish_as | poc |
finish_as | fok |
finish_as | stp |
finish_as | unknown |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/orders/12345'
query_param = 'currency_pair=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
PATCH /spot/orders/{order_id}
Amend an order.
Modify orders in spot, unified account and isolated margin account by default.
Currently both request body and query support currency_pair and account parameters, but request body has higher priority.
currency_pair must be filled in one of the request body or query parameters.
About rate limit: Order modification and order creation share the same rate limit rules.
About matching priority: Only reducing the quantity does not affect the matching priority. Modifying the price or increasing the quantity will adjust the priority to the end of the new price level.
Note: Modifying the quantity to be less than the filled quantity will trigger a cancellation and isolated margin account by default.
Currently both request body and query support currency_pair and account parameters, but request body has higher priority.
currency_pair must be filled in one of the request body or query parameters.
About rate limit: Order modification and order creation share the same rate limit rules.
About matching priority: Only reducing the quantity does not affect the matching priority. Modifying the price or increasing the quantity will adjust the priority to the end of the new price level.
Note: Modifying the quantity to be less than the filled quantity will trigger a cancellation operation.
Name | In | Type | Required | Description |
---|---|---|---|---|
order_id | path | string | true | The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field). |
currency_pair | query | string | false | Currency pair. |
account | query | string | false | Specify query account. |
x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
body | body | object | true | none |
» currency_pair | body | string | false | Currency pair. |
» account | body | string | false | Specify query account. |
» amount | body | string | false | Trading Quantity. Either amountor pricemust be specified. |
» price | body | string | false | Trading Price. Either amountor pricemust be specified. |
» amend_text | body | string | false | Custom info during amending order. |
» action_mode | body | string | false | Processing Mode: |
order_id: The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text
field).
Operations based on custom IDs can only be checked in pending orders. Only order ID can be used after the order is finished (transaction/cancel)
» action_mode: Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Updated. | 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 | When type is limit, it refers to base currency. For instance, BTC_USDT means BTC When different currency according to side - side : buy means quote currency, BTC_USDT means USDT - side : sell means base currency, BTC_USDT means BTC |
» price | string | Price can't be empty when type = limit . |
» time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type =market |
» iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported. |
» auto_repay | boolean | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order. |
» left | string | Amount left to fill. |
» filled_amount | string | Amount traded to fill. |
» fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total . |
» filled_total | string | Total filled in quote currency. |
» avg_deal_price | string | Average fill price. |
» fee | string | Fee deducted. |
» fee_currency | string | Fee currency unit. |
» point_fee | string | Points used to deduct fee. |
» gt_fee | string | GT used to deduct fee. |
» gt_maker_fee | string | GT used to deduct maker fee. |
» gt_taker_fee | string | GT used to deduct taker fee. |
» gt_discount | boolean | Whether GT fee discount is used. |
» rebated_fee | string | Rebated fee. |
» rebated_fee_currency | string | Rebated fee currency unit. |
» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group , he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group , an error will be returned when passing the stp_act parameter. 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled |
» finish_as | string | Order completion statuses include: - open: Awaiting processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled due to liquidation - small: Order quantity too small - depth_not_enough: Cancelled due to insufficient market depth - trader_not_enough: Cancelled due to insufficient counterparty - ioc: Not immediately filled because tif is set to ioc - poc: Not met the order poc - fok: Not fully filled immediately because tif is set to fok - stp: Cancelled due to self-trade prevention - unknown: Unknown |
» fee_discount | string | rate discount. |
Property | Value |
---|---|
status | open |
status | closed |
status | cancelled |
type | limit |
type | market |
side | buy |
side | sell |
time_in_force | gtc |
time_in_force | ioc |
time_in_force | poc |
time_in_force | fok |
stp_act | cn |
stp_act | co |
stp_act | cb |
stp_act | - |
finish_as | open |
finish_as | filled |
finish_as | cancelled |
finish_as | liquidate_cancelled |
finish_as | depth_not_enough |
finish_as | trader_not_enough |
finish_as | small |
finish_as | ioc |
finish_as | poc |
finish_as | fok |
finish_as | stp |
finish_as | unknown |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/orders/12345'
query_param = ''
body='{"currency_pair":"BTC_USDT","account":"spot","amount":"1"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PATCH', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"currency_pair": "BTC_USDT",
"account": "spot",
"amount": "1"
}
Example responses
200 Response
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
DELETE /spot/orders/{order_id}
Cancel a 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
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 | When type is limit, it refers to base currency. For instance, BTC_USDT means BTC When different currency according to side - side : buy means quote currency, BTC_USDT means USDT - side : sell means base currency, BTC_USDT means BTC |
» price | string | Price can't be empty when type = limit . |
» time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type =market |
» iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported. |
» auto_repay | boolean | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order. |
» left | string | Amount left to fill. |
» filled_amount | string | Amount traded to fill. |
» fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total . |
» filled_total | string | Total filled in quote currency. |
» avg_deal_price | string | Average fill price. |
» fee | string | Fee deducted. |
» fee_currency | string | Fee currency unit. |
» point_fee | string | Points used to deduct fee. |
» gt_fee | string | GT used to deduct fee. |
» gt_maker_fee | string | GT used to deduct maker fee. |
» gt_taker_fee | string | GT used to deduct taker fee. |
» gt_discount | boolean | Whether GT fee discount is used. |
» rebated_fee | string | Rebated fee. |
» rebated_fee_currency | string | Rebated fee currency unit. |
» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group , he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group , an error will be returned when passing the stp_act parameter. 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled |
» finish_as | string | Order completion statuses include: - open: Awaiting processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled due to liquidation - small: Order quantity too small - depth_not_enough: Cancelled due to insufficient market depth - trader_not_enough: Cancelled due to insufficient counterparty - ioc: Not immediately filled because tif is set to ioc - poc: Not met the order poc - fok: Not fully filled immediately because tif is set to fok - stp: Cancelled due to self-trade prevention - unknown: Unknown |
» fee_discount | string | rate discount. |
Property | Value |
---|---|
status | open |
status | closed |
status | cancelled |
type | limit |
type | market |
side | buy |
side | sell |
time_in_force | gtc |
time_in_force | ioc |
time_in_force | poc |
time_in_force | fok |
stp_act | cn |
stp_act | co |
stp_act | cb |
stp_act | - |
finish_as | open |
finish_as | filled |
finish_as | cancelled |
finish_as | liquidate_cancelled |
finish_as | depth_not_enough |
finish_as | trader_not_enough |
finish_as | small |
finish_as | ioc |
finish_as | poc |
finish_as | fok |
finish_as | stp |
finish_as | unknown |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/orders/12345'
query_param = 'currency_pair=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
GET /spot/my_trades
List personal trading history.
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 records to be returned in a single list. Default: 100, Minimum: 1, Maximum: 1000 |
page | query | integer(int32) | false | Page number. |
order_id | query | string | false | Filter trades with specified order ID. currency_pair is also required if this field is present |
account | query | string | false | Specify query account. |
from | query | integer(int64) | false | Start timestamp of the query. |
to | query | integer(int64) | false | Time range ending, default to current time. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» id | string | Trade ID. |
» create_time | string | Trading time. |
» create_time_ms | string | Trading time, with millisecond precision. |
» currency_pair | string | Currency pair. |
» side | string | Buy or sell order. |
» role | string | Trade role. No value in public endpoints. |
» amount | string | Trade amount. |
» price | string | Order price. |
» order_id | string | Related order ID. No value in public endpoints. |
» fee | string | Fee deducted. No value in public endpoints. |
» fee_currency | string | Fee currency unit. No value in public endpoints. |
» point_fee | string | Points used to deduct fee. No value in public endpoints. |
» gt_fee | string | GT used to deduct fee. No value in public endpoints. |
» amend_text | string | The custom data that the user remarked when amending the order. |
» sequence_id | string | Represents a unique and consecutive trade ID within a single market. It is used to track and identify trades in the specific market |
» text | string | User defined information. No value in public endpoints. |
Property | Value |
---|---|
side | buy |
side | sell |
role | taker |
role | maker |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/my_trades'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": "1232893232",
"create_time": "1548000000",
"create_time_ms": "1548000000123.456",
"order_id": "4128442423",
"side": "buy",
"role": "maker",
"amount": "0.15",
"price": "0.03",
"fee": "0.0005",
"fee_currency": "ETH",
"point_fee": "0",
"gt_fee": "0",
"sequence_id": "588018",
"text": "t-test"
}
]
GET /spot/time
Get server current time.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
SystemTime
Name | Type | Description |
---|---|---|
» server_time | integer(int64) | Server current time(ms). |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/time'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"server_time": 1597026383085
}
POST /spot/countdown_cancel_all
Countdown cancel orders.
Spot order heartbeat detection. If there is no "cancel existing countdown" or "set new countdown" when the user-set timeout
time is reached, the related spot pending orders
will be automatically cancelled.
This interface can be called repeatedly to set a new countdown or cancel the countdown.
Usage example: Repeat this interface at 30s intervals, setting the countdown timeout
to 30 (seconds)
each time.
If this interface is not called again within 30 seconds, all pending orders on the market
you specified will be automatically cancelled. If no market
is specified, all market cancelled.
If the timeout
is set to 0 within 30 seconds, the countdown timer will be terminated and the automatic order cancellation function will be cancelled.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» timeout | body | integer(int32) | true | Countdown time in seconds |
» currency_pair | body | string | false | Currency pair. |
» timeout: Countdown time in seconds At least 5 seconds, 0 means cancel countdown
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Set countdown successfully. | Inline |
Status Code 200
triggerTime
Name | Type | Description |
---|---|---|
» triggerTime | integer(int64) | Timestamp of the end of the countdown, in milliseconds. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/countdown_cancel_all'
query_param = ''
body='{"timeout":30,"currency_pair":"BTC_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"timeout": 30,
"currency_pair": "BTC_USDT"
}
Example responses
200 Response
{
"triggerTime": "1660039145000"
}
POST /spot/amend_batch_orders
Batch modification of orders.
Modify orders in spot, unified account and isolated margin account by default. Modify uncompleted orders, up to 5 orders can be modified at a time. Request parameters should be passed in array format. If there are order modification failures during the batch modification process, the modification of the next order will continue to be executed, and the execution will return with the corresponding order failure information. The call order of batch modification orders is consistent with the order list order. The return is consistent with the order list order.
Name | In | Type | Required | Description |
---|---|---|---|---|
x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
body | body | array[object] | true | none |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Order modification executed successfully. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Batch order details.] |
» None | object | Batch order details. |
»» order_id | string | Order ID. |
»» amend_text | string | The custom data that the user remarked when amending the order. |
»» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) |
»» succeeded | boolean | Whether the batch of orders succeeded. |
»» label | string | Error label, if any, otherwise an empty string. |
»» message | string | Detailed error message, if any, otherwise an empty string. |
»» id | string | Order ID. |
»» create_time | string | Creation time of order. |
»» update_time | string | Last modification time of order. |
»» create_time_ms | integer(int64) | Creation time of order (in milliseconds). |
»» update_time_ms | integer(int64) | Last modification time of order (in milliseconds). |
»» status | string | Order status - open : to be filled- closed : filled- cancelled : cancelled |
»» currency_pair | string | Currency pair. |
»» type | string | Order Type - limit : Limit Order - market : Market Order |
»» account | string | Account type, spot - 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 traded to fill. |
»» fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total . |
»» filled_total | string | Total filled in quote currency. |
»» avg_deal_price | string | Average fill price. |
»» fee | string | Fee deducted. |
»» fee_currency | string | Fee currency unit. |
»» point_fee | string | Points used to deduct fee. |
»» gt_fee | string | GT used to deduct fee. |
»» gt_discount | boolean | Whether GT fee discount is used. |
»» rebated_fee | string | Rebated fee. |
»» rebated_fee_currency | string | Rebated fee currency unit. |
»» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
»» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group , he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group , an error will be returned when passing the stp_act parameter. 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled |
»» finish_as | string | How the order was finished. - open: processing - filled: filled totally - cancelled: manually cancelled - ioc: time in force is IOC , finish immediately- stp: cancelled because self trade prevention |
Property | Value |
---|---|
status | open |
status | closed |
status | cancelled |
type | limit |
type | market |
account | spot |
account | margin |
account | cross_margin |
account | unified |
side | buy |
side | sell |
time_in_force | gtc |
time_in_force | ioc |
time_in_force | poc |
time_in_force | fok |
stp_act | cn |
stp_act | co |
stp_act | cb |
stp_act | - |
finish_as | open |
finish_as | filled |
finish_as | cancelled |
finish_as | ioc |
finish_as | stp |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/amend_batch_orders'
query_param = ''
body='[{"order_id":"121212","currency_pair":"BTC_USDT","account":"spot","amount":"1","amend_text":"test"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
[
{
"order_id": "121212",
"currency_pair": "BTC_USDT",
"account": "spot",
"amount": "1",
"amend_text": "test"
}
]
Example responses
200 Response
[
{
"order_id": "12332324",
"amend_text": "t-123456",
"text": "t-123456",
"succeeded": true,
"label": "",
"message": "",
"id": "12332324",
"create_time": "1548000000",
"update_time": "1548000100",
"create_time_ms": 1548000000123,
"update_time_ms": 1548000100123,
"currency_pair": "ETC_BTC",
"status": "cancelled",
"type": "limit",
"account": "spot",
"side": "buy",
"amount": "1",
"price": "5.00032",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0.5",
"filled_amount": "1.242",
"filled_total": "2.50016",
"avg_deal_price": "5.00032",
"fee": "0.005",
"fee_currency": "ETH",
"point_fee": "0",
"gt_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "BTC",
"stp_act": "cn",
"finish_as": "stp",
"stp_id": 10240
}
]
GET /spot/insurance_history
Query spot insurance fund historical data.
Name | In | Type | Required | Description |
---|---|---|---|---|
business | query | string | true | Leverage business, margin - position by position; unified - unified account |
currency | query | string | true | Currency. |
page | query | integer(int32) | false | Page number. |
limit | query | integer | false | The maximum number of items returned in the list, the default value is 30. |
from | query | integer(int64) | true | Start timestamp, seconds. |
to | query | integer(int64) | true | End timestamp, in seconds. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» currency | string | Currency. |
» balance | string | balance. |
» time | integer(int64) | Creation time, timestamp, milliseconds. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/insurance_history'
query_param = 'business=margin¤cy=BTC&from=1547706332&to=1547706332'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "BTC",
"balance": "1021.21",
"time": 1727054547
}
]
POST /spot/price_orders
Create a price-triggered order.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | SpotPriceTriggeredOrder | true | none |
» trigger | body | object | true | none |
»» price | body | string | true | Trigger price. |
»» rule | body | string | true | Price trigger condition |
»» expiration | body | integer | true | How long (in seconds) to wait for the condition to be triggered before cancelling the order. |
» put | body | object | true | none |
»» type | body | string | false | Order type, default to limit |
»» side | body | string | true | Order side |
»» price | body | string | true | Order price. |
»» amount | body | string | true | When type is limit, it refers to base currency. For instance, BTC_USDT means BTC |
»» account | body | string | true | Trading account type. Portfolio margin account must set to 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 | Currency pair. |
»» rule: Price trigger condition
>=
: triggered when market price larger than or equal to price
field<=
: or equal to price
field»» type: Order type, default to limit
»» side: Order side
»» amount: When type
is limit, it refers to base currency. For instance, BTC_USDT
means BTC
When different currency according to side
side
: buy
means quote currency, BTC_USDT
means USDT
side
: sell
means base currency, BTC_USDT
means BTC
»» account: Trading account type. Portfolio margin account must set to unified
-normal: spot trading
»» time_in_force: time_in_force
»» text: The source of the order, including:
Parameter | Value |
---|---|
»» rule | >= |
»» rule | <= |
»» type | limit |
»» type | market |
»» side | buy |
»» side | sell |
»» account | normal |
»» account | margin |
»» account | unified |
»» time_in_force | gtc |
»» time_in_force | ioc |
Status | Meaning | Description | Schema |
---|---|---|---|
201 | Created (opens new window) | Order created. | Inline |
Status Code 201
TriggerOrderResponse
Name | Type | Description |
---|---|---|
» id | integer(int64) | Auto order ID. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/price_orders'
query_param = ''
body='{"trigger":{"price":"100","rule":">=","expiration":3600},"put":{"type":"limit","side":"buy","price":"2.15","amount":"2.00000000","account":"normal","time_in_force":"gtc","text":"api"},"market":"GT_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"trigger": {
"price": "100",
"rule": ">=",
"expiration": 3600
},
"put": {
"type": "limit",
"side": "buy",
"price": "2.15",
"amount": "2.00000000",
"account": "normal",
"time_in_force": "gtc",
"text": "api"
},
"market": "GT_USDT"
}
Example responses
201 Response
{
"id": 1432329
}
GET /spot/price_orders
Retrieve running auto order list.
Name | In | Type | Required | Description |
---|---|---|---|---|
status | query | string | true | Only list the orders with this status. |
market | query | string | false | Currency pair. |
account | query | string | false | Trading account type. Portfolio margin account must set to unified . |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
Parameter | Value |
---|---|
status | open |
status | finished |
account | normal |
account | margin |
account | unified |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [SpotPriceTriggeredOrder] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/price_orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"trigger": {
"price": "100",
"rule": ">=",
"expiration": 3600
},
"put": {
"type": "limit",
"side": "buy",
"price": "2.15",
"amount": "2.00000000",
"account": "normal",
"time_in_force": "gtc",
"text": "api"
},
"id": 1283293,
"user": 1234,
"market": "GT_USDT",
"ctime": 1616397800,
"ftime": 1616397801,
"fired_order_id": 0,
"status": "",
"reason": ""
}
]
DELETE /spot/price_orders
Cancel All Price-triggered Orders.
Name | In | Type | Required | Description |
---|---|---|---|---|
market | query | string | false | Currency pair. |
account | query | string | false | Trading account type. Portfolio margin account must set to unified . |
Parameter | Value |
---|---|
account | normal |
account | margin |
account | unified |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Batch cancellation request accepted. Query order status by listing orders. | [SpotPriceTriggeredOrder] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/price_orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"trigger": {
"price": "100",
"rule": ">=",
"expiration": 3600
},
"put": {
"type": "limit",
"side": "buy",
"price": "2.15",
"amount": "2.00000000",
"account": "normal",
"time_in_force": "gtc",
"text": "api"
},
"id": 1283293,
"user": 1234,
"market": "GT_USDT",
"ctime": 1616397800,
"ftime": 1616397801,
"fired_order_id": 0,
"status": "",
"reason": ""
}
]
GET /spot/price_orders/{order_id}
Get a price-triggered order.
Name | In | Type | Required | Description |
---|---|---|---|---|
order_id | path | string | true | Retrieve the data of the order with the specified ID. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Auto order detail. | SpotPriceTriggeredOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"trigger": {
"price": "100",
"rule": ">=",
"expiration": 3600
},
"put": {
"type": "limit",
"side": "buy",
"price": "2.15",
"amount": "2.00000000",
"account": "normal",
"time_in_force": "gtc",
"text": "api"
},
"id": 1283293,
"user": 1234,
"market": "GT_USDT",
"ctime": 1616397800,
"ftime": 1616397801,
"fired_order_id": 0,
"status": "",
"reason": ""
}
DELETE /spot/price_orders/{order_id}
cancel a price-triggered order.
Name | In | Type | Required | Description |
---|---|---|---|---|
order_id | path | string | true | Retrieve the data of the order with the specified ID. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Auto order detail. | SpotPriceTriggeredOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"trigger": {
"price": "100",
"rule": ">=",
"expiration": 3600
},
"put": {
"type": "limit",
"side": "buy",
"price": "2.15",
"amount": "2.00000000",
"account": "normal",
"time_in_force": "gtc",
"text": "api"
},
"id": 1283293,
"user": 1234,
"market": "GT_USDT",
"ctime": 1616397800,
"ftime": 1616397801,
"fired_order_id": 0,
"status": "",
"reason": ""
}
Flash swap.
GET /flash_swap/currency_pairs
List All Supported Currency Pairs In Flash Swap.
BTC_GT
represents selling BTC and buying GT. The limits for each currency may vary across different currency pairs.
It is not necessary that two currencies that can be swapped instantaneously can be exchanged with each other. For example, it is possible to sell BTC and buy GT, but it does not necessarily mean that GT can be sold to buy BTC.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Retrieve data of the specified currency. |
page | query | integer(int32) | false | Page number. |
limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 1000. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | List all supported currencies in flash swap. |
»» currency_pair | string | The currency pair, BTC_USDT represents selling Bitcoin (BTC) and buying Tether (USDT). |
»» sell_currency | string | The currency to be sold. |
»» buy_currency | string | The currency to be bought. |
»» sell_min_amount | string | The minimum quantity required for selling. |
»» sell_max_amount | string | The maximum quantity allowed for selling. |
»» buy_min_amount | string | The minimum quantity required for buying. |
»» buy_max_amount | string | The maximum quantity allowed for buying. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/flash_swap/currency_pairs'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency_pair": "BTC_USDT",
"sell_currency": "BTC",
"buy_currency": "USDT",
"sell_min_amount": "0.00001",
"sell_max_amount": "100",
"buy_min_amount": "10",
"buy_max_amount": "10000000"
}
]
POST /flash_swap/orders
Create a flash swap order.
Initiate a flash swap preview in advance because order creation requires a preview result
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» preview_id | body | string | true | Preview result ID. |
» sell_currency | body | string | true | Name of the asset to be sold, obtained from the interface GET /flash_swap/currency_pairs: Query the list of all trading pairs supporting flash swap |
» sell_amount | body | string | true | Amount to sell (based on the preview result). |
» buy_currency | body | string | true | Name of the asset to be bought, obtained from the interface GET /flash_swap/currency_pairs: Query the list of all trading pairs supporting flash swap |
» buy_amount | body | string | true | Amount to buy (based on the preview result). |
Status | Meaning | Description | Schema |
---|---|---|---|
201 | Created (opens new window) | The flash swap order is created successfully. | Inline |
Status Code 201
Flash swap order.
Name | Type | Description |
---|---|---|
» id | integer(int64) | Flash swap order ID. |
» create_time | integer(int64) | Creation time of order (in milliseconds). |
» user_id | integer(int64) | User ID. |
» sell_currency | string | Currency to sell. |
» sell_amount | string | Amount to sell. |
» buy_currency | string | Currency to buy. |
» buy_amount | string | Amount to buy. |
» price | string | Price. |
» status | integer | Flash swap order status1 - success2 - failure |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/flash_swap/orders'
query_param = ''
body='{"preview_id":"4564564","sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT","buy_amount":"10"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"preview_id": "4564564",
"sell_currency": "BTC",
"sell_amount": "0.1",
"buy_currency": "USDT",
"buy_amount": "10"
}
Example responses
201 Response
{
"id": 54646,
"create_time": 1651116876378,
"update_time": 1651116876378,
"user_id": 11135567,
"sell_currency": "BTC",
"sell_amount": "0.01",
"buy_currency": "USDT",
"buy_amount": "10",
"price": "100",
"status": 1
}
GET /flash_swap/orders
List all flash swap orders.
Name | In | Type | Required | Description |
---|---|---|---|---|
status | query | integer | false | Flash swap order status |
sell_currency | query | string | false | Currency to sell which can be retrieved from supported currency list API GET /flash_swap/currencies |
buy_currency | query | string | false | Currency to buy which can be retrieved from supported currency list API GET /flash_swap/currencies |
reverse | query | boolean | false | If results are sorted by id in reverse order. Default to true |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
page | query | integer(int32) | false | Page number. |
status: Flash swap order status
1
- success
2
- failure
reverse: If results are sorted by id in reverse order. Default to true
true
: sort by id in descending order(recent first)Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Flash swap order.] |
» None | object | Flash swap order. |
»» id | integer(int64) | Flash swap order ID. |
»» create_time | integer(int64) | Creation time of order (in milliseconds). |
»» user_id | integer(int64) | User ID. |
»» sell_currency | string | Currency to sell. |
»» sell_amount | string | Amount to sell. |
»» buy_currency | string | Currency to buy. |
»» buy_amount | string | Amount to buy. |
»» price | string | Price. |
»» status | integer | Flash swap order status1 - success2 - failure |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/flash_swap/orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 54646,
"create_time": 1651116876378,
"update_time": 1651116876378,
"user_id": 11135567,
"sell_currency": "BTC",
"sell_amount": "0.01",
"buy_currency": "USDT",
"buy_amount": "10",
"price": "100",
"status": 1
}
]
GET /flash_swap/orders/{order_id}
Get a single flash swap order's detail.
Name | In | Type | Required | Description |
---|---|---|---|---|
order_id | path | integer | true | Flash swap order ID. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Flash swap order.
Name | Type | Description |
---|---|---|
» id | integer(int64) | Flash swap order ID. |
» create_time | integer(int64) | Creation time of order (in milliseconds). |
» user_id | integer(int64) | User ID. |
» sell_currency | string | Currency to sell. |
» sell_amount | string | Amount to sell. |
» buy_currency | string | Currency to buy. |
» buy_amount | string | Amount to buy. |
» price | string | Price. |
» status | integer | Flash swap order status1 - success2 - failure |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/flash_swap/orders/1'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"id": 54646,
"create_time": 1651116876378,
"update_time": 1651116876378,
"user_id": 11135567,
"sell_currency": "BTC",
"sell_amount": "0.01",
"buy_currency": "USDT",
"buy_amount": "10",
"price": "100",
"status": 1
}
POST /flash_swap/orders/preview
Initiate a flash swap order preview.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» sell_currency | body | string | true | The name of the asset being sold, as obtained from the "GET /flash_swap/currency_pairs" API, which retrieves a list of supported flash swap currency pairs. |
» sell_amount | body | string | false | Amount to sell. |
» buy_currency | body | string | true | The name of the asset being purchased, as obtained from the "GET /flash_swap/currency_pairs" API, which provides a list of supported flash swap currency pairs. |
» buy_amount | body | string | false | Amount to buy. |
» sell_amount: Amount to sell.
It is required to choose one parameter between sell_amount
and buy_amount
» buy_amount: Amount to buy.
It is required to choose one parameter between sell_amount
and buy_amount
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | The flash swap order successfully previewed. | Inline |
Status Code 200
Initiate a flash swap order preview.
Name | Type | Description |
---|---|---|
» preview_id | string | Preview result ID. |
» sell_currency | string | Name of the sold asset, Refer to the interface Query the list of currencies supported for flash swap GET /flash_swap/currenciesto obtain |
» sell_amount | string | Amount to sell. |
» buy_currency | string | Name of the purchased asset, Refer to the interface Query the list of currencies supported for flash swap GET /flash_swap/currenciesto obtain |
» buy_amount | string | Amount to buy. |
» price | string | Price. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/flash_swap/orders/preview'
query_param = ''
body='{"sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"sell_currency": "BTC",
"sell_amount": "0.1",
"buy_currency": "USDT"
}
Example responses
200 Response
{
"preview_id": "3453434",
"sell_currency": "BTC",
"sell_amount": "0.1",
"buy_currency": "USDT",
"buy_amount": "10",
"price": "100"
}
Futures contract API.
GET /futures/{settle}/contracts
List all futures contracts.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Contract] |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/contracts'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"name": "BTC_USDT",
"type": "direct",
"quanto_multiplier": "0.0001",
"ref_discount_rate": "0",
"order_price_deviate": "0.5",
"maintenance_rate": "0.005",
"mark_type": "index",
"last_price": "38026",
"mark_price": "37985.6",
"index_price": "37954.92",
"funding_rate_indicative": "0.000219",
"mark_price_round": "0.01",
"funding_offset": 0,
"in_delisting": false,
"risk_limit_base": "1000000",
"interest_rate": "0.0003",
"order_price_round": "0.1",
"order_size_min": 1,
"ref_rebate_rate": "0.2",
"funding_interval": 28800,
"risk_limit_step": "1000000",
"leverage_min": "1",
"leverage_max": "100",
"risk_limit_max": "8000000",
"maker_fee_rate": "-0.00025",
"taker_fee_rate": "0.00075",
"funding_rate": "0.002053",
"order_size_max": 1000000,
"funding_next_apply": 1610035200,
"short_users": 977,
"config_change_time": 1609899548,
"trade_size": 28530850594,
"position_size": 5223816,
"long_users": 455,
"funding_impact_value": "60000",
"orders_limit": 50,
"trade_id": 10851092,
"orderbook_id": 2129638396,
"enable_bonus": true,
"enable_credit": true,
"create_time": 1669688556,
"funding_cap_ratio": "0.75",
"status": "trading",
"launch_time": 1609899548
}
]
GET /futures/{settle}/contracts/{contract}
Get a single contract.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | path | string | true | Futures contract. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Contract information. | Contract |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/contracts/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"name": "BTC_USDT",
"type": "direct",
"quanto_multiplier": "0.0001",
"ref_discount_rate": "0",
"order_price_deviate": "0.5",
"maintenance_rate": "0.005",
"mark_type": "index",
"last_price": "38026",
"mark_price": "37985.6",
"index_price": "37954.92",
"funding_rate_indicative": "0.000219",
"mark_price_round": "0.01",
"funding_offset": 0,
"in_delisting": false,
"risk_limit_base": "1000000",
"interest_rate": "0.0003",
"order_price_round": "0.1",
"order_size_min": 1,
"ref_rebate_rate": "0.2",
"funding_interval": 28800,
"risk_limit_step": "1000000",
"leverage_min": "1",
"leverage_max": "100",
"risk_limit_max": "8000000",
"maker_fee_rate": "-0.00025",
"taker_fee_rate": "0.00075",
"funding_rate": "0.002053",
"order_size_max": 1000000,
"funding_next_apply": 1610035200,
"short_users": 977,
"config_change_time": 1609899548,
"trade_size": 28530850594,
"position_size": 5223816,
"long_users": 455,
"funding_impact_value": "60000",
"orders_limit": 50,
"trade_id": 10851092,
"orderbook_id": 2129638396,
"enable_bonus": true,
"enable_credit": true,
"create_time": 1669688556,
"funding_cap_ratio": "0.75",
"status": "trading",
"launch_time": 1609899548
}
GET /futures/{settle}/order_book
Futures order book.
Bids will be sorted by price from high to low, while asks sorted reversely.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | true | Futures contract. |
interval | query | string | false | Order depth. 0 means no aggregation is applied. default to 0. |
limit | query | integer | false | Maximum number of order depth data in asks or bids. |
with_id | query | boolean | false | Whether to return depth update ID. This ID increments by 1 each time. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Depth query successful. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» id | integer(int64) | Order Book ID. Increases by 1 on every order book change. Set with_id=true to include this field in response |
» current | number(double) | Response data generation timestamp. |
» update | number(double) | Order book changed timestamp. |
» asks | array | Asks order depth. |
»» futures_order_book_item | object | none |
»»» p | string | Price (quote currency). |
»»» s | integer(int64) | Size. |
»» bids | array | Bids order depth. |
»»» futures_order_book_item | object | none |
»»»» p | string | Price (quote currency). |
»»»» s | integer(int64) | Size. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/order_book'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"id": 123456,
"current": 1623898993.123,
"update": 1623898993.121,
"asks": [
{
"p": "1.52",
"s": 100
},
{
"p": "1.53",
"s": 40
}
],
"bids": [
{
"p": "1.17",
"s": 150
},
{
"p": "1.16",
"s": 203
}
]
}
GET /futures/{settle}/trades
Futures trading history.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | true | Futures contract. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
last_id | query | string | false | Specify the starting point for this list based on a previously retrieved id |
from | query | integer(int64) | false | Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items. |
to | query | integer(int64) | false | Specify end time in Unix seconds, default to current time. |
last_id: Specify the starting point for this list based on a previously retrieved id
This parameter is deprecated. Use from
and to
instead to limit time range
from: Specify starting time in Unix seconds. If not specified, to
and limit
will be used to limit response items.
If items between from
and to
are more than limit
, only limit
number will be returned.
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» id | integer(int64) | Trade ID. |
» create_time | number(double) | Trading time. |
» create_time_ms | number(double) | Trading time, with milliseconds set to 3 decimal places. |
» contract | string | Futures contract. |
» size | integer(int64) | Trading size. |
» price | string | Trading price (quote currency). |
» is_internal | boolean | Whether internal trade. Internal trade refers to the takeover of liquidation orders by the insurance fund and ADL users. Since it is not a normal matching on the market depth, the transaction price may deviate, and it will not be recorded in the K-line. an internal trade, this field will not be returned. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/trades'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800,
"contract": "BTC_USDT",
"size": -100,
"price": "100.123"
}
]
GET /futures/{settle}/candlesticks
Get futures candlesticks.
Return specified contract candlesticks.
If prefix contract
with mark_
, the contract's mark price candlesticks are returned;
if prefix with index_
, index price candlesticks will be returned.
Maximum of 2000 points are returned in one query. Be sure not to exceed the limit when specifying from
, to
and interval
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | true | Futures contract. |
from | query | integer(int64) | false | Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified |
to | query | integer(int64) | false | 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 specified |
limit | query | integer | false | Maximum recent data points to return. limit is conflicted with from and to . If either from or to is specified, request will be rejected. |
interval | query | string | false | Interval time between data points. Note that 1w means natual week(Mon-Sun), while 7d means every 7d since unix 0. 1 natual month, not 30 days |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
interval | 10s |
interval | 1m |
interval | 5m |
interval | 15m |
interval | 30m |
interval | 1h |
interval | 4h |
interval | 8h |
interval | 1d |
interval | 7d |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [data point in every timestamp.] |
» None | object | data point in every timestamp. |
»» t | number(double) | Unix timestamp in seconds. |
»» v | integer(int64) | size volume (contract size). Only returned if contract is not prefixed. |
»» c | string | Close price (quote currency). |
»» h | string | Highest price (quote currency). |
»» l | string | Lowest price (quote currency). |
»» o | string | Open price (quote currency). |
»» sum | string | Trading volume (unit: Quote currency). |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/candlesticks'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"t": 1539852480,
"v": 97151,
"c": "1.032",
"h": "1.032",
"l": "1.032",
"o": "1.032",
"sum": "3580"
}
]
GET /futures/{settle}/premium_index
Premium Index K-Line.
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 specified |
limit | query | integer | false | Maximum recent data points to return. limit is conflicted with from and to . If either from or to is specified, request will be rejected. |
interval | query | string | false | Interval time between data points. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
interval | 10s |
interval | 1m |
interval | 5m |
interval | 15m |
interval | 30m |
interval | 1h |
interval | 4h |
interval | 8h |
interval | 1d |
interval | 7d |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | data point in every timestamp. |
»» t | number(double) | Unix timestamp in seconds. |
»» c | string | Close price. |
»» h | string | Highest price. |
»» l | string | Lowest price`. |
»» o | string | Open price. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/premium_index'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"t": 1539852480,
"c": "0",
"h": "0.00023",
"l": "0",
"o": "0"
}
]
GET /futures/{settle}/tickers
List futures tickers.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | false | Futures contract, return related data only if specified. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» contract | string | Futures contract. |
» last | string | Last trading price. |
» change_percentage | string | Change percentage. |
» total_size | string | Contract total size. |
» low_24h | string | Lowest trading price in recent 24h. |
» high_24h | string | Highest trading price in recent 24h. |
» volume_24h | string | Trade size in recent 24h. |
» volume_24h_btc | string | Trade volumes in recent 24h in BTC(deprecated, use volume_24h_base , volume_24h_quote , volume_24h_settle instead) |
» volume_24h_usd | string | Trade volumes in recent 24h in USD(deprecated, use volume_24h_base , volume_24h_quote , volume_24h_settle instead) |
» volume_24h_base | string | Trade volume in recent 24h, in base currency. |
» volume_24h_quote | string | Trade volume in recent 24h, in quote currency. |
» volume_24h_settle | string | Trade volume in recent 24h, in settle currency. |
» mark_price | string | Recent mark price. |
» funding_rate | string | Funding rate. |
» funding_rate_indicative | string | Indicative Funding rate in next period. (deprecated. use funding_rate ). |
» index_price | string | Index price. |
» quanto_base_rate | string | Exchange rate of base currency and settlement currency in Quanto contract. Does not exists in contracts of other types |
» lowest_ask | string | Recent lowest ask. |
» lowest_size | string | The latest seller's lowest price order quantity. |
» highest_bid | string | Recent highest bid. |
» highest_size | string | The latest buyer's highest price order volume. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/tickers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"contract": "BTC_USDT",
"last": "6432",
"low_24h": "6278",
"high_24h": "6790",
"change_percentage": "4.43",
"total_size": "32323904",
"volume_24h": "184040233284",
"volume_24h_btc": "28613220",
"volume_24h_usd": "184040233284",
"volume_24h_base": "28613220",
"volume_24h_quote": "184040233284",
"volume_24h_settle": "28613220",
"mark_price": "6534",
"funding_rate": "0.0001",
"funding_rate_indicative": "0.0001",
"index_price": "6531",
"highest_bid": "34089.7",
"highest_size": "100",
"lowest_ask": "34217.9",
"lowest_size": "1000"
}
]
GET /futures/{settle}/funding_rate
Funding rate history.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | true | Futures contract. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | History retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» t | integer(int64) | Unix timestamp in seconds. |
» r | string | Funding rate. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/funding_rate'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"t": 1543968000,
"r": "0.000157"
}
]
GET /futures/{settle}/insurance
Futures insurance balance history.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» t | integer(int64) | Unix timestamp in seconds. |
» b | string | Insurance balance. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/insurance'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"t": 1543968000,
"b": "83.0031"
}
]
GET /futures/{settle}/contract_stats
Futures stats.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | true | Futures contract. |
from | query | integer(int64) | false | Start timestamp. |
interval | query | string | false | none |
limit | query | integer | false | none |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» time | integer(int64) | Stat timestamp. |
» lsr_taker | number | Long/short account number ratio. |
» lsr_account | number | Long/short taker size ratio. |
» long_liq_size | integer(int64) | Long liquidation size. |
» long_liq_amount | number(double) | Long liquidation amount(base currency). |
» long_liq_usd | number(double) | Long liquidation volume(quote currency). |
» short_liq_size | integer(int64) | Short liquidation size. |
» short_liq_amount | number(double) | Short liquidation amount(base currency). |
» short_liq_usd | number(double) | Short liquidation volume(quote currency). |
» open_interest | integer(int64) | Open interest size. |
» open_interest_usd | number(double) | Open interest volume(quote currency). |
» top_lsr_account | number(double) | Top trader long/short account ratio. |
» top_lsr_size | number(double) | Top trader long/short position ratio. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/contract_stats'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"time": 1603865400,
"lsr_taker": 100,
"lsr_account": 0.5,
"long_liq_size": 0,
"short_liq_size": 0,
"open_interest": 124724,
"short_liq_usd": 0,
"mark_price": "8865",
"top_lsr_size": 1.02,
"short_liq_amount": 0,
"long_liq_amount": 0,
"open_interest_usd": 1511,
"top_lsr_account": 1.5,
"long_liq_usd": 0
}
]
GET /futures/{settle}/index_constituents/{index}
Get index constituents.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
index | path | string | true | Index name. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» index | string | Index name. |
» constituents | array | Constituents. |
»» IndexConstituent | object | none |
»»» exchange | string | Exchange. |
»»» symbols | array | Symbol list. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/index_constituents/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"index": "BTC_USDT",
"constituents": [
{
"exchange": "Binance",
"symbols": [
"BTC_USDT"
]
},
{
"exchange": "Gate.com",
"symbols": [
"BTC_USDT"
]
},
{
"exchange": "Huobi",
"symbols": [
"BTC_USDT"
]
}
]
}
GET /futures/{settle}/liq_orders
Retrieve liquidation 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 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 to be returned in a single list. |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» time | integer(int64) | Liquidation time. |
» contract | string | Futures contract. |
» size | integer(int64) | User position size. |
» order_size | integer(int64) | Number of forced liquidation orders. |
» order_price | string | Liquidation order price. |
» fill_price | string | Liquidation order average taker price. |
» left | integer(int64) | System liquidation order maker size. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/liq_orders'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"time": 1548654951,
"contract": "BTC_USDT",
"size": 600,
"order_size": -600,
"order_price": "3405",
"fill_price": "3424",
"left": 0
}
]
GET /futures/{settle}/risk_limit_tiers
List risk limit tiers.
When the 'contract' parameter is not passed, the default is to query the risk limits for the top 100 markets.'Limit' and 'offset' correspond to pagination queries at the market level, not to the length of the returned array. This only takes effect empty.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | false | Futures contract, return related data only if specified. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Retrieve risk limit configurations for different tiers under a specified contract.] |
» None | object | Retrieve risk limit configurations for different tiers under a specified contract. |
»» tier | integer(int) | Tier. |
»» risk_limit | string | Position risk limit. |
»» initial_rate | string | Initial margin rate. |
»» maintenance_rate | string | Maintenance margin rate. |
»» leverage_max | string | Maximum leverage. |
»» contract | string | Markets, visible only during market pagination requests. |
»» deduction | string | Maintenance margin quick calculation deduction. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/risk_limit_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"maintenance_rate": "0.01",
"tier": 1,
"initial_rate": "0.02",
"leverage_max": "50",
"risk_limit": "20000",
"contract": "ZTX_USDT",
"deduction": "0"
},
{
"maintenance_rate": "0.013",
"tier": 2,
"initial_rate": "0.025",
"leverage_max": "40",
"risk_limit": "30000",
"contract": "ZTX_USDT",
"deduction": "60"
},
{
"maintenance_rate": "0.015",
"tier": 3,
"initial_rate": "0.02857",
"leverage_max": "35",
"risk_limit": "50000",
"contract": "ZTX_USDT",
"deduction": "120"
},
{
"maintenance_rate": "0.02",
"tier": 4,
"initial_rate": "0.03333",
"leverage_max": "30",
"risk_limit": "70000",
"contract": "ZTX_USDT",
"deduction": "370"
},
{
"maintenance_rate": "0.025",
"tier": 5,
"initial_rate": "0.04",
"leverage_max": "25",
"risk_limit": "100000",
"contract": "ZTX_USDT",
"deduction": "720"
}
]
GET /futures/{settle}/accounts
Query futures account.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» total | string | total is the balance after the user's accumulated deposit, withdraw, profit and loss (including realized profit and loss, fund, fee and referral rebate), excluding unrealized profit and loss. total = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund) |
» unrealised_pnl | string | Unrealized PNL. |
» position_margin | string | Position margin. |
» order_margin | string | Order margin of unfinished orders. |
» available | string | The available balance for transferring or trading(including bonus. Bonus can't be withdrawn. The transfer amount needs to deduct the bonus) |
» point | string | POINT amount. |
» currency | string | Settle currency. |
» in_dual_mode | boolean | Whether dual mode is enabled. |
» enable_credit | boolean | Whether portfolio margin account mode is enabled. |
» position_initial_margin | string | Initial margin position, applicable to the portfolio margin account model. |
» maintenance_margin | string | The maintenance deposit occupied by the position is suitable for the new classic account margin model and unified account model |
» bonus | string | Perpetual Contract Bonus. |
» enable_evolved_classic | boolean | Classic account margin mode, true-new mode, false-old mode. |
» cross_order_margin | string | Full -warehouse hanging order deposit, suitable for the new classic account margin model |
» cross_initial_margin | string | The initial security deposit of the full warehouse is suitable for the new classic account margin model |
» cross_maintenance_margin | string | Maintain deposit in full warehouse, suitable for new classic account margin models |
» cross_unrealised_pnl | string | The full warehouse does not achieve profit and loss, suitable for the new classic account margin model |
» cross_available | string | Full warehouse available amount, suitable for the new classic account margin model |
» cross_margin_balance | string | Full margin balance, suitable for the new classic account margin model. |
» cross_mmr | string | Maintain margin ratio for the full position, suitable for the new classic account margin model |
» cross_imr | string | The initial margin rate of the full position is suitable for the new classic account margin model |
» isolated_position_margin | string | Ware -position margin, suitable for the new classic account margin model. |
» enable_new_dual_mode | boolean | Whether to open a new two-way position mode. |
» margin_mode | integer | Margin mode, 0-classic margin mode, 1-cross-currency margin mode, 2-combined margin mode |
» enable_tiered_mm | boolean | Whether to enable tiered maintenance margin calculation. |
» position_voucher_total | string | Total Position Experience Coupon Amount in Account. |
» history | object | Statistical data. |
»» dnw | string | total amount of deposit and withdraw. |
»» pnl | string | total amount of trading profit and loss. |
»» fee | string | total amount of fee. |
»» refr | string | total amount of referrer rebates. |
»» fund | string | total amount of funding costs. |
»» point_dnw | string | total amount of point deposit and withdraw. |
»» point_fee | string | total amount of point fee. |
»» point_refr | string | total amount of referrer rebates of point fee. |
»» bonus_dnw | string | total amount of perpetual contract bonus transfer. |
»» bonus_offset | string | total amount of perpetual contract bonus deduction. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"user": 1666,
"currency": "USDT",
"total": "9707.803567115145",
"unrealised_pnl": "3371.248828",
"position_margin": "38.712189181",
"order_margin": "0",
"available": "9669.091377934145",
"point": "0",
"bonus": "0",
"in_dual_mode": false,
"enable_evolved_classic": false,
"cross_initial_margin": "61855.56788525",
"cross_maintenance_margin": "682.04678105",
"cross_order_margin": "0",
"cross_unrealised_pnl": "1501.178222634128",
"cross_available": "27549.406108813951",
"cross_margin_balance": "10371.77306201952",
"cross_mmr": "797.2134",
"cross_imr": "116.6097",
"isolated_position_margin": "0",
"history": {
"dnw": "10000",
"pnl": "68.3685",
"fee": "-1.645812875",
"refr": "0",
"fund": "-358.919120009855",
"point_dnw": "0",
"point_fee": "0",
"point_refr": "0",
"bonus_dnw": "0",
"bonus_offset": "0"
},
"enable_tiered_mm": true
}
GET /futures/{settle}/account_book
Query account book.
If the contract field is passed, only records containing this field after 2023-10-30 can be filtered. 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 to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
type | query | string | false | Changing Type: |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
type: Changing Type:
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» time | number(double) | Change time. |
» change | string | Change amount. |
» balance | string | Balance after change. |
» type | string | Changing Type: - dnw: Deposit & Withdraw - pnl: Profit & Loss by reducing position - fee: Trading fee - refr: Referrer rebate - fund: Funding - point_dnw: point_fee: POINT Trading fee - point_refr: POINT Referrer rebate - bonus_offset: bouns deduction |
» text | string | Comment. |
» contract | string | Futures contract, the field is only available for data after 2023-10-30. |
» trade_id | string | trade id. |
» id | string | Account change record ID. |
Property | Value |
---|---|
type | dnw |
type | pnl |
type | fee |
type | refr |
type | fund |
type | point_dnw |
type | point_fee |
type | point_refr |
type | bonus_offset |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"time": 1682294400.123456,
"change": "0.000010152188",
"balance": "4.59316525194",
"text": "ETH_USD:6086261",
"type": "fee",
"contract": "ETH_USD",
"trade_id": "1",
"id": "1"
}
]
GET /futures/{settle}/positions
List all positions of a user.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
holding | query | boolean | false | Return only real positions - true, return all - false. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Position] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
GET /futures/{settle}/positions/{contract}
Get single position.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | path | string | true | Futures contract. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Position information. | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions/BTC_USDT'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
POST /futures/{settle}/positions/{contract}/margin
Update position margin.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | path | string | true | Futures contract. |
change | query | string | true | Margin change amount, positive number increases, negative number. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Position information. | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions/BTC_USDT/margin'
query_param = 'change=0.01'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
POST /futures/{settle}/positions/{contract}/leverage
Update position leverage.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | path | string | true | Futures contract. |
leverage | query | string | true | New position leverage. |
cross_leverage_limit | query | string | false | Cross margin leverage(valid only when leverage is 0). |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Position information. | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions/BTC_USDT/leverage'
query_param = 'leverage=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
POST /futures/{settle}/positions/cross_mode
Switch to the full position-by-store mode.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
body | body | object | true | none |
» mode | body | string | true | Full position-by-position model, ISOLATED-by-position, CROSS-full position. |
» contract | body | string | true | Contract Market. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Position information. | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions/cross_mode'
query_param = ''
body='{"mode":"ISOLATED","contract":"BTC_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"mode": "ISOLATED",
"contract": "BTC_USDT"
}
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
POST /futures/{settle}/dual_comp/positions/cross_mode
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
body | body | object | true | none |
» mode | body | string | true | Full position-by-position model, ISOLATED-by-position, CROSS-full position. |
» contract | body | string | true | Contract Market. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Position] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_comp/positions/cross_mode'
query_param = ''
body='{"mode":"ISOLATED","contract":"BTC_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"mode": "ISOLATED",
"contract": "BTC_USDT"
}
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
POST /futures/{settle}/positions/{contract}/risk_limit
Update position risk limit.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | path | string | true | Futures contract. |
risk_limit | query | string | true | New Risk Limit Value. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Position information. | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions/BTC_USDT/risk_limit'
query_param = 'risk_limit=1000000'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
POST /futures/{settle}/dual_mode
Enable or disable dual mode.
The prerequisite for changing mode is that all positions have no holdings.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
dual_mode | query | boolean | true | Whether to enable dual mode. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Updated. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» total | string | total is the balance after the user's accumulated deposit, withdraw, profit and loss (including realized profit and loss, fund, fee and referral rebate), excluding unrealized profit and loss. total = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund) |
» unrealised_pnl | string | Unrealized PNL. |
» position_margin | string | Position margin. |
» order_margin | string | Order margin of unfinished orders. |
» available | string | The available balance for transferring or trading(including bonus. Bonus can't be withdrawn. The transfer amount needs to deduct the bonus) |
» point | string | POINT amount. |
» currency | string | Settle currency. |
» in_dual_mode | boolean | Whether dual mode is enabled. |
» enable_credit | boolean | Whether portfolio margin account mode is enabled. |
» position_initial_margin | string | Initial margin position, applicable to the portfolio margin account model. |
» maintenance_margin | string | The maintenance deposit occupied by the position is suitable for the new classic account margin model and unified account model |
» bonus | string | Perpetual Contract Bonus. |
» enable_evolved_classic | boolean | Classic account margin mode, true-new mode, false-old mode. |
» cross_order_margin | string | Full -warehouse hanging order deposit, suitable for the new classic account margin model |
» cross_initial_margin | string | The initial security deposit of the full warehouse is suitable for the new classic account margin model |
» cross_maintenance_margin | string | Maintain deposit in full warehouse, suitable for new classic account margin models |
» cross_unrealised_pnl | string | The full warehouse does not achieve profit and loss, suitable for the new classic account margin model |
» cross_available | string | Full warehouse available amount, suitable for the new classic account margin model |
» cross_margin_balance | string | Full margin balance, suitable for the new classic account margin model. |
» cross_mmr | string | Maintain margin ratio for the full position, suitable for the new classic account margin model |
» cross_imr | string | The initial margin rate of the full position is suitable for the new classic account margin model |
» isolated_position_margin | string | Ware -position margin, suitable for the new classic account margin model. |
» enable_new_dual_mode | boolean | Whether to open a new two-way position mode. |
» margin_mode | integer | Margin mode, 0-classic margin mode, 1-cross-currency margin mode, 2-combined margin mode |
» enable_tiered_mm | boolean | Whether to enable tiered maintenance margin calculation. |
» position_voucher_total | string | Total Position Experience Coupon Amount in Account. |
» history | object | Statistical data. |
»» dnw | string | total amount of deposit and withdraw. |
»» pnl | string | total amount of trading profit and loss. |
»» fee | string | total amount of fee. |
»» refr | string | total amount of referrer rebates. |
»» fund | string | total amount of funding costs. |
»» point_dnw | string | total amount of point deposit and withdraw. |
»» point_fee | string | total amount of point fee. |
»» point_refr | string | total amount of referrer rebates of point fee. |
»» bonus_dnw | string | total amount of perpetual contract bonus transfer. |
»» bonus_offset | string | total amount of perpetual contract bonus deduction. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_mode'
query_param = 'dual_mode=true'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"user": 1666,
"currency": "USDT",
"total": "9707.803567115145",
"unrealised_pnl": "3371.248828",
"position_margin": "38.712189181",
"order_margin": "0",
"available": "9669.091377934145",
"point": "0",
"bonus": "0",
"in_dual_mode": false,
"enable_evolved_classic": false,
"cross_initial_margin": "61855.56788525",
"cross_maintenance_margin": "682.04678105",
"cross_order_margin": "0",
"cross_unrealised_pnl": "1501.178222634128",
"cross_available": "27549.406108813951",
"cross_margin_balance": "10371.77306201952",
"cross_mmr": "797.2134",
"cross_imr": "116.6097",
"isolated_position_margin": "0",
"history": {
"dnw": "10000",
"pnl": "68.3685",
"fee": "-1.645812875",
"refr": "0",
"fund": "-358.919120009855",
"point_dnw": "0",
"point_fee": "0",
"point_refr": "0",
"bonus_dnw": "0",
"bonus_offset": "0"
},
"enable_tiered_mm": true
}
GET /futures/{settle}/dual_comp/positions/{contract}
Retrieve position detail in dual mode.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | path | string | true | Futures contract. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Position] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_comp/positions/BTC_USDT'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
POST /futures/{settle}/dual_comp/positions/{contract}/margin
Update position margin in dual mode.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | path | string | true | Futures contract. |
change | query | string | true | Margin change amount, positive number increases, negative number. |
dual_side | query | string | true | Long or short position. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Position] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_comp/positions/BTC_USDT/margin'
query_param = 'change=0.01&dual_side=dual_long'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
POST /futures/{settle}/dual_comp/positions/{contract}/leverage
Update position leverage in dual mode.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | path | string | true | Futures contract. |
leverage | query | string | true | New position leverage. |
cross_leverage_limit | query | string | false | Cross margin leverage(valid only when leverage is 0). |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Position] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_comp/positions/BTC_USDT/leverage'
query_param = 'leverage=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
POST /futures/{settle}/dual_comp/positions/{contract}/risk_limit
Update position risk limit in dual mode.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | path | string | true | Futures contract. |
risk_limit | query | string | true | New Risk Limit Value. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Position] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_comp/positions/BTC_USDT/risk_limit'
query_param = 'risk_limit=1000000'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
POST /futures/{settle}/orders
Create a futures order.
size
, not the number of coins. The number of coins corresponding to each contract is returned in the contract details interface
quanto_multiplier
reduce_only
to true
can prevent the position from being penetrated when reducing the positionsize
to 0 and close
to true
reduce_only
to true
at the same time - reduce_only: Make sure to only perform position reduction operations to prevent increased positionsstp_act
to determine the use of a strategy that restricts user transactions. For detailed usage, refer to the body parameter stp_act
Name | In | Type | Required | Description |
---|---|---|---|---|
x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
body | body | FuturesOrder | true | none |
» contract | body | string | true | Futures contract. |
» size | body | integer(int64) | true | Order size. Specify positive number to make a bid, and negative number to ask |
» iceberg | body | integer(int64) | false | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
» price | body | string | false | Order price. 0 for market order with tif set as ioc . |
» close | body | boolean | false | Set as true to close the position, with size set to 0. |
» reduce_only | body | boolean | false | Set as true to be reduce-only order. |
» tif | body | string | false | Time in force |
» text | body | string | false | Order custom information, users can use this field to set a custom ID, and the user-defined field must meet the following conditions: |
» auto_size | body | string | false | Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0 |
» stp_act | body | string | false | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies |
|settle|path|string|true|Settle currency.|
» tif: Time in force
» text: Order custom information, users can use this field to set a custom ID, and the user-defined field must meet the following conditions:
t-
t-
is not calculated, the length cannot exceed 28 bytesIn addition to user-defined information, the following are internal reserved fields that identifies the source of the order:
» stp_act: Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies
STP Group
, he can pass stp_act
to limit the user's self-trade prevetion strategy. If stp_act
is not passed, the default is cn
strategy.STP group
, an error will be returned when passing the stp_act
parameter.Parameter | Value |
---|---|
» tif | gtc |
» tif | ioc |
» tif | poc |
» tif | fok |
» auto_size | close_long |
» auto_size | close_short |
» stp_act | co |
» stp_act | cn |
» stp_act | cb |
» stp_act | - |
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
201 | Created (opens new window) | Order details. | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders'
query_param = ''
body='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"contract": "BTC_USDT",
"size": 6024,
"iceberg": 0,
"price": "3765",
"tif": "gtc",
"text": "t-my-custom-id",
"stp_act": "-"
}
Example responses
201 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
GET /futures/{settle}/orders
List futures orders.
GET /futures/{settle}/orders_timerange
.Name | In | Type | Required | Description |
---|---|---|---|---|
contract | query | string | false | Futures contract, return related data only if specified. |
status | query | string | true | Only list the orders with this status. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
last_id | query | string | false | Specify the currency name to query in batches, and support up to 100 pass parameters at a time. |
settle | path | string | true | Settle currency. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [FuturesOrder] |
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | X-Pagination-Limit | integer | Request limit specified. | |
200 | X-Pagination-Offset | integer | Request offset specified. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
open
orders matched.DELETE /futures/{settle}/orders
Cancel all open
orders matched.
Zero-filled order cannot be retrieved 10 minutes after order cancellation.
Name | In | Type | Required | Description |
---|---|---|---|---|
x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
contract | query | string | true | Futures contract. |
side | query | string | false | Specify all buy orders or all sell orders, both are included if not specified. Set to bid, set to ask to cancel all sell ordersspecified. Set to bid, set to ask to cancel all sell ordersspecified. Set to bid, set to ask to cancel all sell orders |
settle | path | string | true | Settle currency. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | All orders matched cancelled. | [FuturesOrder] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders'
query_param = 'contract=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
GET /futures/{settle}/orders_timerange
List Futures Orders By Time Range.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | false | Futures contract, return related data only if specified. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [FuturesOrder] |
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | X-Pagination-Limit | integer | Request limit specified. | |
200 | X-Pagination-Offset | integer | Request offset specified. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders_timerange'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
POST /futures/{settle}/batch_orders
Create a batch of futures orders.
succeeded
field of type bool indicates whether the execution was successful or notlabel
field is included to indicate the cause of the errorName | In | Type | Required | Description |
---|---|---|---|---|
x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
body | body | array[FuturesOrder] | true | none |
settle | path | string | true | Settle currency. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Request is completed. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Futures order details.] |
» None | object | Futures order details. |
»» succeeded | boolean | Whether the batch of orders succeeded. |
»» label | string | Error label, only exists if execution fails. |
»» detail | string | Error detail, only present if execution failed and details need to be given |
»» id | integer(int64) | Futures order ID. |
»» user | integer | User ID. |
»» create_time | number(double) | Creation time of order. |
»» finish_time | number(double) | Order finished time. Not returned if order is open. |
»» finish_as | string | How the order was finished. - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC , finish immediately- auto_deleveraged: finished by ADL - increasing position while reduce-only set- position_closed: cancelled because of position close- position_closed: canceled because the position was closed - reduce_out: only reduce positions by excluding hard-to-fill orders - stp: cancelled because self trade prevention |
»» status | string | Order status - open : waiting to be traded- finished : finished |
»» contract | string | Futures contract. |
»» size | integer(int64) | Order size. Specify positive number to make a bid, and negative number to ask |
»» iceberg | integer(int64) | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
»» price | string | Order price. 0 for market order with tif set as ioc . |
»» is_close | boolean | Is the order to close position. |
»» is_reduce_only | boolean | Is the order reduce-only. |
»» is_liq | boolean | Is the order for liquidation. |
»» tif | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none |
»» left | integer(int64) | Size left to be traded. |
»» fill_price | string | Fill price of the order. |
»» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance |
»» tkfr | string | Taker fee. |
»» mkfr | string | Maker fee. |
»» refu | integer | Reference user ID. |
»» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group , he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group , an error will be returned when passing the stp_act parameter. 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled |
»» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
Property | Value |
---|---|
finish_as | filled |
finish_as | cancelled |
finish_as | liquidated |
finish_as | ioc |
finish_as | auto_deleveraged |
finish_as | reduce_only |
finish_as | position_closed |
finish_as | reduce_out |
finish_as | stp |
status | open |
status | finished |
tif | gtc |
tif | ioc |
tif | poc |
tif | fok |
stp_act | co |
stp_act | cn |
stp_act | cb |
stp_act | - |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/batch_orders'
query_param = ''
body='[{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
[
{
"contract": "BTC_USDT",
"size": 6024,
"iceberg": 0,
"price": "3765",
"tif": "gtc",
"text": "t-my-custom-id",
"stp_act": "-"
}
]
Example responses
200 Response
[
{
"succeeded": true,
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
GET /futures/{settle}/orders/{order_id}
Get a single order.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
order_id | path | string | true | Order ID returned, or user custom ID(i.e., text field). |
order_id: Order ID returned, or user custom ID(i.e., text
field).
Operations based on custom ID can only be checked when the order is in orderbook. finished, it can be checked within 60 seconds after the end of the order. After that, only order ID is accepted.
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Order details. | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
DELETE /futures/{settle}/orders/{order_id}
Cancel a single order.
Name | In | Type | Required | Description |
---|---|---|---|---|
x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
settle | path | string | true | Settle currency. |
order_id | path | string | true | Order ID returned, or user custom ID(i.e., text field). |
order_id: Order ID returned, or user custom ID(i.e., text
field).
Operations based on custom ID can only be checked when the order is in orderbook. finished, it can be checked within 60 seconds after the end of the order. After that, only order ID is accepted.
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Order details. | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
PUT /futures/{settle}/orders/{order_id}
Amend an order.
Name | In | Type | Required | Description |
---|---|---|---|---|
x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
body | body | object | true | none |
» size | body | integer(int64) | false | New order size, including filled part. |
» price | body | string | false | New order price. |
» amend_text | body | string | false | Custom info during amending order. |
settle | path | string | true | Settle currency. |
order_id | path | string | true | Order ID returned, or user custom ID(i.e., text field). |
» size: New order size, including filled part.
order_id: Order ID returned, or user custom ID(i.e., text
field).
Operations based on custom ID can only be checked when the order is in orderbook. finished, it can be checked within 60 seconds after the end of the order. After that, only order ID is accepted.
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Order details. | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders/12345'
query_param = ''
body='{"size":100,"price":"54321"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PUT', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"size": 100,
"price": "54321"
}
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
GET /futures/{settle}/my_trades
List personal trading history.
By default, only data within the past 6 months is supported.
If you need to query data for a longer period, please use GET /futures/{settle}/my_trades_timerange
.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | false | Futures contract, return related data only if specified. |
order | query | integer(int64) | false | Futures order ID, return related data only if specified. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
last_id | query | string | false | Specify the starting point for this list based on a previously retrieved id |
last_id: Specify the starting point for this list based on a previously retrieved id
This parameter is deprecated. If you need to iterate through and retrieve more records, we recommend using 'GET /futures/{settle}/my_trades_timerange'.
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» id | integer(int64) | Trade ID. |
» create_time | number(double) | Trading time. |
» contract | string | Futures contract. |
» order_id | string | Order ID related. |
» size | integer(int64) | Trading size. |
» close_size | integer(int64) | Number of closed positions: close_size=0 && size>0 Open long position close_size=0 && size<0 Open short position close_size>0 && size>0 && size <= close_size Close > close_size Close short position and open long position close_size<0 && size<0 && size >= close_size Close long postion close_size<0 && size<0 && size < close_size Close long position and open short position |
» price | string | Trading price. |
» role | string | Trade role. Available values are taker and maker . |
» text | string | User defined information. |
» fee | string | Fee deducted. |
» point_fee | string | Points used to deduct fee. |
Property | Value |
---|---|
role | taker |
role | maker |
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | X-Pagination-Limit | integer | Request limit specified. | |
200 | X-Pagination-Offset | integer | Request offset specified. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/my_trades'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800.123,
"contract": "BTC_USDT",
"order_id": "21893289839",
"size": 100,
"price": "100.123",
"text": "t-123456",
"fee": "0.01",
"point_fee": "0",
"role": "taker",
"close_size": 0
}
]
GET /futures/{settle}/my_trades_timerange
List personal trading history by time range.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | false | Futures contract, return related data only if specified. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
role | query | string | false | Query role, maker or taker. |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» trade_id | string | Trade ID. |
» create_time | number(double) | Trading time. |
» contract | string | Futures contract. |
» order_id | string | Order ID related. |
» size | integer(int64) | Trading size. |
» close_size | integer(int64) | Number of closed positions: close_size=0 && size>0 Open long position close_size=0 && size<0 Open short position close_size>0 && size>0 && size <= close_size Close > close_size Close short position and open long position close_size<0 && size<0 && size >= close_size Close long postion close_size<0 && size<0 && size < close_size Close long position and open short position |
» price | string | Trading price. |
» role | string | Trade role. Available values are taker and maker . |
» text | string | User defined information. |
» fee | string | Fee deducted. |
» point_fee | string | Points used to deduct fee. |
Property | Value |
---|---|
role | taker |
role | maker |
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | X-Pagination-Limit | integer | Request limit specified. | |
200 | X-Pagination-Offset | integer | Request offset specified. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/my_trades_timerange'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"trade_id": "121234231",
"create_time": 1514764800.123,
"contract": "BTC_USDT",
"order_id": "21893289839",
"size": 100,
"price": "100.123",
"text": "t-123456",
"fee": "0.01",
"point_fee": "0",
"role": "taker",
"close_size": 0
}
]
GET /futures/{settle}/position_close
List position close history.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | false | Futures contract, return related data only if specified. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
side | query | string | false | Query side. long or shot. |
pnl | query | string | false | Query profit or loss. |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» time | number(double) | Position close time. |
» contract | string | Futures contract. |
» side | string | Position side, long or short. |
» pnl | string | PNL. |
» pnl_pnl | string | PNL - Position P/L. |
» pnl_fund | string | PNL - Funding Fees. |
» pnl_fee | string | PNL - Transaction Fees. |
» text | string | Text of close order. |
» max_size | string | Max Trade Size. |
» accum_size | string | Cumulative closed position volume. |
» first_open_time | integer(int64) | First Open Time. |
» long_price | string | When 'side' is 'long,' it indicates the opening average price; when closing average price. |
» short_price | string | When 'side' is 'long,' it indicates the opening average price; when closing average price |
Property | Value |
---|---|
side | long |
side | short |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/position_close'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"time": 1546487347,
"pnl": "0.00013",
"pnl_pnl": "0.00011",
"pnl_fund": "0.00001",
"pnl_fee": "0.00001",
"side": "long",
"contract": "BTC_USDT",
"text": "web",
"max_size": "100",
"accum_size": "100",
"first_open_time": 1546487347,
"long_price": "2026.87",
"short_price": "2544.4"
}
]
GET /futures/{settle}/liquidates
List liquidation history.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | false | Futures contract, return related data only if specified. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
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 a liquidation timestamp. |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» time | integer(int64) | Liquidation time. |
» contract | string | Futures contract. |
» leverage | string | Position leverage. Not returned in public endpoints. |
» size | integer(int64) | Position size. |
» margin | string | Position margin. Not returned in public endpoints. |
» entry_price | string | Average entry price. Not returned in public endpoints. |
» liq_price | string | Liquidation price. Not returned in public endpoints. |
» mark_price | string | Mark price. Not returned in public endpoints. |
» order_id | integer(int64) | Liquidation order ID. Not returned in public endpoints. |
» order_price | string | Liquidation order price. |
» fill_price | string | Liquidation order average taker price. |
» left | integer(int64) | Liquidation order maker size. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/liquidates'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"time": 1548654951,
"contract": "BTC_USDT",
"size": 600,
"leverage": "25",
"margin": "0.006705256878",
"entry_price": "3536.123",
"liq_price": "3421.54",
"mark_price": "3420.27",
"order_id": 317393847,
"order_price": "3405",
"fill_price": "3424",
"left": 0
}
]
GET /futures/{settle}/auto_deleverages
List Auto-Deleveraging History.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | false | Futures contract, return related data only if specified. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
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 an auto-deleveraging timestamp. |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» time | integer(int64) | Automatic deleveraging time. |
» user | integer(int64) | User ID. |
» order_id | integer(int64) | Order ID. Order IDs before 2023-02-20 are null. |
» contract | string | Futures contract. |
» leverage | string | Position leverage. |
» cross_leverage_limit | string | Cross margin leverage(valid only when leverage is 0). |
» entry_price | string | Average entry price. |
» fill_price | string | Average fill price. |
» trade_size | integer(int64) | Trading size. |
» position_size | integer(int64) | Positions after auto-deleveraging. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/auto_deleverages'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"time": 1675841679,
"contract": "ACH_USDT",
"order_id": 73873128,
"user": 1666,
"cross_leverage_limit": "0",
"leverage": "0",
"entry_price": "2649.648633636364",
"fill_price": "2790.8082",
"position_size": 1,
"trade_size": -10
}
]
POST /futures/{settle}/countdown_cancel_all
Countdown cancel orders.
Heartbeat detection for contract orders: When the user-set timeout
time is reached, if neither the existing countdown is canceled nor a new countdown is set, the relevant contract orders will be automatically canceled.
This API can be called repeatedly to or cancel the countdown.
Usage example: Repeatedly call this API at 30-second intervals, setting the timeout
to 30 (seconds) each time.
If this API is not called again within 30 seconds, all open orders on your specified market
will be automatically canceled.
If the timeout
is set to 0 within 30 seconds, the countdown timer will terminate, and the automatic order cancellation function will be disabled.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» timeout | body | integer(int32) | true | Countdown time in seconds |
» contract | body | string | false | Futures contract. |
settle | path | string | true | Settle currency. |
» timeout: Countdown time in seconds At least 5 seconds, 0 means cancel countdown
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Set countdown successfully. | Inline |
Status Code 200
triggerTime
Name | Type | Description |
---|---|---|
» triggerTime | integer(int64) | Timestamp of the end of the countdown, in milliseconds. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/countdown_cancel_all'
query_param = ''
body='{"timeout":30,"contract":"BTC_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"timeout": 30,
"contract": "BTC_USDT"
}
Example responses
200 Response
{
"triggerTime": "1660039145000"
}
GET /futures/{settle}/fee
Query user trading fee rates.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | false | Futures contract, return related data only if specified. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
FuturesFee
Name | Type | Description |
---|---|---|
» additionalProperties | object | The returned result is a map type, where the key represents the market and taker and maker fee rates. |
»» taker_fee | string | Taker fee. |
»» maker_fee | string | maker fee. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/fee'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"1INCH_USDT": {
"taker_fee": "0.00025",
"maker_fee": "-0.00010"
},
"AAVE_USDT": {
"taker_fee": "0.00025",
"maker_fee": "-0.00010"
}
}
POST /futures/{settle}/batch_cancel_orders
Cancel a batch of orders with an ID list.
Multiple different order IDs can be specified. A maximum of 20 records.
Name | In | Type | Required | Description |
---|---|---|---|---|
x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
body | body | array[string] | true | none |
settle | path | string | true | Settle currency. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Order cancellation operation completed. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» FutureCancelOrderResult | object | Order cancellation result. |
»» id | string | Order ID. |
»» user_id | integer(int64) | User ID. |
»» succeeded | boolean | Whether cancellation succeeded. |
»» message | string | Error message when failed to cancel the order; empty if succeeded. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/batch_cancel_orders'
query_param = ''
body='["1","2","3"]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
[
"1",
"2",
"3"
]
Example responses
200 Response
[
{
"user_id": 111,
"id": "123456",
"succeeded": true,
"message": ""
}
]
POST /futures/{settle}/batch_amend_orders
Batch modify orders with specified IDs.
Multiple different order IDs can be specified. A maximum of 10 orders can.
Name | In | Type | Required | Description |
---|---|---|---|---|
x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
body | body | array[BatchAmendOrderReq] | true | none |
settle | path | string | true | Settle currency. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Request is completed. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Futures order details.] |
» None | object | Futures order details. |
»» succeeded | boolean | Whether the batch of orders succeeded. |
»» label | string | Error label, only exists if execution fails. |
»» detail | string | Error detail, only present if execution failed and details need to be given |
»» id | integer(int64) | Futures order ID. |
»» user | integer | User ID. |
»» create_time | number(double) | Creation time of order. |
»» finish_time | number(double) | Order finished time. Not returned if order is open. |
»» finish_as | string | How the order was finished. - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC , finish immediately- auto_deleveraged: finished by ADL - increasing position while reduce-only set- position_closed: cancelled because of position close- position_closed: canceled because the position was closed - reduce_out: only reduce positions by excluding hard-to-fill orders - stp: cancelled because self trade prevention |
»» status | string | Order status - open : waiting to be traded- finished : finished |
»» contract | string | Futures contract. |
»» size | integer(int64) | Order size. Specify positive number to make a bid, and negative number to ask |
»» iceberg | integer(int64) | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
»» price | string | Order price. 0 for market order with tif set as ioc . |
»» is_close | boolean | Is the order to close position. |
»» is_reduce_only | boolean | Is the order reduce-only. |
»» is_liq | boolean | Is the order for liquidation. |
»» tif | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none |
»» left | integer(int64) | Size left to be traded. |
»» fill_price | string | Fill price of the order. |
»» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance |
»» tkfr | string | Taker fee. |
»» mkfr | string | Maker fee. |
»» refu | integer | Reference user ID. |
»» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group , he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group , an error will be returned when passing the stp_act parameter. 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled |
»» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
Property | Value |
---|---|
finish_as | filled |
finish_as | cancelled |
finish_as | liquidated |
finish_as | ioc |
finish_as | auto_deleveraged |
finish_as | reduce_only |
finish_as | position_closed |
finish_as | reduce_out |
finish_as | stp |
status | open |
status | finished |
tif | gtc |
tif | ioc |
tif | poc |
tif | fok |
stp_act | co |
stp_act | cn |
stp_act | cb |
stp_act | - |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/batch_amend_orders'
query_param = ''
body='[{"order_id":121212,"amend_text":"batch amend text","size":100,"price":"54321"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
[
{
"order_id": 121212,
"amend_text": "batch amend text",
"size": 100,
"price": "54321"
}
]
Example responses
200 Response
[
{
"succeeded": true,
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
GET /futures/{settle}/risk_limit_table
Query risk limit table by table_id.
Just pass table_id.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
table_id | query | string | true | Risk limit table ID. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Information for each tier of the risk limit ladder. |
»» 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. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/risk_limit_table'
query_param = 'table_id=CYBER_USDT_20241122'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"tier": 1,
"risk_limit": "10000",
"initial_rate": "0.025",
"maintenance_rate": "0.015",
"leverage_max": "40",
"deduction": "0"
},
{
"tier": 2,
"risk_limit": "30000",
"initial_rate": "0.03333",
"maintenance_rate": "0.02",
"leverage_max": "30",
"deduction": "50"
},
{
"tier": 3,
"risk_limit": "50000",
"initial_rate": "0.04545",
"maintenance_rate": "0.03",
"leverage_max": "22",
"deduction": "350"
},
{
"tier": 4,
"risk_limit": "70000",
"initial_rate": "0.05555",
"maintenance_rate": "0.04",
"leverage_max": "18",
"deduction": "850"
},
{
"tier": 5,
"risk_limit": "100000",
"initial_rate": "0.1",
"maintenance_rate": "0.085",
"leverage_max": "10",
"deduction": "4000"
},
{
"tier": 6,
"risk_limit": "150000",
"initial_rate": "0.333",
"maintenance_rate": "0.3",
"leverage_max": "3",
"deduction": "25500"
},
{
"tier": 7,
"risk_limit": "200000",
"initial_rate": "0.5",
"maintenance_rate": "0.45",
"leverage_max": "2",
"deduction": "48000"
},
{
"tier": 8,
"risk_limit": "300000",
"initial_rate": "1",
"maintenance_rate": "0.95",
"leverage_max": "1",
"deduction": "148000"
}
]
POST /futures/{settle}/price_orders
Create a price-triggered order.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | FuturesPriceTriggeredOrder | true | none |
» initial | body | object | true | none |
»» contract | body | string | true | 合约标识 |
»» size | body | integer(int64) | false | 代表需要平仓的合约张数, 全平仓:size=0 |
»» price | body | string | true | 交易价, 当价格为 0 时, 表示通过市价方式来下单 |
»» close | body | boolean | false | 单仓模式全部平仓时,必须设置为true执行平仓操作 |
»» tif | body | string | false | Time in force 策略,默认为gtc, 市价单当前只支持 ioc 模式市价单当前只支持 ioc 模式 |
»» text | body | string | false | 订单的来源, 包括: |
»» reduce_only | body | boolean | false | 设置为 true 的时候执行自动减仓操作, 设为 true可确保订单不会开新仓, 只用于平仓或减仓 |
»» auto_size | body | string | false | 单仓模式不需设置auto_size |
» trigger | body | object | true | none |
»» strategy_type | body | integer(int32) | false | 触发策略 |
»» price_type | body | integer(int32) | false | 参考价格Type. 0 - 最新成交价, 1 - 标记价格, 2 - 指数价格 |
»» price | body | string | false | 价格触发时为价格, 价差触发时为价差 |
»» rule | body | integer(int32) | false | 价格条件Type |
»» expiration | body | integer | false | 最长等待触发时间, 超时则取消该订单, 单位是秒 s |
» order_type | body | string | false | Types of stop-profit and stop-loss, including: |
settle | path | string | true | Settle currency. |
部分平仓:plan-close-short-position size>0 部分平仓:plan-close-long-position size<0
gtc: GoodTillCancelled
ioc: ImmediateOrCancelled
web: 网页
api: API 调用
app: 移动端
»» auto_size: 单仓模式不需设置auto_size
»» strategy_type: 触发策略
»» rule: 价格条件Type
strategy_type
和 price_type
算出的价格大于等于 Trigger.Price
时触发, 同时Trigger.Price must > last_pricestrategy_type
和 price_type
算出的价格小于等于 Trigger.Price
时触发, 同时Trigger.Price must < last_price» order_type: Types of stop-profit and stop-loss, including:
close-long-order
: Entrusting order stop profit and stop loss, flat long positionclose-short-order
: loss, short positionclose-long-position
: Position stop-profit stop loss, used to close long positionsclose-short-position
: Position stop-profit stop loss, used to close all short positionsplan-close-long-position
: Position plan take profit and stop loss, used to close long positions in all or part of long positionsplan-close-short-position
: Position plan stop-profit and stop loss, used to close all short positions or partially close short positionsThe two types of entrusted order stop-profit and stop-loss are read-only and cannot be passed in through requests
Parameter | Value |
---|---|
»» tif | gtc |
»» tif | ioc |
»» strategy_type | 0 |
»» strategy_type | 1 |
»» price_type | 0 |
»» price_type | 1 |
»» price_type | 2 |
»» rule | 1 |
»» rule | 2 |
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
201 | Created (opens new window) | Order created. | Inline |
Status Code 201
TriggerOrderResponse
Name | Type | Description |
---|---|---|
» id | integer(int64) | Auto order ID. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/price_orders'
query_param = ''
body='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"order_type": "close-long-order"
}
Example responses
201 Response
{
"id": 1432329
}
GET /futures/{settle}/price_orders
List All Price-triggered Orders.
Name | In | Type | Required | Description |
---|---|---|---|---|
status | query | string | true | Only list the orders with this status. |
contract | query | string | false | Futures contract, return related data only if specified. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
settle | path | string | true | Settle currency. |
Parameter | Value |
---|---|
status | open |
status | finished |
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [FuturesPriceTriggeredOrder] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/price_orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
]
DELETE /futures/{settle}/price_orders
Cancel All Price-triggered Orders.
Name | In | Type | Required | Description |
---|---|---|---|---|
contract | query | string | false | Futures contract, return related data only if specified. |
settle | path | string | true | Settle currency. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Batch cancellation request accepted. Query order status by listing orders. | [FuturesPriceTriggeredOrder] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/price_orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
]
GET /futures/{settle}/price_orders/{order_id}
Get a price-triggered order.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
order_id | path | string | true | Retrieve the data of the order with the specified ID. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Auto order detail. | FuturesPriceTriggeredOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
DELETE /futures/{settle}/price_orders/{order_id}
cancel a price-triggered order.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
order_id | path | string | true | Retrieve the data of the order with the specified ID. |
Parameter | Value |
---|---|
settle | btc |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Auto order detail. | FuturesPriceTriggeredOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
Delivery contract API.
GET /delivery/{settle}/contracts
List all futures contracts.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [DeliveryContract] |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/contracts'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"name": "BTC_USDT_20200814",
"underlying": "BTC_USDT",
"cycle": "WEEKLY",
"type": "direct",
"quanto_multiplier": "0.0001",
"mark_type": "index",
"last_price": "9017",
"mark_price": "9019",
"index_price": "9005.3",
"basis_rate": "0.185095",
"basis_value": "13.7",
"basis_impact_value": "100000",
"settle_price": "0",
"settle_price_interval": 60,
"settle_price_duration": 1800,
"settle_fee_rate": "0.0015",
"expire_time": 1593763200,
"order_price_round": "0.1",
"mark_price_round": "0.1",
"leverage_min": "1",
"leverage_max": "100",
"maintenance_rate": "1000000",
"risk_limit_base": "140.726652109199",
"risk_limit_step": "1000000",
"risk_limit_max": "8000000",
"maker_fee_rate": "-0.00025",
"taker_fee_rate": "0.00075",
"ref_discount_rate": "0",
"ref_rebate_rate": "0.2",
"order_price_deviate": "0.5",
"order_size_min": 1,
"order_size_max": 1000000,
"orders_limit": 50,
"orderbook_id": 63,
"trade_id": 26,
"trade_size": 435,
"position_size": 130,
"config_change_time": 1593158867,
"in_delisting": false
}
]
GET /delivery/{settle}/contracts/{contract}
Get a single contract.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | path | string | true | Futures contract. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Contract information. | DeliveryContract |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/contracts/BTC_USDT_20200814'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"name": "BTC_USDT_20200814",
"underlying": "BTC_USDT",
"cycle": "WEEKLY",
"type": "direct",
"quanto_multiplier": "0.0001",
"mark_type": "index",
"last_price": "9017",
"mark_price": "9019",
"index_price": "9005.3",
"basis_rate": "0.185095",
"basis_value": "13.7",
"basis_impact_value": "100000",
"settle_price": "0",
"settle_price_interval": 60,
"settle_price_duration": 1800,
"settle_fee_rate": "0.0015",
"expire_time": 1593763200,
"order_price_round": "0.1",
"mark_price_round": "0.1",
"leverage_min": "1",
"leverage_max": "100",
"maintenance_rate": "1000000",
"risk_limit_base": "140.726652109199",
"risk_limit_step": "1000000",
"risk_limit_max": "8000000",
"maker_fee_rate": "-0.00025",
"taker_fee_rate": "0.00075",
"ref_discount_rate": "0",
"ref_rebate_rate": "0.2",
"order_price_deviate": "0.5",
"order_size_min": 1,
"order_size_max": 1000000,
"orders_limit": 50,
"orderbook_id": 63,
"trade_id": 26,
"trade_size": 435,
"position_size": 130,
"config_change_time": 1593158867,
"in_delisting": false
}
GET /delivery/{settle}/order_book
Futures order book.
Bids will be sorted by price from high to low, while asks sorted reversely.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | true | Futures contract. |
interval | query | string | false | Order depth. 0 means no aggregation is applied. default to 0. |
limit | query | integer | false | Maximum number of order depth data in asks or bids. |
with_id | query | boolean | false | Whether to return depth update ID. This ID increments by 1 each time. |
Parameter | Value |
---|---|
settle | usdt |
interval | 0 |
interval | 0.1 |
interval | 0.01 |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Depth query successful. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» id | integer(int64) | Order Book ID. Increases by 1 on every order book change. Set with_id=true to include this field in response |
» current | number(double) | Response data generation timestamp. |
» update | number(double) | Order book changed timestamp. |
» asks | array | Asks order depth. |
»» futures_order_book_item | object | none |
»»» p | string | Price (quote currency). |
»»» s | integer(int64) | Size. |
»» bids | array | Bids order depth. |
»»» futures_order_book_item | object | none |
»»»» p | string | Price (quote currency). |
»»»» s | integer(int64) | Size. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/order_book'
query_param = 'contract=BTC_USDT_20200814'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"id": 123456,
"current": 1623898993.123,
"update": 1623898993.121,
"asks": [
{
"p": "1.52",
"s": 100
},
{
"p": "1.53",
"s": 40
}
],
"bids": [
{
"p": "1.17",
"s": 150
},
{
"p": "1.16",
"s": 203
}
]
}
GET /delivery/{settle}/trades
Futures trading history.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | true | Futures contract. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
last_id | query | string | false | Specify the starting point for this list based on a previously retrieved id |
from | query | integer(int64) | false | Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items. |
to | query | integer(int64) | false | Specify end time in Unix seconds, default to current time. |
last_id: Specify the starting point for this list based on a previously retrieved id
This parameter is deprecated. Use from
and to
instead to limit time range
from: Specify starting time in Unix seconds. If not specified, to
and limit
will be used to limit response items.
If items between from
and to
are more than limit
, only limit
number will be returned.
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» id | integer(int64) | Trade ID. |
» create_time | number(double) | Trading time. |
» create_time_ms | number(double) | Trading time, with milliseconds set to 3 decimal places. |
» contract | string | Futures contract. |
» size | integer(int64) | Trading size. |
» price | string | Trading price (quote currency). |
» is_internal | boolean | Whether internal trade. Internal trade refers to the takeover of liquidation orders by the insurance fund and ADL users. Since it is not a normal matching on the market depth, the transaction price may deviate, and it will not be recorded in the K-line. an internal trade, this field will not be returned. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/trades'
query_param = 'contract=BTC_USDT_20200814'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800,
"contract": "BTC_USDT",
"size": -100,
"price": "100.123"
}
]
GET /delivery/{settle}/candlesticks
Get futures candlesticks.
Return specified contract candlesticks.
If prefix contract
with mark_
, the contract's mark price candlesticks are returned;
if prefix with index_
, index price candlesticks will be returned.
Maximum of 2000 points are returned in one query. Be sure not to exceed the limit when specifying from
, to
and interval
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | true | Futures contract. |
from | query | integer(int64) | false | Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified |
to | query | integer(int64) | false | 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 specified |
limit | query | integer | false | Maximum recent data points to return. limit is conflicted with from and to . If either from or to is specified, request will be rejected. |
interval | query | string | false | Time interval between data points, note that 1w represents a natural week, 7d time is aligned with Unix initial timeweek, 7d time is aligned with Unix initial time |
Parameter | Value |
---|---|
settle | usdt |
interval | 10s |
interval | 30s |
interval | 1m |
interval | 5m |
interval | 15m |
interval | 30m |
interval | 1h |
interval | 2h |
interval | 4h |
interval | 6h |
interval | 8h |
interval | 12h |
interval | 1d |
interval | 7d |
interval | 1w |
interval | 30d |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | data point in every timestamp. |
»» t | number(double) | Unix timestamp in seconds. |
»» v | integer(int64) | size volume (contract size). Only returned if contract is not prefixed. |
»» c | string | Close price (quote currency). |
»» h | string | Highest price (quote currency). |
»» l | string | Lowest price (quote currency). |
»» o | string | Open price (quote currency). |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/candlesticks'
query_param = 'contract=BTC_USDT_20200814'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"t": 1539852480,
"v": 97151,
"c": "1.032",
"h": "1.032",
"l": "1.032",
"o": "1.032"
}
]
GET /delivery/{settle}/tickers
List futures tickers.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | false | Futures contract. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» contract | string | Futures contract. |
» last | string | Last trading price. |
» change_percentage | string | Change percentage. |
» total_size | string | Contract total size. |
» low_24h | string | Lowest trading price in recent 24h. |
» high_24h | string | Highest trading price in recent 24h. |
» volume_24h | string | Trade size in recent 24h. |
» volume_24h_btc | string | Trade volumes in recent 24h in BTC(deprecated, use volume_24h_base , volume_24h_quote , volume_24h_settle instead) |
» volume_24h_usd | string | Trade volumes in recent 24h in USD(deprecated, use volume_24h_base , volume_24h_quote , volume_24h_settle instead) |
» volume_24h_base | string | Trade volume in recent 24h, in base currency. |
» volume_24h_quote | string | Trade volume in recent 24h, in quote currency. |
» volume_24h_settle | string | Trade volume in recent 24h, in settle currency. |
» mark_price | string | Recent mark price. |
» funding_rate | string | Funding rate. |
» funding_rate_indicative | string | Indicative Funding rate in next period. (deprecated. use funding_rate ). |
» index_price | string | Index price. |
» quanto_base_rate | string | Exchange rate of base currency and settlement currency in Quanto contract. Does not exists in contracts of other types |
» basis_rate | string | Basis rate. |
» basis_value | string | Basis value. |
» lowest_ask | string | Recent lowest ask. |
» lowest_size | string | The latest seller's lowest price order quantity. |
» highest_bid | string | Recent highest bid. |
» highest_size | string | The latest buyer's highest price order volume. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/tickers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"contract": "BTC_USDT",
"last": "6432",
"low_24h": "6278",
"high_24h": "6790",
"change_percentage": "4.43",
"total_size": "32323904",
"volume_24h": "184040233284",
"volume_24h_btc": "28613220",
"volume_24h_usd": "184040233284",
"volume_24h_base": "28613220",
"volume_24h_quote": "184040233284",
"volume_24h_settle": "28613220",
"mark_price": "6534",
"funding_rate": "0.0001",
"funding_rate_indicative": "0.0001",
"index_price": "6531",
"highest_bid": "34089.7",
"highest_size": "100",
"lowest_ask": "34217.9",
"lowest_size": "1000"
}
]
GET /delivery/{settle}/insurance
Futures insurance balance history.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» t | integer(int64) | Unix timestamp in seconds. |
» b | string | Insurance balance. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/insurance'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"t": 1543968000,
"b": "83.0031"
}
]
GET /delivery/{settle}/accounts
Query futures account.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» total | string | total is the balance after the user's accumulated deposit, withdraw, profit and loss (including realized profit and loss, fund, fee and referral rebate), excluding unrealized profit and loss. total = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund) |
» unrealised_pnl | string | Unrealized PNL. |
» position_margin | string | Position margin. |
» order_margin | string | Order margin of unfinished orders. |
» available | string | The available balance for transferring or trading(including bonus. Bonus can't be withdrawn. The transfer amount needs to deduct the bonus) |
» point | string | POINT amount. |
» currency | string | Settle currency. |
» in_dual_mode | boolean | Whether dual mode is enabled. |
» enable_credit | boolean | Whether portfolio margin account mode is enabled. |
» position_initial_margin | string | Initial margin position, applicable to the portfolio margin account model. |
» maintenance_margin | string | The maintenance deposit occupied by the position is suitable for the new classic account margin model and unified account model |
» bonus | string | Perpetual Contract Bonus. |
» enable_evolved_classic | boolean | Classic account margin mode, true-new mode, false-old mode. |
» cross_order_margin | string | Full -warehouse hanging order deposit, suitable for the new classic account margin model |
» cross_initial_margin | string | The initial security deposit of the full warehouse is suitable for the new classic account margin model |
» cross_maintenance_margin | string | Maintain deposit in full warehouse, suitable for new classic account margin models |
» cross_unrealised_pnl | string | The full warehouse does not achieve profit and loss, suitable for the new classic account margin model |
» cross_available | string | Full warehouse available amount, suitable for the new classic account margin model |
» cross_margin_balance | string | Full margin balance, suitable for the new classic account margin model. |
» cross_mmr | string | Maintain margin ratio for the full position, suitable for the new classic account margin model |
» cross_imr | string | The initial margin rate of the full position is suitable for the new classic account margin model |
» isolated_position_margin | string | Ware -position margin, suitable for the new classic account margin model. |
» enable_new_dual_mode | boolean | Whether to open a new two-way position mode. |
» margin_mode | integer | Margin mode, 0-classic margin mode, 1-cross-currency margin mode, 2-combined margin mode |
» enable_tiered_mm | boolean | Whether to enable tiered maintenance margin calculation. |
» position_voucher_total | string | Total Position Experience Coupon Amount in Account. |
» history | object | Statistical data. |
»» dnw | string | total amount of deposit and withdraw. |
»» pnl | string | total amount of trading profit and loss. |
»» fee | string | total amount of fee. |
»» refr | string | total amount of referrer rebates. |
»» fund | string | total amount of funding costs. |
»» point_dnw | string | total amount of point deposit and withdraw. |
»» point_fee | string | total amount of point fee. |
»» point_refr | string | total amount of referrer rebates of point fee. |
»» bonus_dnw | string | total amount of perpetual contract bonus transfer. |
»» bonus_offset | string | total amount of perpetual contract bonus deduction. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"user": 1666,
"currency": "USDT",
"total": "9707.803567115145",
"unrealised_pnl": "3371.248828",
"position_margin": "38.712189181",
"order_margin": "0",
"available": "9669.091377934145",
"point": "0",
"bonus": "0",
"in_dual_mode": false,
"enable_evolved_classic": false,
"cross_initial_margin": "61855.56788525",
"cross_maintenance_margin": "682.04678105",
"cross_order_margin": "0",
"cross_unrealised_pnl": "1501.178222634128",
"cross_available": "27549.406108813951",
"cross_margin_balance": "10371.77306201952",
"cross_mmr": "797.2134",
"cross_imr": "116.6097",
"isolated_position_margin": "0",
"history": {
"dnw": "10000",
"pnl": "68.3685",
"fee": "-1.645812875",
"refr": "0",
"fund": "-358.919120009855",
"point_dnw": "0",
"point_fee": "0",
"point_refr": "0",
"bonus_dnw": "0",
"bonus_offset": "0"
},
"enable_tiered_mm": true
}
GET /delivery/{settle}/account_book
Query account book.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
type | query | string | false | Changing Type: |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
type: Changing Type:
Parameter | Value |
---|---|
settle | usdt |
type | dnw |
type | pnl |
type | fee |
type | refr |
type | fund |
type | point_dnw |
type | point_fee |
type | point_refr |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» time | number(double) | Change time. |
» change | string | Change amount. |
» balance | string | Balance after change. |
» type | string | Changing Type: - dnw: Deposit & Withdraw - pnl: Profit & Loss by reducing position - fee: Trading fee - refr: Referrer rebate - fund: Funding - point_dnw: point_fee: POINT Trading fee - point_refr: POINT Referrer rebate - bonus_offset: bouns deduction |
» text | string | Comment. |
» contract | string | Futures contract, the field is only available for data after 2023-10-30. |
» trade_id | string | trade id. |
» id | string | Account change record ID. |
Property | Value |
---|---|
type | dnw |
type | pnl |
type | fee |
type | refr |
type | fund |
type | point_dnw |
type | point_fee |
type | point_refr |
type | bonus_offset |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"time": 1682294400.123456,
"change": "0.000010152188",
"balance": "4.59316525194",
"text": "ETH_USD:6086261",
"type": "fee",
"contract": "ETH_USD",
"trade_id": "1",
"id": "1"
}
]
GET /delivery/{settle}/positions
List all positions of a user.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Position] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/positions'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
]
GET /delivery/{settle}/positions/{contract}
Get single position.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | path | string | true | Futures contract. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Position information. | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/positions/BTC_USDT_20200814'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
POST /delivery/{settle}/positions/{contract}/margin
Update position margin.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | path | string | true | Futures contract. |
change | query | string | true | Margin change amount, positive number increases, negative number. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Position information. | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/positions/BTC_USDT_20200814/margin'
query_param = 'change=0.01'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
POST /delivery/{settle}/positions/{contract}/leverage
Update position leverage.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | path | string | true | Futures contract. |
leverage | query | string | true | New position leverage. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Position information. | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/positions/BTC_USDT_20200814/leverage'
query_param = 'leverage=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
POST /delivery/{settle}/positions/{contract}/risk_limit
Update position risk limit.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | path | string | true | Futures contract. |
risk_limit | query | string | true | New position risk limit. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Position information. | Position |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/positions/BTC_USDT_20200814/risk_limit'
query_param = 'risk_limit=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": -9440,
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005"
}
POST /delivery/{settle}/orders
Create a futures order.
Zero-filled order cannot be retrieved 10 minutes after order cancellation.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | FuturesOrder | true | none |
» contract | body | string | true | Futures contract. |
» size | body | integer(int64) | true | Order size. Specify positive number to make a bid, and negative number to ask |
» iceberg | body | integer(int64) | false | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
» price | body | string | false | Order price. 0 for market order with tif set as ioc . |
» close | body | boolean | false | Set as true to close the position, with size set to 0. |
» reduce_only | body | boolean | false | Set as true to be reduce-only order. |
» tif | body | string | false | Time in force |
» text | body | string | false | Order custom information, users can use this field to set a custom ID, and the user-defined field must meet the following conditions: |
» auto_size | body | string | false | Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0 |
» stp_act | body | string | false | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies |
|settle|path|string|true|Settle currency.|
» tif: Time in force
» text: Order custom information, users can use this field to set a custom ID, and the user-defined field must meet the following conditions:
t-
t-
is not calculated, the length cannot exceed 28 bytesIn addition to user-defined information, the following are internal reserved fields that identifies the source of the order:
» stp_act: Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies
STP Group
, he can pass stp_act
to limit the user's self-trade prevetion strategy. If stp_act
is not passed, the default is cn
strategy.STP group
, an error will be returned when passing the stp_act
parameter.Parameter | Value |
---|---|
» tif | gtc |
» tif | ioc |
» tif | poc |
» tif | fok |
» auto_size | close_long |
» auto_size | close_short |
» stp_act | co |
» stp_act | cn |
» stp_act | cb |
» stp_act | - |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
201 | Created (opens new window) | Order details. | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/orders'
query_param = ''
body='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"contract": "BTC_USDT",
"size": 6024,
"iceberg": 0,
"price": "3765",
"tif": "gtc",
"text": "t-my-custom-id",
"stp_act": "-"
}
Example responses
201 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
GET /delivery/{settle}/orders
List futures orders.
Zero-filled order cannot be retrieved 10 minutes after order cancellation.
Name | In | Type | Required | Description |
---|---|---|---|---|
contract | query | string | false | Futures contract. |
status | query | string | true | Only list the orders with this status. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
last_id | query | string | false | Specify the currency name to query in batches, and support up to 100 pass parameters at a time. |
count_total | query | integer | false | Whether to return total number matched. Default to 0(no return). |
settle | path | string | true | Settle currency. |
Parameter | Value |
---|---|
status | open |
status | finished |
count_total | 0 |
count_total | 1 |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [FuturesOrder] |
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | X-Pagination-Limit | integer | Request limit specified. | |
200 | X-Pagination-Offset | integer | Request offset specified. | |
200 | X-Pagination-Total | integer | Total number matched. Only returned if count_total set to 1. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
open
orders matched.DELETE /delivery/{settle}/orders
Cancel all open
orders matched.
Zero-filled order cannot be retrieved 10 minutes after order cancellation.
Name | In | Type | Required | Description |
---|---|---|---|---|
contract | query | string | true | Futures contract. |
side | query | string | false | All bids or asks. Both included if not specified. |
settle | path | string | true | Settle currency. |
Parameter | Value |
---|---|
side | ask |
side | bid |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | All orders matched cancelled. | [FuturesOrder] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/orders'
query_param = 'contract=BTC_USDT_20200814'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
]
GET /delivery/{settle}/orders/{order_id}
Get a single order.
Zero-filled order cannot be retrieved 10 minutes after order cancellation.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
order_id | path | string | true | Retrieve the data of the order with the specified ID. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Order details. | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
DELETE /delivery/{settle}/orders/{order_id}
Cancel a single order.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
order_id | path | string | true | Retrieve the data of the order with the specified ID. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Order details. | FuturesOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": 6024,
"iceberg": 0,
"left": 6024,
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-"
}
GET /delivery/{settle}/my_trades
List personal trading history.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | false | Futures contract. |
order | query | integer(int64) | false | Futures order ID, return related data only if specified. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
last_id | query | string | false | Specify the currency name to query in batches, and support up to 100 pass parameters at a time. |
count_total | query | integer | false | Whether to return total number matched. Default to 0(no return). |
Parameter | Value |
---|---|
settle | usdt |
count_total | 0 |
count_total | 1 |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» id | integer(int64) | Trade ID. |
» create_time | number(double) | Trading time. |
» contract | string | Futures contract. |
» order_id | string | Order ID related. |
» size | integer(int64) | Trading size. |
» close_size | integer(int64) | Number of closed positions: close_size=0 && size>0 Open long position close_size=0 && size<0 Open short position close_size>0 && size>0 && size <= close_size Close > close_size Close short position and open long position close_size<0 && size<0 && size >= close_size Close long postion close_size<0 && size<0 && size < close_size Close long position and open short position |
» price | string | Trading price. |
» role | string | Trade role. Available values are taker and maker . |
» text | string | User defined information. |
» fee | string | Fee deducted. |
» point_fee | string | Points used to deduct fee. |
Property | Value |
---|---|
role | taker |
role | maker |
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | X-Pagination-Limit | integer | Request limit specified. | |
200 | X-Pagination-Offset | integer | Request offset specified. | |
200 | X-Pagination-Total | integer | Total number matched. Only returned if count_total set to 1. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/my_trades'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800.123,
"contract": "BTC_USDT",
"order_id": "21893289839",
"size": 100,
"price": "100.123",
"text": "t-123456",
"fee": "0.01",
"point_fee": "0",
"role": "taker",
"close_size": 0
}
]
GET /delivery/{settle}/position_close
List position close history.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | false | Futures contract. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» time | number(double) | Position close time. |
» contract | string | Futures contract. |
» side | string | Position side, long or short. |
» pnl | string | PNL. |
» pnl_pnl | string | PNL - Position P/L. |
» pnl_fund | string | PNL - Funding Fees. |
» pnl_fee | string | PNL - Transaction Fees. |
» text | string | Text of close order. |
» max_size | string | Max Trade Size. |
» accum_size | string | Cumulative closed position volume. |
» first_open_time | integer(int64) | First Open Time. |
» long_price | string | When 'side' is 'long,' it indicates the opening average price; when closing average price. |
» short_price | string | When 'side' is 'long,' it indicates the opening average price; when closing average price |
Property | Value |
---|---|
side | long |
side | short |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/position_close'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"time": 1546487347,
"pnl": "0.00013",
"pnl_pnl": "0.00011",
"pnl_fund": "0.00001",
"pnl_fee": "0.00001",
"side": "long",
"contract": "BTC_USDT",
"text": "web",
"max_size": "100",
"accum_size": "100",
"first_open_time": 1546487347,
"long_price": "2026.87",
"short_price": "2544.4"
}
]
GET /delivery/{settle}/liquidates
List liquidation history.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | false | Futures contract. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
at | query | integer | false | Specify a liquidation timestamp. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» time | integer(int64) | Liquidation time. |
» contract | string | Futures contract. |
» leverage | string | Position leverage. Not returned in public endpoints. |
» size | integer(int64) | Position size. |
» margin | string | Position margin. Not returned in public endpoints. |
» entry_price | string | Average entry price. Not returned in public endpoints. |
» liq_price | string | Liquidation price. Not returned in public endpoints. |
» mark_price | string | Mark price. Not returned in public endpoints. |
» order_id | integer(int64) | Liquidation order ID. Not returned in public endpoints. |
» order_price | string | Liquidation order price. |
» fill_price | string | Liquidation order average taker price. |
» left | integer(int64) | Liquidation order maker size. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/liquidates'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"time": 1548654951,
"contract": "BTC_USDT",
"size": 600,
"leverage": "25",
"margin": "0.006705256878",
"entry_price": "3536.123",
"liq_price": "3421.54",
"mark_price": "3420.27",
"order_id": 317393847,
"order_price": "3405",
"fill_price": "3424",
"left": 0
}
]
GET /delivery/{settle}/settlements
List settlement history.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | false | Futures contract. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
at | query | integer | false | Specify a settlement timestamp. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» time | integer(int64) | Liquidation time. |
» contract | string | Futures contract. |
» leverage | string | Position leverage. |
» size | integer(int64) | Position size. |
» margin | string | Position margin. |
» entry_price | string | Average entry price. |
» settle_price | string | Settled price. |
» profit | string | Profit. |
» fee | string | Fee deducted. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/settlements'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"time": 1548654951,
"contract": "BTC_USDT",
"size": 600,
"leverage": "25",
"margin": "0.006705256878",
"entry_price": "3536.123",
"settle_price": "3421.54",
"profit": "-6.87498",
"fee": "0.03079386"
}
]
GET /delivery/{settle}/risk_limit_tiers
List risk limit tiers.
When the 'contract' parameter is not passed, the default is to query the risk limits for the top 100 markets.'Limit' and 'offset' correspond to pagination queries at the market level, not to the length of the returned array. This only takes effect empty.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
contract | query | string | false | Futures contract. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Retrieve risk limit configurations for different tiers under a specified contract.] |
» None | object | Retrieve risk limit configurations for different tiers under a specified contract. |
»» tier | integer(int) | Tier. |
»» risk_limit | string | Position risk limit. |
»» initial_rate | string | Initial margin rate. |
»» maintenance_rate | string | Maintenance margin rate. |
»» leverage_max | string | Maximum leverage. |
»» contract | string | Markets, visible only during market pagination requests. |
»» deduction | string | Maintenance margin quick calculation deduction. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/risk_limit_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"maintenance_rate": "0.01",
"tier": 1,
"initial_rate": "0.02",
"leverage_max": "50",
"risk_limit": "20000",
"contract": "ZTX_USDT",
"deduction": "0"
},
{
"maintenance_rate": "0.013",
"tier": 2,
"initial_rate": "0.025",
"leverage_max": "40",
"risk_limit": "30000",
"contract": "ZTX_USDT",
"deduction": "60"
},
{
"maintenance_rate": "0.015",
"tier": 3,
"initial_rate": "0.02857",
"leverage_max": "35",
"risk_limit": "50000",
"contract": "ZTX_USDT",
"deduction": "120"
},
{
"maintenance_rate": "0.02",
"tier": 4,
"initial_rate": "0.03333",
"leverage_max": "30",
"risk_limit": "70000",
"contract": "ZTX_USDT",
"deduction": "370"
},
{
"maintenance_rate": "0.025",
"tier": 5,
"initial_rate": "0.04",
"leverage_max": "25",
"risk_limit": "100000",
"contract": "ZTX_USDT",
"deduction": "720"
}
]
POST /delivery/{settle}/price_orders
Create a price-triggered order.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | FuturesPriceTriggeredOrder | true | none |
» initial | body | object | true | none |
»» contract | body | string | true | 合约标识 |
»» size | body | integer(int64) | false | 代表需要平仓的合约张数, 全平仓:size=0 |
»» price | body | string | true | 交易价, 当价格为 0 时, 表示通过市价方式来下单 |
»» close | body | boolean | false | 单仓模式全部平仓时,必须设置为true执行平仓操作 |
»» tif | body | string | false | Time in force 策略,默认为gtc, 市价单当前只支持 ioc 模式市价单当前只支持 ioc 模式 |
»» text | body | string | false | 订单的来源, 包括: |
»» reduce_only | body | boolean | false | 设置为 true 的时候执行自动减仓操作, 设为 true可确保订单不会开新仓, 只用于平仓或减仓 |
»» auto_size | body | string | false | 单仓模式不需设置auto_size |
» trigger | body | object | true | none |
»» strategy_type | body | integer(int32) | false | 触发策略 |
»» price_type | body | integer(int32) | false | 参考价格Type. 0 - 最新成交价, 1 - 标记价格, 2 - 指数价格 |
»» price | body | string | false | 价格触发时为价格, 价差触发时为价差 |
»» rule | body | integer(int32) | false | 价格条件Type |
»» expiration | body | integer | false | 最长等待触发时间, 超时则取消该订单, 单位是秒 s |
» order_type | body | string | false | Types of stop-profit and stop-loss, including: |
settle | path | string | true | Settle currency. |
部分平仓:plan-close-short-position size>0 部分平仓:plan-close-long-position size<0
gtc: GoodTillCancelled
ioc: ImmediateOrCancelled
web: 网页
api: API 调用
app: 移动端
»» auto_size: 单仓模式不需设置auto_size
»» strategy_type: 触发策略
»» rule: 价格条件Type
strategy_type
和 price_type
算出的价格大于等于 Trigger.Price
时触发, 同时Trigger.Price must > last_pricestrategy_type
和 price_type
算出的价格小于等于 Trigger.Price
时触发, 同时Trigger.Price must < last_price» order_type: Types of stop-profit and stop-loss, including:
close-long-order
: Entrusting order stop profit and stop loss, flat long positionclose-short-order
: loss, short positionclose-long-position
: Position stop-profit stop loss, used to close long positionsclose-short-position
: Position stop-profit stop loss, used to close all short positionsplan-close-long-position
: Position plan take profit and stop loss, used to close long positions in all or part of long positionsplan-close-short-position
: Position plan stop-profit and stop loss, used to close all short positions or partially close short positionsThe two types of entrusted order stop-profit and stop-loss are read-only and cannot be passed in through requests
Parameter | Value |
---|---|
»» tif | gtc |
»» tif | ioc |
»» strategy_type | 0 |
»» strategy_type | 1 |
»» price_type | 0 |
»» price_type | 1 |
»» price_type | 2 |
»» rule | 1 |
»» rule | 2 |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
201 | Created (opens new window) | Order created. | Inline |
Status Code 201
TriggerOrderResponse
Name | Type | Description |
---|---|---|
» id | integer(int64) | Auto order ID. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/price_orders'
query_param = ''
body='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"order_type": "close-long-order"
}
Example responses
201 Response
{
"id": 1432329
}
GET /delivery/{settle}/price_orders
List All Price-triggered Orders.
Name | In | Type | Required | Description |
---|---|---|---|---|
status | query | string | true | Only list the orders with this status. |
contract | query | string | false | Futures contract, return related data only if specified. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
settle | path | string | true | Settle currency. |
Parameter | Value |
---|---|
status | open |
status | finished |
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [FuturesPriceTriggeredOrder] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/price_orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
]
DELETE /delivery/{settle}/price_orders
Cancel All Price-triggered Orders.
Name | In | Type | Required | Description |
---|---|---|---|---|
contract | query | string | true | Futures contract. |
settle | path | string | true | Settle currency. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Batch cancellation request accepted. Query order status by listing orders. | [FuturesPriceTriggeredOrder] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/price_orders'
query_param = 'contract=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
]
GET /delivery/{settle}/price_orders/{order_id}
Get a price-triggered order.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
order_id | path | string | true | Retrieve the data of the order with the specified ID. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Auto order detail. | FuturesPriceTriggeredOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
DELETE /delivery/{settle}/price_orders/{order_id}
cancel a price-triggered order.
Name | In | Type | Required | Description |
---|---|---|---|---|
settle | path | string | true | Settle currency. |
order_id | path | string | true | Retrieve the data of the order with the specified ID. |
Parameter | Value |
---|---|
settle | usdt |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Auto order detail. | FuturesPriceTriggeredOrder |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/delivery/usdt/price_orders/string'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"initial": {
"contract": "BTC_USDT",
"size": 100,
"price": "5.03"
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "3000",
"rule": 1,
"expiration": 86400
},
"id": 1283293,
"user": 1234,
"create_time": 1514764800,
"finish_time": 1514764900,
"trade_id": 13566,
"status": "finished",
"finish_as": "cancelled",
"reason": "",
"order_type": "close-long-order"
}
Options API.
GET /options/underlyings
List all underlyings.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» name | string | Underlying name. |
» index_price | string | Spot index price (quote currency). |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/underlyings'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"name": "BTC_USDT",
"index_price": "70000"
}
]
GET /options/expirations
List all expiration times.
Name | In | Type | Required | Description |
---|---|---|---|---|
underlying | query | string | true | Underlying (Obtained by listing underlying endpoint). |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List expiration times of specified underlying. | [integer] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | integer(int64) | Unix timestamp of the expiration time. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/expirations'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
1637913600
]
GET /options/contracts
List all the contracts with specified underlying and expiration time.
Name | In | Type | Required | Description |
---|---|---|---|---|
underlying | query | string | true | Underlying (Obtained by listing underlying endpoint). |
expiration | query | integer(int64) | false | Unix timestamp of the expiration time. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Options contract detail.] |
» None | object | Options contract detail. |
»» name | string | Options contract name. |
»» tag | string | tag. |
»» create_time | number(double) | Creation time. |
»» expiration_time | number(double) | Expiration time. |
»» is_call | boolean | true means call options, while false is put options. |
»» multiplier | string | Multiplier used in converting from invoicing to settlement currency. |
»» underlying | string | Underlying. |
»» underlying_price | string | Underlying price (quote currency). |
»» last_price | string | Last trading price. |
»» mark_price | string | Current mark price (quote currency). |
»» index_price | string | Current index price (quote currency). |
»» maker_fee_rate | string | Maker fee rate, where negative means rebate. |
»» taker_fee_rate | string | Taker fee rate. |
»» order_price_round | string | Minimum order price increment. |
»» mark_price_round | string | Minimum mark price increment. |
»» order_size_min | integer(int64) | Minimum order size the contract allowed. |
»» order_size_max | integer(int64) | Maximum order size the contract allowed. |
»» order_price_deviate | string | The positive and negative offset allowed between the order price and the current mark price, that order_price must meet the following conditions:order_price is within the range of mark_price +/- order_price_deviate * underlying_price and does not distinguish between buy and sell orders |
»» ref_discount_rate | string | Referral fee rate discount. |
»» ref_rebate_rate | string | Referrer commission rate. |
»» orderbook_id | integer(int64) | Current orderbook ID. |
»» trade_id | integer(int64) | Current trade ID. |
»» trade_size | integer(int64) | Historical accumulated trade size. |
»» position_size | integer(int64) | Current total long position size. |
»» orders_limit | integer | Maximum number of open orders. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/contracts'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"name": "BTC_USDT-20211130-65000-C",
"tag": "WEEK",
"create_time": 1636702700,
"expiration_time": 1637913600,
"is_call": true,
"strike_price": "65000",
"last_price": "13000",
"mark_price": "14010",
"orderbook_id": 9,
"trade_id": 1,
"trade_size": 10,
"position_size": 10,
"underlying": "BTC_USDT",
"underlying_price": "70000",
"multiplier": "0.0001",
"order_price_round": "0.1",
"mark_price_round": "0.1",
"maker_fee_rate": "0.0004",
"taker_fee_rate": "0.0004",
"price_limit_fee_rate": "0.1",
"ref_discount_rate": "0",
"ref_rebate_rate": "0",
"order_price_deviate": "0.5",
"order_size_min": 1,
"order_size_max": 100000,
"orders_limit": 50
}
]
GET /options/contracts/{contract}
Query specified contract detail.
Name | In | Type | Required | Description |
---|---|---|---|---|
contract | path | string | true | none |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Options contract detail.
Name | Type | Description |
---|---|---|
» name | string | Options contract name. |
» tag | string | tag. |
» create_time | number(double) | Creation time. |
» expiration_time | number(double) | Expiration time. |
» is_call | boolean | true means call options, while false is put options. |
» multiplier | string | Multiplier used in converting from invoicing to settlement currency. |
» underlying | string | Underlying. |
» underlying_price | string | Underlying price (quote currency). |
» last_price | string | Last trading price. |
» mark_price | string | Current mark price (quote currency). |
» index_price | string | Current index price (quote currency). |
» maker_fee_rate | string | Maker fee rate, where negative means rebate. |
» taker_fee_rate | string | Taker fee rate. |
» order_price_round | string | Minimum order price increment. |
» mark_price_round | string | Minimum mark price increment. |
» order_size_min | integer(int64) | Minimum order size the contract allowed. |
» order_size_max | integer(int64) | Maximum order size the contract allowed. |
» order_price_deviate | string | The positive and negative offset allowed between the order price and the current mark price, that order_price must meet the following conditions:order_price is within the range of mark_price +/- order_price_deviate * underlying_price and does not distinguish between buy and sell orders |
» ref_discount_rate | string | Referral fee rate discount. |
» ref_rebate_rate | string | Referrer commission rate. |
» orderbook_id | integer(int64) | Current orderbook ID. |
» trade_id | integer(int64) | Current trade ID. |
» trade_size | integer(int64) | Historical accumulated trade size. |
» position_size | integer(int64) | Current total long position size. |
» orders_limit | integer | Maximum number of open orders. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/contracts/BTC_USDT-20211130-65000-C'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"name": "BTC_USDT-20211130-65000-C",
"tag": "WEEK",
"create_time": 1636702700,
"expiration_time": 1637913600,
"is_call": true,
"strike_price": "65000",
"last_price": "13000",
"mark_price": "14010",
"orderbook_id": 9,
"trade_id": 1,
"trade_size": 10,
"position_size": 10,
"underlying": "BTC_USDT",
"underlying_price": "70000",
"multiplier": "0.0001",
"order_price_round": "0.1",
"mark_price_round": "0.1",
"maker_fee_rate": "0.0004",
"taker_fee_rate": "0.0004",
"price_limit_fee_rate": "0.1",
"ref_discount_rate": "0",
"ref_rebate_rate": "0",
"order_price_deviate": "0.5",
"order_size_min": 1,
"order_size_max": 100000,
"orders_limit": 50
}
GET /options/settlements
List settlement history.
Name | In | Type | Required | Description |
---|---|---|---|---|
underlying | query | string | true | Underlying (Obtained by listing underlying endpoint). |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» time | number(double) | Last changed time of configuration. |
» contract | string | Options contract name. |
» profit | string | Settlement profit per size (quote currency). |
» fee | string | Settlement fee per size (quote currency). |
» strike_price | string | Strike price (quote currency). |
» settle_price | string | Settlement price (quote currency). |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/settlements'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"time": 1598839200,
"profit": "312.35",
"fee": "0.3284",
"settle_price": "11687.65",
"contract": "BTC-WEEKLY-200824-11000-P",
"strike_price": "12000"
}
]
GET /options/settlements/{contract}
Get specified contract's settlement.
Name | In | Type | Required | Description |
---|---|---|---|---|
contract | path | string | true | none |
underlying | query | string | true | Underlying (Obtained by listing underlying endpoint). |
at | query | integer(int64) | true | none |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» time | number(double) | Last changed time of configuration. |
» contract | string | Options contract name. |
» profit | string | Settlement profit per size (quote currency). |
» fee | string | Settlement fee per size (quote currency). |
» strike_price | string | Strike price (quote currency). |
» settle_price | string | Settlement price (quote currency). |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/settlements/BTC_USDT-20211130-65000-C'
query_param = 'underlying=BTC_USDT&at=0'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"time": 1598839200,
"profit": "312.35",
"fee": "0.3284",
"settle_price": "11687.65",
"contract": "BTC-WEEKLY-200824-11000-P",
"strike_price": "12000"
}
GET /options/my_settlements
List my options settlements.
Name | In | Type | Required | Description |
---|---|---|---|---|
underlying | query | string | true | Underlying (Obtained by listing underlying endpoint). |
contract | query | string | false | Options contract name. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» time | number(double) | Settlement time. |
» underlying | string | Underlying. |
» contract | string | Options contract name. |
» strike_price | string | Strike price (quote currency). |
» settle_price | string | Settlement price (quote currency). |
» size | integer(int64) | Size. |
» settle_profit | string | Settlement profit (quote currency). |
» fee | string | Fee (quote currency). |
» realised_pnl | string | The accumulated profit and loss of opening a position, including premium, fee, settlement profit, etc. (quote currency) |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/my_settlements'
query_param = 'underlying=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"size": -1,
"settle_profit": "0",
"contract": "BTC_USDT-20220624-26000-C",
"strike_price": "26000",
"time": 1656057600,
"settle_price": "20917.461281337048",
"underlying": "BTC_USDT",
"realised_pnl": "-0.00116042",
"fee": "0"
}
]
GET /options/order_book
Options order book.
Bids will be sorted by price from high to low, while asks sorted reversely.
Name | In | Type | Required | Description |
---|---|---|---|---|
contract | query | string | true | Options contract name. |
interval | query | string | false | Order depth. 0 means no aggregation is applied. default to 0. |
limit | query | integer | false | Maximum number of order depth data in asks or bids. |
with_id | query | boolean | false | Whether to return depth update ID. This ID increments by 1 each time. |
Parameter | Value |
---|---|
interval | 0 |
interval | 0.1 |
interval | 0.01 |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Depth query successful. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» id | integer(int64) | Order Book ID. Increases by 1 on every order book change. Set with_id=true to include this field in response |
» current | number(double) | Response data generation timestamp. |
» update | number(double) | Order book changed timestamp. |
» asks | array | Asks order depth. |
»» futures_order_book_item | object | none |
»»» p | string | Price (quote currency). |
»»» s | integer(int64) | Size. |
»» bids | array | Bids order depth. |
»»» futures_order_book_item | object | none |
»»»» p | string | Price (quote currency). |
»»»» s | integer(int64) | Size. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/order_book'
query_param = 'contract=BTC_USDT-20210916-5000-C'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"id": 123456,
"current": 1623898993.123,
"update": 1623898993.121,
"asks": [
{
"p": "1.52",
"s": 100
},
{
"p": "1.53",
"s": 40
}
],
"bids": [
{
"p": "1.17",
"s": 150
},
{
"p": "1.16",
"s": 203
}
]
}
GET /options/tickers
List tickers of options contracts.
Name | In | Type | Required | Description |
---|---|---|---|---|
underlying | query | string | true | Underlying (Obtained by listing underlying endpoint). |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Options contract detail. |
»» name | string | Options contract name. |
»» last_price | string | Last trading price (quote currency). |
»» mark_price | string | Current mark price (quote currency). |
»» index_price | string | Current index price (quote currency). |
»» ask1_size | integer(int64) | Best ask size. |
»» ask1_price | string | Best ask price. |
»» bid1_size | integer(int64) | Best bid size. |
»» bid1_price | string | Best bid price. |
»» position_size | integer(int64) | Current total long position size. |
»» mark_iv | string | Implied volatility. |
»» bid_iv | string | Bid side implied volatility. |
»» ask_iv | string | Ask side implied volatility. |
»» leverage | string | Current leverage. Formula: underlying_price / mark_price * delta. |
»» delta | string | Delta. |
»» gamma | string | Gamma. |
»» vega | string | Vega. |
»» theta | string | Theta. |
»» rho | string | Rho. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/tickers'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"name": "BTC_USDT-20211130-65000-C",
"last_price": "13000",
"mark_price": "14010",
"position_size": 10,
"ask1_size": 0,
"ask1_price": "0",
"bid1_size": 1,
"bid1_price": "11",
"vega": "41.41202",
"theta": "-120.1506",
"rho": "6.52485",
"gamma": "0.00004",
"delta": "0.33505",
"mark_iv": "0.123",
"bid_iv": "0.023",
"ask_iv": "0.342",
"leverage": "13"
}
]
GET /options/underlying/tickers/{underlying}
Get underlying ticker.
Name | In | Type | Required | Description |
---|---|---|---|---|
underlying | path | string | true | Underlying. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Options underlying detail.
Name | Type | Description |
---|---|---|
» trade_put | integer(int64) | Total put options trades amount in last 24h. |
» trade_call | integer(int64) | Total call options trades amount in last 24h. |
» index_price | string | Index price (quote currency). |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/underlying/tickers/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"trade_put": 33505,
"trade_call": 123,
"index_price": "76543.3"
}
GET /options/candlesticks
Get options candlesticks.
Name | In | Type | Required | Description |
---|---|---|---|---|
contract | query | string | true | Options contract name. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
interval | query | string | false | Interval time between data points. |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Parameter | Value |
---|---|
interval | 1m |
interval | 5m |
interval | 15m |
interval | 30m |
interval | 1h |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | data point in every timestamp. |
»» t | number(double) | Unix timestamp in seconds. |
»» v | integer(int64) | size volume (contract size). Only returned if contract is not prefixed. |
»» c | string | Close price (quote currency, unit: underlying corresponding option price). |
»» h | string | Highest price (quote currency, unit: underlying corresponding option price) |
»» l | string | Lowest price (quote currency, unit: underlying corresponding option price). |
»» o | string | Open price (quote currency, unit: underlying corresponding option price). |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/candlesticks'
query_param = 'contract=BTC_USDT-20210916-5000-C'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"t": 1539852480,
"v": 97151,
"c": "1.032",
"h": "1.032",
"l": "1.032",
"o": "1.032"
}
]
GET /options/underlying/candlesticks
Mark price candlesticks of an underlying.
Name | In | Type | Required | Description |
---|---|---|---|---|
underlying | query | string | true | Underlying (Obtained by listing underlying endpoint). |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
interval | query | string | false | Interval time between data points. |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Parameter | Value |
---|---|
interval | 1m |
interval | 5m |
interval | 15m |
interval | 30m |
interval | 1h |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [data point in every timestamp.] |
» None | object | data point in every timestamp. |
»» t | number(double) | Unix timestamp in seconds. |
»» v | integer(int64) | size volume (contract size). Only returned if contract is not prefixed. |
»» c | string | Close price (quote currency). |
»» h | string | Highest price (quote currency). |
»» l | string | Lowest price (quote currency). |
»» o | string | Open price (quote currency). |
»» sum | string | Trading volume (unit: Quote currency). |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/underlying/candlesticks'
query_param = 'underlying=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"t": 1539852480,
"v": 97151,
"c": "1.032",
"h": "1.032",
"l": "1.032",
"o": "1.032",
"sum": "3580"
}
]
GET /options/trades
Options trade history.
Name | In | Type | Required | Description |
---|---|---|---|---|
contract | query | string | false | Options contract name. |
type | query | string(P) | false | C is call, while P is put. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» id | integer(int64) | Trade ID. |
» create_time | number(double) | Trading time. |
» create_time_ms | number(double) | Trading time, with milliseconds set to 3 decimal places. |
» contract | string | Futures contract. |
» size | integer(int64) | Trading size. |
» price | string | Trading price (quote currency). |
» is_internal | boolean | Whether internal trade. Internal trade refers to the takeover of liquidation orders by the insurance fund and ADL users. Since it is not a normal matching on the market depth, the transaction price may deviate, and it will not be recorded in the K-line. an internal trade, this field will not be returned. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/trades'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800,
"contract": "BTC_USDT",
"size": -100,
"price": "100.123"
}
]
GET /options/accounts
List options account.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» user | integer(int64) | User ID. |
» total | string | 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 amount. |
» currency | string | Settle currency. |
» orders_limit | integer(int32) | Maximum number of outstanding orders. |
» position_notional_limit | integer(int64) | Notional value upper limit, including the nominal value of positions and outstanding orders |
Property | Value |
---|---|
margin_mode | 0 |
margin_mode | 1 |
margin_mode | 2 |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"user": 666,
"currency": "USDT",
"short_enabled": true,
"mmp_enabled": false,
"liq_triggered": false,
"margin_mode": 0,
"total": "1650.443022",
"position_value": "-40.1136",
"equity": "1610.329422",
"unrealised_pnl": "-0.7811",
"init_margin": "0",
"maint_margin": "135.541485",
"order_margin": "139.74496",
"ask_order_margin": "139.74496",
"bid_order_margin": "0",
"available": "1514.901537",
"point": "0",
"orders_limit": 10,
"position_notional_limit": 1000000
}
GET /options/account_book
List account changing history.
Name | In | Type | Required | Description |
---|---|---|---|---|
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
type | query | string | false | Changing Type: |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
type: Changing Type:
Parameter | Value |
---|---|
type | dnw |
type | prem |
type | fee |
type | refr |
type | set |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» time | number(double) | Change time. |
» change | string | Amount changed (USDT). |
» balance | string | Account total balance after change (USDT). |
» type | string | Changing Type: - dnw: Deposit & Withdraw - prem: Trading premium - fee: Trading fee - refr: Referrer rebate - point_dnw: point_fee: POINT Trading fee - point_refr: POINT Referrer rebate |
» text | string | custom text. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"time": 1636426005,
"change": "-0.16",
"balance": "7378.189",
"text": "BTC_USDT-20211216-5000-P:25",
"type": "fee"
}
]
GET /options/positions
List user's positions of specified underlying.
Name | In | Type | Required | Description |
---|---|---|---|---|
underlying | query | string | false | Underlying. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Options position information.] |
» None | object | Options position information. |
»» user | integer | User ID. |
»» underlying | string | Underlying. |
»» underlying_price | string | Underlying price (quote currency). |
»» contract | string | Options contract name. |
»» size | integer(int64) | Position size (contract size). |
»» entry_price | string | Entry size (quote currency). |
»» mark_price | string | Current mark price (quote currency). |
»» mark_iv | string | Implied volatility. |
»» realised_pnl | string | Realized PNL. |
»» unrealised_pnl | string | Unrealized PNL. |
»» pending_orders | integer | Current open orders. |
»» close_order | object|null | Current close order if any, or null . |
»»» id | integer(int64) | Close order ID. |
»»» price | string | Close order price (quote currency). |
»»» is_liq | boolean | Is the close order from liquidation. |
»» delta | string | Delta. |
»» gamma | string | Gamma. |
»» vega | string | Vega. |
»» theta | string | Theta. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/positions'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"user": 11027586,
"underlying": "BTC_USDT",
"underlying_price": "70000",
"contract": "BTC_USDT-20211216-5000-P",
"size": 10,
"entry_price": "1234",
"realised_pnl": "120",
"mark_price": "6000",
"mark_iv": "0.9638",
"unrealised_pnl": "-320",
"pending_orders": 1,
"close_order": {
"id": 232323,
"price": "5779",
"is_liq": false
},
"delta": "-0.0046",
"gamma": "0",
"vega": "2.87656",
"theta": "-1.00247"
}
]
GET /options/positions/{contract}
Get specified contract position.
Name | In | Type | Required | Description |
---|---|---|---|---|
contract | path | string | true | none |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Options position information.
Name | Type | Description |
---|---|---|
» user | integer | User ID. |
» underlying | string | Underlying. |
» underlying_price | string | Underlying price (quote currency). |
» contract | string | Options contract name. |
» size | integer(int64) | Position size (contract size). |
» entry_price | string | Entry size (quote currency). |
» mark_price | string | Current mark price (quote currency). |
» mark_iv | string | Implied volatility. |
» realised_pnl | string | Realized PNL. |
» unrealised_pnl | string | Unrealized PNL. |
» pending_orders | integer | Current open orders. |
» close_order | object|null | Current close order if any, or null . |
»» id | integer(int64) | Close order ID. |
»» price | string | Close order price (quote currency). |
»» is_liq | boolean | Is the close order from liquidation. |
» delta | string | Delta. |
» gamma | string | Gamma. |
» vega | string | Vega. |
» theta | string | Theta. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/positions/BTC_USDT-20211130-65000-C'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"user": 11027586,
"underlying": "BTC_USDT",
"underlying_price": "70000",
"contract": "BTC_USDT-20211216-5000-P",
"size": 10,
"entry_price": "1234",
"realised_pnl": "120",
"mark_price": "6000",
"mark_iv": "0.9638",
"unrealised_pnl": "-320",
"pending_orders": 1,
"close_order": {
"id": 232323,
"price": "5779",
"is_liq": false
},
"delta": "-0.0046",
"gamma": "0",
"vega": "2.87656",
"theta": "-1.00247"
}
GET /options/position_close
List user's liquidation history of specified underlying.
Name | In | Type | Required | Description |
---|---|---|---|---|
underlying | query | string | true | Underlying (Obtained by listing underlying endpoint). |
contract | query | string | false | Options contract name. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» time | number(double) | Position close time. |
» contract | string | Options contract name. |
» side | string | Position side, long or short. |
» pnl | string | PNL. |
» text | string | Text of close order. |
» settle_size | string | settlement size. |
Property | Value |
---|---|
side | long |
side | short |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/position_close'
query_param = 'underlying=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"time": 1631764800,
"pnl": "-42914.291",
"settle_size": "-10001",
"side": "short",
"contract": "BTC_USDT-20210916-5000-C",
"text": "settled"
}
]
POST /options/orders
Create an options order.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» contract | body | string | true | Contract name. |
» size | body | integer(int64) | true | Order size. Specify positive number to make a bid, and negative number to ask |
» iceberg | body | integer(int64) | false | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
» price | body | string | false | Order price. 0 for market order with tif set as ioc (USDT). |
» close | body | boolean | false | Set as true to close the position, with size set to 0. |
» reduce_only | body | boolean | false | Set as true to be reduce-only order. |
» mmp | body | boolean | false | When set to true, delegate to MMP. |
» tif | body | string | false | Time in force |
» text | body | string | false | User defined information. If not empty, must follow the rules below: |
» tif: Time in force
» text: User defined information. If not empty, must follow the rules below:
t-
t-
prefixParameter | Value |
---|---|
» tif | gtc |
» tif | ioc |
» tif | poc |
Status | Meaning | Description | Schema |
---|---|---|---|
201 | Created (opens new window) | Order detail. | Inline |
Status Code 201
Options order detail.
Name | Type | Description |
---|---|---|
» id | integer(int64) | Options order ID. |
» user | integer | User ID. |
» create_time | number(double) | Creation time of order. |
» finish_time | number(double) | Order finished time. Not returned if order is open. |
» finish_as | string | Ending method, including: - filled: fully completed - canceled: user canceled - liquidated: forced liquidation cancellation - ioc: Not fully filled immediately because tif is set to ioc - auto_deleveraged: automatic deleveraging cancel - reduce_only: Increased position is cancelled, or the position is closed - position_closed: Because the position was closed, the pending order was canceled - reduce_out: Only reduce the excluded pending orders that are not easy to be filled - mmp_cancelled: MMP canceled |
» status | string | Order status - open : waiting to be traded- finished : finished |
» contract | string | Contract name. |
» size | integer(int64) | Order size. Specify positive number to make a bid, and negative number to ask |
» iceberg | integer(int64) | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
» price | string | Order price. 0 for market order with tif set as ioc (USDT). |
» is_close | boolean | Is the order to close position. |
» is_reduce_only | boolean | Is the order reduce-only. |
» is_liq | boolean | Is the order for liquidation. |
» is_mmp | boolean | Whether it is MMP delegation. Corresponds to mmp in the request. |
» tif | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee |
» left | integer(int64) | Size left to be traded. |
» fill_price | string | Fill price of the order. |
» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance |
» tkfr | string | Taker fee. |
» mkfr | string | Maker fee. |
» refu | integer | Reference user ID. |
» refr | string | Referrer rebate. |
Property | Value |
---|---|
finish_as | filled |
finish_as | cancelled |
finish_as | liquidated |
finish_as | ioc |
finish_as | auto_deleveraged |
finish_as | reduce_only |
finish_as | position_closed |
finish_as | reduce_out |
finish_as | mmp_cancelled |
status | open |
status | finished |
tif | gtc |
tif | ioc |
tif | poc |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/orders'
query_param = ''
body='{"size":-1,"iceberg":0,"contract":"BTC_USDT-20210916-5000-C","text":"-","tif":"gtc","price":"100"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"size": -1,
"iceberg": 0,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"tif": "gtc",
"price": "100"
}
Example responses
201 Response
{
"status": "finished",
"size": -1,
"id": 2,
"iceberg": 0,
"is_liq": false,
"is_close": false,
"is_mmp": false,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"fill_price": "100",
"finish_as": "filled",
"left": 0,
"tif": "gtc",
"is_reduce_only": false,
"create_time": 1631763361,
"finish_time": 1631763397,
"price": "100"
}
GET /options/orders
List options orders.
Name | In | Type | Required | Description |
---|---|---|---|---|
contract | query | string | false | Options contract name. |
underlying | query | string | false | Underlying. |
status | query | string | true | Only list the orders with this status. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Parameter | Value |
---|---|
status | open |
status | finished |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Options order detail.] |
» None | object | Options order detail. |
»» id | integer(int64) | Options order ID. |
»» user | integer | User ID. |
»» create_time | number(double) | Creation time of order. |
»» finish_time | number(double) | Order finished time. Not returned if order is open. |
»» finish_as | string | Ending method, including: - filled: fully completed - canceled: user canceled - liquidated: forced liquidation cancellation - ioc: Not fully filled immediately because tif is set to ioc - auto_deleveraged: automatic deleveraging cancel - reduce_only: Increased position is cancelled, or the position is closed - position_closed: Because the position was closed, the pending order was canceled - reduce_out: Only reduce the excluded pending orders that are not easy to be filled - mmp_cancelled: MMP canceled |
»» status | string | Order status - open : waiting to be traded- finished : finished |
»» contract | string | Contract name. |
»» size | integer(int64) | Order size. Specify positive number to make a bid, and negative number to ask |
»» iceberg | integer(int64) | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
»» price | string | Order price. 0 for market order with tif set as ioc (USDT). |
»» is_close | boolean | Is the order to close position. |
»» is_reduce_only | boolean | Is the order reduce-only. |
»» is_liq | boolean | Is the order for liquidation. |
»» is_mmp | boolean | Whether it is MMP delegation. Corresponds to mmp in the request. |
»» tif | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee |
»» left | integer(int64) | Size left to be traded. |
»» fill_price | string | Fill price of the order. |
»» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance |
»» tkfr | string | Taker fee. |
»» mkfr | string | Maker fee. |
»» refu | integer | Reference user ID. |
»» refr | string | Referrer rebate. |
Property | Value |
---|---|
finish_as | filled |
finish_as | cancelled |
finish_as | liquidated |
finish_as | ioc |
finish_as | auto_deleveraged |
finish_as | reduce_only |
finish_as | position_closed |
finish_as | reduce_out |
finish_as | mmp_cancelled |
status | open |
status | finished |
tif | gtc |
tif | ioc |
tif | poc |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
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"
}
]
open
orders matched.DELETE /options/orders
Cancel all open
orders matched.
Name | In | Type | Required | Description |
---|---|---|---|---|
contract | query | string | false | Options contract name. |
underlying | query | string | false | Underlying. |
side | query | string | false | All bids or asks. Both included if not specified. |
Parameter | Value |
---|---|
side | ask |
side | bid |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | All orders matched cancelled. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Options order detail.] |
» None | object | Options order detail. |
»» id | integer(int64) | Options order ID. |
»» user | integer | User ID. |
»» create_time | number(double) | Creation time of order. |
»» finish_time | number(double) | Order finished time. Not returned if order is open. |
»» finish_as | string | Ending method, including: - filled: fully completed - canceled: user canceled - liquidated: forced liquidation cancellation - ioc: Not fully filled immediately because tif is set to ioc - auto_deleveraged: automatic deleveraging cancel - reduce_only: Increased position is cancelled, or the position is closed - position_closed: Because the position was closed, the pending order was canceled - reduce_out: Only reduce the excluded pending orders that are not easy to be filled - mmp_cancelled: MMP canceled |
»» status | string | Order status - open : waiting to be traded- finished : finished |
»» contract | string | Contract name. |
»» size | integer(int64) | Order size. Specify positive number to make a bid, and negative number to ask |
»» iceberg | integer(int64) | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
»» price | string | Order price. 0 for market order with tif set as ioc (USDT). |
»» is_close | boolean | Is the order to close position. |
»» is_reduce_only | boolean | Is the order reduce-only. |
»» is_liq | boolean | Is the order for liquidation. |
»» is_mmp | boolean | Whether it is MMP delegation. Corresponds to mmp in the request. |
»» tif | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee |
»» left | integer(int64) | Size left to be traded. |
»» fill_price | string | Fill price of the order. |
»» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance |
»» tkfr | string | Taker fee. |
»» mkfr | string | Maker fee. |
»» refu | integer | Reference user ID. |
»» refr | string | Referrer rebate. |
Property | Value |
---|---|
finish_as | filled |
finish_as | cancelled |
finish_as | liquidated |
finish_as | ioc |
finish_as | auto_deleveraged |
finish_as | reduce_only |
finish_as | position_closed |
finish_as | reduce_out |
finish_as | mmp_cancelled |
status | open |
status | finished |
tif | gtc |
tif | ioc |
tif | poc |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"status": "finished",
"size": -1,
"id": 2,
"iceberg": 0,
"is_liq": false,
"is_close": false,
"is_mmp": false,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"fill_price": "100",
"finish_as": "filled",
"left": 0,
"tif": "gtc",
"is_reduce_only": false,
"create_time": 1631763361,
"finish_time": 1631763397,
"price": "100"
}
]
GET /options/orders/{order_id}
Get a single order.
Name | In | Type | Required | Description |
---|---|---|---|---|
order_id | path | integer(int64) | true | Order ID returned on successful order creation. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Order detail. | Inline |
Status Code 200
Options order detail.
Name | Type | Description |
---|---|---|
» id | integer(int64) | Options order ID. |
» user | integer | User ID. |
» create_time | number(double) | Creation time of order. |
» finish_time | number(double) | Order finished time. Not returned if order is open. |
» finish_as | string | Ending method, including: - filled: fully completed - canceled: user canceled - liquidated: forced liquidation cancellation - ioc: Not fully filled immediately because tif is set to ioc - auto_deleveraged: automatic deleveraging cancel - reduce_only: Increased position is cancelled, or the position is closed - position_closed: Because the position was closed, the pending order was canceled - reduce_out: Only reduce the excluded pending orders that are not easy to be filled - mmp_cancelled: MMP canceled |
» status | string | Order status - open : waiting to be traded- finished : finished |
» contract | string | Contract name. |
» size | integer(int64) | Order size. Specify positive number to make a bid, and negative number to ask |
» iceberg | integer(int64) | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
» price | string | Order price. 0 for market order with tif set as ioc (USDT). |
» is_close | boolean | Is the order to close position. |
» is_reduce_only | boolean | Is the order reduce-only. |
» is_liq | boolean | Is the order for liquidation. |
» is_mmp | boolean | Whether it is MMP delegation. Corresponds to mmp in the request. |
» tif | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee |
» left | integer(int64) | Size left to be traded. |
» fill_price | string | Fill price of the order. |
» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance |
» tkfr | string | Taker fee. |
» mkfr | string | Maker fee. |
» refu | integer | Reference user ID. |
» refr | string | Referrer rebate. |
Property | Value |
---|---|
finish_as | filled |
finish_as | cancelled |
finish_as | liquidated |
finish_as | ioc |
finish_as | auto_deleveraged |
finish_as | reduce_only |
finish_as | position_closed |
finish_as | reduce_out |
finish_as | mmp_cancelled |
status | open |
status | finished |
tif | gtc |
tif | ioc |
tif | poc |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"status": "finished",
"size": -1,
"id": 2,
"iceberg": 0,
"is_liq": false,
"is_close": false,
"is_mmp": false,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"fill_price": "100",
"finish_as": "filled",
"left": 0,
"tif": "gtc",
"is_reduce_only": false,
"create_time": 1631763361,
"finish_time": 1631763397,
"price": "100"
}
DELETE /options/orders/{order_id}
Cancel a single order.
Name | In | Type | Required | Description |
---|---|---|---|---|
order_id | path | integer(int64) | true | Order ID returned on successful order creation. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Order detail. | Inline |
Status Code 200
Options order detail.
Name | Type | Description |
---|---|---|
» id | integer(int64) | Options order ID. |
» user | integer | User ID. |
» create_time | number(double) | Creation time of order. |
» finish_time | number(double) | Order finished time. Not returned if order is open. |
» finish_as | string | Ending method, including: - filled: fully completed - canceled: user canceled - liquidated: forced liquidation cancellation - ioc: Not fully filled immediately because tif is set to ioc - auto_deleveraged: automatic deleveraging cancel - reduce_only: Increased position is cancelled, or the position is closed - position_closed: Because the position was closed, the pending order was canceled - reduce_out: Only reduce the excluded pending orders that are not easy to be filled - mmp_cancelled: MMP canceled |
» status | string | Order status - open : waiting to be traded- finished : finished |
» contract | string | Contract name. |
» size | integer(int64) | Order size. Specify positive number to make a bid, and negative number to ask |
» iceberg | integer(int64) | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
» price | string | Order price. 0 for market order with tif set as ioc (USDT). |
» is_close | boolean | Is the order to close position. |
» is_reduce_only | boolean | Is the order reduce-only. |
» is_liq | boolean | Is the order for liquidation. |
» is_mmp | boolean | Whether it is MMP delegation. Corresponds to mmp in the request. |
» tif | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee |
» left | integer(int64) | Size left to be traded. |
» fill_price | string | Fill price of the order. |
» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance |
» tkfr | string | Taker fee. |
» mkfr | string | Maker fee. |
» refu | integer | Reference user ID. |
» refr | string | Referrer rebate. |
Property | Value |
---|---|
finish_as | filled |
finish_as | cancelled |
finish_as | liquidated |
finish_as | ioc |
finish_as | auto_deleveraged |
finish_as | reduce_only |
finish_as | position_closed |
finish_as | reduce_out |
finish_as | mmp_cancelled |
status | open |
status | finished |
tif | gtc |
tif | ioc |
tif | poc |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"status": "finished",
"size": -1,
"id": 2,
"iceberg": 0,
"is_liq": false,
"is_close": false,
"is_mmp": false,
"contract": "BTC_USDT-20210916-5000-C",
"text": "-",
"fill_price": "100",
"finish_as": "filled",
"left": 0,
"tif": "gtc",
"is_reduce_only": false,
"create_time": 1631763361,
"finish_time": 1631763397,
"price": "100"
}
POST /options/countdown_cancel_all
Countdown cancel orders.
Option order heartbeat detection, when the timeout
time set by the user is reached, if the existing countdown is not canceled or a new countdown is set, the related option pending order
will be automatically canceled.
This interface can be called repeatedly to set a new countdown or cancel the countdown.
Usage example: Repeat this interface at intervals of 30 seconds, with each countdown timeout
set to 30 (seconds).
If this interface is not called again within 30 seconds, all pending orders on the underlying
contract
you specified will be automatically cancelled. If underlying
contract
is not specified, user will be automatically cancelled
If timeout
is set to 0 within 30 seconds, the countdown timer will expire and the automatic order cancellation function will be cancelled.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» timeout | body | integer(int32) | true | Countdown time in seconds |
» contract | body | string | false | Options contract name. |
» underlying | body | string | false | Underlying. |
» timeout: Countdown time in seconds At least 5 seconds, 0 means cancel countdown
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Set countdown successfully. | Inline |
Status Code 200
triggerTime
Name | Type | Description |
---|---|---|
» triggerTime | integer(int64) | Timestamp of the end of the countdown, in milliseconds. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/countdown_cancel_all'
query_param = ''
body='{"timeout":30,"contract":"BTC_USDT-20241001-46000-C","underlying":"BTC_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"timeout": 30,
"contract": "BTC_USDT-20241001-46000-C",
"underlying": "BTC_USDT"
}
Example responses
200 Response
{
"triggerTime": "1660039145000"
}
GET /options/my_trades
List personal trading history.
Name | In | Type | Required | Description |
---|---|---|---|---|
underlying | query | string | true | Underlying (Obtained by listing underlying endpoint). |
contract | query | string | false | Options contract name. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» id | integer(int64) | Trade ID. |
» create_time | number(double) | Trading time. |
» contract | string | Options contract name. |
» order_id | integer | Order ID related. |
» size | integer(int64) | Trading size. |
» price | string | Trading price (quote currency). |
» underlying_price | string | Underlying price (quote currency). |
» role | string | Trade role. Available values are taker and maker . |
Property | Value |
---|---|
role | taker |
role | maker |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/my_trades'
query_param = 'underlying=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"underlying_price": "48000",
"size": 1,
"contract": "BTC_USDT-20210916-5000-C",
"id": 1,
"role": "taker",
"create_time": 1631763397,
"order_id": 4,
"price": "100"
}
]
POST /options/mmp
MMP Settings
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» underlying | body | string | true | Underlying. |
» window | body | integer(int32) | true | Time window (milliseconds), between 1-5000, 0 means disabling MMP. |
» frozen_period | body | integer(int32) | true | Freeze duration (milliseconds), 0 means always frozen, need to call reset API to unfreeze |
» qty_limit | body | string | true | Trading volume upper limit (positive number, up to 2 decimal places). |
» delta_limit | body | string | true | Upper limit of net delta value (positive number, up to 2 decimal places). |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | MMP Information. | Inline |
Status Code 200
MMP Settings
Name | Type | Description |
---|---|---|
» underlying | string | Underlying. |
» window | integer(int32) | Time window (milliseconds), between 1-5000, 0 means disabling MMP. |
» frozen_period | integer(int32) | Freeze duration (milliseconds), 0 means always frozen, need to call reset API to unfreeze |
» qty_limit | string | Trading volume upper limit (positive number, up to 2 decimal places). |
» delta_limit | string | Upper limit of net delta value (positive number, up to 2 decimal places). |
» trigger_time_ms | integer(int64) | Trigger freeze time (milliseconds), 0 means no freeze is triggered. |
» frozen_until_ms | integer(int64) | Unfreeze time (milliseconds). If the freeze duration is not configured, there will be no unfreeze time after the freeze is triggered. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/mmp'
query_param = ''
body='{"underlying":"BTC_USDT","window":5000,"frozen_period":200,"qty_limit":"10","delta_limit":"10"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"underlying": "BTC_USDT",
"window": 5000,
"frozen_period": 200,
"qty_limit": "10",
"delta_limit": "10"
}
Example responses
200 Response
{
"underlying": "BTC_USDT",
"window": 5000,
"frozen_period": 200,
"qty_limit": "10",
"delta_limit": "10",
"trigger_time_ms": 0,
"frozen_until_ms": 0
}
GET /options/mmp
MMP Query.
Name | In | Type | Required | Description |
---|---|---|---|---|
underlying | query | string | false | Underlying. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [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 disabling MMP. |
»» frozen_period | integer(int32) | Freeze duration (milliseconds), 0 means always frozen, need to call reset API to unfreeze |
»» qty_limit | string | Trading volume upper limit (positive number, up to 2 decimal places). |
»» delta_limit | string | Upper limit of net delta value (positive number, up to 2 decimal places). |
»» trigger_time_ms | integer(int64) | Trigger freeze time (milliseconds), 0 means no freeze is triggered. |
»» frozen_until_ms | integer(int64) | Unfreeze time (milliseconds). If the freeze duration is not configured, there will be no unfreeze time after the freeze is triggered. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/mmp'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"underlying": "BTC_USDT",
"window": 5000,
"frozen_period": 200,
"qty_limit": "10",
"delta_limit": "10",
"trigger_time_ms": 0,
"frozen_until_ms": 0
}
]
POST /options/mmp/reset
MMP Reset
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» underlying | body | string | true | Underlying. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | MMP Information. | Inline |
Status Code 200
MMP Settings
Name | Type | Description |
---|---|---|
» underlying | string | Underlying. |
» window | integer(int32) | Time window (milliseconds), between 1-5000, 0 means disabling MMP. |
» frozen_period | integer(int32) | Freeze duration (milliseconds), 0 means always frozen, need to call reset API to unfreeze |
» qty_limit | string | Trading volume upper limit (positive number, up to 2 decimal places). |
» delta_limit | string | Upper limit of net delta value (positive number, up to 2 decimal places). |
» trigger_time_ms | integer(int64) | Trigger freeze time (milliseconds), 0 means no freeze is triggered. |
» frozen_until_ms | integer(int64) | Unfreeze time (milliseconds). If the freeze duration is not configured, there will be no unfreeze time after the freeze is triggered. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/options/mmp/reset'
query_param = ''
body='{"underlying":"BTC_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"underlying": "BTC_USDT"
}
Example responses
200 Response
{
"underlying": "BTC_USDT",
"window": 5000,
"frozen_period": 200,
"qty_limit": "10",
"delta_limit": "10",
"trigger_time_ms": 0,
"frozen_until_ms": 0
}
Lend & Earn.
GET /earn/uni/currencies
List currencies for lending.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Currency detail.] |
» None | object | Currency detail. |
»» currency | string | Currency name. |
»» min_lend_amount | string | The minimum lending amount, in the unit of the currency. |
»» max_lend_amount | string | The total maximum lending amount, in USDT. |
»» max_rate | string | Maximum rate (Hourly). |
»» min_rate | string | Minimum rate (Hourly). |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "AE",
"min_lend_amount": "100",
"max_lend_amount": "200000000",
"max_rate": "0.00057",
"min_rate": "0.000001"
}
]
GET /earn/uni/currencies/{currency}
Get currency detail for lending.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | path | string | true | Currency. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Currency detail.
Name | Type | Description |
---|---|---|
» currency | string | Currency name. |
» min_lend_amount | string | The minimum lending amount, in the unit of the currency. |
» max_lend_amount | string | The total maximum lending amount, in USDT. |
» max_rate | string | Maximum rate (Hourly). |
» min_rate | string | Minimum rate (Hourly). |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/currencies/btc'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"currency": "AE",
"min_lend_amount": "100",
"max_lend_amount": "200000000",
"max_rate": "0.00057",
"min_rate": "0.000001"
}
POST /earn/uni/lends
Lend or redeem.
Lending: When lending, a minimum lending rate must be set. After successful lending is determined on an hourly basis, earnings will be calculated based on the determined rate. Earnings for each hour will be settled at the top of the hour. If lending fails due to an excessively high interest rate, no interest will be earned for that hour. If funds are redeemed before the hourly for that hour. Priority: Under the same interest rate, wealth management products created or modified earlier will be prioritized for lending. Redemption: For funds that failed to be lent, redemption will be credited immediately. For funds successfully lent, they are entitled to the earnings for that hour, and redemption will be credited in the next hourly interval. Note: The two minutes before and after the hourly mark are the settlement period, during which lending and redemption are prohibited.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» currency | body | string | true | Currency name. |
» amount | body | string | true | The amount of currency could be lent. |
» type | body | string | true | type: lend - lend, redeem - redeem. |
» min_rate | body | string | false | The minimum interest rate. If the value is too high, it might lead to the unsuccessful lending and no profit will be gained for that hour. |
Parameter | Value |
---|---|
» type | lend |
» type | redeem |
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content (opens new window) | Operated successfully. | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/lends'
query_param = ''
body='{"currency":"AE","amount":"100","min_rate":"0.00001","type":"lend"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"currency": "AE",
"amount": "100",
"min_rate": "0.00001",
"type": "lend"
}
GET /earn/uni/lends
List user's lending orders.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Retrieve data of the specified currency. |
page | query | integer(int32) | false | Page number. |
limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Loan record. |
»» currency | string | Currency. |
»» current_amount | string | Current amount. |
»» amount | string | Total amount. |
»» lent_amount | string | Lent amount. |
»» frozen_amount | string | Frozen amount. |
»» min_rate | string | Minimum interest rate. |
»» interest_status | string | Interest status: interest_dividend - Normal dividend, interest_reinvest - Interest reinvestment |
»» reinvest_left_amount | string | Amount not reinvested. |
»» create_time | integer(int64) | Created time of the lending order. |
»» update_time | integer(int64) | Upated time of the lending order. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/lends'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "BTC",
"current_amount": "20.999992",
"amount": "20.999992",
"lent_amount": "0",
"frozen_amount": "0",
"min_rate": "0.1",
"interest_status": "interest_dividend",
"reinvest_left_amount": 0,
"create_time": 1673247054000,
"update_time": 1673247054000
}
]
PATCH /earn/uni/lends
Amend lending order.
Currently only supports amending the minimum interest rate (hour).
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» currency | body | string | false | Currency name. |
» min_rate | body | string | false | Minimum interest rate. |
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content (opens new window) | Updated. | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/lends'
query_param = ''
body='{"currency":"AE","min_rate":"0.0001"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PATCH', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"currency": "AE",
"min_rate": "0.0001"
}
GET /earn/uni/lend_records
List records of lending.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Retrieve data of the specified currency. |
page | query | integer(int32) | false | Page number. |
limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
type | query | string | false | type: lend - lend, redeem - redeem. |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Parameter | Value |
---|---|
type | lend |
type | redeem |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Interest Record. |
»» currency | string | Currency name. |
»» amount | string | current amount. |
»» last_wallet_amount | string | Last wallet amount. |
»» last_lent_amount | string | Last lent amount. |
»» last_frozen_amount | string | Last frozen amount. |
»» type | string | Record type: lend - lend, redeem - redeem. |
»» create_time | integer(int64) | Created time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/lend_records'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"type": "lend",
"currency": "BTC",
"amount": "1",
"last_wallet_amount": "0.2",
"last_lent_amount": "0",
"last_frozen_amount": "0",
"create_time": 1673247054000
}
]
GET /earn/uni/interests/{currency}
Get the user's total interest income of specified currency.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | path | string | true | Currency. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
UniLendInterest
Name | Type | Description |
---|---|---|
» currency | string | Currency. |
» interest | string | Interest. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/interests/btc'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"currency": "AE",
"interest": "123.345"
}
GET /earn/uni/interest_records
List interest records.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Retrieve data of the specified currency. |
page | query | integer(int32) | false | Page number. |
limit | query | integer(int32) | false | Maximum response items. Default: 100, minimum: 1, Maximum: 100. |
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Interest Record. |
»» status | integer | Status: 0 - fail, 1 - success. |
»» currency | string | Currency. |
»» actual_rate | string | Actual Rate. |
»» interest | string | Interest. |
»» interest_status | string | Interest status: interest_dividend - Normal dividend, interest_reinvest - Interest reinvestment |
»» create_time | integer(int64) | Created time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/interest_records'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"status": 1,
"currency": "AE",
"actual_rate": "0.0005",
"interest": "0.05",
"interest_status": "interest_dividend",
"create_time": 1673247054000
}
]
GET /earn/uni/interest_status/{currency}
query currency interest compounding status.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | path | string | true | Currency. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
UniCurrencyInterest
Name | Type | Description |
---|---|---|
» currency | string | Currency. |
» interest_status | string | Interest status: interest_dividend - Normal dividend, interest_reinvest - Interest reinvestment |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/interest_status/btc'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"currency": "BTC",
"interest_status": "interest_dividend"
}
GET /earn/uni/chart
UniLoan currency annualized trend chart.
Name | In | Type | Required | Description |
---|---|---|---|---|
from | query | integer(int64) | true | Start timestamp, unit s, maximum span of 30 days. |
to | query | integer(int64) | true | End timestamp, unit s, maximum span of 30 days. |
asset | query | string | true | Currency name. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | none | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» time | integer(int64) | none |
» value | string | none |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/chart'
query_param = 'from=1719763200&to=1722441600&asset=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"time": 1719705600,
"value": "0.01"
}
]
GET /earn/uni/rate
Currency estimate annualized interest rate.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | none | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» currency | string | none |
» est_rate | string | Unconverted percentage. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/uni/rate'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "USDT",
"est_rate": "0.0226"
}
]
Collateral Loan.
POST /loan/collateral/orders
Place order.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» collateral_amount | body | string | true | Collateral amount. |
» collateral_currency | body | string | true | Collateral. |
» borrow_amount | body | string | true | Borrowing amount. |
» borrow_currency | body | string | true | Borrowed currency. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Success. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» order_id | integer(int64) | Order ID. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/orders'
query_param = ''
body='{"collateral_amount":"1","collateral_currency":"BTC","borrow_amount":"49","borrow_currency":"USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"collateral_amount": "1",
"collateral_currency": "BTC",
"borrow_amount": "49",
"borrow_currency": "USDT"
}
Example responses
200 Response
{
"order_id": 10005578
}
GET /loan/collateral/orders
List Orders.
Name | In | Type | Required | Description |
---|---|---|---|---|
page | query | integer(int32) | false | Page number. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
collateral_currency | query | string | false | Collateral. |
borrow_currency | query | string | false | Borrowed currency. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Collateral Order.] |
» None | object | Collateral Order. |
»» order_id | integer(int64) | Order ID. |
»» collateral_currency | string | Collateral. |
»» collateral_amount | string | Collateral amount. |
»» borrow_currency | string | Borrowed currency. |
»» borrow_amount | string | Borrowing amount. |
»» repaid_amount | string | Repaid amount. |
»» repaid_principal | string | Repaid principal. |
»» repaid_interest | string | Repaid interest. |
»» init_ltv | string | The initial collateralization rate. |
»» current_ltv | string | The current collateralization rate. |
»» liquidate_ltv | string | The liquidation collateralization rate. |
»» status | string | Order status: - initial: Initial state after placing the order - collateral_deducted: Collateral deduction successful - collateral_returning: Loan failed - Collateral return pending - lent: Loan successful - repaying: Repayment in progress - liquidating: Liquidation in progress - finished: Order completed - closed_liquidated: Liquidation and repayment completed |
»» borrow_time | integer(int64) | Borrowing time, timestamp in seconds. |
»» left_repay_total | string | Outstanding principal and interest (outstanding principal + outstanding interest) |
»» left_repay_principal | string | outstanding principal. |
»» left_repay_interest | string | outstanding interest. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"order_id": 10000421,
"collateral_currency": "BTC",
"borrow_currency": "USDT",
"collateral_amount": "1",
"borrow_amount": "1000",
"repaid_amount": "10",
"repaid_principal": "10",
"repaid_interest": "0",
"init_ltv": "0.0003934533764831",
"current_ltv": "0.0004521768651985",
"liquidate_ltv": "0.9",
"status": "initial_status",
"borrow_time": 1688462668,
"left_repay_total": "990.0219384",
"left_repay_interest": "0.0219384"
}
]
GET /loan/collateral/orders/{order_id}
Get a single order.
Name | In | Type | Required | Description |
---|---|---|---|---|
order_id | path | integer(int64) | true | Order ID returned on successful order creation. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Success. | Inline |
Status Code 200
Collateral Order.
Name | Type | Description |
---|---|---|
» order_id | integer(int64) | Order ID. |
» collateral_currency | string | Collateral. |
» collateral_amount | string | Collateral amount. |
» borrow_currency | string | Borrowed currency. |
» borrow_amount | string | Borrowing amount. |
» repaid_amount | string | Repaid amount. |
» repaid_principal | string | Repaid principal. |
» repaid_interest | string | Repaid interest. |
» init_ltv | string | The initial collateralization rate. |
» current_ltv | string | The current collateralization rate. |
» liquidate_ltv | string | The liquidation collateralization rate. |
» status | string | Order status: - initial: Initial state after placing the order - collateral_deducted: Collateral deduction successful - collateral_returning: Loan failed - Collateral return pending - lent: Loan successful - repaying: Repayment in progress - liquidating: Liquidation in progress - finished: Order completed - closed_liquidated: Liquidation and repayment completed |
» borrow_time | integer(int64) | Borrowing time, timestamp in seconds. |
» left_repay_total | string | Outstanding principal and interest (outstanding principal + outstanding interest) |
» left_repay_principal | string | outstanding principal. |
» left_repay_interest | string | outstanding interest. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/orders/100001'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"order_id": 10000421,
"collateral_currency": "BTC",
"borrow_currency": "USDT",
"collateral_amount": "1",
"borrow_amount": "1000",
"repaid_amount": "10",
"repaid_principal": "10",
"repaid_interest": "0",
"init_ltv": "0.0003934533764831",
"current_ltv": "0.0004521768651985",
"liquidate_ltv": "0.9",
"status": "initial_status",
"borrow_time": 1688462668,
"left_repay_total": "990.0219384",
"left_repay_interest": "0.0219384"
}
POST /loan/collateral/repay
Repayment.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» order_id | body | integer(int64) | true | Order ID. |
» repay_amount | body | string | true | Repayment amount, it is mandatory when making partial repayments. |
» repaid_all | body | boolean | true | Repayment method, set to true for full repayment, and false for partial repayment; |
» repaid_all: Repayment method, set to true
for full repayment, and false
for partial repayment;
When partial repayment, the repay_amount parameter cannot be greater than the remaining amount to be repaid by the user.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Operated successfully. | Inline |
Status Code 200
Repay.
Name | Type | Description |
---|---|---|
» repaid_principal | string | Principal. |
» repaid_interest | string | Interest. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/repay'
query_param = ''
body='{"order_id":37438962,"repay_amount":"1000","repaid_all":false}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"order_id": 37438962,
"repay_amount": "1000",
"repaid_all": false
}
Example responses
200 Response
{
"repaid_principal": "11",
"repaid_interest": "111"
}
GET /loan/collateral/repay_records
Repayment history.
Name | In | Type | Required | Description |
---|---|---|---|---|
source | query | string | true | Operation type: repay - Regular repayment, liquidate - Liquidation. |
borrow_currency | query | string | false | Borrowed currency. |
collateral_currency | query | string | false | Collateral. |
page | query | integer(int32) | false | Page number. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
from | query | integer(int64) | false | Start timestamp of the query. |
to | query | integer(int64) | false | Time range ending, default to current time. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Repayment record. |
»» order_id | integer(int64) | Order ID. |
»» record_id | integer(int64) | Repayment record ID. |
»» repaid_amount | string | Repayment amount. |
»» borrow_currency | string | Borrowed currency. |
»» collateral_currency | string | Collateral. |
»» init_ltv | string | The initial collateralization rate. |
»» borrow_time | integer(int64) | Borrowing time, timestamp. |
»» repay_time | integer(int64) | Repayment time, timestamp. |
»» total_interest | string | Total interest. |
»» before_left_principal | string | Principal to be repaid before repayment. |
»» after_left_principal | string | Principal to be repaid after repayment. |
»» before_left_collateral | string | Collateral quantity before repayment. |
»» after_left_collateral | string | Collateral quantity after repayment. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/repay_records'
query_param = 'source=repay'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"order_id": 10000425,
"record_id": 181,
"repaid_amount": "10.00000000000000000000",
"borrow_currency": "USDT",
"collateral_currency": "BTC",
"collateral_amount": "1.00000000000000000000",
"init_ltv": "0.00039345337648310000",
"borrow_time": 1688471851,
"repay_time": 1688526310,
"total_interest": "0.25446901544300000000",
"before_left_principal": "11.00000000",
"pre_left_principal": "990.00000000000000000000",
"after_left_principal": "990.00000000000000000000",
"before_left_collateral": "1.00000000000000000000",
"after_left_collateral": "1.00000000000000000000"
}
]
POST /loan/collateral/collaterals
Increase or redeem collateral.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» order_id | body | integer(int64) | true | Order ID. |
» collateral_currency | body | string | true | Collateral. |
» collateral_amount | body | string | true | Collateral amount. |
» type | body | string | true | Operation types: append - for adding collateral, redeem - for withdrawing collateral |
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content (opens new window) | Operated successfully. | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/collaterals'
query_param = ''
body='{"collateral_amount":"1212","collateral_currency":"BTC","order_id":1130,"type":"append"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"collateral_amount": "1212",
"collateral_currency": "BTC",
"order_id": 1130,
"type": "append"
}
GET /loan/collateral/collaterals
Query collateral adjustment records.
Name | In | Type | Required | Description |
---|---|---|---|---|
page | query | integer(int32) | false | Page number. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
from | query | integer(int64) | false | Start timestamp of the query. |
to | query | integer(int64) | false | Time range ending, default to current time. |
borrow_currency | query | string | false | Borrowed currency. |
collateral_currency | query | string | false | Collateral. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Collateral record. |
»» order_id | integer(int64) | Order ID. |
»» record_id | integer(int64) | Collateral record ID. |
»» borrow_currency | string | Borrowed currency. |
»» borrow_amount | string | Borrowing amount. |
»» collateral_currency | string | Collateral. |
»» before_collateral | string | The collateral amount before adjustment. |
»» after_collateral | string | The collateral amount after adjustment. |
»» before_ltv | string | The collateral ratio before adjustment. |
»» after_ltv | string | The collateral ratio after adjustment. |
»» operate_time | integer(int64) | Timestamp of the operation, in seconds. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/collaterals'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"order_id": 10000417,
"record_id": 10000452,
"borrow_currency": "USDT",
"borrow_amount": "1000.00000000000000000000",
"collateral_currency": "BTC",
"pre_collateral": "1.00000000000000000000",
"after_collateral": "2.00000000000000000000",
"pre_ltv": "0.00039345555621480000",
"after_ltv": "0.00019672777810740000",
"operate_time": 1688461924
}
]
GET /loan/collateral/total_amount
Query the total borrowing and collateral amount for the user.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Total borrowed amount and pledged collateral amount by the user.
Name | Type | Description |
---|---|---|
» borrow_amount | string | Total borrowing amount, calculated in USDT. |
» collateral_amount | string | Total collateral amount, calculated in USDT. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/total_amount'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"borrow_amount": "11",
"collateral_amount": "111"
}
GET /loan/collateral/ltv
Query user's collateralization ratio.
Name | In | Type | Required | Description |
---|---|---|---|---|
collateral_currency | query | string | true | Collateral. |
borrow_currency | query | string | true | Borrowed currency. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
User's currency statistics data.
Name | Type | Description |
---|---|---|
» collateral_currency | string | Collateral. |
» borrow_currency | string | Borrowed currency. |
» init_ltv | string | The initial collateralization rate. |
» alert_ltv | string | Warning collateralization ratio. |
» liquidate_ltv | string | The liquidation collateralization rate. |
» min_borrow_amount | string | Minimum borrowable amount for the loan currency. |
» left_borrowable_amount | string | Remaining borrowable amount for the loan currency. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/ltv'
query_param = 'collateral_currency=BTC&borrow_currency=USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"collateral_currency": "BTC",
"borrow_currency": "USDT",
"init_ltv": "0.7",
"alert_ltv": "0.8",
"liquidate_ltv": "0.9",
"min_borrow_amount": "3",
"left_borrowable_amount": "4233030.635065916703"
}
GET /loan/collateral/currencies
Query supported borrowing and collateral currencies.
Name | In | Type | Required | Description |
---|---|---|---|---|
loan_currency | query | string | false | The parameter loan_currency is used to specify the borrowing currency. If loan_currency is not provided, the API will return all supported borrowing currencies. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Supported borrowing and collateral currencies. |
»» loan_currency | string | Borrowed currency. |
»» collateral_currency | array | List of supported collateral currencies. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/collateral/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"loan_currency": "BTC",
"collateral_currency": [
"BTC",
"ETH",
"GT"
]
}
]
Multi-Collateral Loan.
POST /loan/multi_collateral/orders
Create Multi-Collateral Order.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» order_id | body | string | false | Order ID. |
» order_type | body | string | false | current - current, fixed - fixed, if not specified, default to current. |
» fixed_type | body | string | false | Fixed interest rate loan period: 7d - 7 days, 30d - 30 days. Must be provided for fixed |
» fixed_rate | body | string | false | Fixed interest rate, must be specified for fixed. |
» auto_renew | body | boolean | false | Fixed interest rate, automatic renewal. |
» auto_repay | body | boolean | false | Fixed interest rate, automatic repayment. |
» borrow_currency | body | string | true | Borrowed currency. |
» borrow_amount | body | string | true | Borrowing amount. |
» collateral_currencies | body | array | false | Collateral currency and amount. |
»» CollateralCurrency | body | object | false | none |
»»» currency | body | string | false | Currency. |
»»» amount | body | string | false | Size. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Success. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» order_id | integer(int64) | Order ID. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/orders'
query_param = ''
body='{"order_id":1721387470,"order_type":"fixed","fixed_type":"7d","fixed_rate":0.00001,"auto_renew":true,"auto_repay":true,"borrow_currency":"BTC","borrow_amount":"1","collateral_currencies":[{"currency":"USDT","amount":"1000"}]}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"order_id": 1721387470,
"order_type": "fixed",
"fixed_type": "7d",
"fixed_rate": 0.00001,
"auto_renew": true,
"auto_repay": true,
"borrow_currency": "BTC",
"borrow_amount": "1",
"collateral_currencies": [
{
"currency": "USDT",
"amount": "1000"
}
]
}
Example responses
200 Response
{
"order_id": 10005578
}
GET /loan/multi_collateral/orders
List Multi-Collateral Orders.
Name | In | Type | Required | Description |
---|---|---|---|---|
page | query | integer | false | Page number. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
sort | query | string | false | Query the current interest rate of the currency in the previous hour. |
order_type | query | string | false | Order type: current - Query current orders, fixed - Query fixed orders, defaults to current orders if not specified |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | [Multi-Collateral Order.] |
» None | object | Multi-Collateral Order. |
»» order_id | string | Order ID. |
»» order_type | string | current - current, fixed - fixed. |
»» fixed_type | string | Fixed interest rate loan periods: 7d - 7 days, 30d - 30 days. |
»» fixed_rate | string | Fixed interest rate. |
»» expire_time | integer(int64) | Expiration time, timestamp, unit in seconds. |
»» auto_renew | boolean | Fixed interest rate, automatic renewal. |
»» auto_repay | boolean | Fixed interest rate, automatic repayment. |
»» current_ltv | string | The current collateralization rate. |
»» status | string | Order status: - initial: Initial state after placing the order - collateral_deducted: Collateral deduction successful - collateral_returning: Loan failed - Collateral return pending - lent: Loan successful - repaying: Repayment in progress - liquidating: Liquidation in progress - finished: Order completed - closed_liquidated: Liquidation and repayment completed |
»» borrow_time | integer(int64) | Borrowing time, timestamp in seconds. |
»» total_left_repay_usdt | string | Value of Left repay amount converted in USDT. |
»» total_left_collateral_usdt | string | Value of Collateral amount in USDT. |
»» borrow_currencies | array | Borrowing Currency List. |
»»» BorrowCurrencyInfo | object | none |
»»»» currency | string | Currency. |
»»»» index_price | string | Currency Index Price. |
»»»» left_repay_principal | string | outstanding principal. |
»»»» left_repay_interest | string | outstanding interest. |
»»»» left_repay_usdt | string | Value of left total repayments amount in USDT. |
»»» collateral_currencies | array | Collateral Currency List. |
»»»» CollateralCurrencyInfo | object | none |
»»»»» currency | string | Currency. |
»»»»» index_price | string | Currency Index Price. |
»»»»» left_collateral | string | Left Collateral Amount. |
»»»»» left_collateral_usdt | string | Value of left collateral amount in USDT. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"order_id": "10005578",
"order_type": "fixed",
"fixed_type": "7d",
"fixed_rate": 0.00001,
"expire_time": 1703820105,
"auto_renew": true,
"auto_repay": true,
"current_ltv": "0.0001004349664281",
"status": "lent",
"borrow_time": 1702615021,
"total_left_repay_usdt": "106.491212982",
"total_left_collateral_usdt": "1060300.18",
"borrow_currencies": [
{
"currency": "GT",
"index_price": "10.6491",
"left_repay_principal": "10",
"left_repay_interest": "0.00002",
"left_repay_usdt": "106.491212982"
}
],
"collateral_currencies": [
{
"currency": "BTC",
"index_price": "112794.7",
"left_collateral": "9.4",
"left_collateral_usdt": "1060270.18"
},
{
"currency": "USDT",
"index_price": "1",
"left_collateral": "30",
"left_collateral_usdt": "30"
}
]
}
]
GET /loan/multi_collateral/orders/{order_id}
Get Multi-Collateral Order Detail.
Name | In | Type | Required | Description |
---|---|---|---|---|
order_id | path | string | true | Order ID returned on successful order creation. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Success. | Inline |
Status Code 200
Multi-Collateral Order.
Name | Type | Description |
---|---|---|
» order_id | string | Order ID. |
» order_type | string | current - current, fixed - fixed. |
» fixed_type | string | Fixed interest rate loan periods: 7d - 7 days, 30d - 30 days. |
» fixed_rate | string | Fixed interest rate. |
» expire_time | integer(int64) | Expiration time, timestamp, unit in seconds. |
» auto_renew | boolean | Fixed interest rate, automatic renewal. |
» auto_repay | boolean | Fixed interest rate, automatic repayment. |
» current_ltv | string | The current collateralization rate. |
» status | string | Order status: - initial: Initial state after placing the order - collateral_deducted: Collateral deduction successful - collateral_returning: Loan failed - Collateral return pending - lent: Loan successful - repaying: Repayment in progress - liquidating: Liquidation in progress - finished: Order completed - closed_liquidated: Liquidation and repayment completed |
» borrow_time | integer(int64) | Borrowing time, timestamp in seconds. |
» total_left_repay_usdt | string | Value of Left repay amount converted in USDT. |
» total_left_collateral_usdt | string | Value of Collateral amount in USDT. |
» borrow_currencies | array | Borrowing Currency List. |
»» BorrowCurrencyInfo | object | none |
»»» currency | string | Currency. |
»»» index_price | string | Currency Index Price. |
»»» left_repay_principal | string | outstanding principal. |
»»» left_repay_interest | string | outstanding interest. |
»»» left_repay_usdt | string | Value of left total repayments amount in USDT. |
»» collateral_currencies | array | Collateral Currency List. |
»»» CollateralCurrencyInfo | object | none |
»»»» currency | string | Currency. |
»»»» index_price | string | Currency Index Price. |
»»»» left_collateral | string | Left Collateral Amount. |
»»»» left_collateral_usdt | string | Value of left collateral amount in USDT. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"order_id": "10005578",
"order_type": "fixed",
"fixed_type": "7d",
"fixed_rate": 0.00001,
"expire_time": 1703820105,
"auto_renew": true,
"auto_repay": true,
"current_ltv": "0.0001004349664281",
"status": "lent",
"borrow_time": 1702615021,
"total_left_repay_usdt": "106.491212982",
"total_left_collateral_usdt": "1060300.18",
"borrow_currencies": [
{
"currency": "GT",
"index_price": "10.6491",
"left_repay_principal": "10",
"left_repay_interest": "0.00002",
"left_repay_usdt": "106.491212982"
}
],
"collateral_currencies": [
{
"currency": "BTC",
"index_price": "112794.7",
"left_collateral": "9.4",
"left_collateral_usdt": "1060270.18"
},
{
"currency": "USDT",
"index_price": "1",
"left_collateral": "30",
"left_collateral_usdt": "30"
}
]
}
POST /loan/multi_collateral/repay
Repay Multi-Collateral Loan.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» order_id | body | integer(int64) | true | Order ID. |
» repay_items | body | array | true | Repay Currency Item. |
»» MultiLoanRepayItem | body | object | false | none |
»»» currency | body | string | false | Repayment currency. |
»»» amount | body | string | false | Size. |
»»» repaid_all | body | boolean | false | Repayment method, set to true for full repayment, false for partial repayment. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Operated successfully. | Inline |
Status Code 200
Repay Multi-Collateral Loan.
Name | Type | Description |
---|---|---|
» order_id | integer(int64) | Order ID. |
» repaid_currencies | array | Repay Currency List. |
»» RepayCurrencyRes | object | none |
»»» succeeded | boolean | Has the repayment been successful. |
»»» label | string | Error identifier for unsuccessful operations; empty for successful. |
»»» message | string | Error description in case of operation failure; empty when successful. |
»»» currency | string | Repayment currency. |
»»» repaid_principal | string | Principal. |
»»» repaid_interest | string | Principal. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/repay'
query_param = ''
body='{"order_id":10005578,"repay_items":[{"currency":"btc","amount":"1","repaid_all":false}]}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"order_id": 10005578,
"repay_items": [
{
"currency": "btc",
"amount": "1",
"repaid_all": false
}
]
}
Example responses
200 Response
{
"order_id": 10005679,
"repaid_currencies": [
{
"succeeded": false,
"label": "INVALID_PARAM_VALUE",
"message": "Invalid parameter value",
"currency": "BTC",
"repaid_principal": "1",
"repaid_interest": "0.0001"
},
{
"succeeded": true,
"currency": "BTC",
"repaid_principal": "1",
"repaid_interest": "0.0001"
}
]
}
GET /loan/multi_collateral/repay
List Multi-Collateral Repay Records.
Name | In | Type | Required | Description |
---|---|---|---|---|
type | query | string | true | Operation type: repay - Regular repayment, liquidate - Liquidation. |
borrow_currency | query | string | false | Borrowed currency. |
page | query | integer | false | Page number. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
from | query | integer(int64) | false | Start timestamp of the query. |
to | query | integer(int64) | false | Time range ending, default to current time. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Mult Repay Record. |
»» order_id | integer(int64) | Order ID. |
»» record_id | integer(int64) | Repayment record ID. |
»» init_ltv | string | The initial collateralization rate. |
»» before_ltv | string | Ltv before the operation. |
»» after_ltv | string | Ltv after the operation. |
»» borrow_time | integer(int64) | Borrowing time, timestamp in seconds. |
»» repay_time | integer(int64) | Repayment time, timestamp in seconds. |
»» borrow_currencies | array | List of borrowing information. |
»»» currency | string | 币种 |
»»» index_price | string | 币种指数价格 |
»»» before_amount | string | 操作前数量 |
»»» before_amount_usdt | string | 换算成usdt的操作前价值 |
»»» after_amount | string | 操作后数量 |
»»» after_amount_usdt | string | 换算成usdt的操作后价值 |
»» collateral_currencies | array | List of collateral information. |
»»» currency | string | 币种 |
»»» index_price | string | 币种指数价格 |
»»» before_amount | string | 操作前数量 |
»»» before_amount_usdt | string | 换算成usdt的操作前价值 |
»»» after_amount | string | 操作后数量 |
»»» after_amount_usdt | string | 换算成usdt的操作后价值 |
»» repaid_currencies | array | Repay Currency List. |
»»» RepayRecordRepaidCurrency | object | none |
»»»» currency | string | Repayment currency. |
»»»» index_price | string | Currency Index Price. |
»»»» repaid_amount | string | Repayment amount. |
»»»» repaid_principal | string | Principal. |
»»»» repaid_interest | string | Interest. |
»»»» repaid_amount_usdt | string | Value of the repayment amount in USDT. |
»»» total_interest_list | array | Total Interest List. |
»»»» RepayRecordTotalInterest | object | none |
»»»»» currency | string | Currency. |
»»»»» index_price | string | Currency Index Price. |
»»»»» amount | string | Interest Amount. |
»»»»» amount_usdt | string | Interest amount converted to USDT. |
»»»» left_repay_interest_list | array | List of left repay interest. |
»»»»» RepayRecordLeftInterest | object | none |
»»»»»» currency | string | Currency. |
»»»»»» index_price | string | Currency Index Price. |
»»»»»» before_amount | string | Interest amount before repayment. |
»»»»»» before_amount_usdt | string | Converted value of interest before repayment in USDT. |
»»»»»» after_amount | string | Interest amount after repayment. |
»»»»»» after_amount_usdt | string | Converted value of interest after repayment in USDT. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/repay'
query_param = 'type=repay'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"order_id": 10005679,
"record_id": 1348,
"init_ltv": "0.2141",
"before_ltv": "0.215",
"after_ltv": "0.312",
"borrow_time": 1702995889,
"repay_time": 1703053927,
"borrow_currencies": [
{
"currency": "BAT",
"index_price": "103.02",
"before_amount": "1",
"before_amount_usdt": "103.02",
"after_amount": "0.999017",
"after_amount_usdt": "102.91873134"
}
],
"collateral_currencies": [
{
"currency": "ETC",
"index_price": "0.6014228107",
"before_amount": "1000",
"before_amount_usdt": "601.4228107",
"after_amount": "1000",
"after_amount_usdt": "601.4228107"
}
],
"repaid_currencies": [
{
"currency": "BAT",
"index_price": "103.02",
"repaid_amount": "0.001",
"repaid_principal": "0.000983",
"repaid_interest": "0.000017",
"repaid_amount_usdt": "0.10302"
}
],
"total_interest_list": [
{
"currency": "BAT",
"index_price": "103.02",
"amount": "0.000017",
"amount_usdt": "0.00175134"
}
],
"left_repay_interest_list": [
{
"currency": "BAT",
"index_price": "103.02",
"before_amount": "0.000017",
"before_amount_usdt": "0.00175134",
"after_amount": "0",
"after_amount_usdt": "0"
}
]
}
]
POST /loan/multi_collateral/mortgage
Operate Multi-Collateral.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» order_id | body | integer(int64) | true | Order ID. |
» type | body | string | true | Operation types: append - for adding collateral, redeem - for withdrawing collateral |
» collaterals | body | array | false | Collateral Currency List. |
»» currency | body | string | false | Currency. |
»» amount | body | string | false | Size. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Operated successfully. | Inline |
Status Code 200
Result of multi-collateral adjustment.
Name | Type | Description |
---|---|---|
» order_id | integer(int64) | Order ID. |
» collateral_currencies | array | Collateral Currency Information. |
»» CollateralCurrencyRes | object | none |
»»» succeeded | boolean | Update success status. |
»»» label | string | Error identifier for unsuccessful operations; empty for successful. |
»»» message | string | Error description in case of operation failure; empty when successful. |
»»» currency | string | Currency. |
»»» amount | string | Quantity of successful collateral operation; 0 if the operation fails. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/mortgage'
query_param = ''
body='{"order_id":10005578,"type":"append","collaterals":[{"currency":"btc","amount":"0.5"}]}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"order_id": 10005578,
"type": "append",
"collaterals": [
{
"currency": "btc",
"amount": "0.5"
}
]
}
Example responses
200 Response
{
"order_id": 10005679,
"collateral_currencies": [
{
"succeeded": true,
"currency": "btc",
"amount": "0.5"
}
]
}
GET /loan/multi_collateral/mortgage
Query collateral adjustment records.
Name | In | Type | Required | Description |
---|---|---|---|---|
page | query | integer | false | Page number. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
from | query | integer(int64) | false | Start timestamp of the query. |
to | query | integer(int64) | false | Time range ending, default to current time. |
collateral_currency | query | string | false | Collateral. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Multi-Collateral adjustment record. |
»» order_id | integer(int64) | Order ID. |
»» record_id | integer(int64) | Collateral record ID. |
»» before_ltv | string | The collateral ratio before adjustment. |
»» after_ltv | string | The collateral ratio before adjustment. |
»» operate_time | integer(int64) | Operation time, timestamp in seconds. |
»» borrow_currencies | array | Borrowing Currency List. |
»»» currency | string | 币种 |
»»» index_price | string | 币种指数价格 |
»»» before_amount | string | 操作前数量 |
»»» before_amount_usdt | string | 换算成usdt的操作前价值 |
»»» after_amount | string | 操作后数量 |
»»» after_amount_usdt | string | 换算成usdt的操作后价值 |
»» collateral_currencies | array | Collateral Currency List. |
»»» currency | string | 币种 |
»»» index_price | string | 币种指数价格 |
»»» before_amount | string | 操作前数量 |
»»» before_amount_usdt | string | 换算成usdt的操作前价值 |
»»» after_amount | string | 操作后数量 |
»»» after_amount_usdt | string | 换算成usdt的操作后价值 |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/mortgage'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"order_id": 10000417,
"record_id": 10000452,
"before_ltv": "0.00039345555621480000",
"after_ltv": "0.00019672777810740000",
"operate_time": 1688461924,
"borrow_currencies": [
{
"currency": "BTC",
"index_price": "30000",
"before_amount": "0.1",
"before_amount_usdt": "1000",
"after_amount": "0.6",
"after_amount_usdt": "1006"
}
],
"collateral_currencies": [
{
"currency": "BTC",
"index_price": "30000",
"before_amount": "0.1",
"before_amount_usdt": "1000",
"after_amount": "0.6",
"after_amount_usdt": "1006"
}
]
}
]
GET /loan/multi_collateral/currency_quota
List User Currency Quota.
Name | In | Type | Required | Description |
---|---|---|---|---|
type | query | string | true | Currency type: collateral - Collateral currency, borrow - Borrowing. |
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 passedseparated by commas; when it is a borrowing currency, only one currency can be passedseparated by commas; when it is a borrowing currency, only one commas; when it is a borrowing currency, only one currency can be passed |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Currency Quota. |
»» currency | string | Currency. |
»» index_price | string | Currency Index Price. |
»» min_quota | string | Minimum borrowing/collateral quota for the currency. |
»» left_quota | string | Remaining borrowing/collateral limit for the currency. |
»» left_quote_usdt | string | Remaining currency limit converted to USDT. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/currency_quota'
query_param = 'type=collateral¤cy=BTC'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "BTC",
"index_price": "35306.1",
"min_quota": "0",
"left_quota": "2768152.4958445218723677",
"left_quote_usdt": "97732668833.536273678"
}
]
GET /loan/multi_collateral/currencies
Query supported borrowing and collateral currencies in Multi-Collateral.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Borrowing and collateral currencies supported for Multi-Collateral.
Name | Type | Description |
---|---|---|
» loan_currencies | array | List of supported borrowing currencies. |
»» MultiLoanItem | object | none |
»»» currency | string | Currency. |
»»» price | string | Latest price of the currency. |
»» collateral_currencies | array | List of supported collateral currencies. |
»»» MultiCollateralItem | object | none |
»»»» currency | string | Currency. |
»»»» index_price | string | Currency Index Price. |
»»»» discount | string | Discount. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"loan_currencies": [
{
"currency": "BTC",
"price": "1212"
},
{
"currency": "GT",
"price": "12"
}
],
"collateral_currencies": [
{
"currency": "BTC",
"index_price": "1212",
"discount": "0.7"
}
]
}
GET /loan/multi_collateral/ltv
Get Multi-Collateral ratio.
The Multi-Collateral ratio is fixed, irrespective of the currency.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Collateral Ratio.
Name | Type | Description |
---|---|---|
» init_ltv | string | The initial collateralization rate. |
» alert_ltv | string | Warning collateralization ratio. |
» liquidate_ltv | string | The liquidation collateralization rate. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/ltv'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"init_ltv": "0.7",
"alert_ltv": "0.8",
"liquidate_ltv": "0.9"
}
GET /loan/multi_collateral/fixed_rate
Query fixed interest rates for the currency for 7 days and 30 days.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Multi-collateral fixed interest rate. |
»» currency | string | Currency. |
»» rate_7d | string | Fixed interest rate for a lending period of 7 days. |
»» rate_30d | string | Fixed interest rate for a lending period of 30 days. |
»» update_time | integer(int64) | Update time, timestamp, unit in seconds. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/fixed_rate'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "BTC",
"rate_7d": "0.000023",
"rate_30d": "0.1",
"update_time": 1703820105
}
]
GET /loan/multi_collateral/current_rate
Query the current interest rate of the currency.
Query the current interest rate of the currency in the previous hour.
Name | In | Type | Required | Description |
---|---|---|---|---|
currencies | query | array[string] | true | Specify currency name query array, separated by commas, maximum 100items. |
vip_level | query | string | false | VIP level, defaults to 0 if not transferred. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Multi-currency pledge current interest rate. |
»» currency | string | Currency. |
»» current_rate | string | Currency current interest rate. |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/loan/multi_collateral/current_rate'
query_param = 'currencies=BTC,GT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"currency": "BTC",
"current_rate": "0.000023"
}
]
Earn service.
POST /earn/staking/eth2/swap
ETH2 swap.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» side | body | string | true | 1-Forward Swap(ETH -> ETH2), 2-Reverse Swap(ETH2 -> ETH). |
» amount | body | string | true | amount. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | swap success. | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/staking/eth2/swap'
query_param = ''
body='{"side":"1","amount":"1.5"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"side": "1",
"amount": "1.5"
}
GET /earn/staking/eth2/rate_records
ETH2 historical rate of return query.
Check the ETH earnings rate record for the last 31 days.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successful. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» date_time | integer(int64) | Date and Time Stamp. |
» date | string | Date. |
» rate | string | percentage. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/staking/eth2/rate_records'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"date_time": 1690348815,
"date": "2023-07-26",
"rate": "60.00"
},
{
"date_time": 1690435215,
"date": "2023-07-27",
"rate": "20.00"
}
]
GET /earn/dual/investment_plan
Dual Investment product list.
Name | In | Type | Required | Description |
---|---|---|---|---|
plan_id | query | integer(int64) | false | Financial project id. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successful. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» id | integer(int32) | Plan ID. |
» instrument_name | string | Instrument Name. |
» invest_currency | string | Investment Currency. |
» exercise_currency | string | Strike Currency. |
» exercise_price | number(double) | Strike price. |
» delivery_time | integer(int32) | Settlement time. |
» min_copies | integer(int32) | Minimum Copies. |
» max_copies | integer(int32) | Maximum Copies. |
» per_value | string | Per Unit Value. |
» apy_display | string | APY. |
» start_time | integer(int32) | start time. |
» end_time | integer(int32) | Finished time. |
» status | string | Status: NOTSTARTED -not started ONGOING -ongoing ENDED -ended |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/dual/investment_plan'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 272,
"instrument_name": "DOGE-17NOV23-0.067-P",
"type": "put",
"invest_currency": "USDT",
"exercise_currency": "DOGE",
"exercise_price": 0.067,
"delivery_time": 1700208000,
"min_copies": 1,
"max_copies": 1000,
"start_time": 1697685172,
"end_time": 1697685172,
"status": "ONGOING",
"apy_display": "0.0114000000",
"per_value": "1"
}
]
GET /earn/dual/orders
Dual Investment order list.
Name | In | Type | Required | Description |
---|---|---|---|---|
from | query | integer(int64) | false | Start checkout time. |
to | query | integer(int64) | false | End settlement time. |
page | query | integer(int32) | false | Page number. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successful. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» id | integer(int32) | Order ID. |
» plan_id | integer(int32) | Plan ID. |
» copies | string | Copies. |
» invest_amount | string | Investment Amount. |
» settlement_amount | string | Settlement Amount. |
» create_time | integer(int32) | Creation time. |
» complete_time | integer(int32) | Completion Time. |
» status | string | Status:INIT -INITSETTLEMENT_SUCCESS -Settlement SuccessSETTLEMENT_PROCESSING -SEttlement ProcessingCANCELED -CanceledFAILED -Failed |
» invest_currency | string | Investment Currency. |
» exercise_currency | string | Strike Currency. |
» exercise_price | string | Strike price. |
» settlement_price | string | settlement price. |
» settlement_currency | string | Settle currency. |
» apy_display | string | APY. |
» apy_settlement | string | Settlement APY. |
» delivery_time | integer(int32) | Settlement time. |
» text | string | Custom order information. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/dual/orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 373,
"plan_id": 176,
"copies": "1.0000000000",
"invest_amount": "0.0000000000",
"settlement_amount": "0.0000000000",
"create_time": 1697685172,
"complete_time": 1697685172,
"status": "CANCELED",
"invest_currency": "USDT",
"exercise_currency": "BTC",
"settlement_currency": "",
"exercise_price": "24500.0000000000",
"settlement_price": "0.0000000000",
"delivery_time": 1697685172,
"apy_display": "0.6800000000",
"apy_settlement": "0.0000000000",
"text": "t-custom-text"
}
]
POST /earn/dual/orders
Place Dual Investment order.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» plan_id | body | string | true | Plan ID. |
» amount | body | string | true | Subscription amount, mutually exclusive with the copies field. |
» text | body | string | false | User defined information. If not empty, must follow the rules below: |
» text: User defined information. If not empty, must follow the rules below:
t-
t-
prefixStatus | 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 = '/earn/dual/orders'
query_param = ''
body='{"plan_id":"176","amount":"1","text":"t-custom-text"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"plan_id": "176",
"amount": "1",
"text": "t-custom-text"
}
GET /earn/structured/products
Structured Product List.
Name | In | Type | Required | Description |
---|---|---|---|---|
type | query | string | false | Product Type (Default empty to query all) |
status | query | string | true | Status (Default empty to query all) |
page | query | integer(int32) | false | Page number. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
type: Product Type (Default empty to query all)
SharkFin2.0
-Shark Fin
BullishSharkFin
-Bullish Treasure
BearishSharkFin
-Bearish Treasure
DoubleNoTouch
-Volatility Treasure
RangeAccrual
-Range Smart Yield
SnowBall
-Snowball
status: Status (Default empty to query all)
in_process
-In progress
will_begin
-Not started
wait_settlement
-Pending settlement
done
-Completed
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successful. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Structured Products. |
»» id | integer(int32) | Plan ID. |
»» type | string | product type: SharkFin2.0 -Shark Fin2.0 BullishSharkFin -Bullish Shark Fin BearishSharkFin -Bearish Shark FinDoubleNoTouch -Double No-TouchRangeAccrual -Range AccrualSnowBall -Snow Ball |
»» name_en | string | name. |
»» investment_coin | string | Investment Currency. |
»» investment_period | string | Investment term. |
»» min_annual_rate | string | Minimum annual rate. |
»» mid_annual_rate | string | Intermediate annual rate. |
»» max_annual_rate | string | Maximum annual rate. |
»» watch_market | string | Watch market. |
»» start_time | integer(int32) | start time. |
»» end_time | integer(int32) | Finished time. |
»» status | string | Status: in_process -in progress will_begin -will begin wait_settlement -waiting for settlement done -done |
Code samples
# coding: utf-8
import requests
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/structured/products'
query_param = 'status=in_process'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 3700,
"type": "BullishSharkFin",
"name_en": "Bullish Sharkfin_USDT",
"investment_period": 7,
"min_annual_rate": "0.50",
"mid_annual_rate": "7.50",
"max_annual_rate": "13.00",
"watch_market": "BTC_USDT",
"investment_coin": "USDT",
"start_time": 1698224400,
"end_time": 1700902800,
"status": "in_process"
}
]
GET /earn/structured/orders
Structured Product Order List.
Name | In | Type | Required | Description |
---|---|---|---|---|
from | query | integer(int64) | false | Start timestamp |
to | query | integer(int64) | false | Termination Timestamp |
page | query | integer(int32) | false | Page number. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successful. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Structured order. |
»» id | integer(int32) | Order ID. |
»» pid | string | Plan ID. |
»» lock_coin | string | Locked coin. |
»» amount | string | Locked amount. |
»» status | string | Status: SUCCESS - SUCCESS FAILED - FAILED DONE - DONE |
»» income | string | Income. |
»» create_time | integer(int32) | Created time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/structured/orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 35,
"pid": "3691",
"lock_coin": "ETH",
"amount": "20",
"status": "SUCCESS",
"income": "0.000000",
"create_time": 1697685172
}
]
POST /earn/structured/orders
Place Structured Product Order.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» pid | body | string | false | Plan ID. |
» amount | body | string | false | Purchase Amount. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Success. | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/structured/orders'
query_param = ''
body='{"pid":"1","amount":"0.5"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"pid": "1",
"amount": "0.5"
}
GET /earn/staking/coins
Staking Coins.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» coin | body | string | false | Currency. |
» cointype | body | string | false | Coin Type swap-Voucher lock-Locked. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successful. | [string] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/staking/coins'
query_param = ''
body='{"coin":"string","cointype":"string"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"coin": "string",
"cointype": "string"
}
Example responses
200 Response
[
"GT",
"SOL",
"USDT",
"ALEO",
"DOT",
"TRX",
"ADA"
]
POST /earn/staking/swap
On-chain Token Swap for Earned Coins.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» coin | body | string | true | Currency. |
» side | body | string | true | 0 - Stake 1 - Redeem. |
» amount | body | string | true | Size. |
» pid | body | integer(int32) | false | DeFi-type Mining Protocol Identifier. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | swap success. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» id | integer | Order ID. |
» pid | integer | Plan ID. |
» uid | integer | User ID. |
» coin | string | Currency. |
» type | integer | Type 0-质押 1-赎回 |
» subtype | string | 子Type |
» amount | string | Amount. |
» exchange_rate | string | Exchange Ratio. |
» exchange_amount | string | 兑换金额 |
» updateStamp | integer | 更新Timestamp |
» createStamp | integer | Transaction timestamp. |
» status | integer | status 1-success. |
» protocol_type | integer | DEFI协议Type |
» client_order_id | string | 参考ID |
» source | string | Order source. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/earn/staking/swap'
query_param = ''
body='{"coin":"GT","side":"0","amount":"1.5"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"coin": "GT",
"side": "0",
"amount": "1.5"
}
Example responses
200 Response
{
"id": 21000,
"uid": 12345,
"coin": "GT",
"type": 0,
"exchange_rate": "1.00000000",
"amount": "2",
"pid": 1,
"status": 1,
"createStamp": 1752200661
}
Get account detail.
GET /account/detail
Get account detail.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successful. | Inline |
Status Code 200
AccountDetail
Name | Type | Description |
---|---|---|
» ip_whitelist | array | IP whitelist. |
» currency_pairs | array | CurrencyPair whitelisting. |
» user_id | integer(int64) | User ID. |
» tier | integer(int64) | User VIP level. |
» key | object | API Key detail. |
»» mode | integer(int32) | mode: 1 - classic account 2 - portfolio margin account. |
» copy_trading_role | integer(int32) | User role: 0 - Normal user, 1 - Copy trading leader, follower, 3 - Both leader and follower |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/detail'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"user_id": 1667201533,
"ip_whitelist": [
"127.0.0.1"
],
"currency_pairs": [
"USDT_BTC"
],
"key": {
"mode": 1
},
"tier": 2,
"copy_trading_role": 1
}
GET /account/rate_limit
Get user transaction rate limit information.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successful. | [Inline] |
Status Code 200
AccountRateLimit
Name | Type | Description |
---|---|---|
AccountRateLimit | array | Account flow limit. |
» tier | string | Frequency limit level (For detailed frequency limit rules, see Transaction ratio frequency limit) |
» ratio | string | Transaction rate. |
» main_ratio | string | Total transaction ratio of main account. |
» updated_at | string | Update time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/rate_limit'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"type": "spot",
"tier": "1",
"ratio": "0",
"main_ratio": "0",
"updated_at": "1728230400"
},
{
"type": "futures",
"tier": "1",
"ratio": "0",
"main_ratio": "0",
"updated_at": "1728230400"
}
]
POST /account/stp_groups
Create STP Group.
Only the main account is allowed to create a new STP user group.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | true | none |
» id | body | integer(int64) | false | STP Group ID. |
» name | body | string | true | STP Group name. |
» creator_id | body | integer(int64) | false | Creator ID. |
» create_time | body | integer(int64) | false | Creation time. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | User added successfully. Returning the current users within the STP group. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» id | integer(int64) | STP Group ID. |
» name | string | STP Group name. |
» creator_id | integer(int64) | Creator ID. |
» create_time | integer(int64) | Creation time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/stp_groups'
query_param = ''
body='{"name":"stp_name"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"name": "stp_name"
}
Example responses
200 Response
{
"id": 123435,
"name": "group",
"create_time": 1548000000,
"creator_id": 10000
}
GET /account/stp_groups
List STP Groups.
Retrieve the list of STP groups created by the main account user only.
Name | In | Type | Required | Description |
---|---|---|---|---|
name | query | string | false | Perform a fuzzy search based on the name. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» id | integer(int64) | STP Group ID. |
» name | string | STP Group name. |
» creator_id | integer(int64) | Creator ID. |
» create_time | integer(int64) | Creation time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/stp_groups'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"id": 123435,
"name": "group",
"create_time": 1548000000,
"creator_id": 10000
}
]
GET /account/stp_groups/{stp_id}/users
List users of the STP group.
Only the main account that created this STP group can query the account.
Name | In | Type | Required | Description |
---|---|---|---|---|
stp_id | path | integer(int64) | true | STP Group ID. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» user_id | integer(int64) | User ID. |
» stp_id | integer(int64) | STP Group ID. |
» create_time | integer(int64) | Creation time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/stp_groups/1/users'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"user_id": 10000,
"stp_id": 1,
"create_time": 1548000000
}
]
POST /account/stp_groups/{stp_id}/users
Add users to the STP group.
Name | In | Type | Required | Description |
---|---|---|---|---|
stp_id | path | integer(int64) | true | STP Group ID. |
body | body | array[integer] | true | User ID. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | User added successfully. Returning the current users within the STP group. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» user_id | integer(int64) | User ID. |
» stp_id | integer(int64) | STP Group ID. |
» create_time | integer(int64) | Creation time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/stp_groups/1/users'
query_param = ''
body='[1,2,3]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
[
1,
2,
3
]
Example responses
200 Response
[
{
"user_id": 10000,
"stp_id": 1,
"create_time": 1548000000
}
]
DELETE /account/stp_groups/{stp_id}/users
Delete the user in the STP group.
Name | In | Type | Required | Description |
---|---|---|---|---|
stp_id | path | integer(int64) | true | STP Group ID. |
user_id | query | integer(int64) | true | STP user ID, multiple can be separated by commas. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Success. | [Inline] |
Status Code 200
Name | Type | Description |
---|---|---|
None | array | none |
» user_id | integer(int64) | User ID. |
» stp_id | integer(int64) | STP Group ID. |
» create_time | integer(int64) | Creation time. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/stp_groups/1/users'
query_param = 'user_id=1'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
[
{
"user_id": 10000,
"stp_id": 1,
"create_time": 1548000000
}
]
POST /account/debit_fee
Set GT deduction.
Enable or disable GT deduction for the current account.
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | DebitFee | true | none |
» enabled | body | boolean | true | Whether GT fee discount is used. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Success. | None |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/debit_fee'
query_param = ''
body='{"enabled":true}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
Body parameter
{
"enabled": true
}
GET /account/debit_fee
Query GT deduction configuration.
Query the current GT deduction configuration for the account.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Success. | DebitFee |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/debit_fee'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"enabled": true
}
broker rebate endpints.
GET /rebate/agency/transaction_history
The agency obtains the transaction history of the recommended user.
Record time range cannot exceed 30 days.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency_pair | query | string | false | Specify the currency pair, if not specified, return all currency pairs. |
user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned. |
from | query | integer(int64) | false | Time range beginning, default to 7 days before current time. |
to | query | integer(int64) | false | Time range ending, default to current time. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» currency_pair | string | Currency pair. |
» total | integer(int64) | Total. |
» list | array | List of transaction history. |
»» AgencyTransaction | object | none |
»»» transaction_time | integer(int64) | Transaction Time. (unix timestamp). |
»»» user_id | integer(int64) | User ID. |
»»» group_name | string | Group name. |
»»» fee | string | Fee. |
»»» fee_asset | string | Fee currency. |
»»» currency_pair | string | Currency pair. |
»»» amount | string | Commission Amount. |
»»» amount_asset | string | Commission Asset. |
»»» source | string | Source. SPOT - SPOT Rebate, FUTURES - Futures Rebate. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/agency/transaction_history'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"total": 100,
"list": [
{
"transaction_time": 1539852480,
"user_id": 10000,
"group_name": "gateio",
"fee": "1",
"fee_asset": "GT",
"currency_pair": "GT_USDT",
"amount": "1000",
"source": "SPOT",
"amount_asset": "GT"
}
]
}
GET /rebate/agency/commission_history
The agency obtains the commission history of the recommended user.
Record time range cannot exceed 30 days.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Filter by currency. Return all currency records if not specified. |
user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned. |
from | query | integer(int64) | false | Time range beginning, default to 7 days before current time. |
to | query | integer(int64) | false | Time range ending, default to current time. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» currency_pair | string | Currency pair. |
» total | integer(int64) | Total. |
» list | array | List of comission history. |
»» AgencyCommission | object | none |
»»» commission_time | integer(int64) | Commission Time. (unix timestamp). |
»»» user_id | integer(int64) | User ID. |
»»» group_name | string | Group name. |
»»» commission_amount | string | Commission Amount. |
»»» commission_asset | string | Commission Asset. |
»»» source | string | Source. SPOT - SPOT Rebate, FUTURES - Futures Rebate. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/agency/commission_history'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"total": 100,
"list": [
{
"commission_time": 1539852480,
"user_id": 10000,
"group_name": "gateio",
"commission_amount": "1000",
"source": "SPOT",
"commission_asset": "GT"
}
]
}
GET /rebate/partner/transaction_history
Partner obtains transaction records of recommended users.
Record time range cannot exceed 30 days.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency_pair | query | string | false | Specify the currency pair, if not specified, return all currency pairs. |
user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned. |
from | query | integer(int64) | false | Time range beginning, default to 7 days before current time. |
to | query | integer(int64) | false | Time range ending, default to current time. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» total | integer(int64) | Total. |
» list | array | List of transaction history. |
»» PartnerTransaction | object | none |
»»» transaction_time | integer(int64) | Transaction Time. (unix timestamp). |
»»» user_id | integer(int64) | User ID. |
»»» group_name | string | Group name. |
»»» fee | string | Fee. |
»»» fee_asset | string | Fee currency. |
»»» currency_pair | string | Currency pair. |
»»» amount | string | Commission Amount. |
»»» amount_asset | string | Commission Asset. |
»»» source | string | Source. SPOT - SPOT Rebate, FUTURES - Futures Rebate. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/partner/transaction_history'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"total": 15,
"list": [
{
"user_id": 1879032535,
"group_name": "test",
"fee": "0.00044800",
"transaction_time": 1718615824,
"amount": "29.98688000USDT",
"amount_asset": "USDT",
"currency_pair": "BCH_USDT",
"source": "SPOT",
"fee_asset": "BCH"
}
]
}
GET /rebate/partner/commission_history
Partner obtains commission records of recommended users.
Record time range cannot exceed 30 days.
Name | In | Type | Required | Description |
---|---|---|---|---|
currency | query | string | false | Filter by currency. Return all currency records if not specified. |
user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned. |
from | query | integer(int64) | false | Time range beginning, default to 7 days before current time. |
to | query | integer(int64) | false | Time range ending, default to current time. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» total | integer(int64) | Total. |
» list | array | List of comission history. |
»» PartnerCommission | object | none |
»»» commission_time | integer(int64) | Commission Time. (unix timestamp). |
»»» user_id | integer(int64) | User ID. |
»»» group_name | string | Group name. |
»»» commission_amount | string | Commission Amount. |
»»» commission_asset | string | Commission Asset. |
»»» source | string | Source. SPOT - SPOT Rebate, FUTURES - Futures Rebate. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/partner/commission_history'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"total": 52,
"list": [
{
"user_id": 1879043947,
"commission_time": 1718616728,
"commission_amount": "0.2216934846",
"commission_asset": "USDT",
"source": "SPOT",
"group_name": "test"
}
]
}
GET /rebate/partner/sub_list
Partner subordinate list.
Including sub-agents, direct customers, indirect customers.
Name | In | Type | Required | Description |
---|---|---|---|---|
user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned. |
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» total | integer(int64) | Total. |
» list | array | Subordinate list. |
»» PartnerSub | object | none |
»»» user_id | integer(int64) | User ID. |
»»» user_join_time | integer(int64) | The time when the user joined the system, in seconds Unix timestamp. |
»»» type | integer(int64) | Type (1-Sub-agent 2-Indirect Customer 3-Direct Customer). |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/partner/sub_list'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"total": 3,
"list": [
{
"user_id": 1,
"user_join_time": 1666255731,
"type": 1
},
{
"user_id": 2,
"user_join_time": 1666271213,
"type": 2
},
{
"user_id": 3,
"user_join_time": 1666422143,
"type": 3
}
]
}
GET /rebate/broker/commission_history
The broker obtains the user's commission rebate records.
Record time range cannot exceed 30 days.
Name | In | Type | Required | Description |
---|---|---|---|---|
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned. |
from | query | integer(int64) | false | The start time of the query record. If not specified, the default is to push forward 30 days from the current time. |
to | query | integer(int64) | false | Time range ending, default to current time. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» total | integer(int64) | Total. |
» list | array | List of comission history. |
»» BrokerCommission | object | none |
»»» commission_time | integer(int64) | Commission Time. (unix timestamp). |
»»» user_id | integer(int64) | User ID. |
»»» group_name | string | Group name. |
»»» amount | string | The amount of commission rebates. |
»»» fee | string | Fee. |
»»» fee_asset | string | Fee currency. |
»»» rebate_fee | string | The income from rebates, converted to USDT. |
»»» source | string | Rebate Type: Spot、Futures、Options.、Alpha |
»»» currency_pair | string | Currency pair. |
»»» sub_broker_info | object | The sub broker info. |
»»»» user_id | integer(int64) | The sub broker user ID. |
»»»» original_commission_rate | string | The sub broker original commission rate. |
»»»» relative_commission_rate | string | The sub broker relative commission rate. |
»»»» commission_rate | string | The sub broker actual commission rate. |
»»» alpha_contract_addr | string | Alpha token address |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/broker/commission_history'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"list": [
{
"user_id": 110285113,
"group_name": "",
"commission_time": 1702545051,
"fee": "0.0020000000",
"source": "SPOT",
"amount": "0.00040000",
"rebate_fee": "0.0004000000",
"fee_asset": "BEAM",
"currency_pair": "BEAM_USDT",
"sub_broker_info": {
"user_id": 110285114,
"original_commission_rate": "0.2",
"relative_commission_rate": "0.5",
"commission_rate": "0.1"
},
"alpha_contract_addr": "0x9a26f5433671751c3276a065f57e5a02d2817973"
}
],
"total": 47
}
GET /rebate/broker/transaction_history
The broker obtains the user's trading history.
Record time range cannot exceed 30 days.
Name | In | Type | Required | Description |
---|---|---|---|---|
limit | query | integer | false | Maximum number of records to be returned in a single list. |
offset | query | integer | false | List offset, starting from 0. |
user_id | query | integer(int64) | false | User ID. If not specified, all user records will be returned. |
from | query | integer(int64) | false | The start time of the query record. If not specified, the default is to push forward 30 days from the current time. |
to | query | integer(int64) | false | Time range ending, default to current time. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» total | integer(int64) | Total. |
» list | array | List of transaction history. |
»» BrokerTransaction | object | none |
»»» transaction_time | integer(int64) | Transaction Time. (unix timestamp). |
»»» user_id | integer(int64) | User ID. |
»»» group_name | string | Group name. |
»»» fee | string | fee (usdt). |
»»» currency_pair | string | Currency pair. |
»»» amount | string | Commission Amount. |
»»» fee_asset | string | Fee currency. |
»»» source | string | Rebate Type: Spot、Futures、Options.、Alpha |
»»» sub_broker_info | object | The sub broker info. |
»»»» user_id | integer(int64) | The sub broker user ID. |
»»»» original_commission_rate | string | The sub broker original commission rate. |
»»»» relative_commission_rate | string | The sub broker relative commission rate. |
»»»» commission_rate | string | The sub broker actual commission rate. |
»»» alpha_contract_addr | string | Alpha token address |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/broker/transaction_history'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"list": [
{
"user_id": 110285442,
"group_name": "",
"fee": "0.5000045000",
"transaction_time": 1702545051,
"amount": "-1000.00900000",
"currency_pair": "DOGE_USDT",
"source": "Futures",
"fee_asset": "USDT",
"sub_broker_info": {
"user_id": 110285114,
"original_commission_rate": "0.2",
"relative_commission_rate": "0.5",
"commission_rate": "0.1"
},
"alpha_contract_addr": "0x9a26f5433671751c3276a065f57e5a02d2817973"
}
],
"total": 47
}
GET /rebate/user/info
User retrieves rebate information.
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | Successfully retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» None | object | Retrieve user rebate information. |
»» invite_uid | integer(int64) | My inviter's UID. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/user/info'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
Example responses
200 Response
{
"invite_uid": 987
}
GET /rebate/user/sub_relation
User-subordinate relationship.
Query whether the specified user is in the system.
Name | In | Type | Required | Description |
---|---|---|---|---|
user_id_list | query | string | true | Query the user's ID list, split by,, if there are more than 100, take 100. |
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK (opens new window) | List retrieved. | Inline |
Status Code 200
Name | Type | Description |
---|---|---|
» list | array | Subordinate relationship list. |
»» UserSub | object | none |
»»» uid | integer(int64) | User ID. |
»»» belong | string | The system to which the user belongs (partner referral). If empty, it means not belonging to any system. |
»»» type | integer(int64) | Type (0-not in the system 1-direct subordinate agent 2-indirect subordinate agent 3-direct customer 4-indirect direct customer 5-ordinary user) |
»»» ref_uid | integer(int64) | Inviter user ID. |
WARNING
To perform this operation, you must be authenticated by API key and secret
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/rebate/user/sub_relation'
query_param = 'user_id_list=1, 2, 3'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
Example responses
200 Response
{
"list": [
{
"belong": "",
"ref_uid": 0,
"type": 0,
"uid": 9
},
{
"belong": "partner",
"type": 1,
"ref_uid": 1,
"uid": 2
},
{
"belong": "referral",
"type": 5,
"ref_uid": 1,
"uid": 3
}
]
}
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
user_id | integer(int64) | false | read-only | User ID. |
mode | integer(int32) | false | none | Mode: 1 - classic 2 - portfolio account. |
name | string | false | none | API key name. |
perms | array | false | none | none |
» name | string | false | none | Permission function name (no value will be cleared) - wallet: wallet - spot: spot/leverage - futures: perpetual contract - delivery: delivery contract - earn: financial management - custody: custody - options: options - account: account information - loan: loan - margin: leverage - unified: unified account - copy: copy |
» read_only | boolean | false | none | read only. |
ip_whitelist | array | false | none | ip white list (list will be removed if no value is passed). |
key | string | false | read-only | API Key |
state | integer(int32) | false | read-only | State 1 - normal 2 - locked 3 - frozen. |
created_at | integer(int64) | false | read-only | Creation time. |
updated_at | integer(int64) | false | read-only | Last update time. |
last_access | integer(int64) | false | read-only | Last access time. |
{
"user_id": 0,
"mode": 0,
"name": "string",
"perms": [
{
"name": "string",
"read_only": true
}
],
"ip_whitelist": [
"string"
],
"key": "string",
"state": 0,
"created_at": 0,
"updated_at": 0,
"last_access": 0
}
Spot order detail.
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
trigger | object | true | none | none |
» price | string | true | none | Trigger price. |
» rule | string | true | none | Price trigger condition - >= : triggered when market price larger than or equal to price field- <= : or equal to price field |
» expiration | integer | true | none | How long (in seconds) to wait for the condition to be triggered before cancelling the order. |
put | object | true | none | none |
» type | string | false | none | Order type, default to limit - limit : Limit Order - market : Market Order |
» side | string | true | none | Order side - buy: buy side - sell: sell side |
» price | string | true | none | Order price. |
» amount | string | true | none | When type is limit, it refers to base currency. For instance, BTC_USDT means BTC When different currency according to side - side : buy means quote currency, BTC_USDT means USDT - side : sell means base currency, BTC_USDT means BTC |
» account | string | true | none | Trading account type. Portfolio margin account must set to unified -normal: spot trading - margin: margin trading - unified: unified trading |
» 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 - app: app |
id | integer(int64) | false | read-only | Auto order ID. |
user | integer | false | read-only | User ID. |
market | string | true | none | Currency pair. |
ctime | integer(int64) | false | read-only | Creation time. |
ftime | integer(int64) | false | read-only | Finished time. |
fired_order_id | integer(int64) | false | read-only | ID of the newly created order on condition triggered. |
status | string | false | read-only | Status - open: open - cancelled: being manually cancelled - finish: successfully executed - failed: failed to execute - expired - expired |
reason | string | false | read-only | Additional remarks on how the order was finished. |
Property | Value |
---|---|
rule | >= |
rule | <= |
type | limit |
type | market |
side | buy |
side | sell |
account | normal |
account | margin |
account | unified |
time_in_force | gtc |
time_in_force | ioc |
{
"trigger": {
"price": "string",
"rule": ">=",
"expiration": 0
},
"put": {
"type": "limit",
"side": "buy",
"price": "string",
"amount": "string",
"account": "normal",
"time_in_force": "gtc",
"auto_borrow": false,
"auto_repay": false,
"text": "string"
},
"id": 0,
"user": 0,
"market": "string",
"ctime": 0,
"ftime": 0,
"fired_order_id": 0,
"status": "string",
"reason": "string"
}
Futures contract details.
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
name | string | false | none | Futures contract. |
type | string | false | none | Futures contract type. |
quanto_multiplier | string | false | none | Multiplier used in converting from invoicing to settlement currency. |
leverage_min | string | false | none | Minimum leverage. |
leverage_max | string | false | none | Maximum leverage. |
maintenance_rate | string | false | none | Maintenance rate of margin. |
mark_type | string | false | none | Mark price type, internal - based on internal trading, external index price |
mark_price | string | false | none | Current mark price. |
index_price | string | false | none | Current index price. |
last_price | string | false | none | Last trading price. |
maker_fee_rate | string | false | none | Maker fee rate, where negative means rebate. |
taker_fee_rate | string | false | none | Taker fee rate. |
order_price_round | string | false | none | Minimum order price increment. |
mark_price_round | string | false | none | Minimum mark price increment. |
funding_rate | string | false | none | Current funding rate. |
funding_interval | integer | false | none | Funding application interval, unit in seconds. |
funding_next_apply | number(double) | false | none | Next funding time. |
risk_limit_base | string | false | none | Risk limit base,deprecated. |
risk_limit_step | string | false | none | Step of adjusting risk limit,deprecated. |
risk_limit_max | string | false | none | Maximum risk limit the contract allowed,deprecated,It is recommended to use /futures/{settle}/risk_limit_tiers to query risk limits. |
order_size_min | integer(int64) | false | none | Minimum order size the contract allowed. |
order_size_max | integer(int64) | false | none | Maximum order size the contract allowed. |
order_price_deviate | string | false | none | deviation between order price and current index price. If price of an order is denoted as order_price, it must meet the following condition: abs(order_price - mark_price) <= mark_price * order_price_deviate |
ref_discount_rate | string | false | none | Referral fee rate discount. |
ref_rebate_rate | string | false | none | Referrer commission rate. |
orderbook_id | integer(int64) | false | none | Current orderbook ID. |
trade_id | integer(int64) | false | none | Current trade ID. |
trade_size | integer(int64) | false | none | Historical accumulated trade size. |
position_size | integer(int64) | false | none | Current total long position size. |
config_change_time | number(double) | false | none | Last changed time of configuration. |
in_delisting | boolean | false | none | in_delisting=true And when position_size>0, it means the contract is in the offline transition periodin_delisting=true contract is offline |
orders_limit | integer | false | none | Maximum number of open orders. |
enable_bonus | boolean | false | none | Whether bouns is enabled. |
enable_credit | boolean | false | none | Whether portfolio margin account is enabled. |
create_time | number(double) | false | none | Created time of the contract. |
funding_cap_ratio | string | false | none | The factor for the maximum of the funding rate. Maximum of funding rate = (1/market maximum leverage - maintenance margin rate) * funding_cap_ratio |
status | string | false | none | Contract Status Types include: prelaunch, trading, delisting, delisted. |
launch_time | integer(int64) | false | none | Contract expiry timestamp. |
Property | Value |
---|---|
type | inverse |
type | direct |
mark_type | internal |
mark_type | index |
{
"name": "string",
"type": "inverse",
"quanto_multiplier": "string",
"leverage_min": "string",
"leverage_max": "string",
"maintenance_rate": "string",
"mark_type": "internal",
"mark_price": "string",
"index_price": "string",
"last_price": "string",
"maker_fee_rate": "string",
"taker_fee_rate": "string",
"order_price_round": "string",
"mark_price_round": "string",
"funding_rate": "string",
"funding_interval": 0,
"funding_next_apply": 0.1,
"risk_limit_base": "string",
"risk_limit_step": "string",
"risk_limit_max": "string",
"order_size_min": 0,
"order_size_max": 0,
"order_price_deviate": "string",
"ref_discount_rate": "string",
"ref_rebate_rate": "string",
"orderbook_id": 0,
"trade_id": 0,
"trade_size": 0,
"position_size": 0,
"config_change_time": 0.1,
"in_delisting": true,
"orders_limit": 0,
"enable_bonus": true,
"enable_credit": true,
"create_time": 0.1,
"funding_cap_ratio": "string",
"status": "string",
"launch_time": 0
}
Futures position details.
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
user | integer(int64) | false | read-only | User ID. |
contract | string | false | read-only | Futures contract. |
size | integer(int64) | false | read-only | Position size. |
leverage | string | false | none | Position leverage. 0 means cross margin; positive number means isolated margin |
risk_limit | string | false | none | Position risk limit. |
leverage_max | string | false | read-only | Maximum leverage under current risk limit. |
maintenance_rate | string | false | read-only | Maintenance rate under current risk limit. |
value | string | false | read-only | Position value calculated in settlement currency. |
margin | string | false | none | Position margin. |
entry_price | string | false | read-only | Entry price. |
liq_price | string | false | read-only | Liquidation price. |
mark_price | string | false | read-only | Current mark price. |
initial_margin | string | false | read-only | The initial margin occupied by the position, applicable to the portfolio margin account |
maintenance_margin | string | false | read-only | Maintenance margin required for the position, applicable to portfolio margin account |
unrealised_pnl | string | false | read-only | Unrealized PNL. |
realised_pnl | string | false | read-only | Realized PNL. |
pnl_pnl | string | false | read-only | Realized PNL - Position P/L. |
pnl_fund | string | false | read-only | Realized PNL - Funding Fees. |
pnl_fee | string | false | read-only | Realized PNL - Transaction Fees. |
history_pnl | string | false | read-only | History realized PNL. |
last_close_pnl | string | false | read-only | PNL of last position close. |
realised_point | string | false | read-only | Realized POINT PNL. |
history_point | string | false | read-only | History realized POINT PNL. |
adl_ranking | integer | false | read-only | Ranking of auto deleveraging, a total of 1-5 grades, 1 is the highest, 5 is the lowest, and 6 is the special case when there is no position held or in liquidation |
pending_orders | integer | false | read-only | Current open orders. |
close_order | object|null | false | read-only | Current close order if any, or null . |
» id | integer(int64) | false | none | Close order ID. |
» price | string | false | none | Close order price. |
» is_liq | boolean | false | none | Is the close order from liquidation. |
mode | string | false | none | Position mode, including: - single : dual mode is not enabled- dual_long : long position in dual mode- dual_short : 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. Each time the position is updated, the value will be +1. |
trade_long_size | integer(int64) | false | read-only | Cumulative long size. |
trade_long_xprice | string | false | read-only | Cumulative long size*price. |
trade_short_size | integer(int64) | false | read-only | Cumulative short size. |
trade_short_xprice | string | false | read-only | Accumulated short size*price. |
trade_max_size | string | false | none | Maximum position. |
open_time | integer(int64) | false | none | First Open Time. |
risk_limit_table | string | false | read-only | Risk limit table ID. |
average_maintenance_rate | string | false | read-only | Average maintenance margin rate. |
voucher_size | string | false | read-only | Experience Coupon Position Size. |
voucher_margin | string | false | read-only | Experience Coupon Position Margin. |
voucher_id | integer(int64) | false | read-only | Experience Coupon ID. |
Property | Value |
---|---|
mode | single |
mode | dual_long |
mode | dual_short |
{
"user": 0,
"contract": "string",
"size": 0,
"leverage": "string",
"risk_limit": "string",
"leverage_max": "string",
"maintenance_rate": "string",
"value": "string",
"margin": "string",
"entry_price": "string",
"liq_price": "string",
"mark_price": "string",
"initial_margin": "string",
"maintenance_margin": "string",
"unrealised_pnl": "string",
"realised_pnl": "string",
"pnl_pnl": "string",
"pnl_fund": "string",
"pnl_fee": "string",
"history_pnl": "string",
"last_close_pnl": "string",
"realised_point": "string",
"history_point": "string",
"adl_ranking": 0,
"pending_orders": 0,
"close_order": {
"id": 0,
"price": "string",
"is_liq": true
},
"mode": "single",
"cross_leverage_limit": "string",
"update_time": 0,
"update_id": 0,
"trade_long_size": 0,
"trade_long_xprice": "string",
"trade_short_size": 0,
"trade_short_xprice": "string",
"trade_max_size": "string",
"open_time": 0,
"risk_limit_table": "string",
"average_maintenance_rate": "string",
"voucher_size": "string",
"voucher_margin": "string",
"voucher_id": 0
}
Futures order details.
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
id | integer(int64) | false | read-only | Futures order ID. |
user | integer | false | read-only | User ID. |
create_time | number(double) | false | read-only | Creation time of order. |
finish_time | number(double) | false | read-only | Order finished time. Not returned if order is open. |
finish_as | string | false | read-only | How the order was finished. - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC , finish immediately- auto_deleveraged: finished by ADL - increasing position while reduce-only set- position_closed: cancelled because of position close- position_closed: canceled because the position was closed - reduce_out: only reduce positions by excluding hard-to-fill orders - stp: cancelled because self trade prevention |
status | string | false | read-only | Order status - open : waiting to be traded- finished : finished |
contract | string | true | none | Futures contract. |
size | integer(int64) | true | none | Order size. Specify positive number to make a bid, and negative number to ask |
iceberg | integer(int64) | false | none | Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size |
price | string | false | none | Order price. 0 for market order with tif set as ioc . |
close | boolean | false | write-only | Set as true to close the position, with size set to 0. |
is_close | boolean | false | read-only | Is the order to close position. |
reduce_only | boolean | false | write-only | Set as true to be reduce-only order. |
is_reduce_only | boolean | false | read-only | Is the order reduce-only. |
is_liq | boolean | false | read-only | Is the order for liquidation. |
tif | string | false | none | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none |
left | integer(int64) | false | read-only | Size left to be traded. |
fill_price | string | false | read-only | Fill price of the order. |
text | string | false | none | Order custom information, users can use this field to set a custom ID, and the user-defined field must meet the following conditions: 1. Must start with t- 2. If t- is not calculated, the length cannot exceed 28 bytes3. The input content can only contain numbers, letters, underscores (_), midscores (-) or dots (.) In addition to user-defined information, the following are internal reserved fields that identifies the source of the order: - web: web page - api: API call - app: mobile terminal - auto_deleveraging: Automatic position reduction - liquidation: Liquidation under the classic account’s old liquidation mode - liq-x: new liquidation mode (isolated, cross margin one-way mode, non-hedging part of cross margin hedge mode) b. Liquidation under isolated margin in unified account single currency margin mode - hedge-liq-x: Liquidation under the new liquidation mode of the classic account hedge mode, the cross margin hedged part undergoes liquidation, meaning both long and short positions are liquidated simultaneously. - pm_liquidate: Unified account multi-currency margin mode liquidation - comb_margin_liquidate: Unified account portfolio margin mode liquidation - scm_liquidate: Unified account single currency margin mode liquidation - insurance: insurance |
tkfr | string | false | read-only | Taker fee. |
mkfr | string | false | read-only | Maker fee. |
refu | integer | false | read-only | Reference user ID. |
auto_size | string | false | write-only | Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0 |
stp_id | integer | false | read-only | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
stp_act | string | false | none | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group , he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group , an error will be returned when passing the stp_act parameter. 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled |
amend_text | string | false | read-only | The custom data that the user remarked when amending the order. |
Property | Value |
---|---|
finish_as | filled |
finish_as | cancelled |
finish_as | liquidated |
finish_as | ioc |
finish_as | auto_deleveraged |
finish_as | reduce_only |
finish_as | position_closed |
finish_as | reduce_out |
finish_as | stp |
status | open |
status | finished |
tif | gtc |
tif | ioc |
tif | poc |
tif | fok |
auto_size | close_long |
auto_size | close_short |
stp_act | co |
stp_act | cn |
stp_act | cb |
stp_act | - |
{
"id": 0,
"user": 0,
"create_time": 0.1,
"finish_time": 0.1,
"finish_as": "filled",
"status": "open",
"contract": "string",
"size": 0,
"iceberg": 0,
"price": "string",
"close": false,
"is_close": true,
"reduce_only": false,
"is_reduce_only": true,
"is_liq": true,
"tif": "gtc",
"left": 0,
"fill_price": "string",
"text": "string",
"tkfr": "string",
"mkfr": "string",
"refu": 0,
"auto_size": "close_long",
"stp_id": 0,
"stp_act": "co",
"amend_text": "string",
}
Modify contract order parameters.
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
order_id | integer(int64) | false | none | Order id, order_id and text must contain at least one. |
text | string | false | none | User-defined order text, at least one of order_id and text must be passed. |
size | integer(int64) | false | none | The new order size, including the executed order size. - If it is less than or equal to the executed quantity, the order will be cancelled. - The new order direction must be consistent with the original one. - The size of the closing order cannot be modified. - For orders that only reduce positions, if the size is increased, positions may be kicked out. - If the price is not modified, reducing the size will not affect the depth of the queue, and increasing the size will place it at the end of the current price. |
price | string | false | none | New order price. |
amend_text | string | false | none | Custom info during amending order. |
{
"order_id": 0,
"text": "string",
"size": 0,
"price": "string",
"amend_text": "string",
}
Futures order details.
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
initial | object | true | none | none |
» contract | string | true | none | 合约标识 |
» size | integer(int64) | false | none | 代表需要平仓的合约张数, 全平仓:size=0 部分平仓:plan-close-short-position size>0 部分平仓:plan-close-long-position size<0 |
» price | string | true | none | 交易价, 当价格为 0 时, 表示通过市价方式来下单 |
» close | boolean | false | write-only | 单仓模式全部平仓时,必须设置为true执行平仓操作 单仓模式部分平仓时/双仓模式下, 可以不设置close, 或close=false |
» tif | string | false | none | Time in force 策略,默认为gtc, 市价单当前只支持 ioc 模式市价单当前只支持 ioc 模式 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled |
» text | string | false | none | 订单的来源, 包括: - web: 网页 - api: API 调用 - app: 移动端 |
» reduce_only | boolean | false | none | 设置为 true 的时候执行自动减仓操作, 设为 true可确保订单不会开新仓, 只用于平仓或减仓 |
» auto_size | string | false | write-only | 单仓模式不需设置auto_size 双仓模式全部平仓(size=0)时, 必须设置auto_size, close_long 平多头, close_short 平空头 双仓模式部分平仓(size≠0)时, 不需设置auto_size |
» is_reduce_only | boolean | false | read-only | 是否为只减仓委托. 对应请求中的reduce_only . |
» is_close | boolean | false | read-only | 是否为平仓委托. 对应请求中的close . |
trigger | object | true | none | none |
» strategy_type | integer(int32) | false | none | 触发策略 - 0: 价格触发, 即当价格满足条件时触发 - 1: 价差触发, 即指定 price_type 的最近一次价格减去倒数第二个价格的差值目前暂时只支持0即最新成交价 |
» price_type | integer(int32) | false | none | 参考价格Type. 0 - 最新成交价, 1 - 标记价格, 2 - 指数价格 |
» price | string | false | none | 价格触发时为价格, 价差触发时为价差 |
» rule | integer(int32) | false | none | 价格条件Type - 1: 表示根据 strategy_type 和 price_type 算出的价格大于等于 Trigger.Price 时触发, 同时Trigger.Price must > last_price- 2: 表示根据 strategy_type 和 price_type 算出的价格小于等于 Trigger.Price 时触发, 同时Trigger.Price must < last_price |
» expiration | integer | false | none | 最长等待触发时间, 超时则取消该订单, 单位是秒 s |
id | integer(int64) | false | read-only | Auto order ID. |
user | integer | false | read-only | User ID. |
create_time | number(double) | false | read-only | Creation time. |
finish_time | number(double) | false | read-only | Finished time. |
trade_id | integer(int64) | false | read-only | ID of the newly created order on condition triggered. |
status | string | false | read-only | Auto order status - open : order is active- finished : order is finished- inactive : order is not active, only for close-long-order or close-short-order- invalid : order is close-short-order |
finish_as | string | false | read-only | How order is finished. |
reason | string | false | read-only | Additional remarks on how the order was finished. |
order_type | string | false | none | Types of stop-profit and stop-loss, including: - close-long-order : Entrusting order stop profit and stop loss, flat long position- close-short-order : loss, short position - close-long-position : Position stop-profit stop loss, used to close long positions- close-short-position : Position stop-profit stop loss, used to close all short positions- plan-close-long-position : Position plan take profit and stop loss, used to close long positions in all or part of long positions- plan-close-short-position : Position plan stop-profit and stop loss, used to close all short positions or partially close short positionsThe two types of entrusted order stop-profit and stop-loss are read-only and cannot be passed in through requests |
me_order_id | integer(int64) | false | read-only | Corresponding order ID of order take-profit/stop-loss. |
Property | Value |
---|---|
tif | gtc |
tif | ioc |
strategy_type | 0 |
strategy_type | 1 |
price_type | 0 |
price_type | 1 |
price_type | 2 |
rule | 1 |
rule | 2 |
status | open |
status | finished |
status | inactive |
status | invalid |
finish_as | cancelled |
finish_as | succeeded |
finish_as | failed |
finish_as | expired |
{
"initial": {
"contract": "string",
"size": 0,
"price": "string",
"close": false,
"tif": "gtc",
"text": "string",
"reduce_only": false,
"auto_size": "string",
"is_reduce_only": true,
"is_close": true
},
"trigger": {
"strategy_type": 0,
"price_type": 0,
"price": "string",
"rule": 1,
"expiration": 0
},
"id": 0,
"user": 0,
"create_time": 0.1,
"finish_time": 0.1,
"trade_id": 0,
"status": "open",
"finish_as": "cancelled",
"reason": "string",
"order_type": "string",
"me_order_id": 0
}
Futures contract details.
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
name | string | false | none | Futures contract. |
underlying | string | false | none | Underlying. |
cycle | string | false | none | Cycle type, e.g. WEEKLY, QUARTERLY. |
type | string | false | none | Futures contract type. |
quanto_multiplier | string | false | none | Multiplier used in converting from invoicing to settlement currency. |
leverage_min | string | false | none | Minimum leverage. |
leverage_max | string | false | none | Maximum leverage. |
maintenance_rate | string | false | none | Maintenance rate of margin. |
mark_type | string | false | none | Mark price type, internal - based on internal trading, external index price |
mark_price | string | false | none | Current mark price. |
index_price | string | false | none | Current index price. |
last_price | string | false | none | Last trading price. |
maker_fee_rate | string | false | none | Maker fee rate, where negative means rebate. |
taker_fee_rate | string | false | none | Taker fee rate. |
order_price_round | string | false | none | Minimum order price increment. |
mark_price_round | string | false | none | Minimum mark price increment. |
basis_rate | string | false | none | Fair basis rate. |
basis_value | string | false | none | Fair basis value. |
basis_impact_value | string | false | none | Funding used for calculating impact bid, ask price. |
settle_price | string | false | none | Settle price. |
settle_price_interval | integer | false | none | Settle price update interval. |
settle_price_duration | integer | false | none | Settle price update duration in seconds. |
expire_time | integer(int64) | false | none | Contract expiry timestamp. |
risk_limit_base | string | false | none | Risk limit base. |
risk_limit_step | string | false | none | Step of adjusting risk limit. |
risk_limit_max | string | false | none | Maximum risk limit the contract allowed. |
order_size_min | integer(int64) | false | none | Minimum order size the contract allowed. |
order_size_max | integer(int64) | false | none | Maximum order size the contract allowed. |
order_price_deviate | string | false | none | deviation between order price and current index price. If price of an order is denoted as order_price, it must meet the following condition: abs(order_price - mark_price) <= mark_price * order_price_deviate |
ref_discount_rate | string | false | none | Referral fee rate discount. |
ref_rebate_rate | string | false | none | Referrer commission rate. |
orderbook_id | integer(int64) | false | none | Current orderbook ID. |
trade_id | integer(int64) | false | none | Current trade ID. |
trade_size | integer(int64) | false | none | Historical accumulated trade size. |
position_size | integer(int64) | false | none | Current total long position size. |
config_change_time | number(double) | false | none | Last changed time of configuration. |
in_delisting | boolean | false | none | Contract is delisting. |
orders_limit | integer | false | none | Maximum number of open orders. |
Property | Value |
---|---|
cycle | WEEKLY |
cycle | BI-WEEKLY |
cycle | QUARTERLY |
cycle | BI-QUARTERLY |
type | inverse |
type | direct |
mark_type | internal |
mark_type | index |
{
"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
}