# Gate API v4 v4.69.0

    Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

    Welcome to Gate.io API

    APIv4 provides spot, margin and futures trading operations. There are public APIs to retrieve the real-time market statistics, and private APIs which needs authentication to trade on user's behalf.

    # Access URL

    REST API BaseURL:

    • Live trading: https://api.gateio.ws/api/v4
    • Futures TestNet trading: https://fx-api-testnet.gateio.ws/api/v4
    • Futures live trading alternative (futures only): https://fx-api.gateio.ws/api/v4

    # SDK

    Available SDK:

    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.

    # About APIv4 key improvement

    Previously(before April 2020) futures APIv4 key are separated from spot one, but this is no longer the case anymore. You can create multiple keys with each key having multiple permissions now. e.g. you can create one key with spot read/write and futures read/write permission which can be used in both spot and futures trading.

    History API keys will not be affected by this improvement. Previous spot key and futures key are now one key with only spot permissions enabled, another only futures permission enabled. You can reconfigure their permissions after migration.

    # Comparison with APIv2

    APIv4 is a standalone brand-new HTTP REST API, currently used in parallel with APIv2. APIv4 provides complete trading operations, with more highly secured authentication method. What's more, APIv4 specification is written following OpenAPI Specification (opens new window). SDKs and documents are all generated from the same spec, which ensures consistency between documents and implementation.

    The ways APIv4 and APIv2 differ are:

    1. Their API keys are separated from each other. Once logged into the web console, v2 API keys are generated on "APIKeys" page, while v4 "APIv4Keys" page.
    2. APIv2 supports only spot trading, while v4 supports all trading operations in spot, margin and futures.

    Which one to choose:

    1. If margin or futures trading are needed, choose APIv4.
    2. If only spot trading or wallet operation is required, choose on your own.

    # Application for Marketers

    In order to further improve the platform's opening depth and trading liquidity, we will recruit institutional market makers in an open and transparent way, and provide a professional market maker's service rate scheme for professional institutional market makers according to their contribution to the platform's liquidity.

    1. Provide Gateio UID
    2. Provide other transaction volume screenshot or VIP level
    3. Brief introduction of market making method and scale

    Provide the above content and submit to [email protected] , we will accept within 3 working days.

    TIP

    Vip11 and above need to open GT deduction in the personal center to enjoy the professional market rate.

    # Technical Support

    If you have any questions or suggestions during the use, you can contact us in any of the following ways:

    • Submit Work Order Feedback
    • Online Work Order Feedback
    • Send your contact information and questions to [email protected] We will assign technical specialists to serve you.

    If you encounter API errors, it is recommended that you sort out the following content, so that we can quickly analyze the problem for you:

    1. Problem Description
    2. Gateio UID
    3. Request URI and parameters
    4. Error Code
    5. Responses

    DANGER

    Even if you submit a problem, you should not submit the API key information to customer service or others, otherwise there will be serious asset risk. If it has been accidentally leaked, please delete the existing API and rebuild it.

    # Changelog

    v4.69.0

    2024-03-25

    • Add text field in POST /delivery/{settle}/price_orders response

    v4.68.0

    2024-03-18

    • New feature: add GET /unified/currency_discount_tiers endpoint, list currency discount tiers
    • Add type parameter in GET /unified/loans endpoint
    • Add type parameter in GET /unified/interest_records endpoint

    v4.67.0

    2024-03-11

    • Add filled_amount field in POST /spot/orders,POST /spot/batch_orders response
    • In frequency limit rule for the wallet withdrawal interface, the speed limit description has been corrected from 10r/10s to 1r/3s(No modification to the original rate limiting behavior)

    v4.66.1

    2024-02-19

    • New feature: add GET /wallet/small_balance endpoint, list small balance.
    • New feature: add GET /wallet/small_balance_history endpoint, list small balance history.
    • New feature: add GET /unified/estimate_rate endpoint, get unified estimate rate.

    v4.65.0

    2024-01-29

    • Add debit_fee field in GET /spot/batch_fee response
    • Add user_id parameter in DELETE /account/stp_groups/{stp_id}/users endpoint
    • Spot API introduces asynchronous support modes for create orders: ACK, RESULT, FULL. For details, please refer to SPOT API

    v4.64.0

    2024-01-22

    • Add order_type parameter in GET /loan/multi_collateral/orders endpoint
    • Add order_type,fixed_type,fixed_rate,expire_time,auto_renew,auto_repay field in GET /loan/multi_collateral/orders response
    • Add before_ltv,after_ltv field in GET /loan/multi_collateral/repay response
    • New feature: add GET /loan/multi_collateral/fixed_rate endpoint, query multi-collateral fix rate.
    • Add unrealised_pnl,borrowed field in GET /wallet/total_balance response

    v4.63.0

    2024-01-15

    • Add decimal field in GET /wallet/currency_chains response
    • New feature: add GET /futures/{settle}/risk_limit_tiers endpoint, list risk limit tiers.

    v4.62.0

    2024-01-02

    • New feature: add POST /futures/{settle}/batch_cancel_orders endpoint, users have the ability to batch cancel orders.
    • New feature: add multi-collateral-loan api. (/loan/multi_collateral/**)

    v4.61.0

    2023-12-18

    • New features: The broker obtains the user's commission rebate records in GET /rebate/broker/commission_history and GET /rebate/broker/commission_history endpoints

    v4.60.0

    2023-12-01

    • Breaking change: New Unified API is online. The old /portfoli/* endpoints are deprecated.
    • New features: add earn product api. (/earn/**)
    • Add trade_id field in GET /futures/{settle}/account_book response

    v4.59.0

    2023-11-22

    • Add funding_cap_ratio field in GET /futures/{settle}/contracts response
    • Add contract field in GET /delivery/{settle}/account_book response
    • Add withdraw_percent_on_chains field in GET /wallet/withdraw_status response
    • Add leverage field in GET /portfolio/accounts response

    v4.58.0

    2023-11-03

    • Add loanable field in GET /margin/cross/currencies response
    • Add biz_info field in GET /futures/{settle}/orders/{order_id} response
    • Add tier field in GET /account/detail response
    • Add max_base_amountmax_quote_amount field in GET /spot/currency_pairs response

    v4.57.0

    2023-10-20

    • New feature: API Gateway inbound & outbound time, For more details, please refer to the API Gateway in/out time
    • New feature: support portfolio account in POST /spot/orders endpoint
    • New feature: add PUT /earn/uni/interest_reinvest endpoint, users have the option to enable or disable interest reinvestment.
    • New feature: add POST /spot/amend_batch_orders endpoint, users have the ability to batch modify orders.
    • Add sequence_id field in GET /spot/trades response
    • Add text field in GET /spot/account_book response
    • Add text field in GET /spot/my_trades response
    • GET /portfolio/spot/ordersGET /portfolio/spot/ordersGET /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

    • Add repayment_type field in GET /margin/cross/repayments and GET /portfolio/loan_records endpoints.
    • Add request parameter holding in GET /futures/{settle}/positions endpoint
    • Add request parameter role in GET /futures/{settle}/my_trades_timerange endpoint
    • Add request parameter side and pnl in GET /futures/{settle}/position_close endpoint

    v4.55.0

    2023-09-12

    • Add new POST /portfolio/account_mode endpoint, allow to change the mode.

    v4.54.0

    2023-08-28

    • Add contract_address field in GET /wallet/currency_chains endpoint.
    • Add 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

    • New feature: delete user in STP group in DELETE /account/stp_groups/{stp_id}/users endpoint

    v4.52.0

    2023-08-07

    • New feature: add collateral loan api

    v4.51.0

    2023-07-29

    • Adjusted and optimized the account book types
    • Add mode field in GET /account/detail edpoint.

    v4.50.0

    2023-07-14

    • New feature: New Portfolio API. Currently, these services are only available to whitelisted users. If you are interested in accessing these APIs, please contact our institutional department for further information.
    • Add new endpoint GET /flash_swap/currency_pairs, list all flash swap currency pair

    v4.49.0

    2023-07-03

    • Add new frequency limit rule,the new rule is expected to take effect on 2023-07-10 (UTC+8)
    • In the 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

    • Add client_order_id fields in GET /wallet/sub_account_transfers edpoint.

    v4.47.0

    2023-05-23

    • New feature: add STP group admin api
    • New feature: query estimated interest rates of margin and cross margin in GET /margin/uni/estimate_rate and GET /margin/cross/estimate_rate endpoints.
    • New feature: list futures order by time range in GET /futures/{settle}/orders_timerange endpoint
    • Add underlyingunderlying_pricemark_ivdeltagammavegatheta fields in GET /options/positions/{contract} endpoint.

    v4.46.0

    2023-05-08

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

    v4.45.0

    2023-04-21

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

    v4.44.0

    2023-04-07

    • Add ORDER_BOOK_NOT_FOUND and FAILED_RETRIEVE_ASSETS error messages.

    v4.43.0

    2023-03-27

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

    v4.42.0

    2023-03-13

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

    v4.41.0

    2023-03-03

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

    v4.40.0

    2023-02-24

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

    v4.39.0

    2023-02-09

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

    v4.38.0

    2023-02-04

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

    v4.37.0

    2023-01-20

    • Add new rebate API endpoints.

    v4.36.0

    2022-12-23

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

    v4.35.0

    2022-12-09

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

    v4.34.0

    2022-11-25

    • Support market order in POST /spot/orders endpoint

    v4.33.0

    2022-11-11

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

    v4.32.0

    2022-10-28

    • Improve options api document

    v4.31.0

    2022-10-14

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

    v4.30.0

    2022-09-23

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

    v4.29.0

    2022-09-09

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

    v4.28.0

    2022-08-12

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

    v4.27.0

    2022-07-29

    • Add basis_ratebasis_value fields in GET /delivery/{settle}/tickers response
    • Add X-Client-Request-Id http header for tracking request
    • new create a batch of futures order endpoint POST /futures/{settle}/batch_orders
    • new FOK tif type for futures order

    v4.26.0

    2022-07-15

    • Spot Price-Trigger order supports portfolio margin account
    • Add GET /wallet/saved_address to list saved address
    • POST /wallet/transfers returns tx_id field
    • Add GET /wallet/sub_account_cross_margin_balances to query subaccount's cross_margin account
    • Add status field in GET /margin/currency_pairs response

    v4.25.1

    2022-07-06

    • New GET /spot/time endpoint which get system's time info.
    • New GET /options/my_settlements endpoint which list my selttlements.
    • Add change_utc0, change_utc8 fields in GET /spot/tickers endpoint

    v4.25.0

    2022-06-24

    • Support portfolio margin account API
    • Cross-margin add more fields. Please refer to endpoint document for more details.
    • Add status field in GET /margin/cross/currencies endpoint, determine whether the cross currency is disabled 0-disable 1-enable
    • New POST /spot/cross_liquidate_orders spot trading endpoint that close position when the cross-currency is disabled
    • Add bouns and history fields in GET /futures/{settle}/accounts endpoint
    • Add textfee and point_fee fields in GET /futures/{settle}/my_trades endpoint
    • Fix typo for cancel a price-triggered order endpoints
    • POST /wallet/sub_account_transfers supports transferring to cross_margin

    v4.24.0

    2022-05-20

    • Support flash swap operations with new API group /flash_swap. Spot operation permission is required.
    • New wallet APIs GET /wallet/sub_account_margin_balances and GET /wallet/sub_account_futures_balances to help main account retrieving sub accounts' margin and perpetual contract balances
    • New perpetual contract API GET /futures/{settle}/index_constituents/{index} to retrieve index price constituents
    • Fix missing fields like order_type in FuturesPriceTriggeredOrder

    v4.23.4

    2022-04-25

    • Add PUT /futures/{settle}/orders/{order_id} to amend perpetual futures orders
    • Spot candlesticks supports 30d interval

    v4.23.3

    2022-04-01

    1. Spot candlestick API returns base currency amount
    2. Spot currency detail add chain field.
    3. Add withdrawal and deposit status in GET /wallet/currency_chains response
    4. Add missing cross_leverage_limit in perpetual contract's dual mode position leverage update API
    5. Support more intervals in perpetual and delivery contract candlesticks

    v4.23.2

    2022-01-21

    1. Add fee in withdrawal and deposit history
    2. Add fix fee rate in spot Currency

    v4.23.1

    2021-12-23

    1. Spot orders support new time_in_force FOK
    2. New FOK_NOT_FILL error label

    v4.23.0

    2021-12-09

    1. Add options API
    2. Add detailed rate limiting rules
    3. Add GET /wallet/currency_chains to retrieve chains supported by currency
    4. Add additional status for deposit and withdrawal history

    v4.22.4

    2021-11-01

    1. Data type of ctime and ftime in SpotPriceTriggeredOrder should be int64

    v4.22.3

    2021-10-27

    1. GET /spot/trades supports time range based query using from and to.

    v4.22.2

    2021-09-29

    1. Add more status in withdrawal or deposit record model
    2. Add new write only field auto_size in FuturesOrder to support closing dual mode position.

    v4.22.1

    2021-09-07

    1. New wallet API GET /wallet/total_balance to retrieve all user's estimate balance.
    2. Add locked and risk in margin account response
    3. Margin and cross margin loans support custom text input.

    v4.22.0

    2021-08-13

    1. Delivery contract API supports BTC settled
    2. Spot API GET /spot/orders and GET /spot/my_trades supports query by time range
    3. Add margin and cross margin max borrowable API
    4. Multiple document enhancements.

    v4.21.6

    2021-08-12

    1. Fix incorrect address field name in GET /wallet/deposit_address

    v4.21.5

    2021-06-30

    • GET /spot/orders, GET /spot/orders/{order_id} and GET /spot/my_trades allow empty currency_pair if operated against finished orders
    • Add fixed withdrawal fee on multiple chains in GET /wallet/withdraw_status response
    • Add GET /margin/transferable and GET /margin/cross/transferable to retrieve maximum transferable amount from margin and cross margin account
    • Add from and to parameter to specify time range for futures position closes history API

    v4.21.4

    2021-06-23

    • Add cross margin account change history API GET /margin/cross/account_book
    • Add millisecond timestamp in GET /margin/account_book response

    v4.21.3

    2021-06-17

    • Add order book timestamp for both spot and futures trading

    v4.21.2

    2021-06-07

    • Futures API support cross margin leverage modification
    • Add new spot cross margin API /margin/cross
    • Add spot order operations using spot cross margin account
    • Add unpaid interests in spot margin account query
    • Add new millisecond fields create_time_ms and update_time_ms in spot orders.
    • Add DELETE /withdrawals/{withdrawal_id} to cancel withdrawal operation

    v4.20.1

    2021-04-14

    • Update document links

    v4.20.0

    2021-03-25

    • Support spot auto orders with API group /spot/price_orders

    v4.19.6

    2021-03-22

    • Add trading timestamp in spot currency pair

    v4.19.5

    2021-03-18

    • Spot and Futures operations based on order ID also accept user custom ID(but only for 30 minutes since creation)

    v4.19.4

    2021-03-10

    • /wallet/sub_account_transfers supports transferals with sub user's perpetual contract account

    v4.19.3

    2021-03-04

    • Add margin loans auto repay API /margin/auto_repay
    • Add multichain_address in /wallet/deposit_address for currencies with multiple deposit addresses
    • Optimize documentation

    v4.19.2

    2021-03-01

    • Add /wallet/fee API to retrieve trading fee. Previous /spot/fee is deprecated in favour of this one.
    • Add new field chain in withdrawal operation.
    • Add new field with_id in /futures/{settle}/order_book API and id field in its response
    • Add new offset in API /futures/{settle}/position_close to retrieve position close history with pagination.
    • Add contract value calculation. Refer to Contract model for details.
    • Fix incorrect field type in futures stats API

    v4.18.4

    2021-01-22

    • Add field create_time_ms in spot Trade model
    • ETF currency pairs' ticker add net value related info

    v4.18.1

    2021-01-07

    • Add iceberg order support for spot orders
    • Fix incorrect field types in /futures/{settle}/contract_stats

    v4.18.0

    2020-12-21

    • Add new spot API/spot/currencies and /spot/currencies/{currency} to retrieve currency info
    • Add more fields, e.g., top_lsr_account, top_lsr_size, in futures ContractStat model.

    v4.17.1

    2020-12-16

    • Increase maximum of limit in /spot/order_book to 100

    v4.17.0

    2020-12-15

    • Add /wallet/sub_account_balances to retrieve sub accounts' balances.

    v4.16.1

    2020-12-10

    • Fix mistaken field name dual_mode in futures position model which should be mode instead.

    v4.16.0

    2020-12-09

    Spot

    • Increase order number limit each currency pair to 10 in POST /spot/batch_orders
    • Add new query parameter reverse in GET /spot/trades to trace back trading history

    Futures

    • Add perpetual contract dual mode position support. Use /futures/{settle}/dual_mode to set position's dual mode. For dual mode position operations, refer to /futures/{settle}/dual_comp/positions API group
    • Add perpetual contract new field in_dual_mode in futures account response model; dual_mode in position response model.
    • Add new perpetual contract public API /futures/{settle}/liq_orders to query liquidated orders in markets

    v4.15.5

    2020-11-04

    • Add /futures/{settle}/contract_stats API to retrieve contract stats
    • Add /margin/{currency_pair} to retrieve single margin currency pair detail

    v4.15.4

    2020-09-01

    • Add point_type in GET /spot/fee response
    • Add GET /wallet/withdraw_status API
    • Add C# SDK entry

    v4.15.2

    2020-08-12

    • Add GET /spot/fee to retrieve spot order trading fee rates

    v4.15.1

    2020-08-04

    • Add GET /spot/open_orders to retrieve all open orders in spot trading
    • Add GET /margin/account_book to retrieve margin account balance history

    v4.14.1

    2020-07-08

    • maximum length of text field in order extends to 28(prefix excluded)

    v4.14.0

    2020-07-06

    • New Delivery contract APIs /delivery

    v4.13.1

    2020-06-28

    • Add GET /wallet/sub_account_transfers to list sub account transfer records

    v4.13.0

    2020-05-20

    • APIv4 now supports withdraw API. Refer to POST /withdrawals and "Authentication" section for details.
    • POST /wallet/transfers supports transferring between spot and futures account
    • Wallet API supports retrieving deposits and withdrawals history
    • Futures orders and personal trades retrieving now supports offset field
    • Futures Contract model add new field in_delisting

    v4.12.0

    2020-04-08

    • APIv4 Key management improved. Keys are no longer separated with different trading types. Every key can now have multiple operation permissions. Refer to "About APIv4 key improvement" for details.
    • Add POST /wallet/sub_account_transfers to support transferring between main and sub account
    • GET /spot/candlesticks adds query parameters from and to to support retrieving history data points

    v4.11.2

    2020-03-29

    • Add filled_total in Order to replace fill_price (the latter is badly named)
    • Add new error label POC_FILL_IMMEDIATELY

    v4.11.1

    2020-03-23

    • Add role in GET /spot/my_trades response
    • Fix missing currency account in GET /margin/funding_accounts

    v4.11.0

    2020-03-20

    • Spot order supports GT fee discount
    • Spot order time in force supports poc

    v4.10.1

    2020-02-24

    • Add trade_status in spot currency pair

    v4.10.0

    2020-02-17

    • Margin order creation adds new field auto_borrow(write only) to borrow the insufficient part by the system if balance is not enough
    • Add new API POST /spot/cancel_batch_orders to support batch cancellation with specified order IDs
    • Add new document section "Error handling" and "Which one to choose, APIv4 or APIv2?"

    v4.9.1

    2020-01-07

    • Add fee and recent modification time in Order and BatchOrder
    • Add fee in GET /spot/my_trades response

    v4.9.0

    2019-12-17

    • last_id in GET /futures/{settle}/trades is deprecated. Use from and to to retrieve trading history

    v4.8.2

    2019-12-02

    • Add /spot/batch_orders to support creating a bundle of spot or margin orders
    • Fee rate of margin loan repayment enjoys VIP discount
    • Loan add new fields fee_rate(fee rate of lending loan) and orig_id(original loan ID if loan is auto renewed)

    v4.8.1

    2019-11-27

    • Fix missing settle in GET /futures/{settle}/positions docs and code snippet

    v4.8.0

    2019-11-07

    • Futures API now supports settling in USDT.
    • Change /futures to /futures/{settle} in ALL futures API to support futures operations in different settle currency.
    • currency field in /futures/{settle}/accounts response adds new value: USDT
    • Add volume_24h_base, volume_24h_quote and volume_24h_settle in /futures/{setttle}/tickers response to replace volume_24h_btc and volume_24h_usd. The latter two are still preserved for compatibility usage, but are NOT recommended for any futures operations.

    To use USDT futures, just replace /futures with /futures/usdt, e.g. use GET /futures/usdt/accounts to retrieve futures accounts settled in USDT, while GET /futures/btc/accounts returns accounts in BTC.

    For compatibility, GET /futures/xxx defaults to GET /futures/btc/xxx, e.g. GET /futures/accounts will be treated as GET /futures/btc/accounts

    v4.7.3

    2019-07-18

    • Add text in /spot/orders and /futures/orders to support user defined order information

    v4.6.3

    2019-06-11

    • Add point information in Futures account and position

    v4.7.2

    2019-05-29

    • Change rate in Loan as non-required for lending side.

    v4.7.1

    2019-04-17

    • Add wallet v4 API. Support transfers between spot and margin account for now.
    • GET /margin/loans can sort by rate and support an optional parameter currency_pair
    • Fix miscellaneous document issues

    v4.6.2

    2019-04-24

    • Fix price-triggered futures order's docs incorrect override docs for GET /futures/orders/{order_id} and DELETE /futures/orders/{order_id}

    v4.6.1

    2019-04-02

    • Add high_24h, low_24h and funding_rate_indicative in futures ticker

    v4.6.0

    2019-03-21

    SDK related only

    • Rename futures order related function name in SDKs to avoid duplication with spot order API in Go
    • Fix query parameter not decoded while generating authentication signature

    v4.5.2

    2019-03-14

    • currency_pair in /spot/order_book should be a required parameter
    • Optimize document code samples

    v4.5.1

    2019-03-11

    • Fix missing URL parameter description

    v4.5.0

    2019-03-05

    To avoid version confusion, all versions in APIv4 (documents and SDKs are both included) will start with 4 from now on

    • Add Spot v4 API to provide improved API capability
    • Add Margin v4 API to provide support for margin loans and trading
    • Add Futures price triggered auto order API support. Refer to /futures/price_orders for details
    • Base URL of all Gate API v4 real trading changed to https://api.gateio.ws/api/v4

    v1.3.0

    2019-02-13

    Important update

    • Domain of base URLs are changed to fx-api.gateio.ws and fx-api-testnet.gateio.ws respectively, *.gateio.io is deprecated and will soon be out of service.

    v1.2.1

    2019-02-13

    • Add volumn_24h_usd and volume_24h_btc in GET /futures/tickers response

    v1.2.0

    2019-01-17

    • Add GET /futures/contracts/{contract} to get one single contract
    • Add GET /futures/positions/{contract} to get one single position
    • Add GET /futures/account_book to retrieve user account balance history
    • Add config_change_time in Contract model
    • fix miscellaneous document issues

    v1.1.0

    2019-01-08

    • Add more fields to Contract, Position, FuturesOrder
    • Add API GET /futures/position_close to retrieve position close history
    • Add optional order_id support for API GET /futures/my_trades
    • Change the status code of DELETE /futures/orders and DELETE /futures/orders/{order_id} from 204 to 200, with cancelled order details returned on success.
    • Request DELETE /futures/orders/{order_id} with invalid order ID or order that has been finished will return 404 instead of ignoring the error
    • POST /futures/orders now supports POC, iceberg

    v1.0.0

    2018-12-30

    • Initial release

    # General

    # Matching mechanism

    # Matching priority

    Gate.io Order matching follows Price Priority > Time priority principle.

    Suppose that the order book is as follows:

    Order Order time Ask/Selling price
    A 10:00 100
    B 10:00 102
    C 10:01 100

    If the current price of 10:02 pays 102, the final transaction order is: A, C, B

    # Order life cycle

    A valid order sent to the matching engine is immediately confirmed and executed with existing orders, with the executing result sent back to the client.

    If an order is fully executed, then it is closed. If any part of the order is not executed immediately, orders with TimeInForce set to IOC will be cancelled, while others will be appended to the price list, waiting for subsequent filling or being cancelled.

    # Data Center

    Gate.io data center is located in AWS Japan's ap-northeast-1 region.

    # API Overview

    API Classification Category Links Overview
    host + /api/v4/spot/* Spot Trading Including currency status, market information, order, transaction records and other functions
    host + /api/v4/margin/* Margin Trading Margin account management, lending, repayment, etc
    host + /api/v4/wallet/* Wallet Management Charge and withdrawal records, balance inquiries, fund transfers, etc.
    host + /api/v4/withdrawals/* Withdrawal Withdrawal of digital currency

    # Margin Migration Instructions

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

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

    Margin account related endpoints:

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

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

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

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

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

    # API

    # HTTP convention

    • All read endpoints use GET method. They accept only request parameters. No request body will be read.
    • DELETE methods remove resources(like orders), but not all removing operation using DELETE, as DELETEs don't read request body either. For complex removing operations, POST method is used with parameters filled in request body.
    • Updating is done using POST, PUT or PATCH method. Their parameters are either in body or request parameters for different endpoints. Refer to endpoint detail for how to send the request.
    • All endpoints return HTTP status code 2xx on success. 401 is returned on authentication failure. Other 4xx codes mean the request is malformed. 5xx means the server encounter some critical error on processing the request. Commit issues if 5xx is met.

    # Time

    All time related fields are unix timestamp in seconds if no extra note, but they may differ in formats(int64, number or string). Possible values like the following may be returned:

    • 1596531048
    • "1596531048"
    • 1596531048.285
    • "1596531048.285"

    The best way to handle time fields is parsing them as a number with decimal places. If higher precision is not needed, you can safely cast them to integer(or long). Our SDKs listed above has already taken proper deserialization to handle them

    # API Gateway in/out time

    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

    Pagination is achieved using one of the following method

    • page-limit
    • limit-offset

    In both method, limit limits the maximum number of records returned in one request. If no additional explanation, it defaults to 100 if not provided and its maximum value is limited to 1000.

    page starts from 1, mimicking common paging used in web pages. To iterate the whole list, use the same limit and increment page by 1 until the records' length is shorter than the limit

    offset starts from 0, behaving like common DB search. To iterate the whole list, increment offset by limit until the records' length is shorter than the limit.

    For example, if the total number of orders is 201. Using page-limit method, send request parameters like the following:

    1. page=1&limit=100
    2. page=2&limit=100
    3. page=3&limit=100

    Using limit-offset method, send request parameters like:

    1. limit=100&offset=0
    2. limit=100&offset=100
    3. limit=100&offset=200

    Some endpoints may return additional pagination metadata. If present, they are sent back through the response header. Take GET /futures/{settle}/orders as an example, following headers will be returned

    • X-Pagination-Limit: request limit
    • X-Pagination-Offset: request offset
    • X-Pagination-Total: total record number satisfying the request

    # Frequency limit rule

    Markets Endpoints Limits Based On Include
    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.

    WebSocket:

    • The message limit sent to the server: unlimited.
    • Number of connections per IP: ≤ 300

    # Return Format

    All API responses are in JSON format, and users need to transform and extract data by themselves.

    The HTTP status code 2XX will be returned when all operations are successful. 401 indicates that there is a problem with the certification. Other 4xx status codes indicate that the request is invalid. If it is a 5xx error, the server has encountered an unknown serious error when processing the request. Please give feedback as soon as possible。

    Return Status

    Status Code Description
    200/201 Request succeeded
    202 Request accepted by the server, but processing is not done yet
    204 Request succeeded, but the server doesn't return body
    400 Invalid request
    401 Authentication failed
    404 Not found
    429 Too many requests
    5xx Server error

    # Data Type

    Type Description
    string String type, in double quotation marks. Price and amount are also formatted in string format
    integer 32-bit integer,Mainly related to status codes, size, times, etc.
    integer(int64) 64-bit integer,Mainly involves ID and higher precision timestamp
    float Floating point number. Some time and stat fields use float.
    object Object,Contains a child object{}
    array List,Includes multiple groups of content
    boolean true is true,false is false

    # Portfolio Margin Account

    TIP

    The Portfolio Margin Account is no longer maintained, please refer to the new version of the Unified Account

    Since version 4.25.0, we start supporting portfolio margin account. Gate.io's Portfolio Margin Account is a new feature of Gate.io's trading system. Its main function is to break the capital isolation between cross-margin leverage account and USD cross-margin perpetual contract account inside a Classic Account and achieve the multi-currency margin sharing among multi-product lines. Thanks to the margin sharing, users don't need to transfer funds between the two accounts, and the profit and loss of positions among different trading products can offset each other and effectively improve the capital utilization rate. See more details in the Help Center

    Before using the portfolio margin account's API key, you should create the API key on the API management page. The API key supports spot and perpetual contracts trading only.

    If permissions of the API key can't be checked, ensure your cross-margin account has available balance first.

    # Transfer

    The classic account and portfolio margin account are two different capital isolation accounts. If you want to achieve multi-currency margin sharing among multi-product lines, use the portfolio margin account please.

    The funds of the portfolio margin account come from the classic account. Due to the change of funds in the classic account, the transfer of funds can only be performed using the API Key of the classic account.

    The portfolio margin account is upgraded based on the cross-margin account of the original classic account, so the classic account only needs to transfer its spot funds to the cross-margin account to deposit the portfolio margin account. Similarly, withdrawals from portfolio margin account can be achieved by the classic account performing transferals from the cross margin to its spot account.

    The API Key of the portfolio margin account can only perform transferals among its own multiple accounts. Due to the sharing of margin, the portfolio margin account does not need to transfer funds to its futures account (we also restrict doing so). If the futures account has PNL funds that need to be withdrawn, it must be transferred by the portfolio margin account's API key to its cross-margin account first, so that the classic account can perform withdrawals from portfolio margin account.

    # Spot trading

    The spot trading of the portfolio margin account is almost the same as the classic account, except that cross_margin must be specified in the account parameter when placing orders. For example, if you want to place a buy order for the BTC_USDT currency pair, the order request will be similar to

    POST /spot/orders
    
    {
      "currency_pair": "BTC_USDT",
      "account": "cross_margin",
      "side": "buy",
      ...
    }
    

    For other related restrictions, please refer to the document of the API endpoint directly.

    TIP

    It should be noted that the portfolio margin account is upgraded from the classic account's cross-margin account. The API Key of the classic account originally supports the operation of the cross-margin account. In order not to affect the existing operations of the classic account, we still retain this function of the classic account. So whether it is the API Key of the classic account or the portfolio margin account, both can operate the same the cross margin account (note that the futures accounts are separate)

    # Futures trading

    The API operation of the perpetual contract of the portfolio margin account is exactly the same as that of the classic account, but currently only supports USD settlement

    TIP

    In the futures trading, it should be noted that there is no compatibility for cross-margin accounts like using the API Key of the classic account in spot trading. Therefore, when using the API Key of the classic account for futures trading, assets are kept under classic account-futures, and when using portfolio margin account API Key for futures trading, assets are kept under portfolio margin account-futures. These two are different futures accounts. In addition, funds under classic account-spot cannot share margin with classic account-futures.

    # Request ID

    It is allowed to set an X-Client-Request-Id header in the request, and the API will also carry this header in the response. You can use this field to locate the corresponding request that the API responds to, which is convenient for users to set the request id for tracking.

    # Self-Trade Prevention (STP)

    # Concepts

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

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

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

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

    # STP Strategies

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

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

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

    # API Parameter Adjustment

    Take placing futures order as an example:

    POST /futures/{settle}/orders
    

    New request body parameter:

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

    New response fields:

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

    # User case

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

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

    T1: The STP strategy version released.

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

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

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

    {
    	"status":"finished",
    	"stp_act":"cn",
    	"stp_id":100,
    	"finish_as":"stp"
    }
    
    • If stp_act is co , the order placed by taker will be retained, the order status will be open, and the system will cancel the order of maker.

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

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

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

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

    # Unified Account

    # Description

    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 Integration Process

    • Create a new API KEY or update the permissions of an existing API KEY, checking the unified permission
    • Use the classic account's API KEY to call the POST /api/v4/unified/account_mode endpoint, or upgrade from the WEB page to the Unified Account
    • Use the /api/v4/spot/** API for spot-related operations (ordering, modifying orders, querying orders), with the account=unified option
    • Use the /api/v4/futures/** API for perpetual futures-related operations (ordering, modifying orders, querying orders)
    • Use the /api/v4/unified/** API for Unified Account-related operations (account querying, loan querying)

    # SPOT Trading

    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.

    # Formula

    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

    # AccountBook type

    # General

    • unknown: Unknown
    • login: Log In
    • withdraw: Withdrawals
    • ch_pass: Change Password
    • ch_fund_pass: Change Fund Pass
    • login_failed: Login Failed
    • axs_account: Access Account
    • req_pass_ch: Request Password Change
    • req_fund_pass_ch: Request Fund Pass Change
    • fund_pass_ent: Fund Pass Entered
    • bank_card_add: Bank Card Added
    • frw: Face Recognition For Withdrawal

    # Order

    • new_order: Order Placed
    • cancel_order: Order Cancelled
    • order_fill: Order Filled
    • order_rej: Order Rejected
    • order_fee: Trading Fees
    • system_fee: Trading Fee System Account

    # Withdraw-Deposit

    • withdraw: Withdrawals
    • deposit: Deposits
    • deposit_rej: Deposit Rejected
    • withdraw_rej: Withdrawal Rejected
    • cancel_withdraw: Cancel Withdrawal
    • withdraw_gatecode: GateCode Withdrawals
    • withdraw_fireblock: Fireblocks Withdrawals
    • withdraw_copper: Copper Withdrawals
    • startup_withdraw: Token Withdrawal From Startup
    • deposit_gatecode: GateCode Deposits
    • deposit_fireblock: Fireblocks Deposits
    • deposit_copper: Copper Deposits
    • buy_cl: Buy Crypto Legend
    • buy_cc: Buy Crypto Cabital
    • deposit_finmo: Gate connect Finmo Deposit

    # Startup

    • startup_prtcp: Startup Sale Participation
    • startup_refund: Startup Sale Refund
    • startup_sale: Startup Sale
    • startup_sale_rb: Startup Sale Rolled Back

    # Rebate

    • referral_rebate: Referral Superior Rebate
    • sec_rebate_out: Secondary Rebate Financial Account Transfer Out
    • sec_rebate_in: Affiliate Indirect Superior Rebate Income
    • ab_rebate: API Broker Rebate Income
    • eb_rebate: Exchange Broker Rebate Income
    • u_rebate: Referral Rebate Income
    • ads_rebate: Affiliate Direct Superior Rebate Income
    • au_rebate: Affiliate User Rebate Income
    • pis_rebate: Partner Indirect Superior Rebate Income
    • pds_rebate: Partner Direct Superior Rebate Income
    • pu_rebate: Partner User Rebate Income

    # Convert

    • eth_swap: ETH Swap
    • dust_swap_dctd: Dust Swap-Small Balances Deducted
    • dust_swap_gt_add: Dust Swap-GT Added
    • dust_swap_fee: Dust Swap-Fees Deducted
    • cv_buy: Quick Buy-Bought
    • cv_sell: Quick Sell-Sold

    # C2C

    • c2c_mop: C2C Merchant Order Placed
    • c2c_moc: C2C Merchant Order Canceled
    • c2c_rop: C2C Retail Order Placed
    • c2c_roc: C2C Retail Order Canceled
    • c2c_om: C2C Order Matched
    • c2c_or: C2C Order Rejected
    • c2c_fee: C2C Fees

    # Reward

    • deposit_bonus: Deposit Bonus
    • trading_rewards: Trading Rewards
    • purchase_bonus: Purchase Bonus
    • airdrop: Airdrop
    • award: Award
    • mining_rewards: Mining Rewards

    # Account Transfer In-Out

    • margin_in: Isolated Margin-Transferred In
    • margin_out: Isolated Margin- Transferred Out
    • spot_settle_out: Spot Settlement Transfer Out
    • spot_settle_in: Spot Settlement Transfer Out
    • lending_in: Lending-Transferred In
    • lending_out: Lending-Transferred Out
    • cross_in: PortfolioMarginAccountTransferIn
    • cross_out: PortfolioMarginAccountTransferOut
    • perp_in: Perps- Transferred In
    • perp_out: Perps- Transferred Out
    • perp_settle_in: Perpetual Multi-currency Settlement Transfer In
    • perp_settle_out: Perpetual Multi-currency Settlement Transfer Out
    • delivery_in: Delivery- Transferred In
    • delivery_out: Delivery- Transferred Out
    • ai_in: Auto-Invest-Transferred In
    • ai_out: Auto-Invest-Transferred Out
    • e_options_in: Easy Options- Transferred In
    • e_options_out: Easy Options- Transferred Out
    • options_in: Options- Transferred In
    • options_out: Options- Transferred Out
    • cbbc_in: CBBC- Transferred In
    • cbbc_out: CBBC- Transferred Out
    • warrant_in: Warrant- Transferred In
    • warrant_out: Warrant- Transferred Out
    • subaccount_trf: Subaccount Transfer
    • quant_in: Quant- Transferred In
    • quant_out: Quant- Transferred Out
    • pay_in: Payment Account- Transferred In
    • pay_out: Payment Account- Transferred Out
    • fct_in: Futures Copy Trading - Funds Transfer In
    • fct_out: Futures Copy Trading - Funds Transfer Out

    # Points

    • points_purchase: Points Purchase
    • points_expiration: Points With Expiration
    • points_trf: Points Transfer
    • points_trf_rej: Points Transfer Rejected

    # Finance

    • lending_lent: Lending-Lent
    • collected: Collected
    • interest_in: Interest Income
    • lending_fee: Lending-Fees Deducted
    • hodl_int: HODL Interest
    • redeem: Redeem
    • lend: Lend
    • dual_purchased: Dual C-Purchased
    • dual_settled: Dual C-Settled
    • liq_add: Liquidity Added
    • liq_rm: Liquidity Removed
    • liq_rebalanced: Liquidity Rebalanced
    • slot_int_in: Slot Auction Staking Interest Income
    • str_int_in: Structured Products Staking Interest Income

    # Loan

    • borrow: Borrow
    • repay: Repay
    • margin_borrow: Isolated Margin-Transferred In
    • margin_repay: Isolated Margin- Transferred Out
    • margin_interest_out: Isolated Margin-Interest Deduction
    • cl_borrow: Cryptoloan- Borrowed
    • cl_repay: Cryptoloan- Repaid
    • cl_dctd: Cryptoloan- Collateral Deducted
    • cl_rtd: Cryptoloan- Collateral Returned
    • cross_borrow: PortfolioMarginAccountBorrowIn
    • cross_repay: PortfolioMarginAccountRepay
    • interest_out: Interest

    # Moments

    • donation: Donation
    • rp_sent: Red Packet Sent
    • rp_rcvd: Red Packet Received
    • rp_rej: Red Packet Rejected
    • ls_offered: Live Stream-Reward Offered
    • ls_rcvd: Live Stream- Reward Received
    • pt_offered: Posts- Reward Offered
    • pt_rcvd: Posts- Reward Received
    • subs_deduct: Subscription-Fees Deducted
    • subs_in: Subscription-Fees Received
    • subs_refund: Subscription- Refund
    • subs_in_rcvd: Subscription- Refunds Received

    # PUSH Trading

    • push_dctd: Push- Deduction
    • push_rcvd_dctd: Push- Received-Deducted
    • push_canceled: Push Canceled
    • push_rej: Push Rejected
    • push_sent: Push Sent
    • push_rcvd: Push Received

    # Copy Trading

    • quant_return: Quant- Transaction Returned
    • quant_cmn_in: Quant-Commission Transferred In
    • quant_cmn_out: Quant-Commission Transferred Out
    • quant_cmn_rtd: Quant-Commission Returned
    • fct_refund: Futures Copy Trading - Funds Auto Transfer Out
    • fct_rcvd: Futures Lead Trading - Performance Fee Received
    • fct_fee: Futures Copy Trading - Performance Fee Paid
    • fct_fee_refund: Futures Copy Trading - Performance Fee Refund

    # NFT

    • nft_mp: NFT Auction-Margin Paid
    • nft_bm: NFT Auction-Bid Made
    • nft_om: NFT Auction-Offer Made
    • ntf_mr: NFT Auction-Margin Returned
    • nft_amr: NFT Auction-Aborted-Margin rcvd
    • nft_ocb: NFT Auction-Order Canceled-Back
    • nft_fb: Fixed Price-Bought
    • nft_fs: Fixed Price-For Sale
    • nft_ob: NFT Make-Offer Bought
    • nft_os: NFT Make-Offer Sale
    • nft_cr: Cancel offer refund
    • nft_ir: Refund for invalid offer
    • nft_wf: Withdrawal service fee
    • nft_wfr: Withdrawal service fee
    • ntf_mf: Multi-copy creation service fee
    • ntf_mfr: Multi-copy creation service fee refund
    • ntf_royalty: Royalties
    • nft_cd: NFT Auction-Order Canceled-Deducted
    • nft_crd: NFT Auction-Order Canceled-Rotalty-Deducted
    • nft_cf: crowdfunding
    • nft_cfr: crowdfunding refund
    • nft_ammf: Nft-Amm Frozen
    • nft_ammw: Nft-Amm Withdraw
    • nft_ammdf: Nft-Amm Deal Fee
    • nft_ammd: Nft-Amm Deal

    # Error Handling

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

    The error response body follows a format like:

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

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

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

    import requests
    
    r = requests.get("https://api.gateio.ws/api/v4/futures/btc/contracts/BTC_USD")
    try:
        r.raise_for_status()
    except requests.HTTPError:
        # catch 2xx errors, parse error message in body, and do something based on `label`
        if r.json()['label'] == 'xxx':
            print(r.json())
    

    or with Python SDK (opens new window):

    import json
    from gate_api import FuturesApi
    from gate_api.rest import ApiException
    
    api = FuturesApi()
    try:
        api.get_futures_contract(settle='btc', contract="BTC_USD")
    except ApiException as e:  # ApiException wraps whole error information, see implementation for details
        detail = json.loads(e.value.body)
        if detail['label'] == 'xxx':
            print(detail)
    

    # label list

    • Request parameter or format related
    label Meaning
    INVALID_PARAM_VALUE Invalid parameter value
    INVALID_PROTOCOL Invalid parameter value
    INVALID_ARGUMENT Invalid argument
    INVALID_REQUEST_BODY Invalid request body
    MISSING_REQUIRED_PARAM Missing required parameter
    BAD_REQUEST Invalid request
    INVALID_CONTENT_TYPE Invalid Content-Type header
    NOT_ACCEPTABLE Invalid Accept- Header
    METHOD_NOT_ALLOWED Request method is not allowed
    NOT_FOUND Request URL not exists
    • Authentication related
    label Meaning
    INVALID_CREDENTIALS Invalid credentials provided
    INVALID_KEY Invalid API Key
    IP_FORBIDDEN Request IP not in whitelist
    READ_ONLY API key is read-only
    INVALID_SIGNATURE Invalid signature
    MISSING_REQUIRED_HEADER Missing required authentication header
    REQUEST_EXPIRED Request Timestamp is far from the server time
    ACCOUNT_LOCKED Account is locked
    FORBIDDEN Account has no permission to request operation
    • Wallet related
    label Meaning
    SUB_ACCOUNT_NOT_FOUND Sub account not found
    SUB_ACCOUNT_LOCKED Sub account is locked
    MARGIN_BALANCE_EXCEPTION Abnormal margin account
    MARGIN_TRANSFER_FAILED Failed to transfer with margin account
    TOO_MUCH_FUTURES_AVAILABLE Futures balance exceeds max allowed
    FUTURES_BALANCE_NOT_ENOUGH Futures balance not enough
    ACCOUNT_EXCEPTION Abnormal account
    SUB_ACCOUNT_TRANSFER_FAILED Failed to transfer with sub account
    ADDRESS_NOT_USED Address never being used in web console
    TOO_FAST Withdrawing request exceeds frequency limit
    WITHDRAWAL_OVER_LIMIT Withdrawal limit exceeded
    API_WITHDRAW_DISABLED API withdrawal operation is disabled temporarily
    INVALID_WITHDRAW_ID Invalid withdraw ID
    INVALID_WITHDRAW_CANCEL_STATUS Cancelling withdrawal not allowed with current status
    DUPLICATE_REQUEST Duplicate request
    ORDER_EXISTS Order already exists, do not resubmit
    INVALID_CLIENT_ORDER_ID The client_order_id is invalid
    • Spot and margin trading related
    label Meaning
    INVALID_PRECISION Invalid precision
    INVALID_CURRENCY Invalid currency
    INVALID_CURRENCY_PAIR Invalid currency pair
    POC_FILL_IMMEDIATELY Order would match and take immediately so it's cancelled
    ORDER_NOT_FOUND Order not found
    ORDER_CLOSED Order already closed
    ORDER_CANCELLED Order already cancelled
    QUANTITY_NOT_ENOUGH Amount is not enough
    BALANCE_NOT_ENOUGH Balance is not enough
    MARGIN_NOT_SUPPORTED Request currency pair doesn't provide margin trading
    MARGIN_BALANCE_NOT_ENOUGH Margin balance is not enough
    AMOUNT_TOO_LITTLE Amount does not reach minimum required
    AMOUNT_TOO_MUCH Amount exceeds maximum allowed
    REPEATED_CREATION Repeated creation
    LOAN_NOT_FOUND Margin loan is not found
    LOAN_RECORD_NOT_FOUND Margin loan record is not found
    NO_MATCHED_LOAN No loan can match request borrow requirement
    NOT_MERGEABLE Request loans cannot be merged
    NO_CHANGE No change is made
    REPAY_TOO_MUCH Repay more than required
    TOO_MANY_CURRENCY_PAIRS Too many currency pairs in batch orders creation
    TOO_MANY_ORDERS Too many orders in one currency pair in batch orders creation
    MIXED_ACCOUNT_TYPE More than one account type is used in batch orders creation
    AUTO_BORROW_TOO_MUCH Auto borrow exceeds maximum allowed
    TRADE_RESTRICTED Trading is restricted due to high debt ratio
    FOK_NOT_FILL FOK order cannot be filled completely
    INITIAL_MARGIN_TOO_LOW User's total initial margin rate is too low
    NO_MERGEABLE_ORDERS Orders can be merged not found
    ORDER_BOOK_NOT_FOUND Insufficient liquidity
    FAILED_RETRIEVE_ASSETS Failed to retrieve account assets
    • Futures related
    label Meaning
    USER_NOT_FOUND User has no futures account
    CONTRACT_NO_COUNTER No counter order found
    CONTRACT_NOT_FOUND Contract not found
    RISK_LIMIT_EXCEEDED Risk limit exceeded
    INSUFFICIENT_AVAILABLE Balance is not enough
    LIQUIDATE_IMMEDIATELY Operation may cause liquidation
    LEVERAGE_TOO_HIGH leverage too high
    LEVERAGE_TOO_LOW leverage too low
    ORDER_NOT_FOUND Order not found
    ORDER_NOT_OWNED Order not owned
    ORDER_FINISHED Order already finished
    TOO_MANY_ORDERS Too many open orders
    POSITION_CROSS_MARGIN margin updating is not allowed in cross margin
    POSITION_IN_LIQUIDATION Position is being liquidated
    POSITION_IN_CLOSE Position is closing
    POSITION_EMPTY Position is empty
    REMOVE_TOO_MUCH Changed margin exceeds allowed
    RISK_LIMIT_NOT_MULTIPLE Risk limit is not a multiple of step
    RISK_LIMIT_TOO_HIGH Risk limit too high
    RISK_LIMIT_TOO_lOW Risk limit too low
    PRICE_TOO_DEVIATED Order price deviates too much from mark price
    SIZE_TOO_LARGE Order size exceeds maximum
    SIZE_TOO_SMALL Order size does not reach minimum
    PRICE_OVER_LIQUIDATION Price to increase position can not exceeds liquidation price
    PRICE_OVER_BANKRUPT Price to decrease position cannot exceeds bankrupting price
    ORDER_POC_IMMEDIATE POC order will be finished immediately
    INCREASE_POSITION POC order will increase position
    CONTRACT_IN_DELISTING Contract is delisting, only reduce-only order or close order is allowed
    POSITION_NOT_FOUND Position not found
    POSITION_DUAL_MODE Operation forbidden in dual-mode
    ORDER_PENDING Operation forbidden with pending orders
    POSITION_HOLDING Operation forbidden with holding position
    REDUCE_EXCEEDED Reduce order would exceed position in dual-mode
    NO_CHANGE No change is made
    AMEND_WITH_STOP Amend forbidden with stop order
    ORDER_FOK Killed for FOK
    • Collateral Loan related
    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
    • Portfolio related
    label Meaning
    USER_LIAB User has liab
    USER_PENDING_ORDERS User has pending orders
    MODE_SET already set portfolio_margin mode
    • Earn related
    label 含义
    ERR_BALANCE_NOT_ENOUGH balance not enough
    ERR_PRODUCT_SELL_OUT Target quota reached
    ERR_PRODUCT_BUY The project is not yet open for purchase
    ERR_CREATE_ORDER Put order fail
    ERR_QUOTA_LOWER_LIMIT Not meeting the minimum order amount
    ERR_QUOTA_SUPERIOR_LIMIT The maximum order limit has been reached
    ERR_ORDER_NUMBER_LIMIT The maximum order quantity has been reached
    ERR_PRODUCT_CLOSE Project closed
    COPIES_NOT_ENOUGH Not enough shares available to subscribe
    COPIES_TOO_SMALL Investment share is too small
    COPIES_TOO_BIG The number of investment shares exceeds the upper limit
    TOTAL_AMOUNT_24 The total amount of pledge and redemption within 24 hours exceeds the limit
    TOTAL_BUYCOUNT_24 Pledge and redemption times exceeding the limit within 24 hours
    REDEEM_24_LIMIT Redemption are allowed 24 hours after the last staking
    • Server errors
    label Meaning
    INTERNAL Internal server error
    SERVER_ERROR Internal server error
    TOO_BUSY Server is too busy at the moment

    # Authentication

    # Generate API key

    Before calling the private API interface, the API key of the account needs to be generated to verify the identity. You can log in on the website and generate it in [account management] - > [APIv4 keys], or click here to generate API keys.

    Each account can create 20 API keys, and the permission configuration of each key is independent of each other. It is recommended to set a note name for each key to indicate its purpose.

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

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

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

    TIP

    Note: If the key is named with spot or futures, then it could be the default name after APIv4 migration. For details refer to About APIv4 key improvement section

    Created key can also be updated or deleted, but any modification(s) can take up to 5 minutes to take effect.

    Please note that futures TestNet trading is a separate environment from futures real trading. Real trading API keys cannot be used in TestNet. If you want to test futures API with TestNet, you need to log into the console to generate TestNet API keys(in "Futures TestNet APIKeys" tab on " APIv4Keys" page). Making futures requests are identical between real and TestNet trading, with the only exceptions are different base URLs and different API keys.

    # APIv4 Permissions

    When creating a Key, you can configure whether to enable spot, margin, contract, wallet, or withdrawal permissions for the Key, and whether to enable read-write or read-only permissions.

    Products Permissions
    spot/margin Read-only query orders Read-write query orders & place orders
    perpetual contract Read-only query orders Read-write query orders & place orders
    delivery contract Read-only query orders Read-write query orders & place orders
    wallet Read-only Query for withdrawal transfer records Read-write Query for account records & fund transfers
    withdrawal Read-only Query cash withdrawal records Read-write Query cash withdrawal records & withdrawals

    All GET operations are read requests, while others are write requests. Each permission group can be set to disabled, read-only or read-write.

    Please note that even though withdrawal API has only one operation(i.e. POST /withdrawals), for general concern, it is still separated from wallet API into a standalone permission group, while withdrawal history retrieving API stays inside wallet operations( i.e., GET /wallet/withdrawals).

    # APIv4 signed request requirements

    1. Generate APIv4 Key pairs in web console, and make sure it has the right permissions.
    2. Set request header KEY to the key.
    3. Set request header Timestamp to current time formatted in Unix time in seconds. Pay attention that the gap between its value and current time cannot exceed 60 seconds.
    4. Set request header SIGN to encrypted request signature. Refer to next section for how signature string is generated. Signature generation method is HexEncode(HMAC_SHA512(secret, signature_string)), i.e., the hexadecimal digest output of HMAC-SHA512 with APIv4 secret as secret and signature string as message,
    5. Make sure request client's IP is in your APIv4 Key's IP whitelist.

    # API Signature string generation

    In APIv4, signature string is concatenated as the following way:

    Request Method + "\n" + Request URL + "\n" + Query String + "\n" + HexEncode(SHA512(Request Payload)) + "\n" + Timestamp

    # Request Method

    Request method in UPPERCASE, e.g. POST, GET

    # Request URL

    Request url. Protocol, host and port are not included, e.g. /api/v4/futures/orders

    # Query String

    Request query string without URL encode. query parameters order should be the same as how they are concatenated in the request URL, e.g. status=finished&limit=50. Use empty string("") if no query parameters.

    # HexEncode(SHA512(Request Payload))

    Hash the request body with SHA512 and output its Hex encoded form. If no request body, use empty string's hashed result, i.e. cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e

    # Timestamp

    Timestamp request header value.

    Examples

    Note: all example signature string are broken into multiple lines for displaying purpose only. Only the \n character in signature string is reserved in reality.

    Suppose the key we used is key, while the secret is secret.

    1. List all orders
    	GET /api/v4/futures/orders?contract=BTC_USD&status=finished&limit=50 HTTP/1.1
    

    Signature string:

    	GET\n
    	/api/v4/futures/orders\n
    	contract=BTC_USD&status=finished&limit=50\n
    	cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e\n
    	1541993715
    

    Explanation:

    • /api/v4/futures/orders: request url
    • contract=BTC_USD&status=finished&limit=50: keep the query string as it is in the request url
    • request body use empty string's hashed result
    • 1541993715: Unix timestamp in seconds

    Signature generated

    55f84ea195d6fe57ce62464daaa7c3c02fa9d1dde954e4c898289c9a2407a3d6fb3faf24deff16790d726b66ac9f74526668b13bd01029199cc4fcc522418b8a

    1. Create an order
    	POST /api/v4/futures/orders HTTP/1.1
    
    	{"contract":"BTC_USD","type":"limit","size":100,"price":6800,"time_in_force":"gtc"}
    

    Signature string:

    	POST\n
    	/api/v4/futures/orders\n
    	\n
    	ad3c169203dc3026558f01b4df307641fa1fa361f086b2306658886d5708767b1854797c68d9e62fef2f991645aa82673622ebf417e091d0bd22bafe5d956cca\n
    	1541993715
    

    Explanation:

    • request query string is empty, use plain empty string
    • use the hashed result of the json-string-formatted request body

    Signature generated

    eae42da914a590ddf727473aff25fc87d50b64783941061f47a3fdb92742541fc4c2c14017581b4199a1418d54471c269c03a38d788d802e2c306c37636389f0

    
    # example authentication implementation in Python
    
    """
    Python SDK is recommended as it has already implemented the authentication process for every API:
    """
    
    import time
    import hashlib
    import hmac
    import requests
    import json
    
    def gen_sign(method, url, query_string=None, payload_string=None):
        key = ''        # api_key
        secret = ''     # api_secret
    
        t = time.time()
        m = hashlib.sha512()
        m.update((payload_string or "").encode('utf-8'))
        hashed_payload = m.hexdigest()
        s = '%s\n%s\n%s\n%s\n%s' % (method, url, query_string or "", hashed_payload, t)
        sign = hmac.new(secret.encode('utf-8'), s.encode('utf-8'), hashlib.sha512).hexdigest()
        return {'KEY': key, 'Timestamp': str(t), 'SIGN': sign}
    
    if __name__ == "__main__":
        host = "https://api.gateio.ws"
        prefix = "/api/v4"
        common_headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
        url = '/futures/orders'
        body = {"contract": "BTC_USD", "size": 100, "price": "30", "tif": "gtc"}
        request_content = json.dumps(body)
        sign_headers = gen_sign('POST', prefix + url, "", request_content)
        sign_headers.update(common_headers)
        print('signature headers: %s' % sign_headers)
        res = requests.post(host + prefix + url, headers=sign_headers, data=request_content)
        print(res.status_code)
        print(res.content)
    

    # FAQ

    • How to retrieve POST /wallet/transfers history?

      Records of transfers generated through POST /wallet/transfers has multiple methods to be retrieved based on account, including:

      • GET /margin/account_book to retrieve transferals from or to margin account.
      • GET /futures/{settle}/account_book?type=dnw to retrieve perpetual contract account history
      • GET /delivery/{settle}/account_book?type=dnw to retrieve delivery contract account history
    • How to create margin orders?

      Margin order creation has been merged into spot order APIs. In POST /spot/orders or POST /spot/batch_orders, set account to margin to create margin orders.

    • Futures operation returns error USER_NOT_FOUND

      Futures account is not initialized yet. Making a deposit to your futures account will help. Note that each settle currency is associated with an independent futures account.

    • Futures operation returns error CONTRACT_NOT_FOUND

      Every settle currency has its own contract list. Make sure the contract you specified is supported by the settle currency. You can query the list with

      GET /futures/{settle}/contracts or GET /delivery/{settle}/contracts

    • Difference between sub account and main account

      • Sub account API Key cannot operate transferals between main and sub account, i.e., POST /wallet/sub_account_transfers
      • Sub account API Key cannot operate withdrawal, i.e., POST /withdrawals
      • If sub account does not have some business permission, even if its API key has the permission, the operations will be rejected too.
    • I have other question(s) not covered above

      Contact support for the issue. If the problem is related to one of the SDKs, you can also open an issue in the corresponding GitHub repository.

      When submitting an issue, please include the following information to help identify the problem:

      • User ID
        • Original request URL, request parameters and request body
        • What API key was used and where was it used, TestNet or real trading(API secret is not needed)
        • Programming language. Providing a code snippet will be better
        • Whether SDK was used. If so, which method caused the problem

    # Withdrawal

    Withdrawal operations

    # Withdraw

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/withdrawals'
    query_param = ''
    body='{"withdraw_order_id":"order_123456","currency":"USDT","address":"1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs","amount":"222.61","memo":"","chain":"TRX"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/withdrawals"
    query_param=""
    body_param='{"withdraw_order_id":"order_123456","currency":"USDT","address":"1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs","amount":"222.61","memo":"","chain":"TRX"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /withdrawals

    Withdraw

    Body parameter

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

    Parameters

    Name In Type Required Description
    body body object true none
    » withdraw_order_id body string false Client order id, up to 32 length and can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
    » amount body string true Currency amount
    » currency body string true Currency name
    » address body string false Withdrawal address. Required for withdrawals
    » memo body string false Additional remarks with regards to the withdrawal
    » chain body string true Name of the chain used in withdrawals

    Example responses

    202 Response

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

    Responses

    Status Meaning Description Schema
    202 Accepted (opens new window) Withdraw request is accepted. Refer to withdrawal records for status Inline

    Response Schema

    Status Code 202

    Name Type Description
    » id string Record ID
    » txid string Hash record of the withdrawal
    » withdraw_order_id string Client order id, up to 32 length and can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
    » timestamp string Operation time
    » amount string Currency amount
    » currency string Currency name
    » address string Withdrawal address. Required for withdrawals
    » memo string Additional remarks with regards to the withdrawal
    » status string Record status.

    - DONE: done
    - CANCEL: cancelled
    - REQUEST: requesting
    - MANUAL: pending manual approval
    - BCODE: GateCode operation
    - EXTPEND: pending confirm after sending
    - FAIL: pending confirm when fail
    - INVALID: invalid order
    - VERIFY: verifying
    - PROCES: processing
    - PEND: pending
    - DMOVE: required manual approval
    - SPLITPEND: the order is automatically split due to large amount
    » chain string Name of the chain used in withdrawals

    # Enumerated Values

    Property Value
    status DONE
    status CANCEL
    status REQUEST
    status MANUAL
    status BCODE
    status EXTPEND
    status FAIL
    status INVALID
    status VERIFY
    status PROCES
    status PEND
    status DMOVE
    status SPLITPEND

    WARNING

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

    # Cancel withdrawal with specified ID

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/withdrawals/210496'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/withdrawals/210496"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    DELETE /withdrawals/{withdrawal_id}

    Cancel withdrawal with specified ID

    Parameters

    Name In Type Required Description
    withdrawal_id path string true none

    Example responses

    202 Response

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

    Responses

    Status Meaning Description Schema
    202 Accepted (opens new window) Cancellation accepted. Refer to record status for the cancellation result Inline

    Response Schema

    Status Code 202

    Name Type Description
    » id string Record ID
    » txid string Hash record of the withdrawal
    » withdraw_order_id string Client order id, up to 32 length and can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
    » timestamp string Operation time
    » amount string Currency amount
    » currency string Currency name
    » address string Withdrawal address. Required for withdrawals
    » memo string Additional remarks with regards to the withdrawal
    » status string Record status.

    - DONE: done
    - CANCEL: cancelled
    - REQUEST: requesting
    - MANUAL: pending manual approval
    - BCODE: GateCode operation
    - EXTPEND: pending confirm after sending
    - FAIL: pending confirm when fail
    - INVALID: invalid order
    - VERIFY: verifying
    - PROCES: processing
    - PEND: pending
    - DMOVE: required manual approval
    - SPLITPEND: the order is automatically split due to large amount
    » chain string Name of the chain used in withdrawals

    # Enumerated Values

    Property Value
    status DONE
    status CANCEL
    status REQUEST
    status MANUAL
    status BCODE
    status EXTPEND
    status FAIL
    status INVALID
    status VERIFY
    status PROCES
    status PEND
    status DMOVE
    status SPLITPEND

    WARNING

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

    # Wallet

    Wallet

    # List chains supported for specified currency

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/currency_chains'
    query_param = 'currency=GT'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/wallet/currency_chains?currency=GT \
      -H 'Accept: application/json'
    
    

    GET /wallet/currency_chains

    List chains supported for specified currency

    Parameters

    Name In Type Required Description
    currency query string true Currency name

    Example responses

    200 Response

    [
      {
        "chain": "ETH",
        "name_cn": "以太坊ERC20",
        "name_en": "ETH/ERC20",
        "is_disabled": 0,
        "is_deposit_disabled": 0,
        "is_withdraw_disabled": 0
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » chain string Chain name
    » name_cn string Chain name in Chinese
    » name_en string Chain name in English
    » 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

    # Generate currency deposit address

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/deposit_address'
    query_param = 'currency=USDT'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/wallet/deposit_address"
    query_param="currency=USDT"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /wallet/deposit_address

    Generate currency deposit address

    Parameters

    Name In Type Required Description
    currency query string true Currency name

    Example responses

    200 Response

    {
      "currency": "USDT",
      "address": "LPXtk1kWHioP62SzfqwKbYE3Z7Wt2ujYEc",
      "multichain_addresses": [
        {
          "chain": "TRX",
          "address": "LPXtk1kWHioP62SzfqwKbYE3Z7Wt2ujYEc",
          "payment_id": "",
          "payment_name": "",
          "obtain_failed": 0
        }
      ]
    }
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) Address successfully generated Inline

    Response Schema

    Status Code 200

    Name Type Description
    » currency string Currency detail
    » address string Deposit address
    » multichain_addresses array none
    »» MultiChainAddressItem object none
    »»» chain string Name of the chain
    »»» address string Deposit address
    »»» payment_id string Notes that some currencies required(e.g., Tag, Memo) when depositing
    »»» payment_name string Note type, Tag or Memo
    »»» obtain_failed integer The obtain failed status- 0: address successfully obtained- 1: failed to obtain address

    WARNING

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

    # Retrieve withdrawal records

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/withdrawals'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/wallet/withdrawals"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /wallet/withdrawals

    Retrieve withdrawal records

    Record time range cannot exceed 30 days

    Parameters

    Name In Type Required Description
    currency query string false Filter by currency. Return all currency records if not specified
    from query integer(int64) false Time range beginning, default to 7 days before current time
    to query integer(int64) false Time range ending, default to current time
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0

    Example responses

    200 Response

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

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » 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
    » fee string fee
    » currency string Currency name
    » address string Withdrawal address. Required for withdrawals
    » memo string Additional remarks with regards to the withdrawal
    » status string Record status.

    - DONE: done
    - CANCEL: cancelled
    - REQUEST: requesting
    - MANUAL: pending manual approval
    - BCODE: GateCode operation
    - EXTPEND: pending confirm after sending
    - FAIL: pending confirm when fail
    - INVALID: invalid order
    - VERIFY: verifying
    - PROCES: processing
    - PEND: pending
    - DMOVE: required manual approval
    - SPLITPEND: the order is automatically split due to large amount
    » chain string Name of the chain used in withdrawals

    # Enumerated Values

    Property Value
    status DONE
    status CANCEL
    status REQUEST
    status MANUAL
    status BCODE
    status EXTPEND
    status FAIL
    status INVALID
    status VERIFY
    status PROCES
    status PEND
    status DMOVE
    status SPLITPEND

    WARNING

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

    # Retrieve deposit records

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/deposits'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/wallet/deposits"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /wallet/deposits

    Retrieve deposit records

    Record time range cannot exceed 30 days

    Parameters

    Name In Type Required Description
    currency query string false Filter by currency. Return all currency records if not specified
    from query integer(int64) false Time range beginning, default to 7 days before current time
    to query integer(int64) false Time range ending, default to current time
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0

    Example responses

    200 Response

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

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » id string Record ID
    » txid string Hash record of the withdrawal
    » withdraw_order_id string Client order id, up to 32 length and can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
    » timestamp string Operation time
    » amount string Currency amount
    » currency string Currency name
    » address string Withdrawal address. Required for withdrawals
    » memo string Additional remarks with regards to the withdrawal
    » status string Record status.

    - DONE: done
    - CANCEL: cancelled
    - REQUEST: requesting
    - MANUAL: pending manual approval
    - BCODE: GateCode operation
    - EXTPEND: pending confirm after sending
    - FAIL: pending confirm when fail
    - INVALID: invalid order
    - VERIFY: verifying
    - PROCES: processing
    - PEND: pending
    - DMOVE: required manual approval
    - SPLITPEND: the order is automatically split due to large amount
    » chain string Name of the chain used in withdrawals

    # Enumerated Values

    Property Value
    status DONE
    status CANCEL
    status REQUEST
    status MANUAL
    status BCODE
    status EXTPEND
    status FAIL
    status INVALID
    status VERIFY
    status PROCES
    status PEND
    status DMOVE
    status SPLITPEND

    WARNING

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

    # Transfer between trading accounts

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/transfers'
    query_param = ''
    body='{"currency":"BTC","from":"spot","to":"margin","amount":"1","currency_pair":"BTC_USDT"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/wallet/transfers"
    query_param=""
    body_param='{"currency":"BTC","from":"spot","to":"margin","amount":"1","currency_pair":"BTC_USDT"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /wallet/transfers

    Transfer between trading accounts

    Transfer between different accounts. Currently support transfers between the following:

    1. spot - margin
    2. spot - futures(perpetual)
    3. spot - delivery
    4. spot - cross margin
    5. spot - options

    Body parameter

    {
      "currency": "BTC",
      "from": "spot",
      "to": "margin",
      "amount": "1",
      "currency_pair": "BTC_USDT"
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » currency body string true Transfer currency. For futures account, currency can be set to POINT or settle currency
    » from body string true Account to transfer from
    » to body string true Account to transfer to
    » amount body string true Transfer amount
    » currency_pair body string false Margin currency pair. Required if transfer from or to margin account
    » settle body string false Futures settle currency. Required if transferring from or to futures account

    # Enumerated Values

    Parameter Value
    » from spot
    » from margin
    » from futures
    » from delivery
    » from cross_margin
    » from options
    » to spot
    » to margin
    » to futures
    » to delivery
    » to cross_margin
    » to options

    Example responses

    200 Response

    {
      "tx_id": 59636381286
    }
    

    Responses

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

    Response Schema

    Status Code 200

    TransactionID

    Name Type Description
    » tx_id integer(int64) Order id

    WARNING

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

    # Transfer between main and sub accounts

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/sub_account_transfers'
    query_param = ''
    body='{"client_order_id":"da3ce7a088c8b0372b741419c7829033","currency":"BTC","sub_account":"10002","direction":"to","amount":"1","sub_account_type":"spot"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/wallet/sub_account_transfers"
    query_param=""
    body_param='{"client_order_id":"da3ce7a088c8b0372b741419c7829033","currency":"BTC","sub_account":"10002","direction":"to","amount":"1","sub_account_type":"spot"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /wallet/sub_account_transfers

    Transfer between main and sub accounts

    Support transferring with sub user's spot or futures account. Note that only main user's spot account is used no matter which sub user's account is operated.

    Body parameter

    {
      "client_order_id": "da3ce7a088c8b0372b741419c7829033",
      "currency": "BTC",
      "sub_account": "10002",
      "direction": "to",
      "amount": "1",
      "sub_account_type": "spot"
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » currency body string true Transfer currency name
    » sub_account body string true Sub account user ID
    » direction body string true Transfer direction. to - transfer into sub account; from - transfer out from sub account
    » amount body string true Transfer amount
    » client_order_id body string false The custom ID provided by the customer serves as a safeguard against duplicate transfers. It can be a combination of letters (case-sensitive), numbers, hyphens '-', and underscores '_', with a length ranging from 1 to 64 characters.
    » sub_account_type body string false Target sub user's account. spot - spot account, futures - perpetual contract account, cross_margin - cross margin account, delivery - delivery account

    Responses

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

    WARNING

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

    # Retrieve transfer records between main and sub accounts

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/sub_account_transfers'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/wallet/sub_account_transfers"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /wallet/sub_account_transfers

    Retrieve transfer records between main and sub accounts

    Record time range cannot exceed 30 days

    Note: only records after 2020-04-10 can be retrieved

    Parameters

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

    Example responses

    200 Response

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

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » currency string Transfer currency name
    » sub_account string Sub account user ID
    » direction string Transfer direction. to - transfer into sub account; from - transfer out from sub account
    » amount string Transfer amount
    » uid string Main account user ID
    » client_order_id string The custom ID provided by the customer serves as a safeguard against duplicate transfers. It can be a combination of letters (case-sensitive), numbers, hyphens '-', and underscores '_', with a length ranging from 1 to 64 characters.
    » timest string Transfer timestamp
    » source string Where the operation is initiated from
    » sub_account_type string Target sub user's account. spot - spot account, futures - perpetual contract account, cross_margin - cross margin account, delivery - delivery account

    WARNING

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

    # Sub-account transfers to sub-account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/sub_account_to_sub_account'
    query_param = ''
    body='{"currency":"usdt","sub_account_from":"10001","sub_account_from_type":"spot","sub_account_to":"10002","sub_account_to_type":"spot","amount":"1"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/wallet/sub_account_to_sub_account"
    query_param=""
    body_param='{"currency":"usdt","sub_account_from":"10001","sub_account_from_type":"spot","sub_account_to":"10002","sub_account_to_type":"spot","amount":"1"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /wallet/sub_account_to_sub_account

    Sub-account transfers to sub-account

    It is possible to perform balance transfers between two sub-accounts under the same main account. You can use either the API Key of the main account or the API Key of the sub-account to initiate the transfer.

    Body parameter

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

    Parameters

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

    Responses

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

    WARNING

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

    # Retrieve withdrawal status

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/withdraw_status'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/wallet/withdraw_status"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /wallet/withdraw_status

    Retrieve withdrawal status

    Parameters

    Name In Type Required Description
    currency query string false Retrieve data of the specified currency

    Example responses

    200 Response

    [
      {
        "currency": "GT",
        "name": "GateToken",
        "name_cn": "GateToken",
        "deposit": "0",
        "withdraw_percent": "0%",
        "withdraw_fix": "0.01",
        "withdraw_day_limit": "20000",
        "withdraw_day_limit_remain": "20000",
        "withdraw_amount_mini": "0.11",
        "withdraw_eachtime_limit": "20000",
        "withdraw_fix_on_chains": {
          "BTC": "20",
          "ETH": "15",
          "TRX": "0",
          "EOS": "2.5"
        },
        "withdraw_percent_on_chains": {
          "ETH": "0%",
          "GTEVM": "0%"
        }
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » currency string Currency
    » 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

    # Retrieve sub account balances

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/sub_account_balances'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/wallet/sub_account_balances"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /wallet/sub_account_balances

    Retrieve sub account balances

    Parameters

    Name In Type Required Description
    sub_uid query string false User ID of sub-account, you can query multiple records separated by ,. If not specified, it will return the records of all sub accounts

    Example responses

    200 Response

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

    Responses

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

    Response Schema

    Status Code 200

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

    WARNING

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

    # Query sub accounts' margin balances

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/sub_account_margin_balances'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/wallet/sub_account_margin_balances"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /wallet/sub_account_margin_balances

    Query sub accounts' margin balances

    Parameters

    Name In Type Required Description
    sub_uid query string false User ID of sub-account, you can query multiple records separated by ,. If not specified, it will return the records of all sub accounts

    Example responses

    200 Response

    [
      {
        "uid": "10000",
        "available": [
          {
            "locked": false,
            "currency_pair": "BTC_USDT",
            "risk": "9999.99",
            "base": {
              "available": "0.1",
              "borrowed": "0",
              "interest": "0",
              "currency": "BTC",
              "locked": "0"
            },
            "quote": {
              "available": "0",
              "borrowed": "0",
              "interest": "0",
              "currency": "USDT",
              "locked": "0"
            }
          }
        ]
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » uid string User ID
    » available array Margin account balances
    »» None object Margin account detail. base refers to base currency, while `quotes to quote currency
    »»» currency_pair string Currency pair
    »»» locked boolean Whether account is locked
    »»» risk string Current risk rate of margin account
    »»» base object Account currency details
    »»»» currency string Currency name
    »»»» available string Amount suitable for margin trading.
    »»»» locked string Locked amount, used in margin trading
    »»»» borrowed string Borrowed amount
    »»»» interest string Unpaid interests
    »»» quote object Account currency details
    »»»» currency string Currency name
    »»»» available string Amount suitable for margin trading.
    »»»» locked string Locked amount, used in margin trading
    »»»» borrowed string Borrowed amount
    »»»» interest string Unpaid interests

    WARNING

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

    # Query sub accounts' futures account balances

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/sub_account_futures_balances'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/wallet/sub_account_futures_balances"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /wallet/sub_account_futures_balances

    Query sub accounts' futures account balances

    Parameters

    Name In Type Required Description
    sub_uid query string false User ID of sub-account, you can query multiple records separated by ,. If not specified, it will return the records of all sub accounts
    settle query string false Query only balances of specified settle currency

    Example responses

    200 Response

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

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » uid string User ID
    » available object Futures account balances
    »» additionalProperties object none
    »»» total string total is the balance after the user's accumulated deposit, withdraw, profit and loss (including realized profit and loss, fund, fee and referral rebate), excluding unrealized profit and loss.
    total = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund)
    »»» unrealised_pnl string Unrealized PNL
    »»» position_margin string Position margin
    »»» order_margin string Order margin of unfinished orders
    »»» available string The available balance for transferring or trading(including bonus. Bonus can't be be withdrawn. The transfer amount needs to deduct the bonus)
    »»» point string POINT amount
    »»» currency string Settle currency
    »»» in_dual_mode boolean Whether dual mode is enabled
    »»» enable_credit boolean Whether portfolio margin account mode is enabled
    »»» position_initial_margin string Initial margin position, applicable to the portfolio margin account model
    »»» maintenance_margin string Maintenance margin position, applicable to the portfolio margin account model
    »»» bonus string Perpetual Contract Bonus
    »»» history object Statistical data
    »»»» dnw string total amount of deposit and withdraw
    »»»» pnl string total amount of trading profit and loss
    »»»» fee string total amount of fee
    »»»» refr string total amount of referrer rebates
    »»»» fund string total amount of funding costs
    »»»» point_dnw string total amount of point deposit and withdraw
    »»»» point_fee string total amount of point fee
    »»»» point_refr string total amount of referrer rebates of point fee
    »»»» bonus_dnw string total amount of perpetual contract bonus transfer
    »»»» bonus_offset string total amount of perpetual contract bonus deduction

    WARNING

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

    # Query subaccount's cross_margin account info

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/sub_account_cross_margin_balances'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/wallet/sub_account_cross_margin_balances"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /wallet/sub_account_cross_margin_balances

    Query subaccount's cross_margin account info

    Parameters

    Name In Type Required Description
    sub_uid query string false User ID of sub-account, you can query multiple records separated by ,. If not specified, it will return the records of all sub accounts

    Example responses

    200 Response

    [
      {
        "uid": "100000",
        "available": {
          "user_id": 100003,
          "locked": false,
          "total": "20.000000",
          "borrowed": "0.000000",
          "interest": "0",
          "borrowed_net": "0",
          "net": "20",
          "leverage": "3",
          "risk": "9999.99",
          "total_initial_margin": "0.00",
          "total_margin_balance": "20.00",
          "total_maintenance_margin": "0.00",
          "total_initial_margin_rate": "9999.9900",
          "total_maintenance_margin_rate": "9999.9900",
          "total_available_margin": "20.00",
          "balances": {
            "USDT": {
              "available": "20.000000",
              "freeze": "0.000000",
              "borrowed": "0.000000",
              "interest": "0.000000"
            }
          }
        }
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » uid string User ID
    » available object none
    »» user_id integer(int64) User ID of the cross margin account. 0 means that the subaccount has not yet opened a cross margin account
    »» locked boolean Whether account is locked
    »» balances object none
    »»» CrossMarginBalance object none
    »»»» available string Available amount
    »»»» freeze string Locked amount
    »»»» borrowed string Borrowed amount
    »»»» interest string Unpaid interests
    »»» total string Total account value in USDT, i.e., the sum of all currencies' (available+freeze)*price*discount
    »»» borrowed string Total borrowed value in USDT, i.e., the sum of all currencies' borrowed*price*discount
    »»» borrowed_net string Total borrowed value in USDT * borrowed factor
    »»» net string Total net assets in USDT
    »»» leverage string Position leverage
    »»» interest string Total unpaid interests in USDT, i.e., the sum of all currencies' interest*price*discount
    »»» risk string Risk rate. When it belows 110%, liquidation will be triggered. Calculation formula: total / (borrowed+interest)
    »»» total_initial_margin string Total initial margin
    »»» total_margin_balance string Total margin balance
    »»» total_maintenance_margin string Total maintenance margin
    »»» total_initial_margin_rate string Total initial margin rate
    »»» total_maintenance_margin_rate string Total maintenance margin rate
    »»» total_available_margin string Total available margin

    WARNING

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

    # Query saved address

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/saved_address'
    query_param = 'currency=USDT'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/wallet/saved_address"
    query_param="currency=USDT"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /wallet/saved_address

    Query saved address

    Parameters

    Name In Type Required Description
    currency query string true Currency
    chain query string false Chain name
    limit query string false Maximum number returned, 100 at most

    Example responses

    200 Response

    [
      {
        "currency": "usdt",
        "chain": "TRX",
        "address": "TWYirLzw2RARB2jfeFcfRPmeuU3rC7rakT",
        "name": "gate",
        "tag": "",
        "verified": "1"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » currency string Currency
    » chain string Chain name
    » address string Address
    » name string Name
    » tag string Tag
    » verified string Whether to pass the verification 0-unverified, 1-verified

    WARNING

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

    # Retrieve personal trading fee

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/fee'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/wallet/fee"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /wallet/fee

    Retrieve personal trading fee

    Parameters

    Name In Type Required Description
    currency_pair query string false Specify a currency pair to retrieve precise fee rate
    settle query string false Specify the settlement currency of the contract to get more accurate rate settings

    # Detailed descriptions

    currency_pair: Specify a currency pair to retrieve precise fee rate

    This field is optional. In most cases, the fee rate is identical among all currency pairs

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

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

    # Enumerated Values

    Parameter Value
    settle BTC
    settle USDT
    settle USD

    Example responses

    200 Response

    {
      "user_id": 10001,
      "taker_fee": "0.002",
      "maker_fee": "0.002",
      "futures_taker_fee": "-0.00025",
      "futures_maker_fee": "0.00075",
      "gt_discount": false,
      "gt_taker_fee": "0",
      "gt_maker_fee": "0",
      "loan_fee": "0.18",
      "point_type": "1",
      "delivery_taker_fee": "0.00016",
      "delivery_maker_fee": "-0.00015",
      "debit_fee": 3
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » user_id integer(int64) User ID
    » taker_fee string taker fee rate
    » maker_fee string maker fee rate
    » gt_discount boolean If GT deduction is enabled
    » gt_taker_fee string Taker fee rate if using GT deduction. It will be 0 if GT deduction is disabled
    » gt_maker_fee string Maker fee rate if using GT deduction. It will be 0 if GT deduction is disabled
    » loan_fee string Loan fee rate of margin lending
    » point_type string Point type. 0 - Initial version. 1 - new version since 202009
    » futures_taker_fee string Futures trading taker fee
    » futures_maker_fee string Future trading maker fee
    » 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

    # Retrieve user's total balances

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/total_balance'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/wallet/total_balance"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /wallet/total_balance

    Retrieve user's total balances

    This endpoint returns an approximate sum of exchanged amount from all currencies to input currency for each account.The exchange rate and account balance could have been cached for at most 1 minute. It is not recommended to use its result for any trading calculation.

    For trading calculation, use the corresponding account query endpoint for each account type. For example:

    • GET /spot/accounts to query spot account balance
    • GET /margin/accounts to query margin account balance
    • GET /futures/{settle}/accounts to query futures account balance

    Parameters

    Name In Type Required Description
    currency query string false Currency unit used to calculate the balance amount. BTC, CNY, USD and USDT are allowed. USDT is the default.

    Example responses

    200 Response

    {
      "details": {
        "cross_margin": {
          "amount": "0",
          "currency": "USDT"
        },
        "spot": {
          "currency": "USDT",
          "amount": "42264489969935775.5160259954878034182418"
        },
        "finance": {
          "amount": "662714381.70310327810191647181",
          "currency": "USDT"
        },
        "margin": {
          "amount": "1259175.664137668554329559",
          "currency": "USDT",
          "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"
      }
    }
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) Request is valid and is successfully responded Inline

    Response Schema

    Status Code 200

    User's balance in all accounts

    Name Type Description
    » total object Total balances calculated with specified currency unit
    »» amount string Account total balance amount
    »» currency string Currency
    »» unrealised_pnl string Unrealised_pnl, this field will only appear in futures, options, delivery, and total accounts
    »» borrowed string Borrowed,this field will only appear in margin and cross_margin accounts
    » details object Total balances in different accounts

    - cross_margin: cross margin account
    - spot: spot account
    - finance: finance account
    - margin: margin account
    - quant: quant account
    - futures: futures account
    - delivery: delivery account
    - warrant: warrant account
    - cbbc: cbbc account
    »» additionalProperties object Total balances calculated with specified currency unit
    »»» amount string Account total balance amount
    »»» currency string Currency
    »»» unrealised_pnl string Unrealised_pnl, this field will only appear in futures, options, delivery, and total accounts
    »»» borrowed string Borrowed,this field will only appear in margin and cross_margin accounts

    # Enumerated Values

    Property Value
    currency BTC
    currency CNY
    currency USD
    currency USDT
    currency BTC
    currency CNY
    currency USD
    currency USDT

    WARNING

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

    # List small balance

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/small_balance'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/wallet/small_balance"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /wallet/small_balance

    List small balance

    Example responses

    200 Response

    [
      {
        "currency": "FLOKI",
        "available_balance": "182.29400000",
        "estimated_as_btc": "0.00000012",
        "convertible_to_gt": "0.001080"
      },
      {
        "currency": "MBLK",
        "available_balance": "0.91723337",
        "estimated_as_btc": "0.00000102",
        "convertible_to_gt": "0.009188"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Convert Small Balance

    Name Type Description
    » 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

    # Convert small balance

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/small_balance'
    query_param = ''
    body='{"currency":["FLOKI","MBLK"]}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/wallet/small_balance"
    query_param=""
    body_param='{"currency":["FLOKI","MBLK"]}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /wallet/small_balance

    Convert small balance

    Body parameter

    {
      "currency": [
        "FLOKI",
        "MBLK"
      ]
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » currency body array false Currency

    Responses

    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

    # List small balance history

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/wallet/small_balance_history'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/wallet/small_balance_history"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /wallet/small_balance_history

    List small balance history

    Parameters

    Name In Type Required Description
    currency query string false Currency
    page query integer(int32) false Page number
    limit query integer(int32) false Maximum response items. Default: 100, minimum: 1, Maximum: 100

    Example responses

    200 Response

    [
      {
        "id": "28583810",
        "create_time": 1706670777,
        "currency": "FLOKI",
        "amount": "182.29400000",
        "gt_amount": "0.001079"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Convert Small Balance

    Name Type Description
    » 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

    # SubAccount

    Sub-accounts management

    # Create a new sub-account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/sub_accounts'
    query_param = ''
    body='{"remark":"remark","login_name":"sub_account_for_trades"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/sub_accounts"
    query_param=""
    body_param='{"remark":"remark","login_name":"sub_account_for_trades"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /sub_accounts

    Create a new sub-account

    Body parameter

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

    Parameters

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

    Example responses

    201 Response

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

    Responses

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

    Response Schema

    Status Code 201

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

    WARNING

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

    # List sub-accounts

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/sub_accounts'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/sub_accounts"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /sub_accounts

    List sub-accounts

    Parameters

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

    # Detailed descriptions

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

    Example responses

    200 Response

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

    Responses

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

    Response Schema

    Status Code 200

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

    WARNING

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

    # Get the sub-account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/sub_accounts/0'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/sub_accounts/0"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /sub_accounts/{user_id}

    Get the sub-account

    Parameters

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

    Example responses

    200 Response

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

    Responses

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

    Response Schema

    Status Code 200

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

    WARNING

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

    # Create API Key of the sub-account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/sub_accounts/0/keys'
    query_param = ''
    body='{"mode":1,"name":"spot","perms":[{"read_only":false,"name":"options"},{"read_only":false,"name":"spot"},{"read_only":false,"name":"delivery"},{"read_only":false,"name":"wallet"},{"read_only":false,"name":"futures"}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/sub_accounts/0/keys"
    query_param=""
    body_param='{"mode":1,"name":"spot","perms":[{"read_only":false,"name":"options"},{"read_only":false,"name":"spot"},{"read_only":false,"name":"delivery"},{"read_only":false,"name":"wallet"},{"read_only":false,"name":"futures"}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /sub_accounts/{user_id}/keys

    Create API Key of the sub-account

    Body parameter

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

    Parameters

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

    # Detailed descriptions

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

    • wallet: wallet
    • spot: spot/margin
    • futures: perpetual contract
    • delivery: delivery
    • earn: earn
    • options: options\m- account: Account
    • unified: unified
    • loan: Loan

    # Enumerated Values

    Parameter Value
    »» name wallet
    »» name spot
    »» name futures
    »» name delivery
    »» name earn
    »» name options
    »» name account
    »» name unified
    »» name loan

    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
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » user_id string User ID
    » mode integer(int32) Mode: 1 - classic 2 - portfolio account
    » name string API key name
    » perms array none
    »» name string Permission name (all permissions will be removed if no value is passed)

    - wallet: wallet
    - spot: spot/margin
    - futures: perpetual contract
    - delivery: delivery
    - earn: earn
    - options: options\m- account: Account
    - unified: unified
    - loan: Loan
    »» read_only boolean read only
    » ip_whitelist array ip white list (list will be removed if no value is passed)
    » key string API Key
    » state integer(int32) State 1 - normal 2 - locked 3 - frozen
    » created_at string Creation time
    » updated_at string Last update time

    # Enumerated Values

    Property Value
    name wallet
    name spot
    name futures
    name delivery
    name earn
    name options
    name account
    name unified
    name loan

    WARNING

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

    # List all API Key of the sub-account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/sub_accounts/0/keys'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/sub_accounts/0/keys"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /sub_accounts/{user_id}/keys

    List all API Key of the sub-account

    Parameters

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

    Example responses

    200 Response

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

    Responses

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

    WARNING

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

    # Update API key of the sub-account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/sub_accounts/0/keys/string'
    query_param = ''
    body='{"mode":1,"name":"spot","perms":[{"read_only":false,"name":"options"},{"read_only":false,"name":"spot"},{"read_only":false,"name":"delivery"},{"read_only":false,"name":"wallet"},{"read_only":false,"name":"futures"}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('PUT', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="PUT"
    url="/sub_accounts/0/keys/string"
    query_param=""
    body_param='{"mode":1,"name":"spot","perms":[{"read_only":false,"name":"options"},{"read_only":false,"name":"spot"},{"read_only":false,"name":"delivery"},{"read_only":false,"name":"wallet"},{"read_only":false,"name":"futures"}],"ip_whitelist":["127.0.0.1","127.0.0.2"]}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

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

    Update API key of the sub-account

    Body parameter

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

    Parameters

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

    # Detailed descriptions

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

    • wallet: wallet
    • spot: spot/margin
    • futures: perpetual contract
    • delivery: delivery
    • earn: earn
    • options: options\m- account: Account
    • unified: unified
    • loan: Loan

    # Enumerated Values

    Parameter Value
    »» name wallet
    »» name spot
    »» name futures
    »» name delivery
    »» name earn
    »» name options
    »» name account
    »» name unified
    »» name loan

    Responses

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

    WARNING

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

    # Delete API key of the sub-account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/sub_accounts/0/keys/string'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/sub_accounts/0/keys/string"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

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

    Delete API key of the sub-account

    Parameters

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

    Responses

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

    WARNING

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

    # Get the API Key of the sub-account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/sub_accounts/0/keys/string'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/sub_accounts/0/keys/string"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

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

    Get the API Key of the sub-account

    Parameters

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

    Example responses

    200 Response

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

    Responses

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

    WARNING

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

    # Lock the sub-account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/sub_accounts/0/lock'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/sub_accounts/0/lock"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /sub_accounts/{user_id}/lock

    Lock the sub-account

    Parameters

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

    Responses

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

    WARNING

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

    # Unlock the sub-account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/sub_accounts/0/unlock'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/sub_accounts/0/unlock"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /sub_accounts/{user_id}/unlock

    Unlock the sub-account

    Parameters

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

    Responses

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

    WARNING

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

    # Unified

    Unified account

    # Get unified account information

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/unified/accounts'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/unified/accounts"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /unified/accounts

    Get unified account information

    The assets of each currency in the account will be adjusted according to their liquidity, defined by corresponding adjustment coefficients, and then uniformly converted to USD to calculate the total asset value and position value of the account.

    You can refer to the Formula in the documentation

    Parameters

    Name In Type Required Description
    currency query string false Retrieve data of the specified currency

    Example responses

    200 Response

    {
      "user_id": 10001,
      "locked": false,
      "balances": {
        "ETH": {
          "available": "0",
          "freeze": "0",
          "borrowed": "0.075393666654",
          "negative_liab": "0",
          "futures_pos_liab": "0",
          "equity": "1016.1",
          "total_freeze": "0",
          "total_liab": "0"
        },
        "POINT": {
          "available": "9999999999.017023138734",
          "freeze": "0",
          "borrowed": "0",
          "negative_liab": "0",
          "futures_pos_liab": "0",
          "equity": "12016.1",
          "total_freeze": "0",
          "total_liab": "0"
        },
        "USDT": {
          "available": "0.00000062023",
          "freeze": "0",
          "borrowed": "0",
          "negative_liab": "0",
          "futures_pos_liab": "0",
          "equity": "16.1",
          "total_freeze": "0",
          "total_liab": "0"
        }
      },
      "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"
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » user_id integer(int64) User ID
    » refresh_time integer(int64) Time of the most recent refresh
    » locked boolean Whether account is locked
    » balances object none
    »» UnifiedBalance object none
    »»» available string Available amount
    »»» freeze string Locked amount
    »»» borrowed string Borrowed amount
    »»» negative_liab string Negative Liabilities
    »»» futures_pos_liab string Borrowing to Open Positions in Futures
    »»» equity string Equity
    »»» total_freeze string Total freeze
    »»» total_liab string Total liabilities
    »» total string The total asset value in USD, calculated as the sum of the product of (available + freeze) * price for all currencies.
    »» borrowed string The total borrowed amount in USD, calculated as the sum of the product of borrowed * price for all currencies (excluding points cards).
    »» total_initial_margin string Total initial margin
    »» total_margin_balance string Total margin balance
    »» total_maintenance_margin string Total maintenance margin
    »» total_initial_margin_rate string Total initial margin rate
    »» total_maintenance_margin_rate string Total maintenance margin rate
    »» total_available_margin string Total available margin
    »» unified_account_total string Total amount of the portfolio margin account
    »» unified_account_total_liab string Total liabilities of the portfolio margin account
    »» unified_account_total_equity string Total equity of the portfolio margin account
    »» leverage string Leverage

    WARNING

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

    # Set mode of the unified account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/unified/account_mode'
    query_param = ''
    body='{"mode":"cross_margin","enabled":true}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/unified/account_mode"
    query_param=""
    body_param='{"mode":"cross_margin","enabled":true}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /unified/account_mode

    Set mode of the unified account

    Body parameter

    {
      "mode": "cross_margin",
      "enabled": true
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » mode body string true Portfolio mode
    » enabled body boolean true Is it enabled?

    # Detailed descriptions

    » mode: Portfolio mode

    • cross_margin : cross margin
    • usdt_futures : usdt futures

    Example responses

    200 Response

    {
      "cross_margin": true,
      "usdt_futures": true
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » additionalProperties boolean none

    WARNING

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

    # Query mode of the unified account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/unified/account_mode'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/unified/account_mode"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /unified/account_mode

    Query mode of the unified account

    cross_margin - cross margin, usdt_futures - usdt futures

    Example responses

    200 Response

    {
      "cross_margin": true,
      "usdt_futures": true
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » additionalProperties boolean none

    WARNING

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

    # Query about the maximum borrowing for the unified account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/unified/borrowable'
    query_param = 'currency=BTC'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/unified/borrowable"
    query_param="currency=BTC"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /unified/borrowable

    Query about the maximum borrowing for the unified account

    Parameters

    Name In Type Required Description
    currency query string true Retrieve data of the specified currency

    Example responses

    200 Response

    {
      "currency": "ETH",
      "amount": "10000"
    }
    

    Responses

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

    Response Schema

    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

    # Query about the maximum transferable for the unified account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/unified/transferable'
    query_param = 'currency=BTC'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/unified/transferable"
    query_param="currency=BTC"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /unified/transferable

    Query about the maximum transferable for the unified account

    Parameters

    Name In Type Required Description
    currency query string true Retrieve data of the specified currency

    Example responses

    200 Response

    {
      "currency": "ETH",
      "amount": "10000"
    }
    

    Responses

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

    Response Schema

    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

    # Borrow or repay

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/unified/loans'
    query_param = ''
    body='{"currency":"BTC","amount":"0.1","type":"borrow","repaid_all":false,"text":"t-test"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/unified/loans"
    query_param=""
    body_param='{"currency":"BTC","amount":"0.1","type":"borrow","repaid_all":false,"text":"t-test"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /unified/loans

    Borrow or repay

    When borrowing, it is essential to ensure that the borrowed amount is not below the minimum borrowing threshold for the specific cryptocurrency and does not exceed the maximum borrowing limit set by the platform and the user.

    The interest on the loan will be automatically deducted from the account at regular intervals. It is the user's responsibility to manage the repayment of the borrowed amount.

    For repayment, the option to repay the entire borrowed amount is available by setting the parameter repaid_all=true

    Body parameter

    {
      "currency": "BTC",
      "amount": "0.1",
      "type": "borrow",
      "repaid_all": false,
      "text": "t-test"
    }
    

    Parameters

    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

    # Enumerated Values

    Parameter Value
    » type borrow
    » type repay

    Responses

    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

    # List loans

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/unified/loans'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/unified/loans"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /unified/loans

    List loans

    Parameters

    Name In Type Required Description
    currency query string false Retrieve data of the specified currency
    page query integer(int32) false Page number
    limit query integer(int32) false Maximum response items. Default: 100, minimum: 1, Maximum: 100
    type query string false Loan type, platform - platform, margin - margin

    Example responses

    200 Response

    [
      {
        "currency": "USDT",
        "currency_pari": "GT_USDT",
        "amount": "1",
        "type": "margin",
        "change_time": 1673247054000,
        "create_time": 1673247054000
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Get load records

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/unified/loan_records'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/unified/loan_records"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /unified/loan_records

    Get load records

    Parameters

    Name In Type Required Description
    type query string false The types of lending records, borrow - indicates the action of borrowing funds, repay - indicates the action of repaying the borrowed funds
    currency query string false Retrieve data of the specified currency
    page query integer(int32) false Page number
    limit query integer(int32) false Maximum response items. Default: 100, minimum: 1, Maximum: 100

    Example responses

    200 Response

    [
      {
        "id": 16442,
        "type": "borrow",
        "margin_mode": "cross",
        "currency_pair": "AE_USDT",
        "currency": "USDT",
        "amount": "1000",
        "create_time": 1673247054000,
        "repayment_type": "auto_repay"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » None object Loan records
    »» id integer(int64) id
    »» type string type: borrow - borrow, repay - repay
    »» repayment_type string Repayment type: none - no repayment type, manual_repay - manual repayment, auto_repay - automatic repayment, cancel_auto_repay - automatic repayment after cancellation
    »» 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

    # List interest records

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/unified/interest_records'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/unified/interest_records"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /unified/interest_records

    List interest records

    Parameters

    Name In Type Required Description
    currency query string false Retrieve data of the specified currency
    page query integer(int32) false Page number
    limit query integer(int32) false Maximum response items. Default: 100, minimum: 1, Maximum: 100
    type query string false Loan type, platform - platform, margin - margin

    Example responses

    200 Response

    [
      {
        "status": 1,
        "currency_pair": "BTC_USDT",
        "currency": "USDT",
        "actual_rate": "0.00000236",
        "interest": "0.00006136",
        "type": "platform",
        "create_time": 1673247054000
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Get unified estimate rate

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/unified/estimate_rate'
    query_param = 'currencies=BTC,GT'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/unified/estimate_rate"
    query_param="currencies=BTC,GT"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /unified/estimate_rate

    Get unified estimate rate

    Due to fluctuations in lending depth, hourly interest rates may vary, and thus, I cannot provide exact rates. When a currency is not supported, the interest rate returned will be an empty string.

    Parameters

    Name In Type Required Description
    currencies query array[string] true Specify the currency names for querying in an array, separated by commas, with a maximum of 10 currencies.

    Example responses

    200 Response

    {
      "BTC": "0.000002",
      "GT": "0.000001",
      "ETH": ""
    }
    

    Responses

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

    Response Schema

    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

    # list currency discount tiers

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/unified/currency_discount_tiers'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/unified/currency_discount_tiers \
      -H 'Accept: application/json'
    
    

    GET /unified/currency_discount_tiers

    list currency discount tiers

    Example responses

    200 Response

    [
      [
        {
          "currency": "USDT",
          "discount_tiers": [
            {
              "tier": "1",
              "discount": "1",
              "lower_limit": "0",
              "upper_limit": "+"
            }
          ]
        },
        {
          "currency": "USDC",
          "discount_tiers": [
            {
              "tier": "1",
              "discount": "1",
              "lower_limit": "0",
              "upper_limit": "10000000"
            },
            {
              "tier": "2",
              "discount": "0.98",
              "lower_limit": "10000000",
              "upper_limit": "15000000"
            },
            {
              "tier": "3",
              "discount": "0.95",
              "lower_limit": "15000000",
              "upper_limit": "20000000"
            },
            {
              "tier": "4",
              "discount": "0.925",
              "lower_limit": "20000000",
              "upper_limit": "50000000"
            },
            {
              "tier": "5",
              "discount": "0.9",
              "lower_limit": "50000000",
              "upper_limit": "100000000"
            },
            {
              "tier": "6",
              "discount": "0",
              "lower_limit": "100000000",
              "upper_limit": "+"
            }
          ]
        },
        {
          "currency": "BTC",
          "discount_tiers": [
            {
              "tier": "1",
              "discount": "0.98",
              "lower_limit": "0",
              "upper_limit": "1000"
            },
            {
              "tier": "2",
              "discount": "0.95",
              "lower_limit": "1000",
              "upper_limit": "10000"
            },
            {
              "tier": "3",
              "discount": "0.9",
              "lower_limit": "10000",
              "upper_limit": "50000"
            },
            {
              "tier": "4",
              "discount": "0.85",
              "lower_limit": "50000",
              "upper_limit": "+"
            }
          ]
        },
        {
          "currency": "ETH",
          "discount_tiers": [
            {
              "tier": "1",
              "discount": "0.98",
              "lower_limit": "0",
              "upper_limit": "1000"
            },
            {
              "tier": "2",
              "discount": "0.95",
              "lower_limit": "1000",
              "upper_limit": "10000"
            },
            {
              "tier": "3",
              "discount": "0.9",
              "lower_limit": "10000",
              "upper_limit": "50000"
            },
            {
              "tier": "4",
              "discount": "0.85",
              "lower_limit": "50000",
              "upper_limit": "+"
            }
          ]
        }
      ]
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » None object Currency discount tiers
    »» currency string Currency name
    »» discount_tiers array Tiered discount
    »»» tier string Tier
    »»» discount string Discount
    »»» lower_limit string Lower limit
    »»» upper_limit string Upper limit,+ indicates positive infinity

    # Spot

    Spot trading

    # List all currencies' details

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/currencies'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/spot/currencies \
      -H 'Accept: application/json'
    
    

    GET /spot/currencies

    List all currencies' details

    Currency has two forms:

    1. Only currency name, e.g., BTC, USDT
    2. <currency>_<chain>, e.g., HT_ETH

    The latter one occurs when one currency has multiple chains. Currency detail contains a chain field whatever the form is. To retrieve all chains of one currency, you can use use all the details which has the name of the currency or name starting with <currency>_.

    Example responses

    200 Response

    [
      {
        "currency": "GT",
        "delisted": false,
        "withdraw_disabled": false,
        "withdraw_delayed": false,
        "deposit_disabled": false,
        "trade_disabled": false,
        "chain": "GT"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » currency string Currency name
    » delisted boolean Whether currency is de-listed
    » withdraw_disabled boolean Whether currency's withdrawal is disabled
    » withdraw_delayed boolean Whether currency's withdrawal is delayed
    » deposit_disabled boolean Whether currency's deposit is disabled
    » trade_disabled boolean Whether currency's trading is disabled
    » fixed_rate string Fixed fee rate. Only for fixed rate currencies, not valid for normal currencies
    » chain string Chain of currency

    # Get details of a specific currency

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/currencies/GT'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/spot/currencies/GT \
      -H 'Accept: application/json'
    
    

    GET /spot/currencies/{currency}

    Get details of a specific currency

    Parameters

    Name In Type Required Description
    currency path string true Currency name

    Example responses

    200 Response

    {
      "currency": "GT",
      "delisted": false,
      "withdraw_disabled": false,
      "withdraw_delayed": false,
      "deposit_disabled": false,
      "trade_disabled": false,
      "chain": "GT"
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » currency string Currency name
    » delisted boolean Whether currency is de-listed
    » withdraw_disabled boolean Whether currency's withdrawal is disabled
    » withdraw_delayed boolean Whether currency's withdrawal is delayed
    » deposit_disabled boolean Whether currency's deposit is disabled
    » trade_disabled boolean Whether currency's trading is disabled
    » fixed_rate string Fixed fee rate. Only for fixed rate currencies, not valid for normal currencies
    » chain string Chain of currency

    # List all currency pairs supported

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/currency_pairs'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/spot/currency_pairs \
      -H 'Accept: application/json'
    
    

    GET /spot/currency_pairs

    List all currency pairs supported

    Example responses

    200 Response

    [
      {
        "id": "ETH_USDT",
        "base": "ETH",
        "quote": "USDT",
        "fee": "0.2",
        "min_base_amount": "0.001",
        "min_quote_amount": "1.0",
        "max_base_amount": "10000",
        "max_quote_amount": "10000000",
        "amount_precision": 3,
        "precision": 6,
        "trade_status": "tradable",
        "sell_start": 1516378650,
        "buy_start": 1516378650
      }
    ]
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) All currency pairs retrieved [CurrencyPair]

    # Get details of a specifc currency pair

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/currency_pairs/ETH_BTC'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/spot/currency_pairs/ETH_BTC \
      -H 'Accept: application/json'
    
    

    GET /spot/currency_pairs/{currency_pair}

    Get details of a specifc currency pair

    Parameters

    Name In Type Required Description
    currency_pair path string true Currency pair

    Example responses

    200 Response

    {
      "id": "ETH_USDT",
      "base": "ETH",
      "quote": "USDT",
      "fee": "0.2",
      "min_base_amount": "0.001",
      "min_quote_amount": "1.0",
      "max_base_amount": "10000",
      "max_quote_amount": "10000000",
      "amount_precision": 3,
      "precision": 6,
      "trade_status": "tradable",
      "sell_start": 1516378650,
      "buy_start": 1516378650
    }
    

    Responses

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

    # Retrieve ticker information

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/tickers'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/spot/tickers \
      -H 'Accept: application/json'
    
    

    GET /spot/tickers

    Retrieve ticker information

    Return only related data if currency_pair is specified; otherwise return all of them

    Parameters

    Name In Type Required Description
    currency_pair query string false Currency pair
    timezone query string false Timezone

    # Enumerated Values

    Parameter Value
    timezone utc0
    timezone utc8
    timezone all

    Example responses

    200 Response

    [
      {
        "currency_pair": "BTC3L_USDT",
        "last": "2.46140352",
        "lowest_ask": "2.477",
        "highest_bid": "2.4606821",
        "change_percentage": "-8.91",
        "change_utc0": "-8.91",
        "change_utc8": "-8.91",
        "base_volume": "656614.0845820589",
        "quote_volume": "1602221.66468375534639404191",
        "high_24h": "2.7431",
        "low_24h": "1.9863",
        "etf_net_value": "2.46316141",
        "etf_pre_net_value": "2.43201848",
        "etf_pre_timestamp": 1611244800,
        "etf_leverage": "2.2803019447281203"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » currency_pair string Currency pair
    » last string Last trading price
    » lowest_ask string Recent lowest ask
    » highest_bid string Recent highest bid
    » change_percentage string Change percentage in the last 24h
    » change_utc0 string utc0 timezone, the percentage change in the last 24 hours
    » change_utc8 string utc8 timezone, the percentage change in the last 24 hours
    » base_volume string Base currency trade volume in the last 24h
    » quote_volume string Quote currency trade volume in the last 24h
    » high_24h string Highest price in 24h
    » low_24h string Lowest price in 24h
    » etf_net_value string ETF net value
    » etf_pre_net_value string|null ETF previous net value at re-balancing time
    » etf_pre_timestamp integer(int64)|null ETF previous re-balancing time
    » etf_leverage string|null ETF current leverage

    # Retrieve order book

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/order_book'
    query_param = 'currency_pair=BTC_USDT'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/spot/order_book?currency_pair=BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /spot/order_book

    Retrieve order book

    Order book will be sorted by price from high to low on bids; low to high on asks

    Parameters

    Name In Type Required Description
    currency_pair query string true Currency pair
    interval query string false Order depth. 0 means no aggregation is applied. default to 0
    limit query integer false Maximum number of order depth data in asks or bids
    with_id query boolean false Return order book ID

    Example responses

    200 Response

    {
      "id": 123456,
      "current": 1623898993123,
      "update": 1623898993121,
      "asks": [
        [
          "1.52",
          "1.151"
        ],
        [
          "1.53",
          "1.218"
        ]
      ],
      "bids": [
        [
          "1.17",
          "201.863"
        ],
        [
          "1.16",
          "725.464"
        ]
      ]
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » id integer(int64) Order book ID, which is updated whenever the order book is changed. Valid only when with_id is set to true
    » current integer(int64) The timestamp of the response data being generated (in milliseconds)
    » update integer(int64) The timestamp of when the orderbook last changed (in milliseconds)
    » asks array Asks order depth
    »» None array price and amount
    » bids array Bids order depth
    »» None array price and amount

    # Retrieve market trades

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/trades'
    query_param = 'currency_pair=BTC_USDT'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/spot/trades?currency_pair=BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /spot/trades

    Retrieve market trades

    You can use from and to to query by time range, or use last_id by scrolling page. The default behavior is by time range.

    Scrolling query using last_id is not recommended any more. If last_id is specified, time range query parameters will be ignored.

    Parameters

    Name In Type Required Description
    currency_pair query string true Currency pair
    limit query integer(int32) false Maximum number of records to be returned in a single list. Default: 100, Minimum: 1, Maximum: 1000
    last_id query string false Specify list staring point using the id of last record in previous list-query results
    reverse query boolean false Whether the id of records to be retrieved should be less than the last_id specified. Default to false.
    from query integer(int64) false Start timestamp of the query
    to query integer(int64) false Time range ending, default to current time
    page query integer(int32) false Page number

    # Detailed descriptions

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

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

    No effect if last_id is not specified.

    Example responses

    200 Response

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

    Responses

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

    Response Schema

    Status Code 200

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

    # Enumerated Values

    Property Value
    side buy
    side sell
    role taker
    role maker

    # Market candlesticks

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/candlesticks'
    query_param = 'currency_pair=BTC_USDT'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/spot/candlesticks?currency_pair=BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /spot/candlesticks

    Market candlesticks

    Maximum of 1000 points can be returned in a query. Be sure not to exceed the limit when specifying from, to and interval

    Parameters

    Name In Type Required Description
    currency_pair query string true Currency pair
    limit query integer false Maximum recent data points to return. limit is conflicted with from and to. If either from or to is specified, request will be rejected.
    from query integer(int64) false Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified
    to query integer(int64) false End time of candlesticks, formatted in Unix timestamp in seconds. Default to current time
    interval query string false Interval time between data points. Note that 30d means 1 natual month, not 30 days

    # Enumerated Values

    Parameter Value
    interval 10s
    interval 1m
    interval 5m
    interval 15m
    interval 30m
    interval 1h
    interval 4h
    interval 8h
    interval 1d
    interval 7d
    interval 30d

    Example responses

    200 Response

    [
      [
        "1539852480",
        "971519.677",
        "0.0021724",
        "0.0021922",
        "0.0021724",
        "0.0021737",
        "true"
      ]
    ]
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) Successfully retrieved [[string]]

    Response Schema

    Status Code 200

    Name Type Description
    » None array K-line data for each time granularity, arranged from left to right:

    - Unix timestamp with second precision
    - Trading volume in quote currency
    - Closing price
    - Highest price
    - Lowest price
    - Opening price
    - Trading volume in base currency
    - Whether the window is closed; true indicates the end of this segment of candlestick chart data, false indicates that this segment of candlestick chart data is not yet complete

    # Query user trading fee rates

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/fee'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/spot/fee"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /spot/fee

    Query user trading fee rates

    This API is deprecated in favour of new fee retrieving API /wallet/fee.

    Parameters

    Name In Type Required Description
    currency_pair query string false Specify a currency pair to retrieve precise fee rate

    # Detailed descriptions

    currency_pair: Specify a currency pair to retrieve precise fee rate

    This field is optional. In most cases, the fee rate is identical among all currency pairs

    Example responses

    200 Response

    {
      "user_id": 10001,
      "taker_fee": "0.002",
      "maker_fee": "0.002",
      "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
    }
    

    Responses

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

    Response Schema

    Status Code 200

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

    # Query a batch of user trading fee rates

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/batch_fee'
    query_param = 'currency_pairs=BTC_USDT,ETH_USDT'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/spot/batch_fee"
    query_param="currency_pairs=BTC_USDT,ETH_USDT"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /spot/batch_fee

    Query a batch of user trading fee rates

    Parameters

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

    Example responses

    200 Response

    {
      "BTC_USDT": {
        "user_id": 10001,
        "taker_fee": "0.002",
        "maker_fee": "0.002",
        "gt_discount": false,
        "gt_taker_fee": "0",
        "gt_maker_fee": "0",
        "loan_fee": "0.18",
        "point_type": "1",
        "currency_pair": "BTC_USDT",
        "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
      }
    }
    

    Responses

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

    Response Schema

    Status Code 200

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

    # List spot accounts

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/accounts'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/spot/accounts"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /spot/accounts

    List spot accounts

    Parameters

    Name In Type Required Description
    currency query string false Retrieve data of the specified currency

    Example responses

    200 Response

    [
      {
        "currency": "ETH",
        "available": "968.8",
        "locked": "0"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » currency string Currency detail
    » available string Available amount
    » locked string Locked amount, used in trading

    WARNING

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

    # Query account book

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/account_book'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/spot/account_book"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /spot/account_book

    Query account book

    Record time range cannot exceed 30 days

    Parameters

    Name In Type Required Description
    currency query string false Retrieve data of the specified currency
    from query integer(int64) false Start timestamp of the query
    to query integer(int64) false Time range ending, default to current time
    page query integer(int32) false Page number
    limit query integer false Maximum number of records to be returned in a single list
    type query string false Only retrieve changes of the specified type. All types will be returned if not specified.

    Example responses

    200 Response

    [
      {
        "id": "123456",
        "time": 1547633726123,
        "currency": "BTC",
        "change": "1.03",
        "balance": "4.59316525194",
        "type": "margin_in",
        "text": "3815099"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » id string Balance change record ID
    » time integer(int64) The timestamp of the change (in milliseconds)
    » currency string Currency changed
    » change string Amount changed. Positive value means transferring in, while negative out
    » balance string Balance after change
    » type string Account book type. Please refer to account book type for more detail
    » text string Additional information

    WARNING

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

    # Create a batch of orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/batch_orders'
    query_param = ''
    body='[{"text":"t-abc123","currency_pair":"BTC_USDT","type":"limit","account":"unified","side":"buy","amount":"0.001","price":"65000","time_in_force":"gtc","iceberg":"0"}]'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/spot/batch_orders"
    query_param=""
    body_param='[{"text":"t-abc123","currency_pair":"BTC_USDT","type":"limit","account":"unified","side":"buy","amount":"0.001","price":"65000","time_in_force":"gtc","iceberg":"0"}]'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /spot/batch_orders

    Create a batch of orders

    Batch orders requirements:

    1. custom order field text is required
    2. At most 4 currency pairs, maximum 10 orders each, are allowed in one request
    3. No mixture of spot orders and margin orders, i.e. account must be identical for all orders

    Body parameter

    [
      {
        "text": "t-abc123",
        "currency_pair": "BTC_USDT",
        "type": "limit",
        "account": "unified",
        "side": "buy",
        "amount": "0.001",
        "price": "65000",
        "time_in_force": "gtc",
        "iceberg": "0"
      }
    ]
    

    Parameters

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

    Example responses

    200 Response

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

    Responses

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

    Response Schema

    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- prefix
    3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
    »» succeeded boolean Whether the batch of orders succeeded
    »» label string Error label, if any, otherwise an empty string
    »» message string Detailed error message, if any, otherwise an empty string
    »» id string Order ID
    »» create_time string Creation time of order
    »» update_time string Last modification time of order
    »» create_time_ms integer(int64) Creation time of order (in milliseconds)
    »» update_time_ms integer(int64) Last modification time of order (in milliseconds)
    »» status string Order status

    - open: to be filled
    - closed: filled
    - cancelled: cancelled
    »» currency_pair string Currency pair
    »» type string Order Type

    - limit : Limit Order
    - market : Market Order
    »» account string Account type. spot - use spot account; margin - use margin account; cross_margin - use cross margin account, unified - unified account
    »» side string Order side
    »» amount string Trade amount
    »» price string Order price
    »» time_in_force string Time in force

    - gtc: GoodTillCancelled
    - ioc: ImmediateOrCancelled, taker only
    - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee
    - fok: FillOrKill, fill either completely or none
    »» iceberg string Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported.
    »» auto_repay boolean Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that:

    1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders.
    2. auto_borrow and auto_repay cannot 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-traded

    1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.
    2. stp_id returns 0 by default for orders that have not been set for STP group
    »» stp_act string Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies

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

    - cn: Cancel newest, Cancel new orders and keep old ones
    - co: Cancel oldest, Cancel old orders and keep new ones
    - cb: Cancel both, Both old and new orders will be cancelled
    »» finish_as string How the order was finished.

    - open: processing
    - filled: filled totally
    - cancelled: manually cancelled
    - ioc: time in force is IOC, finish immediately
    - stp: cancelled because self trade prevention

    # Enumerated Values

    Property Value
    status open
    status closed
    status cancelled
    type limit
    type market
    account spot
    account margin
    account cross_margin
    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

    # List all open orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/open_orders'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/spot/open_orders"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /spot/open_orders

    List all open orders

    List open orders in all currency pairs.

    Note that pagination parameters affect record number in each currency pair's open order list. No pagination is applied to the number of currency pairs returned. All currency pairs with open orders will be returned.

    Spot,portfolio and margin orders are returned by default. To list cross margin orders, account must be set to cross_margin

    Parameters

    Name In Type Required Description
    page query integer(int32) false Page number
    limit query integer false Maximum number of records returned in one page in each currency pair
    account query string false Specify operation account. Default to spot ,portfolio and margin account if not specified. Set to cross_margin to operate against margin account. Portfolio margin account must set to cross_margin only

    Example responses

    200 Response

    [
      {
        "currency_pair": "ETH_BTC",
        "total": 1,
        "orders": [
          {
            "id": "12332324",
            "text": "t-123456",
            "create_time": "1548000000",
            "update_time": "1548000100",
            "currency_pair": "ETH_BTC",
            "status": "open",
            "type": "limit",
            "account": "spot",
            "side": "buy",
            "amount": "1",
            "price": "5.00032",
            "time_in_force": "gtc",
            "left": "0.5",
            "filled_total": "2.50016",
            "fee": "0.005",
            "fee_currency": "ETH",
            "point_fee": "0",
            "gt_fee": "0",
            "gt_discount": false,
            "rebated_fee": "0",
            "rebated_fee_currency": "BTC"
          }
        ]
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » currency_pair string Currency pair
    » total integer Total open orders in this currency pair
    » orders array none
    »» None object Spot order details
    »»» id string Order ID
    »»» text string User defined information. If not empty, must follow the rules below:

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

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

    - 101: from android
    - 102: from IOS
    - 103: from IPAD
    - 104: from webapp
    - 3: from web
    - 2: from apiv2
    - apiv4: from apiv4
    »»» amend_text string The custom data that the user remarked when amending the order
    »»» create_time string Creation time of order
    »»» update_time string Last modification time of order
    »»» create_time_ms integer(int64) Creation time of order (in milliseconds)
    »»» update_time_ms integer(int64) Last modification time of order (in milliseconds)
    »»» status string Order status

    - open: to be filled
    - closed: filled
    - cancelled: cancelled
    »»» currency_pair string Currency pair
    »»» type string Order Type

    - limit : Limit Order
    - market : Market Order
    »»» account string Account types, spot - spot account, margin - margin account, unified - unified account, cross_margin - cross margin account. Portfolio margin accounts can only be set to cross_margin
    »»» side string Order side
    »»» amount string When type is limit, it refers to base currency. For instance, BTC_USDT means BTC
    When type is market, it refers to different currency according to side
    - side : buy means quote currency, BTC_USDT means USDT
    - side : sell means base currency,BTC_USDT means BTC
    »»» price string Price can't be empty when type= limit
    »»» time_in_force string Time in force

    - gtc: GoodTillCancelled
    - ioc: ImmediateOrCancelled, taker only
    - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee
    - fok: FillOrKill, fill either completely or none
    Only ioc and fok are supported when type=market
    »»» iceberg string Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported.
    »»» auto_repay boolean Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that:

    1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders.
    2. auto_borrow and auto_repay cannot 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-traded

    1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.
    2. stp_id returns 0 by default for orders that have not been set for STP group
    »»» stp_act string Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies

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

    - cn: Cancel newest, Cancel new orders and keep old ones
    - co: Cancel oldest, Cancel old orders and keep new ones
    - cb: Cancel both, Both old and new orders will be cancelled
    »»» finish_as string How the order was finished.

    - open: processing
    - filled: filled totally
    - cancelled: manually cancelled
    - ioc: time in force is IOC, finish immediately
    - stp: cancelled because self trade prevention

    # Enumerated Values

    Property Value
    status open
    status closed
    status cancelled
    type limit
    type market
    side buy
    side sell
    time_in_force gtc
    time_in_force ioc
    time_in_force poc
    time_in_force fok
    stp_act cn
    stp_act co
    stp_act cb
    stp_act -
    finish_as open
    finish_as filled
    finish_as cancelled
    finish_as ioc
    finish_as stp

    WARNING

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

    # close position when cross-currency is disabled

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/cross_liquidate_orders'
    query_param = ''
    body='{"currency_pair":"GT_USDT","amount":"12","price":"10.15","text":"t-34535"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/spot/cross_liquidate_orders"
    query_param=""
    body_param='{"currency_pair":"GT_USDT","amount":"12","price":"10.15","text":"t-34535"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /spot/cross_liquidate_orders

    close position when cross-currency is disabled

    Currently, only cross-margin accounts are supported to close position when cross currencies are disabled. Maximum buy quantity = (unpaid principal and interest - currency balance - the amount of the currency in the order book) / 0.998

    Body parameter

    {
      "currency_pair": "GT_USDT",
      "amount": "12",
      "price": "10.15",
      "text": "t-34535"
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » text body string false User defined information. If not empty, must follow the rules below:
    » currency_pair body string true Currency pair
    » amount body string true Trade amount
    » price body string true Order price
    » action_mode body string false Processing Mode:

    # Detailed descriptions

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

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

    » action_mode: Processing Mode:

    Different fields are returned when placing an order based on action_mode. This field is only valid during the request, and it is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)

    Example responses

    201 Response

    {
      "id": "1852454420",
      "text": "t-abc123",
      "amend_text": "-",
      "create_time": "1710488334",
      "update_time": "1710488334",
      "create_time_ms": 1710488334073,
      "update_time_ms": 1710488334074,
      "status": "closed",
      "currency_pair": "BTC_USDT",
      "type": "limit",
      "account": "unified",
      "side": "buy",
      "amount": "0.001",
      "price": "65000",
      "time_in_force": "gtc",
      "iceberg": "0",
      "left": "0",
      "filled_amount": "0.001",
      "fill_price": "63.4693",
      "filled_total": "63.4693",
      "avg_deal_price": "63469.3",
      "fee": "0.00000022",
      "fee_currency": "BTC",
      "point_fee": "0",
      "gt_fee": "0",
      "gt_maker_fee": "0",
      "gt_taker_fee": "0",
      "gt_discount": false,
      "rebated_fee": "0",
      "rebated_fee_currency": "USDT",
      "finish_as": "filled"
    }
    

    Responses

    Status Meaning Description Schema
    201 Created (opens new window) order created Order

    WARNING

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

    # Create an order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/orders'
    query_param = ''
    body='{"text":"t-abc123","currency_pair":"BTC_USDT","type":"limit","account":"unified","side":"buy","amount":"0.001","price":"65000","time_in_force":"gtc","iceberg":"0"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/spot/orders"
    query_param=""
    body_param='{"text":"t-abc123","currency_pair":"BTC_USDT","type":"limit","account":"unified","side":"buy","amount":"0.001","price":"65000","time_in_force":"gtc","iceberg":"0"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /spot/orders

    Create an order

    You can place orders with spot, portfolio, margin or cross margin account through setting the accountfield. It defaults to spot, which means spot account is used to place orders. If the user is using unified account, it defaults to the unified account.

    When margin account is used, i.e., account is margin, auto_borrow field can be set to true to enable the server to borrow the amount lacked using POST /margin/loans when your account's balance is not enough. Whether margin orders' fill will be used to repay margin loans automatically is determined by the auto repayment setting in your margin account, which can be updated or queried using /margin/auto_repay API.

    When cross margin account is used, i.e., account is cross_margin, auto_borrow can also be enabled to achieve borrowing the insufficient amount automatically if cross account's balance is not enough. But it differs from margin account that automatic repayment is determined by order's auto_repay field and only current order's fill will be used to repay cross margin loans.

    Automatic repayment will be triggered when the order is finished, i.e., its status is either cancelled or closed.

    Order status

    An order waiting to be filled is open, and it stays open until it is filled totally. If fully filled, order is finished and its status turns to closed.If the order is cancelled before it is totally filled, whether or not partially filled, its status is cancelled. Iceberg order

    iceberg field can be used to set the amount shown. Set to -1 to hide the order completely. Note that the hidden part's fee will be charged using taker's fee rate. Self Trade Prevention

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

    Body parameter

    {
      "text": "t-abc123",
      "currency_pair": "BTC_USDT",
      "type": "limit",
      "account": "unified",
      "side": "buy",
      "amount": "0.001",
      "price": "65000",
      "time_in_force": "gtc",
      "iceberg": "0"
    }
    

    Parameters

    Name In Type Required Description
    body body Order true none
    » text body string false User defined information. If not empty, must follow the rules below:
    » currency_pair body string true Currency pair
    » type body string false Order Type
    » account body string false Account types, spot - spot account, margin - margin account, unified - unified account, cross_margin - cross margin account. Portfolio margin accounts can only be set to cross_margin
    » side body string true Order side
    » amount body string true When type is limit, it refers to base currency. For instance, BTC_USDT means BTC
    » price body string false Price can't be empty when type= limit
    » time_in_force body string false Time in force
    » iceberg body string false Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported.
    » auto_borrow body boolean false Used in margin or cross margin trading to allow automatic loan of insufficient amount if balance is not enough.
    » auto_repay body boolean false Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that:
    » stp_act body string false Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies
    » action_mode body string false Processing Mode:

    # Detailed descriptions

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

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

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

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

    » type: Order Type

    • limit : Limit Order
    • market : Market Order

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

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

    » time_in_force: Time in force

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

    » auto_repay: Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that:

    1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders.
    2. auto_borrow and auto_repay cannot be both set to true in one order.

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

    1. After users join the STP Group, he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy。
    2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter。
    3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-'
    • cn: Cancel newest, Cancel new orders and keep old ones
    • co: Cancel oldest, Cancel old orders and keep new ones
    • cb: Cancel both, Both old and new orders will be cancelled

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

    # Enumerated Values

    Parameter Value
    » type limit
    » type market
    » side buy
    » side sell
    » time_in_force gtc
    » time_in_force ioc
    » time_in_force poc
    » time_in_force fok
    » stp_act cn
    » stp_act co
    » stp_act cb
    » stp_act -

    Example responses

    ACK response body example

    {
      "id": "12332324",
      "text": "t-123456",
      "amend_text": "test2"
    }
    

    RESULT response body example

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

    FULL response body example

    {
      "id": "1852454420",
      "text": "t-abc123",
      "amend_text": "-",
      "create_time": "1710488334",
      "update_time": "1710488334",
      "create_time_ms": 1710488334073,
      "update_time_ms": 1710488334074,
      "status": "closed",
      "currency_pair": "BTC_USDT",
      "type": "limit",
      "account": "unified",
      "side": "buy",
      "amount": "0.001",
      "price": "65000",
      "time_in_force": "gtc",
      "iceberg": "0",
      "left": "0",
      "filled_amount": "0.001",
      "fill_price": "63.4693",
      "filled_total": "63.4693",
      "avg_deal_price": "63469.3",
      "fee": "0.00000022",
      "fee_currency": "BTC",
      "point_fee": "0",
      "gt_fee": "0",
      "gt_maker_fee": "0",
      "gt_taker_fee": "0",
      "gt_discount": false,
      "rebated_fee": "0",
      "rebated_fee_currency": "USDT",
      "finish_as": "filled"
    }
    

    Responses

    Status Meaning Description Schema
    201 Created (opens new window) Order created. Order

    WARNING

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

    # List orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/orders'
    query_param = 'currency_pair=BTC_USDT&status=open'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/spot/orders"
    query_param="currency_pair=BTC_USDT&status=open"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /spot/orders

    List orders

    Spot, portfolio and margin orders are returned by default. If cross margin orders are needed, account must be set to cross_margin

    When status is open, i.e., listing open orders, only pagination parameters page and limit are supported and limit cannot be larger than 100. Query by side and time range parameters from and to are not supported.

    When status is finished, i.e., listing finished orders, pagination parameters, time range parameters from and to, and side parameters are all supported. Time range parameters are handled as order finish time.

    Parameters

    Name In Type Required Description
    currency_pair query string true Retrieve results with specified currency pair. It is required for open orders, but optional for finished ones.
    status query string true List orders based on status
    page query integer(int32) false Page number
    limit query integer false Maximum number of records to be returned. If status is open, maximum of limit is 100
    account query string false Specify operation account. Default to spot ,portfolio and margin account if not specified. Set to cross_margin to operate against margin account. Portfolio margin account must set to cross_margin only
    from query integer(int64) false Start timestamp of the query
    to query integer(int64) false Time range ending, default to current time
    side query string false All bids or asks. Both included if not specified

    # Detailed descriptions

    status: List orders based on status

    open - order is waiting to be filled finished - order has been filled or cancelled

    Example responses

    200 Response

    [
      {
        "id": "1852454420",
        "text": "t-abc123",
        "amend_text": "-",
        "create_time": "1710488334",
        "update_time": "1710488334",
        "create_time_ms": 1710488334073,
        "update_time_ms": 1710488334074,
        "status": "closed",
        "currency_pair": "BTC_USDT",
        "type": "limit",
        "account": "unified",
        "side": "buy",
        "amount": "0.001",
        "price": "65000",
        "time_in_force": "gtc",
        "iceberg": "0",
        "left": "0",
        "filled_amount": "0.001",
        "fill_price": "63.4693",
        "filled_total": "63.4693",
        "avg_deal_price": "63469.3",
        "fee": "0.00000022",
        "fee_currency": "BTC",
        "point_fee": "0",
        "gt_fee": "0",
        "gt_maker_fee": "0",
        "gt_taker_fee": "0",
        "gt_discount": false,
        "rebated_fee": "0",
        "rebated_fee_currency": "USDT",
        "finish_as": "filled"
      }
    ]
    

    Responses

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

    WARNING

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

    # Cancel all open orders in specified currency pair

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/orders'
    query_param = 'currency_pair=BTC_USDT'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/spot/orders"
    query_param="currency_pair=BTC_USDT"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    DELETE /spot/orders

    Cancel all open orders in specified currency pair

    If account is not set, all open orders, including spot, portfolio, margin and cross margin ones, will be cancelled.

    You can set account to cancel only orders within the specified account

    Parameters

    Name In Type Required Description
    currency_pair query string true Currency pair
    side query string false All bids or asks. Both included if not specified
    account query string false Specify account type
    action_mode query string false Processing Mode

    # Detailed descriptions

    account: Specify account type

    • classic account:Default to all account types being included
    • portfolio margin account:cross_margin only

    action_mode: Processing Mode

    When placing an order, different fields are returned based on the action_mode

    • ACK: Asynchronous mode, returns only key order fields
    • RESULT: No clearing information
    • FULL: Full mode (default)

    Example responses

    200 Response

    [
      {
        "id": "1852454420",
        "text": "t-abc123",
        "amend_text": "-",
        "create_time": "1710488334",
        "update_time": "1710488334",
        "create_time_ms": 1710488334073,
        "update_time_ms": 1710488334074,
        "status": "closed",
        "currency_pair": "BTC_USDT",
        "type": "limit",
        "account": "unified",
        "side": "buy",
        "amount": "0.001",
        "price": "65000",
        "time_in_force": "gtc",
        "iceberg": "0",
        "left": "0",
        "filled_amount": "0.001",
        "fill_price": "63.4693",
        "filled_total": "63.4693",
        "avg_deal_price": "63469.3",
        "fee": "0.00000022",
        "fee_currency": "BTC",
        "point_fee": "0",
        "gt_fee": "0",
        "gt_maker_fee": "0",
        "gt_taker_fee": "0",
        "gt_discount": false,
        "rebated_fee": "0",
        "rebated_fee_currency": "USDT",
        "finish_as": "filled"
      }
    ]
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) Batch cancellation request accepted. Query order status by listing orders [Order]

    WARNING

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

    # Cancel a batch of orders with an ID list

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/cancel_batch_orders'
    query_param = ''
    body='[{"currency_pair":"BTC_USDT","id":"123456"}]'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/spot/cancel_batch_orders"
    query_param=""
    body_param='[{"currency_pair":"BTC_USDT","id":"123456"}]'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /spot/cancel_batch_orders

    Cancel a batch of orders with an ID list

    Multiple currency pairs can be specified, but maximum 20 orders are allowed per request

    Body parameter

    [
      {
        "currency_pair": "BTC_USDT",
        "id": "123456"
      }
    ]
    

    Parameters

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

    Example responses

    200 Response

    [
      {
        "currency_pair": "BTC_USDT",
        "id": "123456",
        "succeeded": true,
        "label": null,
        "message": null
      }
    ]
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) Batch cancellation completed [Inline]

    Response Schema

    Status Code 200

    Name Type Description
    » CancelOrderResult object Order cancellation result
    »» currency_pair string Order currency pair
    »» id string Order ID
    »» succeeded boolean Whether cancellation succeeded
    »» label string Error label when failed to cancel the order; emtpy if succeeded
    »» message string Error message when failed to cancel the order; empty if succeeded
    »» account string Empty by default. If cancelled order is cross margin order, this field is set to cross_margin

    WARNING

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

    # Get a single order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/orders/12345'
    query_param = 'currency_pair=BTC_USDT'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/spot/orders/12345"
    query_param="currency_pair=BTC_USDT"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /spot/orders/{order_id}

    Get a single order

    Spot, portfolio and margin orders are queried by default. If cross margin orders are needed or portfolio margin account are used, account must be set to cross_margin.

    Parameters

    Name In Type Required Description
    order_id path string true Order ID returned, or user custom ID(i.e., text field).
    currency_pair query string true Currency pair
    account query string false Specify operation account. Default to spot ,portfolio and margin account if not specified. Set to cross_margin to operate against margin account. Portfolio margin account must set to cross_margin only

    # Detailed descriptions

    order_id: Order ID returned, or user custom ID(i.e., text field). Operations based on custom ID can only be checked when the order is in orderbook. When the order is finished, it can be checked within 1 hour after the end of the order. After that, only order ID is accepted.

    Example responses

    200 Response

    {
      "id": "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"
    }
    

    Responses

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

    WARNING

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

    # Amend an order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/orders/12345'
    query_param = 'currency_pair=BTC_USDT'
    body='{"amount":"1","price":"14"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('PATCH', host + prefix + url + "?" + query_param, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="PATCH"
    url="/spot/orders/12345"
    query_param="currency_pair=BTC_USDT"
    body_param='{"amount":"1","price":"14"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    PATCH /spot/orders/{order_id}

    Amend an order

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

    Currently, only supports modification of price or amount fields.

    Regarding rate limiting: modify order and create order sharing rate limiting rules. Regarding matching priority: Only reducing the quantity without modifying the priority of matching, altering the price or increasing the quantity will adjust the priority to the new price at the end Note: If the modified amount is less than the fill amount, the order will be cancelled.

    Body parameter

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

    Parameters

    Name In Type Required Description
    body body object true none
    » amount body string false New order amount. amount and price must specify one of them
    » price body string false New order price. amount and Price must specify one of them"
    » amend_text body string false Custom info during amending order
    » action_mode body string false Processing Mode:
    order_id path string true Order ID returned, or user custom ID(i.e., text field).
    currency_pair query string true Currency pair
    account query string false Specify operation account. Default to spot ,portfolio and margin account if not specified. Set to cross_margin to operate against margin account. Portfolio margin account must set to cross_margin only

    # Detailed descriptions

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

    order_id: Order ID returned, or user custom ID(i.e., text field). Operations based on custom ID can only be checked when the order is in orderbook. When the order is finished, it can be checked within 1 hour after the end of the order. After that, only order ID is accepted.

    Example responses

    200 Response

    {
      "id": "1852454420",
      "text": "t-abc123",
      "amend_text": "-",
      "create_time": "1710488334",
      "update_time": "1710488334",
      "create_time_ms": 1710488334073,
      "update_time_ms": 1710488334074,
      "status": "closed",
      "currency_pair": "BTC_USDT",
      "type": "limit",
      "account": "unified",
      "side": "buy",
      "amount": "0.001",
      "price": "65000",
      "time_in_force": "gtc",
      "iceberg": "0",
      "left": "0",
      "filled_amount": "0.001",
      "fill_price": "63.4693",
      "filled_total": "63.4693",
      "avg_deal_price": "63469.3",
      "fee": "0.00000022",
      "fee_currency": "BTC",
      "point_fee": "0",
      "gt_fee": "0",
      "gt_maker_fee": "0",
      "gt_taker_fee": "0",
      "gt_discount": false,
      "rebated_fee": "0",
      "rebated_fee_currency": "USDT",
      "finish_as": "filled"
    }
    

    Responses

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

    WARNING

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

    # Cancel a single order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/orders/12345'
    query_param = 'currency_pair=BTC_USDT'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/spot/orders/12345"
    query_param="currency_pair=BTC_USDT"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    DELETE /spot/orders/{order_id}

    Cancel a single order

    Spot,portfolio and margin orders are cancelled by default. If trying to cancel cross margin orders or portfolio margin account are used, account must be set to cross_margin

    Parameters

    Name In Type Required Description
    action_mode query string false Processing Mode
    order_id path string true Order ID returned, or user custom ID(i.e., text field).
    currency_pair query string true Currency pair
    account query string false Specify operation account. Default to spot ,portfolio and margin account if not specified. Set to cross_margin to operate against margin account. Portfolio margin account must set to cross_margin only

    # Detailed descriptions

    action_mode: Processing Mode

    When placing an order, different fields are returned based on the action_mode

    • ACK: Asynchronous mode, returns only key order fields
    • RESULT: No clearing information
    • FULL: Full mode (default)

    order_id: Order ID returned, or user custom ID(i.e., text field). Operations based on custom ID can only be checked when the order is in orderbook. When the order is finished, it can be checked within 1 hour after the end of the order. After that, only order ID is accepted.

    Example responses

    200 Response

    {
      "id": "1852454420",
      "text": "t-abc123",
      "amend_text": "-",
      "create_time": "1710488334",
      "update_time": "1710488334",
      "create_time_ms": 1710488334073,
      "update_time_ms": 1710488334074,
      "status": "closed",
      "currency_pair": "BTC_USDT",
      "type": "limit",
      "account": "unified",
      "side": "buy",
      "amount": "0.001",
      "price": "65000",
      "time_in_force": "gtc",
      "iceberg": "0",
      "left": "0",
      "filled_amount": "0.001",
      "fill_price": "63.4693",
      "filled_total": "63.4693",
      "avg_deal_price": "63469.3",
      "fee": "0.00000022",
      "fee_currency": "BTC",
      "point_fee": "0",
      "gt_fee": "0",
      "gt_maker_fee": "0",
      "gt_taker_fee": "0",
      "gt_discount": false,
      "rebated_fee": "0",
      "rebated_fee_currency": "USDT",
      "finish_as": "filled"
    }
    

    Responses

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

    WARNING

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

    # List personal trading history

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/my_trades'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/spot/my_trades"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /spot/my_trades

    List personal trading history

    Spot,portfolio and margin trades are queried by default. If cross margin trades are needed, account must be set to cross_margin

    You can also set from and(or) to to query by time range. If you don't specify from and/or to parameters, only the last 7 days of data will be retured. The range of from and to is not alloed to exceed 30 days. Time range parameters are handled as order finish time.

    Parameters

    Name In Type Required Description
    currency_pair query string false Retrieve results with specified currency pair
    limit query integer false Maximum number of records to be returned in a single list
    page query integer(int32) false Page number
    order_id query string false Filter trades with specified order ID. currency_pair is also required if this field is present
    account query string false Specify operation account. Default to spot ,portfolio and margin account if not specified. Set to cross_margin to operate against margin account. Portfolio margin account must set to cross_margin only
    from query integer(int64) false Start timestamp of the query
    to query integer(int64) false Time range ending, default to current time

    Example responses

    200 Response

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

    Responses

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

    Response Schema

    Status Code 200

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

    # Enumerated Values

    Property Value
    side buy
    side sell
    role taker
    role maker

    WARNING

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

    # Get server current time

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/time'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/spot/time \
      -H 'Accept: application/json'
    
    

    GET /spot/time

    Get server current time

    Example responses

    200 Response

    {
      "server_time": 1597026383085
    }
    

    Responses

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

    Response Schema

    Status Code 200

    SystemTime

    Name Type Description
    » server_time integer(int64) Server current time(ms)

    # Countdown cancel orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/countdown_cancel_all'
    query_param = ''
    body='{"timeout":30,"currency_pair":"BTC_USDT"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/spot/countdown_cancel_all"
    query_param=""
    body_param='{"timeout":30,"currency_pair":"BTC_USDT"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /spot/countdown_cancel_all

    Countdown cancel orders

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

    Body parameter

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

    Parameters

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

    # Detailed descriptions

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

    Example responses

    200 Response

    {
      "triggerTime": "1660039145000"
    }
    

    Responses

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

    Response Schema

    Status Code 200

    triggerTime

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

    WARNING

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

    # Batch modification of orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/amend_batch_orders'
    query_param = ''
    body='[{"order_id":"121212","currency_pair":"BTC_USDT","account":"spot","amount":"1","amend_text":"test"}]'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/spot/amend_batch_orders"
    query_param=""
    body_param='[{"order_id":"121212","currency_pair":"BTC_USDT","account":"spot","amount":"1","amend_text":"test"}]'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /spot/amend_batch_orders

    Batch modification of orders

    Default modification of orders for spot, portfolio, and margin accounts. To modify orders for a cross margin account, the account parameter must be specified as cross_margin. For portfolio margin accounts, the account parameter can only be specified as cross_margin. Currently, only modifications to price or quantity (choose one) are supported. When modifying unfinished orders, a maximum of 5 orders can be batch-modified in one request. The request parameters should be passed in an array format. During batch modification, if one order modification fails, the modification process will continue with the next order. After execution, the response will include corresponding failure information for the failed orders. The sequence of calling for batch order modification should be consistent with the order in the order list. The response content order for batch order modification will also be consistent with the order in the order list.

    Body parameter

    [
      {
        "order_id": "121212",
        "currency_pair": "BTC_USDT",
        "account": "spot",
        "amount": "1",
        "amend_text": "test"
      }
    ]
    

    Parameters

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

    Example responses

    200 Response

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

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) Order modification executed successfully [Inline]

    Response Schema

    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- prefix
    3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
    »» succeeded boolean Whether the batch of orders succeeded
    »» label string Error label, if any, otherwise an empty string
    »» message string Detailed error message, if any, otherwise an empty string
    »» id string Order ID
    »» create_time string Creation time of order
    »» update_time string Last modification time of order
    »» create_time_ms integer(int64) Creation time of order (in milliseconds)
    »» update_time_ms integer(int64) Last modification time of order (in milliseconds)
    »» status string Order status

    - open: to be filled
    - closed: filled
    - cancelled: cancelled
    »» currency_pair string Currency pair
    »» type string Order Type

    - limit : Limit Order
    - market : Market Order
    »» account string Account type. spot - use spot account; margin - use margin account; cross_margin - use cross margin account, unified - unified account
    »» side string Order side
    »» amount string Trade amount
    »» price string Order price
    »» time_in_force string Time in force

    - gtc: GoodTillCancelled
    - ioc: ImmediateOrCancelled, taker only
    - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee
    - fok: FillOrKill, fill either completely or none
    »» iceberg string Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported.
    »» auto_repay boolean Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that:

    1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders.
    2. auto_borrow and auto_repay cannot 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-traded

    1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.
    2. stp_id returns 0 by default for orders that have not been set for STP group
    »» stp_act string Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies

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

    - cn: Cancel newest, Cancel new orders and keep old ones
    - co: Cancel oldest, Cancel old orders and keep new ones
    - cb: Cancel both, Both old and new orders will be cancelled
    »» finish_as string How the order was finished.

    - open: processing
    - filled: filled totally
    - cancelled: manually cancelled
    - ioc: time in force is IOC, finish immediately
    - stp: cancelled because self trade prevention

    # Enumerated Values

    Property Value
    status open
    status closed
    status cancelled
    type limit
    type market
    account spot
    account margin
    account cross_margin
    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

    # Create a price-triggered order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/price_orders'
    query_param = ''
    body='{"trigger":{"price":"100","rule":">=","expiration":3600},"put":{"type":"limit","side":"buy","price":"2.15","amount":"2.00000000","account":"normal","time_in_force":"gtc","text":"api"},"market":"GT_USDT"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/spot/price_orders"
    query_param=""
    body_param='{"trigger":{"price":"100","rule":">=","expiration":3600},"put":{"type":"limit","side":"buy","price":"2.15","amount":"2.00000000","account":"normal","time_in_force":"gtc","text":"api"},"market":"GT_USDT"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /spot/price_orders

    Create a price-triggered order

    Body parameter

    {
      "trigger": {
        "price": "100",
        "rule": ">=",
        "expiration": 3600
      },
      "put": {
        "type": "limit",
        "side": "buy",
        "price": "2.15",
        "amount": "2.00000000",
        "account": "normal",
        "time_in_force": "gtc",
        "text": "api"
      },
      "market": "GT_USDT"
    }
    

    Parameters

    Name In Type Required Description
    body body SpotPriceTriggeredOrder true none
    » trigger body object true none
    »» price body string true Trigger price
    »» rule body string true Price trigger condition
    »» expiration body integer true How long (in seconds) to wait for the condition to be triggered before cancelling the order.
    » put body object true none
    »» type body string false Order type,default to limit
    »» side body string true Order side
    »» price body string true Order price
    »» amount body string true When type is limit, it refers to base currency. For instance, BTC_USDT means BTC
    »» account body string true Trading account type. Portfolio margin account must set to cross_margin
    »» time_in_force body string false time_in_force
    »» text body string false The source of the order, including:
    » market body string true Currency pair

    # Detailed descriptions

    »» rule: Price trigger condition

    • =: triggered when market price larger than or equal to price field

    • <=: triggered when market price less than or equal to price field

    »» type: Order type,default to limit

    • limit : Limit Order
    • market : Market Order

    »» side: Order side

    • buy: buy side
    • sell: sell side

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

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

    »» account: Trading account type. Portfolio margin account must set to cross_margin

    • normal: spot trading
    • margin: margin trading
    • cross_margin: cross_margin trading

    »» time_in_force: time_in_force

    • gtc: GoodTillCancelled
    • ioc: ImmediateOrCancelled, taker only

    »» text: The source of the order, including:

    • web: web
    • api: api
    • app: app

    # Enumerated Values

    Parameter Value
    »» rule >=
    »» rule <=
    »» type limit
    »» type market
    »» side buy
    »» side sell
    »» account normal
    »» account margin
    »» account cross_margin
    »» time_in_force gtc
    »» time_in_force ioc

    Example responses

    201 Response

    {
      "id": 1432329
    }
    

    Responses

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

    Response Schema

    Status Code 201

    TriggerOrderResponse

    Name Type Description
    » id integer(int64) Auto order ID

    WARNING

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

    # Retrieve running auto order list

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/price_orders'
    query_param = 'status=open'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/spot/price_orders"
    query_param="status=open"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /spot/price_orders

    Retrieve running auto order list

    Parameters

    Name In Type Required Description
    status query string true Only list the orders with this status
    market query string false Currency pair
    account query string false Trading account type. Portfolio margin account must set to cross_margin
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0

    # Enumerated Values

    Parameter Value
    status open
    status finished
    account normal
    account margin
    account cross_margin

    Example responses

    200 Response

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

    Responses

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

    WARNING

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

    # Cancel all open orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/price_orders'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/spot/price_orders"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    DELETE /spot/price_orders

    Cancel all open orders

    Parameters

    Name In Type Required Description
    market query string false Currency pair
    account query string false Trading account type. Portfolio margin account must set to cross_margin

    # Enumerated Values

    Parameter Value
    account normal
    account margin
    account cross_margin

    Example responses

    200 Response

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

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) Batch cancellation request accepted. Query order status by listing orders [SpotPriceTriggeredOrder]

    WARNING

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

    # Get a price-triggered order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/price_orders/string'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/spot/price_orders/string"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /spot/price_orders/{order_id}

    Get a price-triggered order

    Parameters

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

    Example responses

    200 Response

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

    Responses

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

    WARNING

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

    # cancel a price-triggered order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/spot/price_orders/string'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/spot/price_orders/string"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    DELETE /spot/price_orders/{order_id}

    cancel a price-triggered order

    Parameters

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

    Example responses

    200 Response

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

    Responses

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

    WARNING

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

    # Margin

    Margin API; margin trading uses spot trading API

    # Margin account list

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/accounts'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/accounts"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/accounts

    Margin account list

    Parameters

    Name In Type Required Description
    currency_pair query string false Currency pair

    Example responses

    200 Response

    [
      {
        "currency_pair": "ETH_BTC",
        "locked": false,
        "risk": "1.1",
        "base": {
          "currency": "ETH",
          "available": "30.1",
          "locked": "0",
          "borrowed": "10.1",
          "interest": "0"
        },
        "quote": {
          "currency": "BTC",
          "available": "10",
          "locked": "0",
          "borrowed": "1.5",
          "interest": "0"
        }
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » None object Margin account detail. base refers to base currency, while `quotes to quote currency
    »» currency_pair string Currency pair
    »» locked boolean Whether account is locked
    »» risk string Current risk rate of margin account
    »» base object Account currency details
    »»» currency string Currency name
    »»» available string Amount suitable for margin trading.
    »»» locked string Locked amount, used in margin trading
    »»» borrowed string Borrowed amount
    »»» interest string Unpaid interests
    »» quote object Account currency details
    »»» currency string Currency name
    »»» available string Amount suitable for margin trading.
    »»» locked string Locked amount, used in margin trading
    »»» borrowed string Borrowed amount
    »»» interest string Unpaid interests

    WARNING

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

    # List margin account balance change history

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/account_book'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/account_book"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/account_book

    List margin account balance change history

    Only transferals from and to margin account are provided for now. Time range allows 30 days at most

    Parameters

    Name In Type Required Description
    currency query string false List records related to specified currency only. If specified, currency_pair is also required.
    currency_pair query string false List records related to specified currency pair. Used in combination with currency. Ignored if currency is not provided
    type query string false Only retrieve changes of the specified type. All types will be returned if not specified.
    from query integer(int64) false Start timestamp of the query
    to query integer(int64) false Time range ending, default to current time
    page query integer(int32) false Page number
    limit query integer false Maximum number of records to be returned in a single list

    Example responses

    200 Response

    [
      {
        "id": "123456",
        "time": "1547633726",
        "time_ms": 1547633726123,
        "currency": "BTC",
        "currency_pair": "BTC_USDT",
        "change": "1.03",
        "balance": "4.59316525194"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » id string Balance change record ID
    » time string Balance changed timestamp
    » time_ms integer(int64) The timestamp of the change (in milliseconds)
    » currency string Currency changed
    » currency_pair string Account currency pair
    » change string Amount changed. Positive value means transferring in, while negative out
    » balance string Balance after change
    » 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

    # Funding account list

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/funding_accounts'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/funding_accounts"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/funding_accounts

    Funding account list

    Parameters

    Name In Type Required Description
    currency query string false Retrieve data of the specified currency

    Example responses

    200 Response

    [
      {
        "currency": "BTC",
        "available": "1.238",
        "locked": "0",
        "lent": "3.32",
        "total_lent": "3.32"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » currency string Currency name
    » available string Available assets to lend, which is identical to spot account available
    » locked string Locked amount. i.e. amount in open loans
    » lent string Outstanding loan amount yet to be repaid
    » total_lent string Amount used for lending. total_lent = lent + locked

    WARNING

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

    # Update user's auto repayment setting

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/auto_repay'
    query_param = 'status=on'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/margin/auto_repay"
    query_param="status=on"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /margin/auto_repay

    Update user's auto repayment setting

    Parameters

    Name In Type Required Description
    status query string true New auto repayment status. on - enabled, off - disabled

    Example responses

    200 Response

    {
      "status": "on"
    }
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) Current auto repayment setting Inline

    Response Schema

    Status Code 200

    AutoRepaySetting

    Name Type Description
    » status string Auto repayment status. on - enabled, off - disabled

    # Enumerated Values

    Property Value
    status on
    status off

    WARNING

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

    # Retrieve user auto repayment setting

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/auto_repay'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/auto_repay"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/auto_repay

    Retrieve user auto repayment setting

    Example responses

    200 Response

    {
      "status": "on"
    }
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) Current auto repayment setting Inline

    Response Schema

    Status Code 200

    AutoRepaySetting

    Name Type Description
    » status string Auto repayment status. on - enabled, off - disabled

    # Enumerated Values

    Property Value
    status on
    status off

    WARNING

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

    # Get the max transferable amount for a specific margin currency

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/transferable'
    query_param = 'currency=BTC'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/transferable"
    query_param="currency=BTC"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/transferable

    Get the max transferable amount for a specific margin currency

    Parameters

    Name In Type Required Description
    currency query string true Retrieve data of the specified currency
    currency_pair query string false Currency pair

    Example responses

    200 Response

    {
      "currency": "ETH",
      "currency_pair": "ETH_USDT",
      "amount": "10000"
    }
    

    Responses

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

    Response Schema

    Status Code 200

    MarginTransferable

    Name Type Description
    » currency string Currency detail
    » currency_pair string Currency pair
    » amount string Max transferable amount

    WARNING

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

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

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/currency_pairs'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/margin/currency_pairs \
      -H 'Accept: application/json'
    
    

    GET /margin/currency_pairs

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

    Example responses

    200 Response

    [
      {
        "id": "ETH_USDT",
        "base": "ETH",
        "quote": "USDT",
        "leverage": 3,
        "min_base_amount": "0.01",
        "min_quote_amount": "100",
        "max_quote_amount": "1000000",
        "status": 1
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » id string Currency pair
    » base string Base currency
    » quote string Quote currency
    » leverage integer Leverage
    » min_base_amount string Minimum base currency to loan, null means no limit
    » min_quote_amount string Minimum quote currency to loan, null means no limit
    » max_quote_amount string Maximum borrowable amount for quote currency. Base currency limit is calculated by quote maximum and market price. null means no limit
    » status integer(int32) Currency pair status

    - 0: disabled
    - 1: enabled

    # Query one single margin currency pair(Deprecated)

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/currency_pairs/BTC_USDT'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/margin/currency_pairs/BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /margin/currency_pairs/{currency_pair}

    Query one single margin currency pair(Deprecated)

    Parameters

    Name In Type Required Description
    currency_pair path string true Margin currency pair

    Example responses

    200 Response

    {
      "id": "ETH_USDT",
      "base": "ETH",
      "quote": "USDT",
      "leverage": 3,
      "min_base_amount": "0.01",
      "min_quote_amount": "100",
      "max_quote_amount": "1000000",
      "status": 1
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » id string Currency pair
    » base string Base currency
    » quote string Quote currency
    » leverage integer Leverage
    » min_base_amount string Minimum base currency to loan, null means no limit
    » min_quote_amount string Minimum quote currency to loan, null means no limit
    » max_quote_amount string Maximum borrowable amount for quote currency. Base currency limit is calculated by quote maximum and market price. null means no limit
    » status integer(int32) Currency pair status

    - 0: disabled
    - 1: enabled

    # Order book of lending loans(Deprecated)

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/funding_book'
    query_param = 'currency=BTC'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/margin/funding_book?currency=BTC \
      -H 'Accept: application/json'
    
    

    GET /margin/funding_book

    Order book of lending loans(Deprecated)

    Parameters

    Name In Type Required Description
    currency query string true Retrieve data of the specified currency

    Example responses

    200 Response

    [
      {
        "rate": "0.002",
        "amount": "320.03",
        "days": 10
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » rate string Loan rate (daily rate)
    » amount string Borrowable amount
    » days integer The number of days till the loan repayment's dateline

    # Lend or borrow(Deprecated)

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/loans'
    query_param = ''
    body='{"side":"borrow","currency":"BTC","rate":"0.002","amount":"1.5","days":10,"auto_renew":true,"currency_pair":"ETH_BTC","fee_rate":"0.18","orig_id":"123424","text":"t-abc"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/margin/loans"
    query_param=""
    body_param='{"side":"borrow","currency":"BTC","rate":"0.002","amount":"1.5","days":10,"auto_renew":true,"currency_pair":"ETH_BTC","fee_rate":"0.18","orig_id":"123424","text":"t-abc"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /margin/loans

    Lend or borrow(Deprecated)

    Body parameter

    {
      "side": "borrow",
      "currency": "BTC",
      "rate": "0.002",
      "amount": "1.5",
      "days": 10,
      "auto_renew": true,
      "currency_pair": "ETH_BTC",
      "fee_rate": "0.18",
      "orig_id": "123424",
      "text": "t-abc"
    }
    

    Parameters

    Name In Type Required Description
    body body Loan true none
    » side body string true Loan side
    » currency body string true Loan currency
    » rate body string false Loan rate. Only rates in [0.0001, 0.01] are supported.
    » amount body string true Loan amount
    » days body integer false Loan days. Only 10 is supported for now
    » auto_renew body boolean false Whether to auto renew the loan upon expiration
    » currency_pair body string false Currency pair. Required if borrowing
    » fee_rate body string false Loan fee rate
    » orig_id body string false Original loan ID of the loan if auto-renewed, otherwise equals to id
    » text body string false User defined custom ID

    # Detailed descriptions

    » rate: Loan rate. Only rates in [0.0001, 0.01] are supported.

    Not required in lending. Market rate calculated from recent rates will be used if not set

    # Enumerated Values

    Parameter Value
    » side lend
    » side borrow

    Example responses

    201 Response

    {
      "id": "123435",
      "create_time": "1548000000",
      "expire_time": "1548100000",
      "side": "borrow",
      "status": "loaned",
      "currency": "BTC",
      "rate": "0.002",
      "amount": "1.5",
      "days": 10,
      "auto_renew": true,
      "currency_pair": "ETH_BTC",
      "left": "0",
      "repaid": "0",
      "paid_interest": "0",
      "unpaid_interest": "0",
      "fee_rate": "0.18",
      "orig_id": "123424",
      "text": "t-abc"
    }
    

    Responses

    Status Meaning Description Schema
    201 Created (opens new window) Loan created Loan

    WARNING

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

    # List all loans(Deprecated)

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/loans'
    query_param = 'status=open&side=lend'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/loans"
    query_param="status=open&side=lend"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/loans

    List all loans(Deprecated)

    Parameters

    Name In Type Required Description
    status query string true Loan status
    side query string true Lend or borrow
    currency query string false Retrieve data of the specified currency
    currency_pair query string false Currency pair
    sort_by query string false Specify which field is used to sort. create_time or rate is supported. Default to create_time
    reverse_sort query boolean false Whether to sort in descending order. Default to true
    page query integer(int32) false Page number
    limit query integer false Maximum number of records to be returned in a single list

    # Enumerated Values

    Parameter Value
    status open
    status loaned
    status finished
    status auto_repaid
    side lend
    side borrow
    sort_by create_time
    sort_by rate

    Example responses

    200 Response

    [
      {
        "id": "123435",
        "create_time": "1548000000",
        "expire_time": "1548100000",
        "side": "borrow",
        "status": "loaned",
        "currency": "BTC",
        "rate": "0.002",
        "amount": "1.5",
        "days": 10,
        "auto_renew": true,
        "currency_pair": "ETH_BTC",
        "left": "0",
        "repaid": "0",
        "paid_interest": "0",
        "unpaid_interest": "0",
        "fee_rate": "0.18",
        "orig_id": "123424",
        "text": "t-abc"
      }
    ]
    

    Responses

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

    WARNING

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

    # Merge multiple lending loans(Deprecated)

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/merged_loans'
    query_param = 'currency=BTC&ids=123,234,345'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/margin/merged_loans"
    query_param="currency=BTC&ids=123,234,345"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /margin/merged_loans

    Merge multiple lending loans(Deprecated)

    Parameters

    Name In Type Required Description
    currency query string true Retrieve data of the specified currency
    ids query string true A comma-separated (,) list of IDs of the loans lent. Maximum of 20 IDs are allowed in a request

    Example responses

    201 Response

    {
      "id": "123435",
      "create_time": "1548000000",
      "expire_time": "1548100000",
      "side": "borrow",
      "status": "loaned",
      "currency": "BTC",
      "rate": "0.002",
      "amount": "1.5",
      "days": 10,
      "auto_renew": true,
      "currency_pair": "ETH_BTC",
      "left": "0",
      "repaid": "0",
      "paid_interest": "0",
      "unpaid_interest": "0",
      "fee_rate": "0.18",
      "orig_id": "123424",
      "text": "t-abc"
    }
    

    Responses

    Status Meaning Description Schema
    201 Created (opens new window) Loans merged Loan

    WARNING

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

    # Retrieve one single loan detail(Deprecated)

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/loans/12345'
    query_param = 'side=lend'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/loans/12345"
    query_param="side=lend"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/loans/{loan_id}

    Retrieve one single loan detail(Deprecated)

    Parameters

    Name In Type Required Description
    side query string true Lend or borrow
    loan_id path string true Loan ID

    # Enumerated Values

    Parameter Value
    side lend
    side borrow

    Example responses

    200 Response

    {
      "id": "123435",
      "create_time": "1548000000",
      "expire_time": "1548100000",
      "side": "borrow",
      "status": "loaned",
      "currency": "BTC",
      "rate": "0.002",
      "amount": "1.5",
      "days": 10,
      "auto_renew": true,
      "currency_pair": "ETH_BTC",
      "left": "0",
      "repaid": "0",
      "paid_interest": "0",
      "unpaid_interest": "0",
      "fee_rate": "0.18",
      "orig_id": "123424",
      "text": "t-abc"
    }
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) List retrieved Loan

    WARNING

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

    # Modify a loan(Deprecated)

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/loans/12345'
    query_param = ''
    body='{"currency":"BTC","side":"borrow","currency_pair":"BTC_USDT","auto_renew":false}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('PATCH', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="PATCH"
    url="/margin/loans/12345"
    query_param=""
    body_param='{"currency":"BTC","side":"borrow","currency_pair":"BTC_USDT","auto_renew":false}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    PATCH /margin/loans/{loan_id}

    Modify a loan(Deprecated)

    Only auto_renew modification is supported currently

    Body parameter

    {
      "currency": "BTC",
      "side": "borrow",
      "currency_pair": "BTC_USDT",
      "auto_renew": false
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » currency body string true Loan currency
    » side body string true Loan side. Possible values are lend and borrow. For LoanRecord patching, only lend is supported
    » auto_renew body boolean true Auto renew
    » currency_pair body string false Currency pair. Required if borrowing
    » loan_id body string false Loan ID. Required for LoanRecord patching
    loan_id path string true Loan ID

    # Enumerated Values

    Parameter Value
    » side lend
    » side borrow

    Example responses

    200 Response

    {
      "id": "123435",
      "create_time": "1548000000",
      "expire_time": "1548100000",
      "side": "borrow",
      "status": "loaned",
      "currency": "BTC",
      "rate": "0.002",
      "amount": "1.5",
      "days": 10,
      "auto_renew": true,
      "currency_pair": "ETH_BTC",
      "left": "0",
      "repaid": "0",
      "paid_interest": "0",
      "unpaid_interest": "0",
      "fee_rate": "0.18",
      "orig_id": "123424",
      "text": "t-abc"
    }
    

    Responses

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

    WARNING

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

    # Cancel lending loan(Deprecated)

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/loans/12345'
    query_param = 'currency=BTC'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/margin/loans/12345"
    query_param="currency=BTC"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    DELETE /margin/loans/{loan_id}

    Cancel lending loan(Deprecated)

    Only lent loans can be cancelled

    Parameters

    Name In Type Required Description
    currency query string true Retrieve data of the specified currency
    loan_id path string true Loan ID

    Example responses

    200 Response

    {
      "id": "123435",
      "create_time": "1548000000",
      "expire_time": "1548100000",
      "side": "borrow",
      "status": "loaned",
      "currency": "BTC",
      "rate": "0.002",
      "amount": "1.5",
      "days": 10,
      "auto_renew": true,
      "currency_pair": "ETH_BTC",
      "left": "0",
      "repaid": "0",
      "paid_interest": "0",
      "unpaid_interest": "0",
      "fee_rate": "0.18",
      "orig_id": "123424",
      "text": "t-abc"
    }
    

    Responses

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

    WARNING

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

    # Repay a loan(Deprecated)

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/loans/12345/repayment'
    query_param = ''
    body='{"currency_pair":"ETH_BTC","currency":"ETH","mode":"partial","amount":"100"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/margin/loans/12345/repayment"
    query_param=""
    body_param='{"currency_pair":"ETH_BTC","currency":"ETH","mode":"partial","amount":"100"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /margin/loans/{loan_id}/repayment

    Repay a loan(Deprecated)

    Body parameter

    {
      "currency_pair": "ETH_BTC",
      "currency": "ETH",
      "mode": "partial",
      "amount": "100"
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » currency_pair body string true Currency pair
    » currency body string true Loan currency
    » mode body string true Repay mode. all - repay all; partial - repay only some portion
    » amount body string false Repay amount. Required in partial mode
    loan_id path string true Loan ID

    # Enumerated Values

    Parameter Value
    » mode all
    » mode partial

    Example responses

    200 Response

    {
      "id": "123435",
      "create_time": "1548000000",
      "expire_time": "1548100000",
      "side": "borrow",
      "status": "loaned",
      "currency": "BTC",
      "rate": "0.002",
      "amount": "1.5",
      "days": 10,
      "auto_renew": true,
      "currency_pair": "ETH_BTC",
      "left": "0",
      "repaid": "0",
      "paid_interest": "0",
      "unpaid_interest": "0",
      "fee_rate": "0.18",
      "orig_id": "123424",
      "text": "t-abc"
    }
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) Loan repaid Loan

    WARNING

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

    # List loan repayment records(Deprecated)

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/loans/12345/repayment'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/loans/12345/repayment"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/loans/{loan_id}/repayment

    List loan repayment records(Deprecated)

    Parameters

    Name In Type Required Description
    loan_id path string true Loan ID

    Example responses

    200 Response

    [
      {
        "id": "12342323",
        "create_time": "1578000000",
        "principal": "100",
        "interest": "2"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » id string Loan record ID
    » create_time string Repayment time
    » principal string Repaid principal
    » interest string Repaid interest

    WARNING

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

    # List repayment records of a specific loan(Deprecated)

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/loan_records'
    query_param = 'loan_id=12345'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/loan_records"
    query_param="loan_id=12345"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/loan_records

    List repayment records of a specific loan(Deprecated)

    Parameters

    Name In Type Required Description
    loan_id query string true Loan ID
    status query string false Loan record status
    page query integer(int32) false Page number
    limit query integer false Maximum number of records to be returned in a single list

    # Enumerated Values

    Parameter Value
    status loaned
    status finished

    Example responses

    200 Response

    [
      {
        "id": "122342323",
        "loan_id": "12840282",
        "create_time": "1548000000",
        "expire_time": "1548100000",
        "status": "loaned",
        "borrow_user_id": "******12",
        "currency": "BTC",
        "rate": "0.002",
        "amount": "1.5",
        "days": 10,
        "auto_renew": false,
        "repaid": "0",
        "paid_interest": "0",
        "unpaid_interest": "0"
      }
    ]
    

    Responses

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

    WARNING

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

    # Get one single loan record(Deprecated)

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/loan_records/12345'
    query_param = 'loan_id=12345'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/loan_records/12345"
    query_param="loan_id=12345"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/loan_records/{loan_record_id}

    Get one single loan record(Deprecated)

    Parameters

    Name In Type Required Description
    loan_id query string true Loan ID
    loan_record_id path string true Loan record ID

    Example responses

    200 Response

    {
      "id": "122342323",
      "loan_id": "12840282",
      "create_time": "1548000000",
      "expire_time": "1548100000",
      "status": "loaned",
      "borrow_user_id": "******12",
      "currency": "BTC",
      "rate": "0.002",
      "amount": "1.5",
      "days": 10,
      "auto_renew": false,
      "repaid": "0",
      "paid_interest": "0",
      "unpaid_interest": "0"
    }
    

    Responses

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

    WARNING

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

    # Modify a loan record(Deprecated)

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/loan_records/12345'
    query_param = ''
    body='{"currency":"BTC","side":"borrow","currency_pair":"BTC_USDT","auto_renew":false}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('PATCH', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="PATCH"
    url="/margin/loan_records/12345"
    query_param=""
    body_param='{"currency":"BTC","side":"borrow","currency_pair":"BTC_USDT","auto_renew":false}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    PATCH /margin/loan_records/{loan_record_id}

    Modify a loan record(Deprecated)

    Only auto_renew modification is supported currently

    Body parameter

    {
      "currency": "BTC",
      "side": "borrow",
      "currency_pair": "BTC_USDT",
      "auto_renew": false
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » currency body string true Loan currency
    » side body string true Loan side. Possible values are lend and borrow. For LoanRecord patching, only lend is supported
    » auto_renew body boolean true Auto renew
    » currency_pair body string false Currency pair. Required if borrowing
    » loan_id body string false Loan ID. Required for LoanRecord patching
    loan_record_id path string true Loan record ID

    # Enumerated Values

    Parameter Value
    » side lend
    » side borrow

    Example responses

    200 Response

    {
      "id": "122342323",
      "loan_id": "12840282",
      "create_time": "1548000000",
      "expire_time": "1548100000",
      "status": "loaned",
      "borrow_user_id": "******12",
      "currency": "BTC",
      "rate": "0.002",
      "amount": "1.5",
      "days": 10,
      "auto_renew": false,
      "repaid": "0",
      "paid_interest": "0",
      "unpaid_interest": "0"
    }
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) Loan record updated LoanRecord

    WARNING

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

    # Get the max borrowable amount for a specific margin currency(Deprecated)

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/borrowable'
    query_param = 'currency=BTC'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/borrowable"
    query_param="currency=BTC"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/borrowable

    Get the max borrowable amount for a specific margin currency(Deprecated)

    Parameters

    Name In Type Required Description
    currency query string true Retrieve data of the specified currency
    currency_pair query string false Currency pair

    Example responses

    200 Response

    {
      "currency": "ETH",
      "currency_pair": "ETH_USDT",
      "amount": "10000"
    }
    

    Responses

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

    Response Schema

    Status Code 200

    MarginBorrowable

    Name Type Description
    » currency string Currency detail
    » currency_pair string Currency pair
    » amount string Max borrowable amount

    WARNING

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

    # Currencies supported by cross margin.

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/cross/currencies'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/margin/cross/currencies \
      -H 'Accept: application/json'
    
    

    GET /margin/cross/currencies

    Currencies supported by cross margin.

    Example responses

    200 Response

    [
      {
        "name": "BTC",
        "rate": "0.0002",
        "prec": "0.000001",
        "discount": "1",
        "min_borrow_amount": "0.01",
        "user_max_borrow_amount": "1000000",
        "total_max_borrow_amount": "10000000",
        "price": "63015.5214",
        "loanable": true,
        "status": 1
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » name string Currency name
    » rate string Minimum lending rate (hourly rate)
    » prec string Currency precision
    » discount string Currency value discount, which is used in total value calculation
    » min_borrow_amount string Minimum currency borrow amount. Unit is currency itself
    » user_max_borrow_amount string Maximum borrow value allowed per user, in USDT
    » total_max_borrow_amount string Maximum borrow value allowed for this currency, in USDT
    » price string Price change between this currency and USDT
    » loanable boolean Whether currency is borrowed
    » status integer status
    - 0 : disable
    - 1 : enable

    # Retrieve detail of one single currency supported by cross margin

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/cross/currencies/BTC'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/margin/cross/currencies/BTC \
      -H 'Accept: application/json'
    
    

    GET /margin/cross/currencies/{currency}

    Retrieve detail of one single currency supported by cross margin

    Parameters

    Name In Type Required Description
    currency path string true Currency name

    Example responses

    200 Response

    {
      "name": "BTC",
      "rate": "0.0002",
      "prec": "0.000001",
      "discount": "1",
      "min_borrow_amount": "0.01",
      "user_max_borrow_amount": "1000000",
      "total_max_borrow_amount": "10000000",
      "price": "63015.5214",
      "loanable": true,
      "status": 1
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » name string Currency name
    » rate string Minimum lending rate (hourly rate)
    » prec string Currency precision
    » discount string Currency value discount, which is used in total value calculation
    » min_borrow_amount string Minimum currency borrow amount. Unit is currency itself
    » user_max_borrow_amount string Maximum borrow value allowed per user, in USDT
    » total_max_borrow_amount string Maximum borrow value allowed for this currency, in USDT
    » price string Price change between this currency and USDT
    » loanable boolean Whether currency is borrowed
    » status integer status
    - 0 : disable
    - 1 : enable

    # Retrieve cross margin account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/cross/accounts'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/cross/accounts"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/cross/accounts

    Retrieve cross margin account

    Example responses

    200 Response

    {
      "user_id": 10001,
      "locked": false,
      "balances": {
        "ETH": {
          "available": "0",
          "freeze": "0",
          "borrowed": "0.075393666654",
          "interest": "0.0000106807603333",
          "negative_liab": "0",
          "futures_pos_liab": "0",
          "equity": "1016.1",
          "total_freeze": "0",
          "total_liab": "0"
        },
        "POINT": {
          "available": "9999999999.017023138734",
          "freeze": "0",
          "borrowed": "0",
          "interest": "0",
          "negative_liab": "0",
          "futures_pos_liab": "0",
          "equity": "12016.1",
          "total_freeze": "0",
          "total_liab": "0"
        },
        "USDT": {
          "available": "0.00000062023",
          "freeze": "0",
          "borrowed": "0",
          "interest": "0",
          "negative_liab": "0",
          "futures_pos_liab": "0",
          "equity": "16.1",
          "total_freeze": "0",
          "total_liab": "0"
        }
      },
      "total": "230.94621713",
      "borrowed": "161.66395521",
      "interest": "0.02290237",
      "risk": "1.4284",
      "total_initial_margin": "1025.0524665088",
      "total_margin_balance": "3382495.944473949183",
      "total_maintenance_margin": "205.01049330176",
      "total_initial_margin_rate": "3299.827135672679",
      "total_maintenance_margin_rate": "16499.135678363399",
      "total_available_margin": "3381470.892007440383",
      "portfolio_margin_total": "3381470.892007440383",
      "portfolio_margin_total_liab": "0",
      "portfolio_margin_total_equity": "100016.1"
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » user_id integer(int64) User ID
    » refresh_time integer(int64) Time of the most recent refresh
    » locked boolean Whether account is locked
    » balances object none
    »» CrossMarginBalance object none
    »»» available string Available amount
    »»» freeze string Locked amount
    »»» borrowed string Borrowed amount
    »»» interest string Unpaid interests
    »»» negative_liab string Negative Liabilities. Formula:Min[available+total+unrealized_pnl,0]
    »»» futures_pos_liab string Borrowing to Open Positions in Futures
    »»» equity string Equity. Formula: available + freeze - borrowed + futures account's total + unrealized_pnl
    »»» total_freeze string Total freeze. Formula: freeze + position_initial_margin + order_margin
    »»» total_liab string Total liabilities. Formula: Max[Abs[Min[quity - total_freeze,0], borrowed]] - futures_pos_liab
    »» total string Total account value in USDT, i.e., the sum of all currencies' (available+freeze)*price*discount
    »» borrowed string Total borrowed value in USDT, i.e., the sum of all currencies' borrowed*price*discount
    »» interest string Total unpaid interests in USDT, i.e., the sum of all currencies' interest*price*discount
    »» risk string Risk rate. When it belows 110%, liquidation will be triggered. Calculation formula: total / (borrowed+interest)
    »» total_initial_margin string Total initial margin
    »» total_margin_balance string Total Margin Balance (∑(positive equity * index price * discount) + ∑(negative equity * index price))
    »» total_maintenance_margin string Total maintenance margin
    »» total_initial_margin_rate string Total initial margin rate
    »» total_maintenance_margin_rate string Total maintenance margin rate
    »» total_available_margin string Total available margin
    »» portfolio_margin_total string Total amount of the portfolio margin account
    »» portfolio_margin_total_liab string Total liabilities of the portfolio margin account
    »» portfolio_margin_total_equity string Total equity of the portfolio margin account

    WARNING

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

    # Retrieve cross margin account change history

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/cross/account_book'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/cross/account_book"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/cross/account_book

    Retrieve cross margin account change history

    Record time range cannot exceed 30 days

    Parameters

    Name In Type Required Description
    currency query string false Filter by currency
    from query integer(int64) false Start timestamp of the query
    to query integer(int64) false Time range ending, default to current time
    page query integer(int32) false Page number
    limit query integer false Maximum number of records to be returned in a single list
    type query string false Only retrieve changes of the specified type. All types will be returned if not specified.

    Example responses

    200 Response

    [
      {
        "id": "123456",
        "time": 1547633726123,
        "currency": "BTC",
        "change": "1.03",
        "balance": "4.59316525194",
        "type": "in"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » id string Balance change record ID
    » time integer(int64) The timestamp of the change (in milliseconds)
    » currency string Currency changed
    » change string Amount changed. Positive value means transferring in, while negative out
    » balance string Balance after change
    » type string Account 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

    # Create a cross margin borrow loan

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/cross/loans'
    query_param = ''
    body='{"currency":"EOS","amount":"110.553635","text":"web"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/margin/cross/loans"
    query_param=""
    body_param='{"currency":"EOS","amount":"110.553635","text":"web"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /margin/cross/loans

    Create a cross margin borrow loan

    Borrow amount cannot be less than currency minimum borrow amount

    Body parameter

    {
      "currency": "EOS",
      "amount": "110.553635",
      "text": "web"
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » currency body string true Currency name
    » amount body string true Borrowed amount
    » text body string false User defined custom ID

    Example responses

    200 Response

    {
      "id": "17",
      "create_time": 1620381696159,
      "update_time": 1620381696159,
      "currency": "EOS",
      "amount": "110.553635",
      "text": "web",
      "status": 2,
      "repaid": "110.506649705159",
      "repaid_interest": "0.046985294841",
      "unpaid_interest": "0.0000074393366667"
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » id string Loan record ID
    » create_time integer(int64) Creation timestamp, in milliseconds
    » update_time integer(int64) Update timestamp, in milliseconds
    » currency string Currency name
    » amount string Borrowed amount
    » text string User defined custom ID
    » status integer(int32) Deprecated. Currently, all statuses have been set to 2.
    Borrow loan status, which includes:

    - 1: failed to borrow
    - 2: borrowed but not repaid
    - 3: repayment complete
    » repaid string Repaid amount
    » repaid_interest string Repaid interest
    » unpaid_interest string Outstanding interest yet to be paid

    # Enumerated Values

    Property Value
    status 1
    status 2
    status 3

    WARNING

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

    # List cross margin borrow history

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/cross/loans'
    query_param = 'status=0'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/cross/loans"
    query_param="status=0"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/cross/loans

    List cross margin borrow history

    Sort by creation time in descending order by default. Set reverse=false to return ascending results.

    Parameters

    Name In Type Required Description
    status query integer true Filter by status. Supported values are 2 and 3. (deprecated.)
    currency query string false Filter by currency
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0
    reverse query boolean false Whether to sort in descending order, which is the default. Set reverse=false to return ascending results

    Example responses

    200 Response

    [
      {
        "id": "17",
        "create_time": 1620381696159,
        "update_time": 1620381696159,
        "currency": "EOS",
        "amount": "110.553635",
        "text": "web",
        "status": 2,
        "repaid": "110.506649705159",
        "repaid_interest": "0.046985294841",
        "unpaid_interest": "0.0000074393366667"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » id string Loan record ID
    » create_time integer(int64) Creation timestamp, in milliseconds
    » update_time integer(int64) Update timestamp, in milliseconds
    » currency string Currency name
    » amount string Borrowed amount
    » text string User defined custom ID
    » status integer(int32) Deprecated. Currently, all statuses have been set to 2.
    Borrow loan status, which includes:

    - 1: failed to borrow
    - 2: borrowed but not repaid
    - 3: repayment complete
    » repaid string Repaid amount
    » repaid_interest string Repaid interest
    » unpaid_interest string Outstanding interest yet to be paid

    # Enumerated Values

    Property Value
    status 1
    status 2
    status 3

    WARNING

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

    # Retrieve single borrow loan detail

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/cross/loans/12345'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/cross/loans/12345"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/cross/loans/{loan_id}

    Retrieve single borrow loan detail

    Parameters

    Name In Type Required Description
    loan_id path string true Borrow loan ID

    Example responses

    200 Response

    {
      "id": "17",
      "create_time": 1620381696159,
      "update_time": 1620381696159,
      "currency": "EOS",
      "amount": "110.553635",
      "text": "web",
      "status": 2,
      "repaid": "110.506649705159",
      "repaid_interest": "0.046985294841",
      "unpaid_interest": "0.0000074393366667"
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » id string Loan record ID
    » create_time integer(int64) Creation timestamp, in milliseconds
    » update_time integer(int64) Update timestamp, in milliseconds
    » currency string Currency name
    » amount string Borrowed amount
    » text string User defined custom ID
    » status integer(int32) Deprecated. Currently, all statuses have been set to 2.
    Borrow loan status, which includes:

    - 1: failed to borrow
    - 2: borrowed but not repaid
    - 3: repayment complete
    » repaid string Repaid amount
    » repaid_interest string Repaid interest
    » unpaid_interest string Outstanding interest yet to be paid

    # Enumerated Values

    Property Value
    status 1
    status 2
    status 3

    WARNING

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

    # Cross margin repayments

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/cross/repayments'
    query_param = ''
    body='{"currency":"EOS","amount":"110.553635"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/margin/cross/repayments"
    query_param=""
    body_param='{"currency":"EOS","amount":"110.553635"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /margin/cross/repayments

    Cross margin repayments

    When the liquidity of the currency is insufficient and the transaction risk is high, the currency will be disabled, and funds cannot be transferred.When the available balance of cross-margin is insufficient, the balance of the spot account can be used for repayment. Please ensure that the balance of the spot account is sufficient, and system uses cross-margin account for repayment first

    Body parameter

    {
      "currency": "EOS",
      "amount": "110.553635"
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » currency body string true Repayment currency
    » amount body string true Repayment amount

    Example responses

    200 Response

    [
      {
        "id": "17",
        "create_time": 1620381696159,
        "update_time": 1620381696159,
        "currency": "EOS",
        "amount": "110.553635",
        "text": "web",
        "status": 2,
        "repaid": "110.506649705159",
        "repaid_interest": "0.046985294841",
        "unpaid_interest": "0.0000074393366667"
      }
    ]
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) Loan repaid [Inline]

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » id string Loan record ID
    » create_time integer(int64) Creation timestamp, in milliseconds
    » update_time integer(int64) Update timestamp, in milliseconds
    » currency string Currency name
    » amount string Borrowed amount
    » text string User defined custom ID
    » status integer(int32) Deprecated. Currently, all statuses have been set to 2.
    Borrow loan status, which includes:

    - 1: failed to borrow
    - 2: borrowed but not repaid
    - 3: repayment complete
    » repaid string Repaid amount
    » repaid_interest string Repaid interest
    » unpaid_interest string Outstanding interest yet to be paid

    # Enumerated Values

    Property Value
    status 1
    status 2
    status 3

    WARNING

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

    # Retrieve cross margin repayments

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/cross/repayments'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/cross/repayments"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/cross/repayments

    Retrieve cross margin repayments

    Sort by creation time in descending order by default. Set reverse=false to return ascending results.

    Parameters

    Name In Type Required Description
    currency query string false none
    loan_id query string false none
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0
    reverse query boolean false Whether to sort in descending order, which is the default. Set reverse=false to return ascending results

    Example responses

    200 Response

    [
      {
        "id": "51",
        "create_time": 1620696347990,
        "loan_id": "30",
        "currency": "BTC",
        "principal": "5.385542",
        "interest": "0.000044879516",
        "repayment_type": "auto_repay"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » id string Loan record ID
    » create_time integer(int64) Repayment time
    » loan_id string Loan record ID
    » currency string Currency name
    » principal string Repaid principal
    » interest string Repaid interest
    » repayment_type string Repayment type: none - no repayment type, manual_repay - manual repayment, auto_repay - automatic repayment, cancel_auto_repay - automatic repayment after cancellation

    WARNING

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

    # Interest records for the cross margin account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/cross/interest_records'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/cross/interest_records"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/cross/interest_records

    Interest records for the cross margin account

    Parameters

    Name In Type Required Description
    currency query string false Retrieve data of the specified currency
    page query integer(int32) false Page number
    limit query integer(int32) false Maximum response items. Default: 100, minimum: 1, Maximum: 100
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp

    Example responses

    200 Response

    [
      {
        "status": 1,
        "currency_pair": "BTC_USDT",
        "currency": "USDT",
        "actual_rate": "0.00000236",
        "interest": "0.00006136",
        "type": "platform",
        "create_time": 1673247054000
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Get the max transferable amount for a specific cross margin currency

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/cross/transferable'
    query_param = 'currency=BTC'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/cross/transferable"
    query_param="currency=BTC"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/cross/transferable

    Get the max transferable amount for a specific cross margin currency

    Parameters

    Name In Type Required Description
    currency query string true Retrieve data of the specified currency

    Example responses

    200 Response

    {
      "currency": "ETH",
      "amount": "10000"
    }
    

    Responses

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

    Response Schema

    Status Code 200

    CrossMarginTransferable

    Name Type Description
    » currency string Currency detail
    » amount string Max transferable amount

    WARNING

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

    # Estimated interest rates

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/cross/estimate_rate'
    query_param = 'currencies=BTC,GT'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/cross/estimate_rate"
    query_param="currencies=BTC,GT"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/cross/estimate_rate

    Estimated interest rates

    Please note that the interest rates are subject to change based on the borrowing and lending demand, and therefore, the provided rates may not be entirely accurate.

    Parameters

    Name In Type Required Description
    currencies query array[string] true An array of up to 10 specifying the currency name

    Example responses

    200 Response

    {
      "BTC": "0.000002",
      "GT": "0.000001"
    }
    

    Responses

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

    Response Schema

    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

    # Get the max borrowable amount for a specific cross margin currency

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/cross/borrowable'
    query_param = 'currency=BTC'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/cross/borrowable"
    query_param="currency=BTC"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/cross/borrowable

    Get the max borrowable amount for a specific cross margin currency

    Parameters

    Name In Type Required Description
    currency query string true Retrieve data of the specified currency

    Example responses

    200 Response

    {
      "currency": "ETH",
      "amount": "10000"
    }
    

    Responses

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

    Response Schema

    Status Code 200

    CrossMarginBorrowable

    Name Type Description
    » currency string Currency detail
    » amount string Max borrowable amount

    WARNING

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

    # MarginUni

    Margin API; margin trading uses spot trading API

    # List lending markets

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/uni/currency_pairs'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/margin/uni/currency_pairs \
      -H 'Accept: application/json'
    
    

    GET /margin/uni/currency_pairs

    List lending markets

    Example responses

    200 Response

    [
      {
        "currency_pair": "AE_USDT",
        "base_min_borrow_amount": "100",
        "quote_min_borrow_amount": "100",
        "leverage": "3"
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Get detail of lending market

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/uni/currency_pairs/AE_USDT'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/margin/uni/currency_pairs/AE_USDT \
      -H 'Accept: application/json'
    
    

    GET /margin/uni/currency_pairs/{currency_pair}

    Get detail of lending market

    Parameters

    Name In Type Required Description
    currency_pair path string true Currency pair

    Example responses

    200 Response

    {
      "currency_pair": "AE_USDT",
      "base_min_borrow_amount": "100",
      "quote_min_borrow_amount": "100",
      "leverage": "3"
    }
    

    Responses

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

    Response Schema

    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

    # Estimate interest Rate

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/uni/estimate_rate'
    query_param = 'currencies=BTC,GT'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/uni/estimate_rate"
    query_param="currencies=BTC,GT"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/uni/estimate_rate

    Estimate interest Rate

    Please note that the interest rates are subject to change based on the borrowing and lending demand, and therefore, the provided rates may not be entirely accurate.

    Parameters

    Name In Type Required Description
    currencies query array[string] true An array of up to 10 specifying the currency name

    Example responses

    200 Response

    {
      "BTC": "0.000002",
      "GT": "0.000001"
    }
    

    Responses

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

    Response Schema

    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

    # Borrow or repay

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/uni/loans'
    query_param = ''
    body='{"currency":"BTC","amount":"0.1","type":"borrow","currency_pair":"BTC_USDT","repaid_all":false}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/margin/uni/loans"
    query_param=""
    body_param='{"currency":"BTC","amount":"0.1","type":"borrow","currency_pair":"BTC_USDT","repaid_all":false}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /margin/uni/loans

    Borrow or repay

    Body parameter

    {
      "currency": "BTC",
      "amount": "0.1",
      "type": "borrow",
      "currency_pair": "BTC_USDT",
      "repaid_all": false
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » currency body string true Currency
    » type body string true type: borrow - borrow, repay - repay
    » amount body string true The amount of lending or repaying
    » repaid_all body boolean false Full repayment. Repay operation only. If the value is true, the amount will be ignored and the loan will be repaid in full.
    » currency_pair body string true Currency pair

    # Enumerated Values

    Parameter Value
    » type borrow
    » type repay

    Responses

    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

    # List loans

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/uni/loans'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/uni/loans"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/uni/loans

    List loans

    Parameters

    Name In Type Required Description
    currency_pair query string false Currency pair
    currency query string false Retrieve data of the specified currency
    page query integer(int32) false Page number
    limit query integer(int32) false Maximum response items. Default: 100, minimum: 1, Maximum: 100

    Example responses

    200 Response

    [
      {
        "currency": "USDT",
        "currency_pari": "GT_USDT",
        "amount": "1",
        "type": "margin",
        "change_time": 1673247054000,
        "create_time": 1673247054000
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Get load records

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/uni/loan_records'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/uni/loan_records"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/uni/loan_records

    Get load records

    Parameters

    Name In Type Required Description
    type query string false type: borrow - borrow, repay - repay
    currency query string false Retrieve data of the specified currency
    currency_pair query string false Currency pair
    page query integer(int32) false Page number
    limit query integer(int32) false Maximum response items. Default: 100, minimum: 1, Maximum: 100

    # Enumerated Values

    Parameter Value
    type borrow
    type repay

    Example responses

    200 Response

    [
      {
        "type": "borrow",
        "currency_pair": "AE_USDT",
        "currency": "USDT",
        "amount": "1000",
        "create_time": 1673247054000
      }
    ]
    

    Responses

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

    Response Schema

    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

    # List interest records

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/margin/uni/interest_records'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/uni/interest_records"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/uni/interest_records

    List interest records

    Parameters

    Name In Type Required Description
    currency_pair query string false Currency pair
    currency query string false Retrieve data of the specified currency
    page query integer(int32) false Page number
    limit query integer false Maximum number of records to be returned in a single list
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp

    Example responses

    200 Response

    [
      {
        "status": 1,
        "currency_pair": "BTC_USDT",
        "currency": "USDT",
        "actual_rate": "0.00000236",
        "interest": "0.00006136",
        "type": "platform",
        "create_time": 1673247054000
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Get maximum borrowable

    Code samples

    # coding: utf-8
    import 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&currency_pair=BTC_USDT'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/margin/uni/borrowable"
    query_param="currency=BTC&currency_pair=BTC_USDT"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /margin/uni/borrowable

    Get maximum borrowable

    Parameters

    Name In Type Required Description
    currency query string true Retrieve data of the specified currency
    currency_pair query string true Currency pair

    Example responses

    200 Response

    {
      "currency": "AE",
      "borrowable": "1123.344",
      "currency_pair": "AE_USDT"
    }
    

    Responses

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

    Response Schema

    Status Code 200

    MaxUniBorrowable

    Name Type Description
    » currency string Currency
    » currency_pair string Currency pair
    » borrowable string Maximum borrowable

    WARNING

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

    # Flash_swap

    Flash swap

    # List All Supported Currencies In Flash Swap (deprecated)

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/flash_swap/currencies'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/flash_swap/currencies \
      -H 'Accept: application/json'
    
    

    GET /flash_swap/currencies

    List All Supported Currencies In Flash Swap (deprecated)

    Example responses

    200 Response

    [
      {
        "currency": "BTC",
        "min_amount": "0.000001",
        "max_amount": "1.000000",
        "swappable": [
          "USDT",
          "GT",
          "ETH"
        ]
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » None object Currencies supported in flash swap
    »» currency string Currency name
    »» min_amount string Minimum amount required in flash swap
    »» max_amount string Maximum amount allowed in flash swap
    »» swappable array Currencies which can be swapped to from this currency

    # List All Supported Currency Pairs In Flash Swap

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/flash_swap/currency_pairs'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/flash_swap/currency_pairs \
      -H 'Accept: application/json'
    
    

    GET /flash_swap/currency_pairs

    List All Supported Currency Pairs In Flash Swap

    BTC_GT represents selling BTC and buying GT. The limits for each currency may vary across different currency pairs.

    It is not necessary that two currencies that can be swapped instantaneously can be exchanged with each other. For example, it is possible to sell BTC and buy GT, but it does not necessarily mean that GT can be sold to buy BTC.

    Parameters

    Name In Type Required Description
    currency query string false Retrieve data of the specified currency

    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"
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Create a flash swap order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/flash_swap/orders'
    query_param = ''
    body='{"preview_id":"4564564","sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT","buy_amount":"10"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/flash_swap/orders"
    query_param=""
    body_param='{"preview_id":"4564564","sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT","buy_amount":"10"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /flash_swap/orders

    Create a flash swap order

    Initiate a flash swap preview in advance because order creation requires a preview result

    Body parameter

    {
      "preview_id": "4564564",
      "sell_currency": "BTC",
      "sell_amount": "0.1",
      "buy_currency": "USDT",
      "buy_amount": "10"
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » preview_id body string true Preview result ID
    » sell_currency body string true The name of the asset being sold, as obtained from the "GET /flash_swap/currency_pairs" API, which retrieves a list of supported flash swap currency pairs.
    » sell_amount body string true Amount to sell (based on the preview result)
    » buy_currency body string true The name of the asset being purchased, as obtained from the "GET /flash_swap/currency_pairs" API, which provides a list of supported flash swap currency pairs.
    » buy_amount body string true Amount to buy (based on the preview result)

    Example responses

    201 Response

    {
      "id": 54646,
      "create_time": 1651116876378,
      "update_time": 1651116876378,
      "user_id": 11135567,
      "sell_currency": "BTC",
      "sell_amount": "0.01",
      "buy_currency": "USDT",
      "buy_amount": "10",
      "price": "100",
      "status": 1
    }
    

    Responses

    Status Meaning Description Schema
    201 Created (opens new window) The flash swap order is created successfully Inline

    Response Schema

    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 status

    1 - success
    2 - failure

    WARNING

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

    # List all flash swap orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/flash_swap/orders'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/flash_swap/orders"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /flash_swap/orders

    List all flash swap orders

    Parameters

    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

    # Detailed descriptions

    status: Flash swap order status

    1 - success 2 - failure

    reverse: If results are sorted by id in reverse order. Default to true

    • true: sort by id in descending order(recent first)
    • false: sort by id in ascending order(oldest first)

    Example responses

    200 Response

    [
      {
        "id": 54646,
        "create_time": 1651116876378,
        "update_time": 1651116876378,
        "user_id": 11135567,
        "sell_currency": "BTC",
        "sell_amount": "0.01",
        "buy_currency": "USDT",
        "buy_amount": "10",
        "price": "100",
        "status": 1
      }
    ]
    

    Responses

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

    Response Schema

    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 status

    1 - success
    2 - failure

    WARNING

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

    # Get a single flash swap order's detail

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/flash_swap/orders/1'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/flash_swap/orders/1"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /flash_swap/orders/{order_id}

    Get a single flash swap order's detail

    Parameters

    Name In Type Required Description
    order_id path integer true Flash swap order ID

    Example responses

    200 Response

    {
      "id": 54646,
      "create_time": 1651116876378,
      "update_time": 1651116876378,
      "user_id": 11135567,
      "sell_currency": "BTC",
      "sell_amount": "0.01",
      "buy_currency": "USDT",
      "buy_amount": "10",
      "price": "100",
      "status": 1
    }
    

    Responses

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

    Response Schema

    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 status

    1 - success
    2 - failure

    WARNING

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

    # Initiate a flash swap order preview

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/flash_swap/orders/preview'
    query_param = ''
    body='{"sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/flash_swap/orders/preview"
    query_param=""
    body_param='{"sell_currency":"BTC","sell_amount":"0.1","buy_currency":"USDT"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /flash_swap/orders/preview

    Initiate a flash swap order preview

    Body parameter

    {
      "sell_currency": "BTC",
      "sell_amount": "0.1",
      "buy_currency": "USDT"
    }
    

    Parameters

    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.

    # Detailed descriptions

    » sell_amount: Amount to sell. It is required to choose one parameter between sell_amount and buy_amount

    » buy_amount: Amount to buy. It is required to choose one parameter between sell_amount and buy_amount

    Example responses

    200 Response

    {
      "preview_id": "3453434",
      "sell_currency": "BTC",
      "sell_amount": "0.1",
      "buy_currency": "USDT",
      "buy_amount": "10",
      "price": "100"
    }
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) The flash swap order successfully previewed Inline

    Response Schema

    Status Code 200

    Initiate a flash swap order preview

    Name Type Description
    » preview_id string Preview result ID
    » sell_currency string Currency to sell which can be retrieved from supported currency list API GET /flash_swap/currencies
    » sell_amount string Amount to sell
    » buy_currency string Currency to buy which can be retrieved from supported currency list API GET /flash_swap/currencies
    » buy_amount string Amount to buy
    » price string Price

    WARNING

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

    # Futures

    Futures contract API

    # List all futures contracts

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/contracts'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/futures/usdt/contracts \
      -H 'Accept: application/json'
    
    

    GET /futures/{settle}/contracts

    List all futures contracts

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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"
      }
    ]
    

    Responses

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

    # Get a single contract

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/contracts/BTC_USDT'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/futures/usdt/contracts/BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /futures/{settle}/contracts/{contract}

    Get a single contract

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract path string true Futures contract

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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"
    }
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) Contract information Contract

    # Futures order book

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/order_book'
    query_param = 'contract=BTC_USDT'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/futures/usdt/order_book?contract=BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /futures/{settle}/order_book

    Futures order book

    Bids will be sorted by price from high to low, while asks sorted reversely

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract query string true Futures contract
    interval query string false Order depth. 0 means no aggregation is applied. default to 0
    limit query integer false Maximum number of order depth data in asks or bids
    with_id query boolean false Whether the order book update ID will be returned. This ID increases by 1 on every order book update

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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
        }
      ]
    }
    

    Responses

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

    Response Schema

    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

    # Futures trading history

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/trades'
    query_param = 'contract=BTC_USDT'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/futures/usdt/trades?contract=BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /futures/{settle}/trades

    Futures trading history

    Parameters

    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

    # Detailed descriptions

    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.

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    [
      {
        "id": 121234231,
        "create_time": 1514764800,
        "contract": "BTC_USDT",
        "size": -100,
        "price": "100.123"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » id integer(int64) Trade ID
    » create_time number(double) Trading time
    » create_time_ms number(double) Trading time, with milliseconds set to 3 decimal places.
    » contract string Futures contract
    » size integer(int64) Trading size
    » price string Trading price (quote currency)
    » is_internal boolean Whether internal trade. Internal trade refers to the takeover of liquidation orders by the insurance fund and ADL users. Since it is not a normal matching on the market depth, the transaction price may deviate, and it will not be recorded in the K-line. If it is not an internal trade, this field will not be returned.

    # Get futures candlesticks

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/candlesticks'
    query_param = 'contract=BTC_USDT'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/futures/usdt/candlesticks?contract=BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /futures/{settle}/candlesticks

    Get futures candlesticks

    Return specified contract candlesticks. If prefix contract with mark_, the contract's mark price candlesticks are returned; if prefix with index_, index price candlesticks will be returned.

    Maximum of 2000 points are returned in one query. Be sure not to exceed the limit when specifying from, to and interval

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract query string true Futures contract
    from query integer(int64) false Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified
    to query integer(int64) false End time of candlesticks, formatted in Unix timestamp in seconds. Default to current time
    limit query integer false Maximum recent data points to return. limit is conflicted with from and to. If either from or to is specified, request will be rejected.
    interval query string false Interval time between data points. Note that 1w means natual week(Mon-Sun), while 7d means every 7d since unix 0. Note that 30d means 1 natual month, not 30 days

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    [
      {
        "t": 1539852480,
        "v": 97151,
        "c": "1.032",
        "h": "1.032",
        "l": "1.032",
        "o": "1.032",
        "sum": "3580"
      }
    ]
    

    Responses

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

    Response Schema

    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)

    # Premium Index K-Line

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/premium_index'
    query_param = 'contract=BTC_USDT'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/futures/usdt/premium_index?contract=BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /futures/{settle}/premium_index

    Premium Index K-Line

    Maximum of 1000 points can be returned in a query. Be sure not to exceed the limit when specifying from, to and interval

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract query string true Futures contract
    from query integer(int64) false Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified
    to query integer(int64) false End time of candlesticks, formatted in Unix timestamp in seconds. Default to current time
    limit query integer false Maximum recent data points to return. limit is conflicted with from and to. If either from or to is specified, request will be rejected.
    interval query string false Interval time between data points

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    [
      {
        "t": 1539852480,
        "c": "0",
        "h": "0.00023",
        "l": "0",
        "o": "0"
      }
    ]
    

    Responses

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

    Response Schema

    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

    # List futures tickers

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/tickers'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/futures/usdt/tickers \
      -H 'Accept: application/json'
    
    

    GET /futures/{settle}/tickers

    List futures tickers

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract query string false Futures contract, return related data only if specified

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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",
        "lowest_ask": "34217.9"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » contract string Futures contract
    » last string Last trading price
    » change_percentage string Change percentage.
    » total_size string Contract total size
    » low_24h string Lowest trading price in recent 24h
    » high_24h string Highest trading price in recent 24h
    » volume_24h string Trade size in recent 24h
    » volume_24h_btc string Trade volumes in recent 24h in BTC(deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead)
    » volume_24h_usd string Trade volumes in recent 24h in USD(deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead)
    » volume_24h_base string Trade volume in recent 24h, in base currency
    » volume_24h_quote string Trade volume in recent 24h, in quote currency
    » volume_24h_settle string Trade volume in recent 24h, in settle currency
    » mark_price string Recent mark price
    » funding_rate string Funding rate
    » funding_rate_indicative string Indicative Funding rate in next period
    » index_price string Index price
    » quanto_base_rate string Exchange rate of base currency and settlement currency in Quanto contract. Does not exists in contracts of other types
    » basis_rate string Basis rate
    » basis_value string Basis value
    » lowest_ask string Recent lowest ask
    » highest_bid string Recent highest bid

    # Funding rate history

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/funding_rate'
    query_param = 'contract=BTC_USDT'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/futures/usdt/funding_rate?contract=BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /futures/{settle}/funding_rate

    Funding rate history

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    [
      {
        "t": 1543968000,
        "r": "0.000157"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » t integer(int64) Unix timestamp in seconds
    » r string Funding rate

    # Futures insurance balance history

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/insurance'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/futures/usdt/insurance \
      -H 'Accept: application/json'
    
    

    GET /futures/{settle}/insurance

    Futures insurance balance history

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    [
      {
        "t": 1543968000,
        "b": "83.0031"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » t integer(int64) Unix timestamp in seconds
    » b string Insurance balance

    # Futures stats

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/contract_stats'
    query_param = 'contract=BTC_USDT'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/futures/usdt/contract_stats?contract=BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /futures/{settle}/contract_stats

    Futures stats

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Get index constituents

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/index_constituents/BTC_USDT'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/futures/usdt/index_constituents/BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /futures/{settle}/index_constituents/{index}

    Get index constituents

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    index path string true Index name

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    {
      "index": "BTC_USDT",
      "constituents": [
        {
          "exchange": "Binance",
          "symbols": [
            "BTC_USDT"
          ]
        },
        {
          "exchange": "Gate.io",
          "symbols": [
            "BTC_USDT"
          ]
        },
        {
          "exchange": "Huobi",
          "symbols": [
            "BTC_USDT"
          ]
        }
      ]
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » index string Index name
    » constituents array Constituents
    »» IndexConstituent object none
    »»» exchange string Exchange
    »»» symbols array Symbol list

    # Retrieve liquidation history

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/liq_orders'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/futures/usdt/liq_orders \
      -H 'Accept: application/json'
    
    

    GET /futures/{settle}/liq_orders

    Retrieve liquidation history

    Interval between from and to cannot exceeds 3600. Some private fields will not be returned in public endpoints. Refer to field description for detail.

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract query string false Futures contract, return related data only if specified
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp
    limit query integer false Maximum number of records to be returned in a single list

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    [
      {
        "time": 1548654951,
        "contract": "BTC_USDT",
        "size": 600,
        "order_price": "3405",
        "fill_price": "3424",
        "left": 0
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » time integer(int64) Liquidation time
    » contract string Futures contract
    » size integer(int64) User position size
    » order_price string Liquidation order price
    » fill_price string Liquidation order average taker price
    » left integer(int64) System liquidation order maker size

    # List risk limit tiers

    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 = 'contract=BTC_USDT'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/futures/usdt/risk_limit_tiers?contract=BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /futures/{settle}/risk_limit_tiers

    List risk limit tiers

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract query string true Futures contract

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    [
      {
        "maintenance_rate": "0.01",
        "tier": 1,
        "initial_rate": "0.02",
        "leverage_max": "50",
        "risk_limit": "500000"
      },
      {
        "initial_rate": "0.03",
        "maintenance_rate": "0.02",
        "tier": 2,
        "risk_limit": "1000000",
        "leverage_max": "33.33"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » 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

    # Query futures account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/accounts'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/futures/usdt/accounts"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /futures/{settle}/accounts

    Query futures account

    Parameters

    Name In Type Required Description
    settle path string true Settle currency

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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,
      "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"
      }
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » total string total is the balance after the user's accumulated deposit, withdraw, profit and loss (including realized profit and loss, fund, fee and referral rebate), excluding unrealized profit and loss.
    total = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund)
    » unrealised_pnl string Unrealized PNL
    » position_margin string Position margin
    » order_margin string Order margin of unfinished orders
    » available string The available balance for transferring or trading(including bonus. Bonus can't be be withdrawn. The transfer amount needs to deduct the bonus)
    » point string POINT amount
    » currency string Settle currency
    » in_dual_mode boolean Whether dual mode is enabled
    » enable_credit boolean Whether portfolio margin account mode is enabled
    » position_initial_margin string Initial margin position, applicable to the portfolio margin account model
    » maintenance_margin string Maintenance margin position, applicable to the portfolio margin account model
    » bonus string Perpetual Contract Bonus
    » history object Statistical data
    »» dnw string total amount of deposit and withdraw
    »» pnl string total amount of trading profit and loss
    »» fee string total amount of fee
    »» refr string total amount of referrer rebates
    »» fund string total amount of funding costs
    »» point_dnw string total amount of point deposit and withdraw
    »» point_fee string total amount of point fee
    »» point_refr string total amount of referrer rebates of point fee
    »» bonus_dnw string total amount of perpetual contract bonus transfer
    »» bonus_offset string total amount of perpetual contract bonus deduction

    WARNING

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

    # Query account book

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/account_book'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/futures/usdt/account_book"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /futures/{settle}/account_book

    Query account book

    If the contract field is provided, it can only filter records that include this field after 2023-10-30.

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract query string false Futures contract, return related data only if specified
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp
    type query string false Changing Type:

    # Detailed descriptions

    type: Changing Type:

    • dnw: Deposit & Withdraw
    • pnl: Profit & Loss by reducing position
    • fee: Trading fee
    • refr: Referrer rebate
    • fund: Funding
    • point_dnw: POINT Deposit & Withdraw
    • point_fee: POINT Trading fee
    • point_refr: POINT Referrer rebate
    • bonus_offset: bouns deduction

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » time number(double) Change time
    » change string Change amount
    » balance string Balance after change
    » type string Changing Type:

    - dnw: Deposit & Withdraw
    - pnl: Profit & Loss by reducing position
    - fee: Trading fee
    - refr: Referrer rebate
    - fund: Funding
    - point_dnw: POINT Deposit & Withdraw
    - point_fee: POINT Trading fee
    - point_refr: POINT Referrer rebate
    - bonus_offset: bouns deduction
    » text string Comment
    » contract string Futures contract, the field is only available for data after 2023-10-30.
    » trade_id string trade id

    # Enumerated Values

    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

    # List all positions of a user

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/positions'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/futures/usdt/positions"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /futures/{settle}/positions

    List all positions of a user

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    [
      {
        "user": 10000,
        "contract": "BTC_USDT",
        "size": -9440,
        "leverage": "0",
        "risk_limit": "100",
        "leverage_max": "100",
        "maintenance_rate": "0.005",
        "value": "2.497143098997",
        "margin": "4.431548146258",
        "entry_price": "3779.55",
        "liq_price": "99999999",
        "mark_price": "3780.32",
        "unrealised_pnl": "-0.000507486844",
        "realised_pnl": "0.045543982432",
        "history_pnl": "0",
        "last_close_pnl": "0",
        "realised_point": "0",
        "history_point": "0",
        "adl_ranking": 5,
        "pending_orders": 16,
        "close_order": {
          "id": 232323,
          "price": "3779",
          "is_liq": false
        },
        "mode": "single",
        "update_time": 1684994406,
        "cross_leverage_limit": "0"
      }
    ]
    

    Responses

    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

    # Get single position

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/positions/BTC_USDT'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/futures/usdt/positions/BTC_USDT"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /futures/{settle}/positions/{contract}

    Get single position

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract path string true Futures contract

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    {
      "user": 10000,
      "contract": "BTC_USDT",
      "size": -9440,
      "leverage": "0",
      "risk_limit": "100",
      "leverage_max": "100",
      "maintenance_rate": "0.005",
      "value": "2.497143098997",
      "margin": "4.431548146258",
      "entry_price": "3779.55",
      "liq_price": "99999999",
      "mark_price": "3780.32",
      "unrealised_pnl": "-0.000507486844",
      "realised_pnl": "0.045543982432",
      "history_pnl": "0",
      "last_close_pnl": "0",
      "realised_point": "0",
      "history_point": "0",
      "adl_ranking": 5,
      "pending_orders": 16,
      "close_order": {
        "id": 232323,
        "price": "3779",
        "is_liq": false
      },
      "mode": "single",
      "update_time": 1684994406,
      "cross_leverage_limit": "0"
    }
    

    Responses

    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

    # Update position margin

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/positions/BTC_USDT/margin'
    query_param = 'change=0.01'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/futures/usdt/positions/BTC_USDT/margin"
    query_param="change=0.01"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /futures/{settle}/positions/{contract}/margin

    Update position margin

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract path string true Futures contract
    change query string true Margin change. Use positive number to increase margin, negative number otherwise.

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    {
      "user": 10000,
      "contract": "BTC_USDT",
      "size": -9440,
      "leverage": "0",
      "risk_limit": "100",
      "leverage_max": "100",
      "maintenance_rate": "0.005",
      "value": "2.497143098997",
      "margin": "4.431548146258",
      "entry_price": "3779.55",
      "liq_price": "99999999",
      "mark_price": "3780.32",
      "unrealised_pnl": "-0.000507486844",
      "realised_pnl": "0.045543982432",
      "history_pnl": "0",
      "last_close_pnl": "0",
      "realised_point": "0",
      "history_point": "0",
      "adl_ranking": 5,
      "pending_orders": 16,
      "close_order": {
        "id": 232323,
        "price": "3779",
        "is_liq": false
      },
      "mode": "single",
      "update_time": 1684994406,
      "cross_leverage_limit": "0"
    }
    

    Responses

    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

    # Update position leverage

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/positions/BTC_USDT/leverage'
    query_param = 'leverage=10'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/futures/usdt/positions/BTC_USDT/leverage"
    query_param="leverage=10"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /futures/{settle}/positions/{contract}/leverage

    Update position leverage

    Parameters

    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)

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    {
      "user": 10000,
      "contract": "BTC_USDT",
      "size": -9440,
      "leverage": "0",
      "risk_limit": "100",
      "leverage_max": "100",
      "maintenance_rate": "0.005",
      "value": "2.497143098997",
      "margin": "4.431548146258",
      "entry_price": "3779.55",
      "liq_price": "99999999",
      "mark_price": "3780.32",
      "unrealised_pnl": "-0.000507486844",
      "realised_pnl": "0.045543982432",
      "history_pnl": "0",
      "last_close_pnl": "0",
      "realised_point": "0",
      "history_point": "0",
      "adl_ranking": 5,
      "pending_orders": 16,
      "close_order": {
        "id": 232323,
        "price": "3779",
        "is_liq": false
      },
      "mode": "single",
      "update_time": 1684994406,
      "cross_leverage_limit": "0"
    }
    

    Responses

    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

    # Update position risk limit

    Code samples

    # coding: utf-8
    import 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=10'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/futures/usdt/positions/BTC_USDT/risk_limit"
    query_param="risk_limit=10"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /futures/{settle}/positions/{contract}/risk_limit

    Update position risk limit

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    {
      "user": 10000,
      "contract": "BTC_USDT",
      "size": -9440,
      "leverage": "0",
      "risk_limit": "100",
      "leverage_max": "100",
      "maintenance_rate": "0.005",
      "value": "2.497143098997",
      "margin": "4.431548146258",
      "entry_price": "3779.55",
      "liq_price": "99999999",
      "mark_price": "3780.32",
      "unrealised_pnl": "-0.000507486844",
      "realised_pnl": "0.045543982432",
      "history_pnl": "0",
      "last_close_pnl": "0",
      "realised_point": "0",
      "history_point": "0",
      "adl_ranking": 5,
      "pending_orders": 16,
      "close_order": {
        "id": 232323,
        "price": "3779",
        "is_liq": false
      },
      "mode": "single",
      "update_time": 1684994406,
      "cross_leverage_limit": "0"
    }
    

    Responses

    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

    # Enable or disable dual mode

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/dual_mode'
    query_param = 'dual_mode=true'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/futures/usdt/dual_mode"
    query_param="dual_mode=true"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /futures/{settle}/dual_mode

    Enable or disable dual mode

    Before setting dual mode, make sure all positions are closed and no orders are open

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    dual_mode query boolean true Whether to enable dual mode

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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,
      "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"
      }
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » total string total is the balance after the user's accumulated deposit, withdraw, profit and loss (including realized profit and loss, fund, fee and referral rebate), excluding unrealized profit and loss.
    total = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund)
    » unrealised_pnl string Unrealized PNL
    » position_margin string Position margin
    » order_margin string Order margin of unfinished orders
    » available string The available balance for transferring or trading(including bonus. Bonus can't be be withdrawn. The transfer amount needs to deduct the bonus)
    » point string POINT amount
    » currency string Settle currency
    » in_dual_mode boolean Whether dual mode is enabled
    » enable_credit boolean Whether portfolio margin account mode is enabled
    » position_initial_margin string Initial margin position, applicable to the portfolio margin account model
    » maintenance_margin string Maintenance margin position, applicable to the portfolio margin account model
    » bonus string Perpetual Contract Bonus
    » history object Statistical data
    »» dnw string total amount of deposit and withdraw
    »» pnl string total amount of trading profit and loss
    »» fee string total amount of fee
    »» refr string total amount of referrer rebates
    »» fund string total amount of funding costs
    »» point_dnw string total amount of point deposit and withdraw
    »» point_fee string total amount of point fee
    »» point_refr string total amount of referrer rebates of point fee
    »» bonus_dnw string total amount of perpetual contract bonus transfer
    »» bonus_offset string total amount of perpetual contract bonus deduction

    WARNING

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

    # Retrieve position detail in dual mode

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/dual_comp/positions/BTC_USDT'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/futures/usdt/dual_comp/positions/BTC_USDT"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /futures/{settle}/dual_comp/positions/{contract}

    Retrieve position detail in dual mode

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract path string true Futures contract

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    [
      {
        "user": 10000,
        "contract": "BTC_USDT",
        "size": -9440,
        "leverage": "0",
        "risk_limit": "100",
        "leverage_max": "100",
        "maintenance_rate": "0.005",
        "value": "2.497143098997",
        "margin": "4.431548146258",
        "entry_price": "3779.55",
        "liq_price": "99999999",
        "mark_price": "3780.32",
        "unrealised_pnl": "-0.000507486844",
        "realised_pnl": "0.045543982432",
        "history_pnl": "0",
        "last_close_pnl": "0",
        "realised_point": "0",
        "history_point": "0",
        "adl_ranking": 5,
        "pending_orders": 16,
        "close_order": {
          "id": 232323,
          "price": "3779",
          "is_liq": false
        },
        "mode": "single",
        "update_time": 1684994406,
        "cross_leverage_limit": "0"
      }
    ]
    

    Responses

    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

    # Update position margin in dual mode

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/dual_comp/positions/BTC_USDT/margin'
    query_param = 'change=0.01&dual_side=dual_long'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/futures/usdt/dual_comp/positions/BTC_USDT/margin"
    query_param="change=0.01&dual_side=dual_long"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /futures/{settle}/dual_comp/positions/{contract}/margin

    Update position margin in dual mode

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract path string true Futures contract
    change query string true Margin change. Use positive number to increase margin, negative number otherwise.
    dual_side query string true Long or short position

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    [
      {
        "user": 10000,
        "contract": "BTC_USDT",
        "size": -9440,
        "leverage": "0",
        "risk_limit": "100",
        "leverage_max": "100",
        "maintenance_rate": "0.005",
        "value": "2.497143098997",
        "margin": "4.431548146258",
        "entry_price": "3779.55",
        "liq_price": "99999999",
        "mark_price": "3780.32",
        "unrealised_pnl": "-0.000507486844",
        "realised_pnl": "0.045543982432",
        "history_pnl": "0",
        "last_close_pnl": "0",
        "realised_point": "0",
        "history_point": "0",
        "adl_ranking": 5,
        "pending_orders": 16,
        "close_order": {
          "id": 232323,
          "price": "3779",
          "is_liq": false
        },
        "mode": "single",
        "update_time": 1684994406,
        "cross_leverage_limit": "0"
      }
    ]
    

    Responses

    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

    # Update position leverage in dual mode

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/dual_comp/positions/BTC_USDT/leverage'
    query_param = 'leverage=10'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/futures/usdt/dual_comp/positions/BTC_USDT/leverage"
    query_param="leverage=10"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /futures/{settle}/dual_comp/positions/{contract}/leverage

    Update position leverage in dual mode

    Parameters

    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)

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    [
      {
        "user": 10000,
        "contract": "BTC_USDT",
        "size": -9440,
        "leverage": "0",
        "risk_limit": "100",
        "leverage_max": "100",
        "maintenance_rate": "0.005",
        "value": "2.497143098997",
        "margin": "4.431548146258",
        "entry_price": "3779.55",
        "liq_price": "99999999",
        "mark_price": "3780.32",
        "unrealised_pnl": "-0.000507486844",
        "realised_pnl": "0.045543982432",
        "history_pnl": "0",
        "last_close_pnl": "0",
        "realised_point": "0",
        "history_point": "0",
        "adl_ranking": 5,
        "pending_orders": 16,
        "close_order": {
          "id": 232323,
          "price": "3779",
          "is_liq": false
        },
        "mode": "single",
        "update_time": 1684994406,
        "cross_leverage_limit": "0"
      }
    ]
    

    Responses

    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

    # Update position risk limit in dual mode

    Code samples

    # coding: utf-8
    import 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=10'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/futures/usdt/dual_comp/positions/BTC_USDT/risk_limit"
    query_param="risk_limit=10"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /futures/{settle}/dual_comp/positions/{contract}/risk_limit

    Update position risk limit in dual mode

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    [
      {
        "user": 10000,
        "contract": "BTC_USDT",
        "size": -9440,
        "leverage": "0",
        "risk_limit": "100",
        "leverage_max": "100",
        "maintenance_rate": "0.005",
        "value": "2.497143098997",
        "margin": "4.431548146258",
        "entry_price": "3779.55",
        "liq_price": "99999999",
        "mark_price": "3780.32",
        "unrealised_pnl": "-0.000507486844",
        "realised_pnl": "0.045543982432",
        "history_pnl": "0",
        "last_close_pnl": "0",
        "realised_point": "0",
        "history_point": "0",
        "adl_ranking": 5,
        "pending_orders": 16,
        "close_order": {
          "id": 232323,
          "price": "3779",
          "is_liq": false
        },
        "mode": "single",
        "update_time": 1684994406,
        "cross_leverage_limit": "0"
      }
    ]
    

    Responses

    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

    # Create a futures order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/orders'
    query_param = ''
    body='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/futures/usdt/orders"
    query_param=""
    body_param='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /futures/{settle}/orders

    Create a futures order

    • Creating futures orders requires size, which is number of contracts instead of currency amount. You can use quanto_multiplier in contract detail response to know how much currency 1 size contract represents
    • Zero-filled order cannot be retrieved 10 minutes after order cancellation. You will get a 404 not found for such orders
    • Set reduce_only to true can keep the position from changing side when reducing position size
    • In single position mode, to close a position, you need to set size to 0 and close to true
    • In dual position mode, to close one side position, you need to set auto_size side, reduce_only to true and size to 0
    • Set stp_act to decide the strategy of self-trade prevention. For detailed usage, refer to the stp_act parameter in request body

    Body parameter

    {
      "contract": "BTC_USDT",
      "size": 6024,
      "iceberg": 0,
      "price": "3765",
      "tif": "gtc",
      "text": "t-my-custom-id",
      "stp_act": "-"
    }
    

    Parameters

    Name In Type Required Description
    body body FuturesOrder true none
    » contract body string true Futures contract
    » size body integer(int64) true Order size. Specify positive number to make a bid, and negative number to ask
    » iceberg body integer(int64) false Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size
    » price body string false Order price. 0 for market order with tif set as ioc
    » close body boolean false Set as true to close the position, with size set to 0
    » reduce_only body boolean false Set as true to be reduce-only order
    » tif body string false Time in force
    » text body string false User defined information. If not empty, must follow the rules below:
    » auto_size body string false Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0
    » stp_act body string false Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies
    settle path string true Settle currency

    # Detailed descriptions

    » tif: 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

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

    1. prefixed with t-
    2. no longer than 28 bytes without t- prefix
    3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created:
    • web: from web
    • api: from API
    • app: from mobile phones
    • auto_deleveraging: from ADL
    • liquidation: from liquidation
    • insurance: from insurance

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

    1. After users join the STP Group, he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy。
    2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter。
    3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-'
    • cn: Cancel newest, Cancel new orders and keep old ones
    • co: Cancel oldest, Cancel old orders and keep new ones
    • cb: Cancel both, Both old and new orders will be cancelled

    # Enumerated Values

    Parameter Value
    » 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
    settle usd

    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": "-"
    }
    

    Responses

    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

    # List futures orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/orders'
    query_param = 'status=open'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/futures/usdt/orders"
    query_param="status=open"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /futures/{settle}/orders

    List futures orders

    • Zero-fill order cannot be retrieved for 10 minutes after cancellation
    • Historical orders, 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}/orders_timerange.

    Parameters

    Name In Type Required Description
    contract query string false Futures contract, return related data only if specified
    status query string true Only list the orders with this status
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0
    last_id query string false Specify list staring point using the id of last record in previous list-query results
    settle path string true Settle currency

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

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

    Responses

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

    # Response Headers

    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

    # Cancel all open orders matched

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/orders'
    query_param = 'contract=BTC_USDT'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/futures/usdt/orders"
    query_param="contract=BTC_USDT"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    DELETE /futures/{settle}/orders

    Cancel all open orders matched

    Zero-filled order cannot be retrieved 10 minutes after order cancellation

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

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

    Responses

    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

    # List Futures Orders By Time Range

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/orders_timerange'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/futures/usdt/orders_timerange"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /futures/{settle}/orders_timerange

    List Futures Orders By Time Range

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract query string false Futures contract, return related data only if specified
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

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

    Responses

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

    # Response Headers

    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

    # Create a batch of futures orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/batch_orders'
    query_param = ''
    body='[{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}]'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/futures/usdt/batch_orders"
    query_param=""
    body_param='[{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}]'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /futures/{settle}/batch_orders

    Create a batch of futures orders

    • Up to 10 orders per request
    • If any of the order's parameters are missing or in the wrong format, all of them will not be executed, and a http status 400 error will be returned directly
    • If the parameters are checked and passed, all are executed. Even if there is a business logic error in the middle (such as insufficient funds), it will not affect other execution orders
    • The returned result is in array format, and the order corresponds to the orders in the request body
    • In the returned result, the succeeded field of type bool indicates whether the execution was successful or not
    • If the execution is successful, the normal order content is included; if the execution fails, the label field is included to indicate the cause of the error
    • In the rate limiting, each order is counted individually

    Body parameter

    [
      {
        "contract": "BTC_USDT",
        "size": 6024,
        "iceberg": 0,
        "price": "3765",
        "tif": "gtc",
        "text": "t-my-custom-id",
        "stp_act": "-"
      }
    ]
    

    Parameters

    Name In Type Required Description
    body body array[FuturesOrder] true none
    settle path string true Settle currency

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

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

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » None object Futures order details
    »» succeeded boolean Whether the batch of orders succeeded
    »» label string Error label, only exists if execution fails
    »» detail string Error detail, only present if execution failed and details need to be given
    »» id integer(int64) Futures order ID
    »» user integer User ID
    »» create_time number(double) Creation time of order
    »» finish_time number(double) Order finished time. Not returned if order is open
    »» finish_as string How the order was finished.

    - filled: all filled
    - cancelled: manually cancelled
    - liquidated: cancelled because of liquidation
    - ioc: time in force is IOC, finish immediately
    - auto_deleveraged: finished by ADL
    - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because of position close
    - 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- prefix
    3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
    Besides user defined information, reserved contents are listed below, denoting how the order is created:

    - web: from web
    - api: from API
    - app: from mobile phones
    - auto_deleveraging: from ADL
    - liquidation: from liquidation
    - insurance: from insurance
    »» tkfr string Taker fee
    »» mkfr string Maker fee
    »» refu integer Reference user ID
    »» stp_act string Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies

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

    - cn: Cancel newest, Cancel new orders and keep old ones
    - co: Cancel oldest, Cancel old orders and keep new ones
    - cb: Cancel both, Both old and new orders will be cancelled
    »» stp_id integer Orders between users in the same stp_id group are not allowed to be self-traded

    1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.
    2. stp_id returns 0 by default for orders that have not been set for STP group

    # Enumerated Values

    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

    # Get a single order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/orders/12345'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/futures/usdt/orders/12345"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /futures/{settle}/orders/{order_id}

    Get a single order

    • Zero-fill order cannot be retrieved for 10 minutes after cancellation
    • Historical orders, by default, only data within the past 6 months is supported.

    Parameters

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

    # Detailed descriptions

    order_id: Order ID returned, or user custom ID(i.e., text field). Operations based on custom ID can only be checked when the order is in orderbook. When the order is finished, it can be checked within 60 seconds after the end of the order. After that, only order ID is accepted.

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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": "-"
    }
    

    Responses

    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

    # Cancel a single order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/orders/12345'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/futures/usdt/orders/12345"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    DELETE /futures/{settle}/orders/{order_id}

    Cancel a single order

    Parameters

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

    # Detailed descriptions

    order_id: Order ID returned, or user custom ID(i.e., text field). Operations based on custom ID can only be checked when the order is in orderbook. When the order is finished, it can be checked within 60 seconds after the end of the order. After that, only order ID is accepted.

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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": "-"
    }
    

    Responses

    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

    # Amend an order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/orders/12345'
    query_param = ''
    body='{"size":100,"price":"54321"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('PUT', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="PUT"
    url="/futures/usdt/orders/12345"
    query_param=""
    body_param='{"size":100,"price":"54321"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    PUT /futures/{settle}/orders/{order_id}

    Amend an order

    Body parameter

    {
      "size": 100,
      "price": "54321"
    }
    

    Parameters

    Name In Type Required Description
    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).

    # Detailed descriptions

    » size: New order size, including filled part.

    • If new size is less than or equal to filled size, the order will be cancelled.
    • Order side must be identical to the original one.
    • Close order size cannot be changed.
    • For reduce only orders, increasing size may leads to other reduce only orders being cancelled.
    • If price is not changed, decreasing size will not change its precedence in order book, while increasing will move it to the last at current price.

    order_id: Order ID returned, or user custom ID(i.e., text field). Operations based on custom ID can only be checked when the order is in orderbook. When the order is finished, it can be checked within 60 seconds after the end of the order. After that, only order ID is accepted.

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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": "-"
    }
    

    Responses

    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

    # List personal trading history

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/my_trades'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/futures/usdt/my_trades"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /futures/{settle}/my_trades

    List personal trading history

    By default, only data within the past 6 months is supported. If you need to query data for a longer period, please use GET /futures/{settle}/my_trades_timerange.

    Parameters

    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

    # Detailed descriptions

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

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » id 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
    » 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

    # Enumerated Values

    Property Value
    role taker
    role maker

    # Response Headers

    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

    # List personal trading history by time range

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/my_trades_timerange'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/futures/usdt/my_trades_timerange"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /futures/{settle}/my_trades_timerange

    List personal trading history by time range

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract query string false Futures contract, return related data only if specified
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0
    role query string false Query role, maker or taker.

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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"
      }
    ]
    

    Responses

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

    Response Schema

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

    # Enumerated Values

    Property Value
    role taker
    role maker

    # Response Headers

    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

    # List position close history

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/position_close'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/futures/usdt/position_close"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /futures/{settle}/position_close

    List position close history

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract query string false Futures contract, return related data only if specified
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp
    side query string false Query side. long or shot
    pnl query string false Query profit or loss

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    [
      {
        "time": 1546487347,
        "pnl": "0.00013",
        "side": "long",
        "contract": "BTC_USDT",
        "text": "web",
        "max_size": "100",
        "first_open_time": 1546487347,
        "long_price": "2026.87",
        "short_price": "2544.4"
      }
    ]
    

    Responses

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

    Response Schema

    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
    » text string Text of close order
    » max_size string Max Trade Size
    » first_open_time integer(int64) First Open Time
    » long_price string When 'side' is 'long,' it indicates the opening average price; when 'side' is 'short,' it indicates the closing average price.
    » short_price string When 'side' is 'long,' it indicates the opening average price; when 'side' is 'short,' it indicates the closing average price

    # Enumerated Values

    Property Value
    side long
    side short

    WARNING

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

    # List liquidation history

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/liquidates'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/futures/usdt/liquidates"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /futures/{settle}/liquidates

    List liquidation history

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract query string false Futures contract, return related data only if specified
    limit query integer false Maximum number of records to be returned in a single list
    at query integer false Specify a liquidation timestamp

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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
      }
    ]
    

    Responses

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

    Response Schema

    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

    # List Auto-Deleveraging History

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/auto_deleverages'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/futures/usdt/auto_deleverages"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /futures/{settle}/auto_deleverages

    List Auto-Deleveraging History

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract query string false Futures contract, return related data only if specified
    limit query integer false Maximum number of records to be returned in a single list
    at query integer false Specify an auto-deleveraging timestamp

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Countdown cancel orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/countdown_cancel_all'
    query_param = ''
    body='{"timeout":30,"contract":"BTC_USDT"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/futures/usdt/countdown_cancel_all"
    query_param=""
    body_param='{"timeout":30,"contract":"BTC_USDT"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /futures/{settle}/countdown_cancel_all

    Countdown cancel orders

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

    Body parameter

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

    Parameters

    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

    # Detailed descriptions

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

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    {
      "triggerTime": "1660039145000"
    }
    

    Responses

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

    Response Schema

    Status Code 200

    triggerTime

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

    WARNING

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

    # Query user trading fee rates

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/fee'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/futures/usdt/fee"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /futures/{settle}/fee

    Query user trading fee rates

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract query string false Futures contract, return related data only if specified

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    {
      "1INCH_USDT": {
        "taker_fee": "0.00025",
        "maker_fee": "-0.00010"
      },
      "AAVE_USDT": {
        "taker_fee": "0.00025",
        "maker_fee": "-0.00010"
      }
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » additionalProperties object The returned result is a map type, where the key represents the market and the value represents the taker and maker fee rates.
    »» taker_fee string Taker fee
    »» maker_fee string maker fee

    WARNING

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

    # Cancel a batch of orders with an ID list

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/batch_cancel_orders'
    query_param = ''
    body='["1","2","3"]'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/futures/usdt/batch_cancel_orders"
    query_param=""
    body_param='["1","2","3"]'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /futures/{settle}/batch_cancel_orders

    Cancel a batch of orders with an ID list

    Multiple distinct order ID list can be specified。Each request can cancel a maximum of 20 records.

    Body parameter

    [
      "1",
      "2",
      "3"
    ]
    

    Parameters

    Name In Type Required Description
    body body array[string] true none
    settle path string true Settle currency

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    Example responses

    200 Response

    [
      {
        "user_id": 111,
        "id": "123456",
        "succeeded": true,
        "message": ""
      }
    ]
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) Order cancellation operation completed [Inline]

    Response Schema

    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

    # Create a price-triggered order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/price_orders'
    query_param = ''
    body='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/futures/usdt/price_orders"
    query_param=""
    body_param='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /futures/{settle}/price_orders

    Create a price-triggered order

    Body parameter

    {
      "initial": {
        "contract": "BTC_USDT",
        "size": 100,
        "price": "5.03"
      },
      "trigger": {
        "strategy_type": 0,
        "price_type": 0,
        "price": "3000",
        "rule": 1,
        "expiration": 86400
      },
      "order_type": "close-long-order"
    }
    

    Parameters

    Name In Type Required Description
    body body FuturesPriceTriggeredOrder true none
    » initial body object true none
    »» contract body string true Futures contract
    »» size body integer(int64) false Order size. Positive size means to buy, while negative one means to sell. Set to 0 to close the position
    »» price body string true Order price. Set to 0 to use market price
    »» close body boolean false Set to true if trying to close the position
    »» tif body string false Time in force. If using market price, only ioc is supported.
    »» text body string false The source of the order, including:
    »» reduce_only body boolean false Set to true to create a reduce-only order
    »» auto_size body string false Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0
    » trigger body object true none
    »» strategy_type body integer(int32) false How the order will be triggered
    »» price_type body integer(int32) false Price type. 0 - latest deal price, 1 - mark price, 2 - index price
    »» price body string false Value of price on price triggered, or price gap on price gap triggered
    »» rule body integer(int32) false Trigger condition type
    »» expiration body integer false How long (in seconds) to wait for the condition to be triggered before cancelling the order.
    » order_type body string false Take-profit/stop-loss types, which include:
    settle path string true Settle currency

    # Detailed descriptions

    »» tif: Time in force. If using market price, only ioc is supported.

    • gtc: GoodTillCancelled
    • ioc: ImmediateOrCancelled

    »» text: The source of the order, including:

    • web: web
    • api: api
    • app: app

    »» strategy_type: How the order will be triggered

    • 0: by price, which means the order will be triggered if price condition is satisfied
    • 1: by price gap, which means the order will be triggered if gap of recent two prices of specified price_type are satisfied. Only 0 is supported currently

    »» rule: Trigger condition type

    • 1: calculated price based on strategy_type and price_type >= price
    • 2: calculated price based on strategy_type and price_type <= price

    » order_type: Take-profit/stop-loss types, which include:

    • close-long-order: order take-profit/stop-loss, close long position
    • close-short-order: order take-profit/stop-loss, close short position
    • close-long-position: position take-profit/stop-loss, close long position
    • close-short-position: position take-profit/stop-loss, close short position
    • plan-close-long-position: position planned take-profit/stop-loss, close long position
    • plan-close-short-position: position planned take-profit/stop-loss, close short position

    The order take-profit/stop-loss can not be passed by request. These two types are read only.

    # Enumerated Values

    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
    settle usd

    Example responses

    201 Response

    {
      "id": 1432329
    }
    

    Responses

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

    Response Schema

    Status Code 201

    TriggerOrderResponse

    Name Type Description
    » id integer(int64) Auto order ID

    WARNING

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

    # List all auto orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/price_orders'
    query_param = 'status=open'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/futures/usdt/price_orders"
    query_param="status=open"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /futures/{settle}/price_orders

    List all auto orders

    Parameters

    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

    # Enumerated Values

    Parameter Value
    status open
    status finished
    settle btc
    settle usdt
    settle usd

    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"
      }
    ]
    

    Responses

    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

    # Cancel all open orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/price_orders'
    query_param = 'contract=BTC_USDT'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/futures/usdt/price_orders"
    query_param="contract=BTC_USDT"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    DELETE /futures/{settle}/price_orders

    Cancel all open orders

    Parameters

    Name In Type Required Description
    contract query string true Futures contract
    settle path string true Settle currency

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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"
      }
    ]
    

    Responses

    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

    # Get a price-triggered order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/price_orders/string'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/futures/usdt/price_orders/string"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /futures/{settle}/price_orders/{order_id}

    Get a price-triggered order

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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"
    }
    

    Responses

    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

    # cancel a price-triggered order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/futures/usdt/price_orders/string'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/futures/usdt/price_orders/string"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    DELETE /futures/{settle}/price_orders/{order_id}

    cancel a price-triggered order

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle btc
    settle usdt
    settle usd

    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"
    }
    

    Responses

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

    WARNING

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

    # Delivery

    Delivery contract API

    # List all futures contracts

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/contracts'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/contracts \
      -H 'Accept: application/json'
    
    

    GET /delivery/{settle}/contracts

    List all futures contracts

    Parameters

    Name In Type Required Description
    settle path string true Settle currency

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    [
      {
        "name": "BTC_USDT_20200814",
        "underlying": "BTC_USDT",
        "cycle": "WEEKLY",
        "type": "direct",
        "quanto_multiplier": "0.0001",
        "mark_type": "index",
        "last_price": "9017",
        "mark_price": "9019",
        "index_price": "9005.3",
        "basis_rate": "0.185095",
        "basis_value": "13.7",
        "basis_impact_value": "100000",
        "settle_price": "0",
        "settle_price_interval": 60,
        "settle_price_duration": 1800,
        "settle_fee_rate": "0.0015",
        "expire_time": 1593763200,
        "order_price_round": "0.1",
        "mark_price_round": "0.1",
        "leverage_min": "1",
        "leverage_max": "100",
        "maintenance_rate": "1000000",
        "risk_limit_base": "140.726652109199",
        "risk_limit_step": "1000000",
        "risk_limit_max": "8000000",
        "maker_fee_rate": "-0.00025",
        "taker_fee_rate": "0.00075",
        "ref_discount_rate": "0",
        "ref_rebate_rate": "0.2",
        "order_price_deviate": "0.5",
        "order_size_min": 1,
        "order_size_max": 1000000,
        "orders_limit": 50,
        "orderbook_id": 63,
        "trade_id": 26,
        "trade_size": 435,
        "position_size": 130,
        "config_change_time": 1593158867,
        "in_delisting": false
      }
    ]
    

    Responses

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

    # Get a single contract

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/contracts/BTC_USDT_20200814'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/contracts/BTC_USDT_20200814 \
      -H 'Accept: application/json'
    
    

    GET /delivery/{settle}/contracts/{contract}

    Get a single contract

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract path string true Futures contract

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    {
      "name": "BTC_USDT_20200814",
      "underlying": "BTC_USDT",
      "cycle": "WEEKLY",
      "type": "direct",
      "quanto_multiplier": "0.0001",
      "mark_type": "index",
      "last_price": "9017",
      "mark_price": "9019",
      "index_price": "9005.3",
      "basis_rate": "0.185095",
      "basis_value": "13.7",
      "basis_impact_value": "100000",
      "settle_price": "0",
      "settle_price_interval": 60,
      "settle_price_duration": 1800,
      "settle_fee_rate": "0.0015",
      "expire_time": 1593763200,
      "order_price_round": "0.1",
      "mark_price_round": "0.1",
      "leverage_min": "1",
      "leverage_max": "100",
      "maintenance_rate": "1000000",
      "risk_limit_base": "140.726652109199",
      "risk_limit_step": "1000000",
      "risk_limit_max": "8000000",
      "maker_fee_rate": "-0.00025",
      "taker_fee_rate": "0.00075",
      "ref_discount_rate": "0",
      "ref_rebate_rate": "0.2",
      "order_price_deviate": "0.5",
      "order_size_min": 1,
      "order_size_max": 1000000,
      "orders_limit": 50,
      "orderbook_id": 63,
      "trade_id": 26,
      "trade_size": 435,
      "position_size": 130,
      "config_change_time": 1593158867,
      "in_delisting": false
    }
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) Contract information DeliveryContract

    # Futures order book

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/order_book'
    query_param = 'contract=BTC_USDT_20200814'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/order_book?contract=BTC_USDT_20200814 \
      -H 'Accept: application/json'
    
    

    GET /delivery/{settle}/order_book

    Futures order book

    Bids will be sorted by price from high to low, while asks sorted reversely

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract query string true Futures contract
    interval query string false Order depth. 0 means no aggregation is applied. default to 0
    limit query integer false Maximum number of order depth data in asks or bids
    with_id query boolean false Whether the order book update ID will be returned. This ID increases by 1 on every order book update

    # Enumerated Values

    Parameter Value
    settle usdt
    interval 0
    interval 0.1
    interval 0.01

    Example responses

    200 Response

    {
      "id": 123456,
      "current": 1623898993.123,
      "update": 1623898993.121,
      "asks": [
        {
          "p": "1.52",
          "s": 100
        },
        {
          "p": "1.53",
          "s": 40
        }
      ],
      "bids": [
        {
          "p": "1.17",
          "s": 150
        },
        {
          "p": "1.16",
          "s": 203
        }
      ]
    }
    

    Responses

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

    Response Schema

    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

    # Futures trading history

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/trades'
    query_param = 'contract=BTC_USDT_20200814'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/trades?contract=BTC_USDT_20200814 \
      -H 'Accept: application/json'
    
    

    GET /delivery/{settle}/trades

    Futures trading history

    Parameters

    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

    # Detailed descriptions

    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.

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    [
      {
        "id": 121234231,
        "create_time": 1514764800,
        "contract": "BTC_USDT",
        "size": -100,
        "price": "100.123"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » id integer(int64) Trade ID
    » create_time number(double) Trading time
    » create_time_ms number(double) Trading time, with milliseconds set to 3 decimal places.
    » contract string Futures contract
    » size integer(int64) Trading size
    » price string Trading price (quote currency)
    » is_internal boolean Whether internal trade. Internal trade refers to the takeover of liquidation orders by the insurance fund and ADL users. Since it is not a normal matching on the market depth, the transaction price may deviate, and it will not be recorded in the K-line. If it is not an internal trade, this field will not be returned.

    # Get futures candlesticks

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/candlesticks'
    query_param = 'contract=BTC_USDT_20200814'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/candlesticks?contract=BTC_USDT_20200814 \
      -H 'Accept: application/json'
    
    

    GET /delivery/{settle}/candlesticks

    Get futures candlesticks

    Return specified contract candlesticks. If prefix contract with mark_, the contract's mark price candlesticks are returned; if prefix with index_, index price candlesticks will be returned.

    Maximum of 2000 points are returned in one query. Be sure not to exceed the limit when specifying from, to and interval

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract query string true Futures contract
    from query integer(int64) false Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified
    to query integer(int64) false End time of candlesticks, formatted in Unix timestamp in seconds. Default to current time
    limit query integer false Maximum recent data points to return. limit is conflicted with from and to. If either from or to is specified, request will be rejected.
    interval query string false Interval time between data points. Note that 1w means natual week(Mon-Sun), while 7d means every 7d since unix 0

    # Enumerated Values

    Parameter Value
    settle usdt
    interval 10s
    interval 30s
    interval 1m
    interval 5m
    interval 15m
    interval 30m
    interval 1h
    interval 2h
    interval 4h
    interval 6h
    interval 8h
    interval 12h
    interval 1d
    interval 7d
    interval 1w
    interval 30d

    Example responses

    200 Response

    [
      {
        "t": 1539852480,
        "v": 97151,
        "c": "1.032",
        "h": "1.032",
        "l": "1.032",
        "o": "1.032"
      }
    ]
    

    Responses

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

    Response Schema

    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)

    # List futures tickers

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/tickers'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/tickers \
      -H 'Accept: application/json'
    
    

    GET /delivery/{settle}/tickers

    List futures tickers

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract query string false Futures contract

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    [
      {
        "contract": "BTC_USDT",
        "last": "6432",
        "low_24h": "6278",
        "high_24h": "6790",
        "change_percentage": "4.43",
        "total_size": "32323904",
        "volume_24h": "184040233284",
        "volume_24h_btc": "28613220",
        "volume_24h_usd": "184040233284",
        "volume_24h_base": "28613220",
        "volume_24h_quote": "184040233284",
        "volume_24h_settle": "28613220",
        "mark_price": "6534",
        "funding_rate": "0.0001",
        "funding_rate_indicative": "0.0001",
        "index_price": "6531",
        "highest_bid": "34089.7",
        "lowest_ask": "34217.9"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » contract string Futures contract
    » last string Last trading price
    » change_percentage string Change percentage.
    » total_size string Contract total size
    » low_24h string Lowest trading price in recent 24h
    » high_24h string Highest trading price in recent 24h
    » volume_24h string Trade size in recent 24h
    » volume_24h_btc string Trade volumes in recent 24h in BTC(deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead)
    » volume_24h_usd string Trade volumes in recent 24h in USD(deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead)
    » volume_24h_base string Trade volume in recent 24h, in base currency
    » volume_24h_quote string Trade volume in recent 24h, in quote currency
    » volume_24h_settle string Trade volume in recent 24h, in settle currency
    » mark_price string Recent mark price
    » funding_rate string Funding rate
    » funding_rate_indicative string Indicative Funding rate in next period
    » index_price string Index price
    » quanto_base_rate string Exchange rate of base currency and settlement currency in Quanto contract. Does not exists in contracts of other types
    » basis_rate string Basis rate
    » basis_value string Basis value
    » lowest_ask string Recent lowest ask
    » highest_bid string Recent highest bid

    # Futures insurance balance history

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/insurance'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/delivery/usdt/insurance \
      -H 'Accept: application/json'
    
    

    GET /delivery/{settle}/insurance

    Futures insurance balance history

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    [
      {
        "t": 1543968000,
        "b": "83.0031"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » t integer(int64) Unix timestamp in seconds
    » b string Insurance balance

    # Query futures account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/accounts'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/delivery/usdt/accounts"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /delivery/{settle}/accounts

    Query futures account

    Parameters

    Name In Type Required Description
    settle path string true Settle currency

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    {
      "user": 1666,
      "currency": "USDT",
      "total": "9707.803567115145",
      "unrealised_pnl": "3371.248828",
      "position_margin": "38.712189181",
      "order_margin": "0",
      "available": "9669.091377934145",
      "point": "0",
      "bonus": "0",
      "in_dual_mode": false,
      "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"
      }
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » total string total is the balance after the user's accumulated deposit, withdraw, profit and loss (including realized profit and loss, fund, fee and referral rebate), excluding unrealized profit and loss.
    total = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund)
    » unrealised_pnl string Unrealized PNL
    » position_margin string Position margin
    » order_margin string Order margin of unfinished orders
    » available string The available balance for transferring or trading(including bonus. Bonus can't be be withdrawn. The transfer amount needs to deduct the bonus)
    » point string POINT amount
    » currency string Settle currency
    » in_dual_mode boolean Whether dual mode is enabled
    » enable_credit boolean Whether portfolio margin account mode is enabled
    » position_initial_margin string Initial margin position, applicable to the portfolio margin account model
    » maintenance_margin string Maintenance margin position, applicable to the portfolio margin account model
    » bonus string Perpetual Contract Bonus
    » history object Statistical data
    »» dnw string total amount of deposit and withdraw
    »» pnl string total amount of trading profit and loss
    »» fee string total amount of fee
    »» refr string total amount of referrer rebates
    »» fund string total amount of funding costs
    »» point_dnw string total amount of point deposit and withdraw
    »» point_fee string total amount of point fee
    »» point_refr string total amount of referrer rebates of point fee
    »» bonus_dnw string total amount of perpetual contract bonus transfer
    »» bonus_offset string total amount of perpetual contract bonus deduction

    WARNING

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

    # Query account book

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/account_book'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/delivery/usdt/account_book"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /delivery/{settle}/account_book

    Query account book

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    limit query integer false Maximum number of records to be returned in a single list
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp
    type query string false Changing Type:

    # Detailed descriptions

    type: Changing Type:

    • dnw: Deposit & Withdraw
    • pnl: Profit & Loss by reducing position
    • fee: Trading fee
    • refr: Referrer rebate
    • fund: Funding
    • point_dnw: POINT Deposit & Withdraw
    • point_fee: POINT Trading fee
    • point_refr: POINT Referrer rebate

    # Enumerated Values

    Parameter Value
    settle usdt
    type dnw
    type pnl
    type fee
    type refr
    type fund
    type point_dnw
    type point_fee
    type point_refr

    Example responses

    200 Response

    [
      {
        "time": 1682294400.123456,
        "change": "0.000010152188",
        "balance": "4.59316525194",
        "text": "ETH_USD:6086261",
        "type": "fee",
        "contract": "ETH_USD",
        "trade_id": "1"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » time number(double) Change time
    » change string Change amount
    » balance string Balance after change
    » type string Changing Type:

    - dnw: Deposit & Withdraw
    - pnl: Profit & Loss by reducing position
    - fee: Trading fee
    - refr: Referrer rebate
    - fund: Funding
    - point_dnw: POINT Deposit & Withdraw
    - point_fee: POINT Trading fee
    - point_refr: POINT Referrer rebate
    - bonus_offset: bouns deduction
    » text string Comment
    » contract string Futures contract, the field is only available for data after 2023-10-30.
    » trade_id string trade id

    # Enumerated Values

    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

    # List all positions of a user

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/positions'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/delivery/usdt/positions"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /delivery/{settle}/positions

    List all positions of a user

    Parameters

    Name In Type Required Description
    settle path string true Settle currency

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    [
      {
        "user": 10000,
        "contract": "BTC_USDT",
        "size": -9440,
        "leverage": "0",
        "risk_limit": "100",
        "leverage_max": "100",
        "maintenance_rate": "0.005",
        "value": "2.497143098997",
        "margin": "4.431548146258",
        "entry_price": "3779.55",
        "liq_price": "99999999",
        "mark_price": "3780.32",
        "unrealised_pnl": "-0.000507486844",
        "realised_pnl": "0.045543982432",
        "history_pnl": "0",
        "last_close_pnl": "0",
        "realised_point": "0",
        "history_point": "0",
        "adl_ranking": 5,
        "pending_orders": 16,
        "close_order": {
          "id": 232323,
          "price": "3779",
          "is_liq": false
        },
        "mode": "single",
        "update_time": 1684994406,
        "cross_leverage_limit": "0"
      }
    ]
    

    Responses

    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

    # Get single position

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/positions/BTC_USDT_20200814'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/delivery/usdt/positions/BTC_USDT_20200814"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /delivery/{settle}/positions/{contract}

    Get single position

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract path string true Futures contract

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    {
      "user": 10000,
      "contract": "BTC_USDT",
      "size": -9440,
      "leverage": "0",
      "risk_limit": "100",
      "leverage_max": "100",
      "maintenance_rate": "0.005",
      "value": "2.497143098997",
      "margin": "4.431548146258",
      "entry_price": "3779.55",
      "liq_price": "99999999",
      "mark_price": "3780.32",
      "unrealised_pnl": "-0.000507486844",
      "realised_pnl": "0.045543982432",
      "history_pnl": "0",
      "last_close_pnl": "0",
      "realised_point": "0",
      "history_point": "0",
      "adl_ranking": 5,
      "pending_orders": 16,
      "close_order": {
        "id": 232323,
        "price": "3779",
        "is_liq": false
      },
      "mode": "single",
      "update_time": 1684994406,
      "cross_leverage_limit": "0"
    }
    

    Responses

    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

    # Update position margin

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/positions/BTC_USDT_20200814/margin'
    query_param = 'change=0.01'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/delivery/usdt/positions/BTC_USDT_20200814/margin"
    query_param="change=0.01"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /delivery/{settle}/positions/{contract}/margin

    Update position margin

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract path string true Futures contract
    change query string true Margin change. Use positive number to increase margin, negative number otherwise.

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    {
      "user": 10000,
      "contract": "BTC_USDT",
      "size": -9440,
      "leverage": "0",
      "risk_limit": "100",
      "leverage_max": "100",
      "maintenance_rate": "0.005",
      "value": "2.497143098997",
      "margin": "4.431548146258",
      "entry_price": "3779.55",
      "liq_price": "99999999",
      "mark_price": "3780.32",
      "unrealised_pnl": "-0.000507486844",
      "realised_pnl": "0.045543982432",
      "history_pnl": "0",
      "last_close_pnl": "0",
      "realised_point": "0",
      "history_point": "0",
      "adl_ranking": 5,
      "pending_orders": 16,
      "close_order": {
        "id": 232323,
        "price": "3779",
        "is_liq": false
      },
      "mode": "single",
      "update_time": 1684994406,
      "cross_leverage_limit": "0"
    }
    

    Responses

    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

    # Update position leverage

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/positions/BTC_USDT_20200814/leverage'
    query_param = 'leverage=10'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/delivery/usdt/positions/BTC_USDT_20200814/leverage"
    query_param="leverage=10"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /delivery/{settle}/positions/{contract}/leverage

    Update position leverage

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract path string true Futures contract
    leverage query string true New position leverage

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    {
      "user": 10000,
      "contract": "BTC_USDT",
      "size": -9440,
      "leverage": "0",
      "risk_limit": "100",
      "leverage_max": "100",
      "maintenance_rate": "0.005",
      "value": "2.497143098997",
      "margin": "4.431548146258",
      "entry_price": "3779.55",
      "liq_price": "99999999",
      "mark_price": "3780.32",
      "unrealised_pnl": "-0.000507486844",
      "realised_pnl": "0.045543982432",
      "history_pnl": "0",
      "last_close_pnl": "0",
      "realised_point": "0",
      "history_point": "0",
      "adl_ranking": 5,
      "pending_orders": 16,
      "close_order": {
        "id": 232323,
        "price": "3779",
        "is_liq": false
      },
      "mode": "single",
      "update_time": 1684994406,
      "cross_leverage_limit": "0"
    }
    

    Responses

    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

    # Update position risk limit

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/positions/BTC_USDT_20200814/risk_limit'
    query_param = 'risk_limit=10'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/delivery/usdt/positions/BTC_USDT_20200814/risk_limit"
    query_param="risk_limit=10"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /delivery/{settle}/positions/{contract}/risk_limit

    Update position risk limit

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    {
      "user": 10000,
      "contract": "BTC_USDT",
      "size": -9440,
      "leverage": "0",
      "risk_limit": "100",
      "leverage_max": "100",
      "maintenance_rate": "0.005",
      "value": "2.497143098997",
      "margin": "4.431548146258",
      "entry_price": "3779.55",
      "liq_price": "99999999",
      "mark_price": "3780.32",
      "unrealised_pnl": "-0.000507486844",
      "realised_pnl": "0.045543982432",
      "history_pnl": "0",
      "last_close_pnl": "0",
      "realised_point": "0",
      "history_point": "0",
      "adl_ranking": 5,
      "pending_orders": 16,
      "close_order": {
        "id": 232323,
        "price": "3779",
        "is_liq": false
      },
      "mode": "single",
      "update_time": 1684994406,
      "cross_leverage_limit": "0"
    }
    

    Responses

    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

    # Create a futures order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/orders'
    query_param = ''
    body='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/delivery/usdt/orders"
    query_param=""
    body_param='{"contract":"BTC_USDT","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /delivery/{settle}/orders

    Create a futures order

    Zero-filled order cannot be retrieved 10 minutes after order cancellation

    Body parameter

    {
      "contract": "BTC_USDT",
      "size": 6024,
      "iceberg": 0,
      "price": "3765",
      "tif": "gtc",
      "text": "t-my-custom-id",
      "stp_act": "-"
    }
    

    Parameters

    Name In Type Required Description
    body body FuturesOrder true none
    » contract body string true Futures contract
    » size body integer(int64) true Order size. Specify positive number to make a bid, and negative number to ask
    » iceberg body integer(int64) false Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size
    » price body string false Order price. 0 for market order with tif set as ioc
    » close body boolean false Set as true to close the position, with size set to 0
    » reduce_only body boolean false Set as true to be reduce-only order
    » tif body string false Time in force
    » text body string false User defined information. If not empty, must follow the rules below:
    » auto_size body string false Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0
    » stp_act body string false Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies
    settle path string true Settle currency

    # Detailed descriptions

    » tif: 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

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

    1. prefixed with t-
    2. no longer than 28 bytes without t- prefix
    3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created:
    • web: from web
    • api: from API
    • app: from mobile phones
    • auto_deleveraging: from ADL
    • liquidation: from liquidation
    • insurance: from insurance

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

    1. After users join the STP Group, he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy。
    2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter。
    3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-'
    • cn: Cancel newest, Cancel new orders and keep old ones
    • co: Cancel oldest, Cancel old orders and keep new ones
    • cb: Cancel both, Both old and new orders will be cancelled

    # Enumerated Values

    Parameter Value
    » tif gtc
    » tif ioc
    » tif poc
    » tif fok
    » auto_size close_long
    » auto_size close_short
    » stp_act co
    » stp_act cn
    » stp_act cb
    » stp_act -
    settle usdt

    Example responses

    201 Response

    {
      "id": 15675394,
      "user": 100000,
      "contract": "BTC_USDT",
      "create_time": 1546569968,
      "size": 6024,
      "iceberg": 0,
      "left": 6024,
      "price": "3765",
      "fill_price": "0",
      "mkfr": "-0.00025",
      "tkfr": "0.00075",
      "tif": "gtc",
      "refu": 0,
      "is_reduce_only": false,
      "is_close": false,
      "is_liq": false,
      "text": "t-my-custom-id",
      "status": "finished",
      "finish_time": 1514764900,
      "finish_as": "cancelled",
      "stp_id": 0,
      "stp_act": "-",
      "amend_text": "-"
    }
    

    Responses

    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

    # List futures orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/orders'
    query_param = 'status=open'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/delivery/usdt/orders"
    query_param="status=open"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /delivery/{settle}/orders

    List futures orders

    Zero-filled order cannot be retrieved 10 minutes after order cancellation

    Parameters

    Name In Type Required Description
    contract query string false Futures contract
    status query string true Only list the orders with this status
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0
    last_id query string false Specify list staring point using the id of last record in previous list-query results
    count_total query integer false Whether to return total number matched. Default to 0(no return)
    settle path string true Settle currency

    # Enumerated Values

    Parameter Value
    status open
    status finished
    count_total 0
    count_total 1
    settle usdt

    Example responses

    200 Response

    [
      {
        "id": 15675394,
        "user": 100000,
        "contract": "BTC_USDT",
        "create_time": 1546569968,
        "size": 6024,
        "iceberg": 0,
        "left": 6024,
        "price": "3765",
        "fill_price": "0",
        "mkfr": "-0.00025",
        "tkfr": "0.00075",
        "tif": "gtc",
        "refu": 0,
        "is_reduce_only": false,
        "is_close": false,
        "is_liq": false,
        "text": "t-my-custom-id",
        "status": "finished",
        "finish_time": 1514764900,
        "finish_as": "cancelled",
        "stp_id": 0,
        "stp_act": "-",
        "amend_text": "-"
      }
    ]
    

    Responses

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

    # Response Headers

    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

    # Cancel all open orders matched

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/orders'
    query_param = 'contract=BTC_USDT_20200814'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/delivery/usdt/orders"
    query_param="contract=BTC_USDT_20200814"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    DELETE /delivery/{settle}/orders

    Cancel all open orders matched

    Zero-filled order cannot be retrieved 10 minutes after order cancellation

    Parameters

    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

    # Enumerated Values

    Parameter Value
    side ask
    side bid
    settle usdt

    Example responses

    200 Response

    [
      {
        "id": 15675394,
        "user": 100000,
        "contract": "BTC_USDT",
        "create_time": 1546569968,
        "size": 6024,
        "iceberg": 0,
        "left": 6024,
        "price": "3765",
        "fill_price": "0",
        "mkfr": "-0.00025",
        "tkfr": "0.00075",
        "tif": "gtc",
        "refu": 0,
        "is_reduce_only": false,
        "is_close": false,
        "is_liq": false,
        "text": "t-my-custom-id",
        "status": "finished",
        "finish_time": 1514764900,
        "finish_as": "cancelled",
        "stp_id": 0,
        "stp_act": "-",
        "amend_text": "-"
      }
    ]
    

    Responses

    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

    # Get a single order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/orders/12345'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/delivery/usdt/orders/12345"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /delivery/{settle}/orders/{order_id}

    Get a single order

    Zero-filled order cannot be retrieved 10 minutes after order cancellation

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    {
      "id": 15675394,
      "user": 100000,
      "contract": "BTC_USDT",
      "create_time": 1546569968,
      "size": 6024,
      "iceberg": 0,
      "left": 6024,
      "price": "3765",
      "fill_price": "0",
      "mkfr": "-0.00025",
      "tkfr": "0.00075",
      "tif": "gtc",
      "refu": 0,
      "is_reduce_only": false,
      "is_close": false,
      "is_liq": false,
      "text": "t-my-custom-id",
      "status": "finished",
      "finish_time": 1514764900,
      "finish_as": "cancelled",
      "stp_id": 0,
      "stp_act": "-",
      "amend_text": "-"
    }
    

    Responses

    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

    # Cancel a single order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/orders/12345'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/delivery/usdt/orders/12345"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    DELETE /delivery/{settle}/orders/{order_id}

    Cancel a single order

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    {
      "id": 15675394,
      "user": 100000,
      "contract": "BTC_USDT",
      "create_time": 1546569968,
      "size": 6024,
      "iceberg": 0,
      "left": 6024,
      "price": "3765",
      "fill_price": "0",
      "mkfr": "-0.00025",
      "tkfr": "0.00075",
      "tif": "gtc",
      "refu": 0,
      "is_reduce_only": false,
      "is_close": false,
      "is_liq": false,
      "text": "t-my-custom-id",
      "status": "finished",
      "finish_time": 1514764900,
      "finish_as": "cancelled",
      "stp_id": 0,
      "stp_act": "-",
      "amend_text": "-"
    }
    

    Responses

    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

    # List personal trading history

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/my_trades'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/delivery/usdt/my_trades"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /delivery/{settle}/my_trades

    List personal trading history

    Parameters

    Name In Type Required Description
    settle path string true Settle currency
    contract query string false Futures contract
    order query integer(int64) false Futures order ID, return related data only if specified
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0
    last_id query string false Specify list staring point using the id of last record in previous list-query results
    count_total query integer false Whether to return total number matched. Default to 0(no return)

    # Enumerated Values

    Parameter Value
    settle usdt
    count_total 0
    count_total 1

    Example responses

    200 Response

    [
      {
        "id": 121234231,
        "create_time": 1514764800.123,
        "contract": "BTC_USDT",
        "order_id": "21893289839",
        "size": 100,
        "price": "100.123",
        "text": "t-123456",
        "fee": "0.01",
        "point_fee": "0",
        "role": "taker"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » id 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
    » 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

    # Enumerated Values

    Property Value
    role taker
    role maker

    # Response Headers

    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

    # List position close history

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/position_close'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/delivery/usdt/position_close"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /delivery/{settle}/position_close

    List position close history

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    [
      {
        "time": 1546487347,
        "pnl": "0.00013",
        "side": "long",
        "contract": "BTC_USDT",
        "text": "web",
        "max_size": "100",
        "first_open_time": 1546487347,
        "long_price": "2026.87",
        "short_price": "2544.4"
      }
    ]
    

    Responses

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

    Response Schema

    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
    » text string Text of close order
    » max_size string Max Trade Size
    » first_open_time integer(int64) First Open Time
    » long_price string When 'side' is 'long,' it indicates the opening average price; when 'side' is 'short,' it indicates the closing average price.
    » short_price string When 'side' is 'long,' it indicates the opening average price; when 'side' is 'short,' it indicates the closing average price

    # Enumerated Values

    Property Value
    side long
    side short

    WARNING

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

    # List liquidation history

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/liquidates'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/delivery/usdt/liquidates"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /delivery/{settle}/liquidates

    List liquidation history

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    [
      {
        "time": 1548654951,
        "contract": "BTC_USDT",
        "size": 600,
        "leverage": "25",
        "margin": "0.006705256878",
        "entry_price": "3536.123",
        "liq_price": "3421.54",
        "mark_price": "3420.27",
        "order_id": 317393847,
        "order_price": "3405",
        "fill_price": "3424",
        "left": 0
      }
    ]
    

    Responses

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

    Response Schema

    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

    # List settlement history

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/settlements'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/delivery/usdt/settlements"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /delivery/{settle}/settlements

    List settlement history

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    [
      {
        "time": 1548654951,
        "contract": "BTC_USDT",
        "size": 600,
        "leverage": "25",
        "margin": "0.006705256878",
        "entry_price": "3536.123",
        "settle_price": "3421.54",
        "profit": "-6.87498",
        "fee": "0.03079386"
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Create a price-triggered order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/price_orders'
    query_param = ''
    body='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/delivery/usdt/price_orders"
    query_param=""
    body_param='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /delivery/{settle}/price_orders

    Create a price-triggered order

    Body parameter

    {
      "initial": {
        "contract": "BTC_USDT",
        "size": 100,
        "price": "5.03"
      },
      "trigger": {
        "strategy_type": 0,
        "price_type": 0,
        "price": "3000",
        "rule": 1,
        "expiration": 86400
      },
      "order_type": "close-long-order"
    }
    

    Parameters

    Name In Type Required Description
    body body FuturesPriceTriggeredOrder true none
    » initial body object true none
    »» contract body string true Futures contract
    »» size body integer(int64) false Order size. Positive size means to buy, while negative one means to sell. Set to 0 to close the position
    »» price body string true Order price. Set to 0 to use market price
    »» close body boolean false Set to true if trying to close the position
    »» tif body string false Time in force. If using market price, only ioc is supported.
    »» text body string false The source of the order, including:
    »» reduce_only body boolean false Set to true to create a reduce-only order
    »» auto_size body string false Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0
    » trigger body object true none
    »» strategy_type body integer(int32) false How the order will be triggered
    »» price_type body integer(int32) false Price type. 0 - latest deal price, 1 - mark price, 2 - index price
    »» price body string false Value of price on price triggered, or price gap on price gap triggered
    »» rule body integer(int32) false Trigger condition type
    »» expiration body integer false How long (in seconds) to wait for the condition to be triggered before cancelling the order.
    » order_type body string false Take-profit/stop-loss types, which include:
    settle path string true Settle currency

    # Detailed descriptions

    »» tif: Time in force. If using market price, only ioc is supported.

    • gtc: GoodTillCancelled
    • ioc: ImmediateOrCancelled

    »» text: The source of the order, including:

    • web: web
    • api: api
    • app: app

    »» strategy_type: How the order will be triggered

    • 0: by price, which means the order will be triggered if price condition is satisfied
    • 1: by price gap, which means the order will be triggered if gap of recent two prices of specified price_type are satisfied. Only 0 is supported currently

    »» rule: Trigger condition type

    • 1: calculated price based on strategy_type and price_type >= price
    • 2: calculated price based on strategy_type and price_type <= price

    » order_type: Take-profit/stop-loss types, which include:

    • close-long-order: order take-profit/stop-loss, close long position
    • close-short-order: order take-profit/stop-loss, close short position
    • close-long-position: position take-profit/stop-loss, close long position
    • close-short-position: position take-profit/stop-loss, close short position
    • plan-close-long-position: position planned take-profit/stop-loss, close long position
    • plan-close-short-position: position planned take-profit/stop-loss, close short position

    The order take-profit/stop-loss can not be passed by request. These two types are read only.

    # Enumerated Values

    Parameter Value
    »» tif gtc
    »» tif ioc
    »» strategy_type 0
    »» strategy_type 1
    »» price_type 0
    »» price_type 1
    »» price_type 2
    »» rule 1
    »» rule 2
    settle usdt

    Example responses

    201 Response

    {
      "id": 1432329
    }
    

    Responses

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

    Response Schema

    Status Code 201

    TriggerOrderResponse

    Name Type Description
    » id integer(int64) Auto order ID

    WARNING

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

    # List all auto orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/price_orders'
    query_param = 'status=open'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/delivery/usdt/price_orders"
    query_param="status=open"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /delivery/{settle}/price_orders

    List all auto orders

    Parameters

    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

    # Enumerated Values

    Parameter Value
    status open
    status finished
    settle usdt

    Example responses

    200 Response

    [
      {
        "initial": {
          "contract": "BTC_USDT",
          "size": 100,
          "price": "5.03"
        },
        "trigger": {
          "strategy_type": 0,
          "price_type": 0,
          "price": "3000",
          "rule": 1,
          "expiration": 86400
        },
        "id": 1283293,
        "user": 1234,
        "create_time": 1514764800,
        "finish_time": 1514764900,
        "trade_id": 13566,
        "status": "finished",
        "finish_as": "cancelled",
        "reason": "",
        "order_type": "close-long-order"
      }
    ]
    

    Responses

    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

    # Cancel all open orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/price_orders'
    query_param = 'contract=BTC_USDT'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/delivery/usdt/price_orders"
    query_param="contract=BTC_USDT"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    DELETE /delivery/{settle}/price_orders

    Cancel all open orders

    Parameters

    Name In Type Required Description
    contract query string true Futures contract
    settle path string true Settle currency

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    [
      {
        "initial": {
          "contract": "BTC_USDT",
          "size": 100,
          "price": "5.03"
        },
        "trigger": {
          "strategy_type": 0,
          "price_type": 0,
          "price": "3000",
          "rule": 1,
          "expiration": 86400
        },
        "id": 1283293,
        "user": 1234,
        "create_time": 1514764800,
        "finish_time": 1514764900,
        "trade_id": 13566,
        "status": "finished",
        "finish_as": "cancelled",
        "reason": "",
        "order_type": "close-long-order"
      }
    ]
    

    Responses

    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

    # Get a price-triggered order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/price_orders/string'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/delivery/usdt/price_orders/string"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /delivery/{settle}/price_orders/{order_id}

    Get a price-triggered order

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    {
      "initial": {
        "contract": "BTC_USDT",
        "size": 100,
        "price": "5.03"
      },
      "trigger": {
        "strategy_type": 0,
        "price_type": 0,
        "price": "3000",
        "rule": 1,
        "expiration": 86400
      },
      "id": 1283293,
      "user": 1234,
      "create_time": 1514764800,
      "finish_time": 1514764900,
      "trade_id": 13566,
      "status": "finished",
      "finish_as": "cancelled",
      "reason": "",
      "order_type": "close-long-order"
    }
    

    Responses

    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

    # cancel a price-triggered order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/delivery/usdt/price_orders/string'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/delivery/usdt/price_orders/string"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    DELETE /delivery/{settle}/price_orders/{order_id}

    cancel a price-triggered order

    Parameters

    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

    # Enumerated Values

    Parameter Value
    settle usdt

    Example responses

    200 Response

    {
      "initial": {
        "contract": "BTC_USDT",
        "size": 100,
        "price": "5.03"
      },
      "trigger": {
        "strategy_type": 0,
        "price_type": 0,
        "price": "3000",
        "rule": 1,
        "expiration": 86400
      },
      "id": 1283293,
      "user": 1234,
      "create_time": 1514764800,
      "finish_time": 1514764900,
      "trade_id": 13566,
      "status": "finished",
      "finish_as": "cancelled",
      "reason": "",
      "order_type": "close-long-order"
    }
    

    Responses

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

    WARNING

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

    # Options

    Options API

    # List all underlyings

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/underlyings'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/options/underlyings \
      -H 'Accept: application/json'
    
    

    GET /options/underlyings

    List all underlyings

    Example responses

    200 Response

    [
      {
        "name": "BTC_USDT",
        "index_price": "70000"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » name string Underlying name
    » index_price string Spot index price (quote currency)

    # List all expiration times

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/expirations'
    query_param = 'underlying=BTC_USDT'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/options/expirations?underlying=BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /options/expirations

    List all expiration times

    Parameters

    Name In Type Required Description
    underlying query string true Underlying (Obtained by listing underlying endpoint)

    Example responses

    200 Response

    [
      1637913600
    ]
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) List expiration times of specified underlying [integer]

    Response Schema

    Status Code 200

    Name Type Description
    » None integer(int64) Unix timestamp of the expiration time

    # List all the contracts with specified underlying and expiration time

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/contracts'
    query_param = 'underlying=BTC_USDT'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/options/contracts?underlying=BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /options/contracts

    List all the contracts with specified underlying and expiration time

    Parameters

    Name In Type Required Description
    underlying query string true Underlying (Obtained by listing underlying endpoint)
    expiration query integer(int64) false Unix timestamp of the expiration time

    Example responses

    200 Response

    [
      {
        "name": "BTC_USDT-20211130-65000-C",
        "tag": "WEEK",
        "create_time": 1636702700,
        "expiration_time": 1637913600,
        "is_call": true,
        "strike_price": "65000",
        "last_price": "13000",
        "mark_price": "14010",
        "orderbook_id": 9,
        "trade_id": 1,
        "trade_size": 10,
        "position_size": 10,
        "underlying": "BTC_USDT",
        "underlying_price": "70000",
        "multiplier": "0.0001",
        "order_price_round": "0.1",
        "mark_price_round": "0.1",
        "maker_fee_rate": "0.0004",
        "taker_fee_rate": "0.0004",
        "price_limit_fee_rate": "0.1",
        "ref_discount_rate": "0",
        "ref_rebate_rate": "0",
        "order_price_deviate": "0.5",
        "order_size_min": 1,
        "order_size_max": 100000,
        "orders_limit": 50
      }
    ]
    

    Responses

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

    Response Schema

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

    # Query specified contract detail

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/contracts/BTC_USDT-20211130-65000-C'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/options/contracts/BTC_USDT-20211130-65000-C \
      -H 'Accept: application/json'
    
    

    GET /options/contracts/{contract}

    Query specified contract detail

    Parameters

    Name In Type Required Description
    contract path string true none

    Example responses

    200 Response

    {
      "name": "BTC_USDT-20211130-65000-C",
      "tag": "WEEK",
      "create_time": 1636702700,
      "expiration_time": 1637913600,
      "is_call": true,
      "strike_price": "65000",
      "last_price": "13000",
      "mark_price": "14010",
      "orderbook_id": 9,
      "trade_id": 1,
      "trade_size": 10,
      "position_size": 10,
      "underlying": "BTC_USDT",
      "underlying_price": "70000",
      "multiplier": "0.0001",
      "order_price_round": "0.1",
      "mark_price_round": "0.1",
      "maker_fee_rate": "0.0004",
      "taker_fee_rate": "0.0004",
      "price_limit_fee_rate": "0.1",
      "ref_discount_rate": "0",
      "ref_rebate_rate": "0",
      "order_price_deviate": "0.5",
      "order_size_min": 1,
      "order_size_max": 100000,
      "orders_limit": 50
    }
    

    Responses

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

    Response Schema

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

    # List settlement history

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/settlements'
    query_param = 'underlying=BTC_USDT'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/options/settlements?underlying=BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /options/settlements

    List settlement history

    Parameters

    Name In Type Required Description
    underlying query string true Underlying (Obtained by listing underlying endpoint)
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp

    Example responses

    200 Response

    [
      {
        "time": 1598839200,
        "profit": "312.35",
        "fee": "0.3284",
        "settle_price": "11687.65",
        "contract": "BTC-WEEKLY-200824-11000-P",
        "strike_price": "12000"
      }
    ]
    

    Responses

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

    Response Schema

    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)

    # Get specified contract's settlement

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/settlements/BTC_USDT-20211130-65000-C'
    query_param = 'underlying=BTC_USDT&at=0'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/options/settlements/BTC_USDT-20211130-65000-C?underlying=BTC_USDT&at=0 \
      -H 'Accept: application/json'
    
    

    GET /options/settlements/{contract}

    Get specified contract's settlement

    Parameters

    Name In Type Required Description
    contract path string true none
    underlying query string true Underlying (Obtained by listing underlying endpoint)
    at query integer(int64) true none

    Example responses

    200 Response

    {
      "time": 1598839200,
      "profit": "312.35",
      "fee": "0.3284",
      "settle_price": "11687.65",
      "contract": "BTC-WEEKLY-200824-11000-P",
      "strike_price": "12000"
    }
    

    Responses

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

    Response Schema

    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)

    # List my options settlements

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/my_settlements'
    query_param = 'underlying=BTC_USDT'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/options/my_settlements"
    query_param="underlying=BTC_USDT"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /options/my_settlements

    List my options settlements

    Parameters

    Name In Type Required Description
    underlying query string true Underlying (Obtained by listing underlying endpoint)
    contract query string false Options contract name
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp

    Example responses

    200 Response

    [
      {
        "size": -1,
        "settle_profit": "0",
        "contract": "BTC_USDT-20220624-26000-C",
        "strike_price": "26000",
        "time": 1656057600,
        "settle_price": "20917.461281337048",
        "underlying": "BTC_USDT",
        "realised_pnl": "-0.00116042",
        "fee": "0"
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Options order book

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/order_book'
    query_param = 'contract=BTC_USDT-20210916-5000-C'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/options/order_book?contract=BTC_USDT-20210916-5000-C \
      -H 'Accept: application/json'
    
    

    GET /options/order_book

    Options order book

    Bids will be sorted by price from high to low, while asks sorted reversely

    Parameters

    Name In Type Required Description
    contract query string true Options contract name
    interval query string false Order depth. 0 means no aggregation is applied. default to 0
    limit query integer false Maximum number of order depth data in asks or bids
    with_id query boolean false Whether the order book update ID will be returned. This ID increases by 1 on every order book update

    # Enumerated Values

    Parameter Value
    interval 0
    interval 0.1
    interval 0.01

    Example responses

    200 Response

    {
      "id": 123456,
      "current": 1623898993.123,
      "update": 1623898993.121,
      "asks": [
        {
          "p": "1.52",
          "s": 100
        },
        {
          "p": "1.53",
          "s": 40
        }
      ],
      "bids": [
        {
          "p": "1.17",
          "s": 150
        },
        {
          "p": "1.16",
          "s": 203
        }
      ]
    }
    

    Responses

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

    Response Schema

    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

    # List tickers of options contracts

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/tickers'
    query_param = 'underlying=BTC_USDT'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/options/tickers?underlying=BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /options/tickers

    List tickers of options contracts

    Parameters

    Name In Type Required Description
    underlying query string true Underlying (Obtained by listing underlying endpoint)

    Example responses

    200 Response

    [
      {
        "name": "BTC_USDT-20211130-65000-C",
        "last_price": "13000",
        "mark_price": "14010",
        "position_size": 10,
        "ask1_size": 0,
        "ask1_price": "0",
        "bid1_size": 1,
        "bid1_price": "11",
        "vega": "41.41202",
        "theta": "-120.1506",
        "rho": "6.52485",
        "gamma": "0.00004",
        "delta": "0.33505",
        "mark_iv": "0.123",
        "bid_iv": "0.023",
        "ask_iv": "0.342",
        "leverage": "13"
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Get underlying ticker

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/underlying/tickers/BTC_USDT'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/options/underlying/tickers/BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /options/underlying/tickers/{underlying}

    Get underlying ticker

    Parameters

    Name In Type Required Description
    underlying path string true Underlying

    Example responses

    200 Response

    {
      "trade_put": 33505,
      "trade_call": 123,
      "index_price": "76543.3"
    }
    

    Responses

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

    Response Schema

    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)

    # Get options candlesticks

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/candlesticks'
    query_param = 'contract=BTC_USDT-20210916-5000-C'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/options/candlesticks?contract=BTC_USDT-20210916-5000-C \
      -H 'Accept: application/json'
    
    

    GET /options/candlesticks

    Get options candlesticks

    Parameters

    Name In Type Required Description
    contract query string true Options contract name
    limit query integer false Maximum number of records to be returned in a single list
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp
    interval query string false Interval time between data points

    # Enumerated Values

    Parameter Value
    interval 1m
    interval 5m
    interval 15m
    interval 30m
    interval 1h

    Example responses

    200 Response

    [
      {
        "t": 1539852480,
        "v": 97151,
        "c": "1.032",
        "h": "1.032",
        "l": "1.032",
        "o": "1.032"
      }
    ]
    

    Responses

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

    Response Schema

    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)

    # Mark price candlesticks of an underlying

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/underlying/candlesticks'
    query_param = 'underlying=BTC_USDT'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/options/underlying/candlesticks?underlying=BTC_USDT \
      -H 'Accept: application/json'
    
    

    GET /options/underlying/candlesticks

    Mark price candlesticks of an underlying

    Parameters

    Name In Type Required Description
    underlying query string true Underlying (Obtained by listing underlying endpoint)
    limit query integer false Maximum number of records to be returned in a single list
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp
    interval query string false Interval time between data points

    # Enumerated Values

    Parameter Value
    interval 1m
    interval 5m
    interval 15m
    interval 30m
    interval 1h

    Example responses

    200 Response

    [
      {
        "t": 1539852480,
        "v": 97151,
        "c": "1.032",
        "h": "1.032",
        "l": "1.032",
        "o": "1.032",
        "sum": "3580"
      }
    ]
    

    Responses

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

    Response Schema

    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)

    # Options trade history

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/trades'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/options/trades \
      -H 'Accept: application/json'
    
    

    GET /options/trades

    Options trade history

    Parameters

    Name In Type Required Description
    contract query string false Options contract name
    type query string(P) false C is call, while P is put
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp

    Example responses

    200 Response

    [
      {
        "id": 121234231,
        "create_time": 1514764800,
        "contract": "BTC_USDT",
        "size": -100,
        "price": "100.123"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » id integer(int64) Trade ID
    » create_time number(double) Trading time
    » create_time_ms number(double) Trading time, with milliseconds set to 3 decimal places.
    » contract string Futures contract
    » size integer(int64) Trading size
    » price string Trading price (quote currency)
    » is_internal boolean Whether internal trade. Internal trade refers to the takeover of liquidation orders by the insurance fund and ADL users. Since it is not a normal matching on the market depth, the transaction price may deviate, and it will not be recorded in the K-line. If it is not an internal trade, this field will not be returned.

    # List options account

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/accounts'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/options/accounts"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /options/accounts

    List options account

    Example responses

    200 Response

    {
      "user": 666,
      "currency": "USDT",
      "short_enabled": true,
      "total": "170",
      "unrealised_pnl": "-600",
      "init_margin": "1300",
      "maint_margin": "1125",
      "order_margin": "0",
      "available": "0",
      "point": "0"
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » user integer User ID
    » total string Total account balance
    » short_enabled boolean If the account is allowed to short
    » 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
    » available string Available balance to transfer out or trade
    » point string POINT amount
    » currency string Settle currency

    WARNING

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

    # List account changing history

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/account_book'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/options/account_book"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /options/account_book

    List account changing history

    Parameters

    Name In Type Required Description
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp
    type query string false Changing Type:

    # Detailed descriptions

    type: Changing Type:

    • dnw: Deposit & Withdraw
    • prem: Trading premium
    • fee: Trading fee
    • refr: Referrer rebate
    • set: settlement PNL

    # Enumerated Values

    Parameter Value
    type dnw
    type prem
    type fee
    type refr
    type set

    Example responses

    200 Response

    [
      {
        "time": 1636426005,
        "change": "-0.16",
        "balance": "7378.189",
        "text": "BTC_USDT-20211216-5000-P:25",
        "type": "fee"
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » time number(double) Change time
    » change string Amount changed (USDT)
    » balance string Account total balance after change (USDT)
    » type string Changing Type:
    - dnw: Deposit & Withdraw
    - prem: Trading premium
    - fee: Trading fee
    - refr: Referrer rebate
    - point_dnw: POINT Deposit & Withdraw
    - point_fee: POINT Trading fee
    - point_refr: POINT Referrer rebate
    » text string custom text

    WARNING

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

    # List user's positions of specified underlying

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/positions'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/options/positions"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /options/positions

    List user's positions of specified underlying

    Parameters

    Name In Type Required Description
    underlying query string false Underlying

    Example responses

    200 Response

    [
      {
        "user": 11027586,
        "underlying": "BTC_USDT",
        "underlying_price": "70000",
        "contract": "BTC_USDT-20211216-5000-P",
        "size": 10,
        "entry_price": "1234",
        "realised_pnl": "120",
        "mark_price": "6000",
        "mark_iv": "0.9638",
        "unrealised_pnl": "-320",
        "pending_orders": 1,
        "close_order": {
          "id": 232323,
          "price": "5779",
          "is_liq": false
        },
        "delta": "-0.0046",
        "gamma": "0",
        "vega": "2.87656",
        "theta": "-1.00247"
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Get specified contract position

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/positions/BTC_USDT-20211130-65000-C'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/options/positions/BTC_USDT-20211130-65000-C"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /options/positions/{contract}

    Get specified contract position

    Parameters

    Name In Type Required Description
    contract path string true none

    Example responses

    200 Response

    {
      "user": 11027586,
      "underlying": "BTC_USDT",
      "underlying_price": "70000",
      "contract": "BTC_USDT-20211216-5000-P",
      "size": 10,
      "entry_price": "1234",
      "realised_pnl": "120",
      "mark_price": "6000",
      "mark_iv": "0.9638",
      "unrealised_pnl": "-320",
      "pending_orders": 1,
      "close_order": {
        "id": 232323,
        "price": "5779",
        "is_liq": false
      },
      "delta": "-0.0046",
      "gamma": "0",
      "vega": "2.87656",
      "theta": "-1.00247"
    }
    

    Responses

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

    Response Schema

    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

    # List user's liquidation history of specified underlying

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/position_close'
    query_param = 'underlying=BTC_USDT'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/options/position_close"
    query_param="underlying=BTC_USDT"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /options/position_close

    List user's liquidation history of specified underlying

    Parameters

    Name In Type Required Description
    underlying query string true Underlying (Obtained by listing underlying endpoint)
    contract query string false Options contract name

    Example responses

    200 Response

    [
      {
        "time": 1631764800,
        "pnl": "-42914.291",
        "settle_size": "-10001",
        "side": "short",
        "contract": "BTC_USDT-20210916-5000-C",
        "text": "settled"
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Enumerated Values

    Property Value
    side long
    side short

    WARNING

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

    # Create an options order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/orders'
    query_param = ''
    body='{"size":-1,"iceberg":0,"contract":"BTC_USDT-20210916-5000-C","text":"-","tif":"gtc","price":"100"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/options/orders"
    query_param=""
    body_param='{"size":-1,"iceberg":0,"contract":"BTC_USDT-20210916-5000-C","text":"-","tif":"gtc","price":"100"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /options/orders

    Create an options order

    Body parameter

    {
      "size": -1,
      "iceberg": 0,
      "contract": "BTC_USDT-20210916-5000-C",
      "text": "-",
      "tif": "gtc",
      "price": "100"
    }
    

    Parameters

    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
    » tif body string false Time in force
    » text body string false User defined information. If not empty, must follow the rules below:

    # Detailed descriptions

    » tif: Time in force

    • gtc: GoodTillCancelled
    • ioc: ImmediateOrCancelled, taker only
    • poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee

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

    1. prefixed with t-
    2. no longer than 28 bytes without t- prefix
    3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created:
    • web: from web
    • api: from API
    • app: from mobile phones
    • auto_deleveraging: from ADL
    • liquidation: from liquidation
    • insurance: from insurance

    # Enumerated Values

    Parameter Value
    » tif gtc
    » tif ioc
    » tif poc

    Example responses

    201 Response

    {
      "status": "finished",
      "size": -1,
      "id": 2,
      "iceberg": 0,
      "is_liq": false,
      "is_close": false,
      "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"
    }
    

    Responses

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

    Response Schema

    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 How the order was finished.

    - filled: all filled
    - cancelled: manually cancelled
    - liquidated: cancelled because of liquidation
    - ioc: time in force is IOC, finish immediately
    - auto_deleveraged: finished by ADL
    - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because of position close
    » 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
    » 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- prefix
    3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
    Besides user defined information, reserved contents are listed below, denoting how the order is created:

    - 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

    # Enumerated Values

    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
    status open
    status finished
    tif gtc
    tif ioc
    tif poc

    WARNING

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

    # List options orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/orders'
    query_param = 'status=open'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/options/orders"
    query_param="status=open"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /options/orders

    List options orders

    Parameters

    Name In Type Required Description
    contract query string false Options contract name
    underlying query string false Underlying
    status query string true Only list the orders with this status
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp

    # Enumerated Values

    Parameter Value
    status open
    status finished

    Example responses

    200 Response

    [
      {
        "status": "finished",
        "size": -1,
        "id": 2,
        "iceberg": 0,
        "is_liq": false,
        "is_close": 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"
      }
    ]
    

    Responses

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

    Response Schema

    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 How the order was finished.

    - filled: all filled
    - cancelled: manually cancelled
    - liquidated: cancelled because of liquidation
    - ioc: time in force is IOC, finish immediately
    - auto_deleveraged: finished by ADL
    - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because of position close
    »» 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
    »» 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- prefix
    3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
    Besides user defined information, reserved contents are listed below, denoting how the order is created:

    - 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

    # Enumerated Values

    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
    status open
    status finished
    tif gtc
    tif ioc
    tif poc

    WARNING

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

    # Cancel all open orders matched

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/orders'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/options/orders"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    DELETE /options/orders

    Cancel all open orders matched

    Parameters

    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

    # Enumerated Values

    Parameter Value
    side ask
    side bid

    Example responses

    200 Response

    [
      {
        "status": "finished",
        "size": -1,
        "id": 2,
        "iceberg": 0,
        "is_liq": false,
        "is_close": 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"
      }
    ]
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) All orders matched cancelled [Inline]

    Response Schema

    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 How the order was finished.

    - filled: all filled
    - cancelled: manually cancelled
    - liquidated: cancelled because of liquidation
    - ioc: time in force is IOC, finish immediately
    - auto_deleveraged: finished by ADL
    - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because of position close
    »» 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
    »» 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- prefix
    3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
    Besides user defined information, reserved contents are listed below, denoting how the order is created:

    - 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

    # Enumerated Values

    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
    status open
    status finished
    tif gtc
    tif ioc
    tif poc

    WARNING

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

    # Get a single order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/orders/12345'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/options/orders/12345"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /options/orders/{order_id}

    Get a single order

    Parameters

    Name In Type Required Description
    order_id path integer(int64) true Order ID returned on successful order creation

    Example responses

    200 Response

    {
      "status": "finished",
      "size": -1,
      "id": 2,
      "iceberg": 0,
      "is_liq": false,
      "is_close": false,
      "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"
    }
    

    Responses

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

    Response Schema

    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 How the order was finished.

    - filled: all filled
    - cancelled: manually cancelled
    - liquidated: cancelled because of liquidation
    - ioc: time in force is IOC, finish immediately
    - auto_deleveraged: finished by ADL
    - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because of position close
    » 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
    » 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- prefix
    3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
    Besides user defined information, reserved contents are listed below, denoting how the order is created:

    - 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

    # Enumerated Values

    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
    status open
    status finished
    tif gtc
    tif ioc
    tif poc

    WARNING

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

    # Cancel a single order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/orders/12345'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/options/orders/12345"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    DELETE /options/orders/{order_id}

    Cancel a single order

    Parameters

    Name In Type Required Description
    order_id path integer(int64) true Order ID returned on successful order creation

    Example responses

    200 Response

    {
      "status": "finished",
      "size": -1,
      "id": 2,
      "iceberg": 0,
      "is_liq": false,
      "is_close": false,
      "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"
    }
    

    Responses

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

    Response Schema

    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 How the order was finished.

    - filled: all filled
    - cancelled: manually cancelled
    - liquidated: cancelled because of liquidation
    - ioc: time in force is IOC, finish immediately
    - auto_deleveraged: finished by ADL
    - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because of position close
    » 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
    » 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- prefix
    3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
    Besides user defined information, reserved contents are listed below, denoting how the order is created:

    - 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

    # Enumerated Values

    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
    status open
    status finished
    tif gtc
    tif ioc
    tif poc

    WARNING

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

    # List personal trading history

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/options/my_trades'
    query_param = 'underlying=BTC_USDT'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/options/my_trades"
    query_param="underlying=BTC_USDT"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /options/my_trades

    List personal trading history

    Parameters

    Name In Type Required Description
    underlying query string true Underlying (Obtained by listing underlying endpoint)
    contract query string false Options contract name
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp

    Example responses

    200 Response

    [
      {
        "underlying_price": "48000",
        "size": 1,
        "contract": "BTC_USDT-20210916-5000-C",
        "id": 1,
        "role": "taker",
        "create_time": 1631763397,
        "order_id": 4,
        "price": "100"
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Enumerated Values

    Property Value
    role taker
    role maker

    WARNING

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

    # EarnUni

    Lend & Earn

    # List currencies for 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 = '/earn/uni/currencies'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/earn/uni/currencies \
      -H 'Accept: application/json'
    
    

    GET /earn/uni/currencies

    List currencies for lending

    Example responses

    200 Response

    [
      {
        "currency": "AE",
        "min_lend_amount": "100",
        "max_lend_amount": "200000000",
        "max_rate": "0.00057",
        "min_rate": "0.000001"
      }
    ]
    

    Responses

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

    Response Schema

    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)

    # Get currency detail for 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 = '/earn/uni/currencies/btc'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/earn/uni/currencies/btc \
      -H 'Accept: application/json'
    
    

    GET /earn/uni/currencies/{currency}

    Get currency detail for lending

    Parameters

    Name In Type Required Description
    currency path string true Currency

    Example responses

    200 Response

    {
      "currency": "AE",
      "min_lend_amount": "100",
      "max_lend_amount": "200000000",
      "max_rate": "0.00057",
      "min_rate": "0.000001"
    }
    

    Responses

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

    Response Schema

    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)

    # Lend or redeem

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/earn/uni/lends'
    query_param = ''
    body='{"currency":"AE","amount":"100","min_rate":"0.00001","type":"lend"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/earn/uni/lends"
    query_param=""
    body_param='{"currency":"AE","amount":"100","min_rate":"0.00001","type":"lend"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /earn/uni/lends

    Lend or redeem

    Lending:

    The minimum interest rate is required in lending. The lending result is updated hourly and the interest profit is paid on the next hour. A high interest rate might lead to unsuccessful lending and no profit will be gained for that hour. If the funds are redeemed before the hourly settlement, no interest can be obtained for that hour. About priority: the orders created or amended first under the same interest rate will be lent out first

    Redemption:

    Funds that failed to be lent can be redeemed immediately. For the successfully lent funds, enjoy the hourly income, and the redemption will arrive at the next hour

    Note:

    Two minutes before and after the hour is the settlement time, lending and redemption are prohibited.

    Body parameter

    {
      "currency": "AE",
      "amount": "100",
      "min_rate": "0.00001",
      "type": "lend"
    }
    

    Parameters

    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.

    # Enumerated Values

    Parameter Value
    » type lend
    » type redeem

    Responses

    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

    # List user's lending orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/earn/uni/lends'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/earn/uni/lends"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /earn/uni/lends

    List user's lending orders

    Parameters

    Name In Type Required Description
    currency query string false Retrieve data of the specified currency
    page query integer(int32) false Page number
    limit query integer(int32) false Maximum response items. Default: 100, minimum: 1, Maximum: 100

    Example responses

    200 Response

    [
      {
        "currency": "BTC",
        "current_amount": "20.999992",
        "amount": "20.999992",
        "lent_amount": "0",
        "frozen_amount": "0",
        "min_rate": "0.1",
        "interest_status": "interest_dividend",
        "reinvest_left_amount": 0,
        "create_time": 1673247054000,
        "update_time": 1673247054000
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » None object Loan record
    »» currency string Currency
    »» current_amount string Current amount
    »» amount string Total amount
    »» lent_amount string Lent amount
    »» frozen_amount string Frozen amount
    »» min_rate string Minimum interest rate
    »» interest_status string Interest status: interest_dividend - regular dividend, interest_reinvest - interest reinvestment
    »» reinvest_left_amount string Amount not reinvested
    »» create_time integer(int64) Created time of the lending order
    »» update_time integer(int64) Upated time of the lending order

    WARNING

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

    # Amend lending order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/earn/uni/lends'
    query_param = ''
    body='{"currency":"AE","min_rate":"0.0001"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('PATCH', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="PATCH"
    url="/earn/uni/lends"
    query_param=""
    body_param='{"currency":"AE","min_rate":"0.0001"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    PATCH /earn/uni/lends

    Amend lending order

    Currently only supports amending the minimum interest rate (hour)

    Body parameter

    {
      "currency": "AE",
      "min_rate": "0.0001"
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » currency body string false Currency name
    » min_rate body string false Minimum interest rate

    Responses

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

    WARNING

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

    # List records of lending

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/earn/uni/lend_records'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/earn/uni/lend_records"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /earn/uni/lend_records

    List records of lending

    Parameters

    Name In Type Required Description
    currency query string false Retrieve data of the specified currency
    page query integer(int32) false Page number
    limit query integer(int32) false Maximum response items. Default: 100, minimum: 1, Maximum: 100
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp
    type query string false type: lend - lend, redeem - redeem

    # Enumerated Values

    Parameter Value
    type lend
    type redeem

    Example responses

    200 Response

    [
      {
        "type": "lend",
        "currency": "BTC",
        "amount": "1",
        "last_wallet_amount": "0.2",
        "last_lent_amount": "0",
        "last_frozen_amount": "0",
        "create_time": 1673247054000
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Get the user's total interest income of specified currency

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/earn/uni/interests/btc'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/earn/uni/interests/btc"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /earn/uni/interests/{currency}

    Get the user's total interest income of specified currency

    Parameters

    Name In Type Required Description
    currency path string true Currency

    Example responses

    200 Response

    {
      "currency": "AE",
      "interest": "123.345"
    }
    

    Responses

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

    Response Schema

    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

    # List interest records

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/earn/uni/interest_records'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/earn/uni/interest_records"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /earn/uni/interest_records

    List interest records

    Parameters

    Name In Type Required Description
    currency query string false Retrieve data of the specified currency
    page query integer(int32) false Page number
    limit query integer(int32) false Maximum response items. Default: 100, minimum: 1, Maximum: 100
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp

    Example responses

    200 Response

    [
      {
        "status": 1,
        "currency": "AE",
        "actual_rate": "0.0005",
        "interest": "0.05",
        "interest_status": "interest_dividend",
        "create_time": 1673247054000
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » None object Interest Record
    »» status integer Status: 0 - fail, 1 - success
    »» currency string Currency
    »» actual_rate string Actual Rate
    »» interest string Interest
    »» interest_status string Interest status: interest_dividend - regular dividend, interest_reinvest - interest reinvestment
    »» create_time integer(int64) Created time

    WARNING

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

    # Set interest reinvestment toggle

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/earn/uni/interest_reinvest'
    query_param = ''
    body='{"currency":"BTC","status":true}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('PUT', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="PUT"
    url="/earn/uni/interest_reinvest"
    query_param=""
    body_param='{"currency":"BTC","status":true}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    PUT /earn/uni/interest_reinvest

    Set interest reinvestment toggle

    Body parameter

    {
      "currency": "BTC",
      "status": true
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » currency body string true Currency
    » status body boolean true Interest toggle settings, true - interest reinvestment, false - regular dividend

    Responses

    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

    # query currency interest compounding status

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/earn/uni/interest_status/btc'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/earn/uni/interest_status/btc"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /earn/uni/interest_status/{currency}

    query currency interest compounding status

    Parameters

    Name In Type Required Description
    currency path string true Currency

    Example responses

    200 Response

    {
      "currency": "BTC",
      "interest_status": "interest_dividend"
    }
    

    Responses

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

    Response Schema

    Status Code 200

    UniCurrencyInterest

    Name Type Description
    » currency string Currency
    » interest_status string Interest status: interest_dividend - regular dividend, interest_reinvest - interest reinvestment

    WARNING

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

    # Collateral-loan

    Collateral Loan

    # Place order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/collateral/orders'
    query_param = ''
    body='{"collateral_amount":"1","collateral_currency":"BTC","borrow_amount":"49","borrow_currency":"USDT"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/loan/collateral/orders"
    query_param=""
    body_param='{"collateral_amount":"1","collateral_currency":"BTC","borrow_amount":"49","borrow_currency":"USDT"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /loan/collateral/orders

    Place order

    Body parameter

    {
      "collateral_amount": "1",
      "collateral_currency": "BTC",
      "borrow_amount": "49",
      "borrow_currency": "USDT"
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » collateral_amount body string true Collateral amount
    » collateral_currency body string true Collateral
    » borrow_amount body string true Borrowing amount
    » borrow_currency body string true Borrowed currency

    Example responses

    200 Response

    {
      "order_id": 10005578
    }
    

    Responses

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

    Response Schema

    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

    # List Orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/collateral/orders'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/loan/collateral/orders"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /loan/collateral/orders

    List Orders

    Parameters

    Name In Type Required Description
    page query integer(int32) false Page number
    limit query integer false Maximum number of records to be returned in a single list
    collateral_currency query string false Collateral
    borrow_currency query string false Borrowed currency

    Example responses

    200 Response

    [
      {
        "order_id": 10000421,
        "collateral_currency": "BTC",
        "borrow_currency": "USDT",
        "collateral_amount": "1",
        "borrow_amount": "1000",
        "repaid_amount": "10",
        "repaid_principal": "10",
        "repaid_interest": "0",
        "init_ltv": "0.0003934533764831",
        "current_ltv": "0.0004521768651985",
        "liquidate_ltv": "0.9",
        "status": "initial_status",
        "borrow_time": 1688462668,
        "left_repay_total": "990.0219384",
        "left_repay_interest": "0.0219384"
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Get a single order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/collateral/orders/100001'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/loan/collateral/orders/100001"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /loan/collateral/orders/{order_id}

    Get a single order

    Parameters

    Name In Type Required Description
    order_id path integer(int64) true Order ID returned on successful order creation

    Example responses

    200 Response

    {
      "order_id": 10000421,
      "collateral_currency": "BTC",
      "borrow_currency": "USDT",
      "collateral_amount": "1",
      "borrow_amount": "1000",
      "repaid_amount": "10",
      "repaid_principal": "10",
      "repaid_interest": "0",
      "init_ltv": "0.0003934533764831",
      "current_ltv": "0.0004521768651985",
      "liquidate_ltv": "0.9",
      "status": "initial_status",
      "borrow_time": 1688462668,
      "left_repay_total": "990.0219384",
      "left_repay_interest": "0.0219384"
    }
    

    Responses

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

    Response Schema

    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

    # Repayment

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/collateral/repay'
    query_param = ''
    body='{"order_id":37438962,"repay_amount":"1000","repaid_all":false}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/loan/collateral/repay"
    query_param=""
    body_param='{"order_id":37438962,"repay_amount":"1000","repaid_all":false}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /loan/collateral/repay

    Repayment

    Body parameter

    {
      "order_id": 37438962,
      "repay_amount": "1000",
      "repaid_all": false
    }
    

    Parameters

    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;

    # Detailed descriptions

    » repaid_all: Repayment method, set to true for full repayment, and false for partial repayment; When set to false for partial repayment, the repay_amount parameter cannot be greater than the remaining amount to be repaid by the user.

    Example responses

    200 Response

    {
      "repaid_principal": "11",
      "repaid_interest": "111"
    }
    

    Responses

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

    Response Schema

    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

    # Repayment history

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/collateral/repay_records'
    query_param = 'source=repay'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/loan/collateral/repay_records"
    query_param="source=repay"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /loan/collateral/repay_records

    Repayment history

    Parameters

    Name In Type Required Description
    source query string true Operation type: repay - Regular repayment, liquidate - Liquidation
    borrow_currency query string false Borrowed currency
    collateral_currency query string false Collateral
    page query integer(int32) false Page number
    limit query integer false Maximum number of records to be returned in a single list
    from query integer(int64) false Start timestamp of the query
    to query integer(int64) false Time range ending, default to current time

    Example responses

    200 Response

    [
      {
        "order_id": 10000425,
        "record_id": 181,
        "repaid_amount": "10.00000000000000000000",
        "borrow_currency": "USDT",
        "collateral_currency": "BTC",
        "collateral_amount": "1.00000000000000000000",
        "init_ltv": "0.00039345337648310000",
        "borrow_time": 1688471851,
        "repay_time": 1688526310,
        "total_interest": "0.25446901544300000000",
        "before_left_principal": "11.00000000",
        "pre_left_principal": "990.00000000000000000000",
        "after_left_principal": "990.00000000000000000000",
        "before_left_collateral": "1.00000000000000000000",
        "after_left_collateral": "1.00000000000000000000"
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Increase or redeem collateral

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/collateral/collaterals'
    query_param = ''
    body='{"collateral_amount":"1212","collateral_currency":"BTC","order_id":1130,"type":"append"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/loan/collateral/collaterals"
    query_param=""
    body_param='{"collateral_amount":"1212","collateral_currency":"BTC","order_id":1130,"type":"append"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /loan/collateral/collaterals

    Increase or redeem collateral

    Body parameter

    {
      "collateral_amount": "1212",
      "collateral_currency": "BTC",
      "order_id": 1130,
      "type": "append"
    }
    

    Parameters

    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

    Responses

    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

    # Query collateral adjustment records

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/collateral/collaterals'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/loan/collateral/collaterals"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /loan/collateral/collaterals

    Query collateral adjustment records

    Parameters

    Name In Type Required Description
    page query integer(int32) false Page number
    limit query integer false Maximum number of records to be returned in a single list
    from query integer(int64) false Start timestamp of the query
    to query integer(int64) false Time range ending, default to current time
    borrow_currency query string false Borrowed currency
    collateral_currency query string false Collateral

    Example responses

    200 Response

    [
      {
        "order_id": 10000417,
        "record_id": 10000452,
        "borrow_currency": "USDT",
        "borrow_amount": "1000.00000000000000000000",
        "collateral_currency": "BTC",
        "pre_collateral": "1.00000000000000000000",
        "after_collateral": "2.00000000000000000000",
        "pre_ltv": "0.00039345555621480000",
        "after_ltv": "0.00019672777810740000",
        "operate_time": 1688461924
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Query the total borrowing and collateral amount for the user

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/collateral/total_amount'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/loan/collateral/total_amount"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /loan/collateral/total_amount

    Query the total borrowing and collateral amount for the user

    Example responses

    200 Response

    {
      "borrow_amount": "11",
      "collateral_amount": "111"
    }
    

    Responses

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

    Response Schema

    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

    # Query user's collateralization ratio

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/collateral/ltv'
    query_param = 'collateral_currency=BTC&borrow_currency=USDT'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/loan/collateral/ltv"
    query_param="collateral_currency=BTC&borrow_currency=USDT"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /loan/collateral/ltv

    Query user's collateralization ratio

    Parameters

    Name In Type Required Description
    collateral_currency query string true Collateral
    borrow_currency query string true Borrowed currency

    Example responses

    200 Response

    {
      "collateral_currency": "BTC",
      "borrow_currency": "USDT",
      "init_ltv": "0.7",
      "alert_ltv": "0.8",
      "liquidate_ltv": "0.9",
      "min_borrow_amount": "3",
      "left_borrowable_amount": "4233030.635065916703"
    }
    

    Responses

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

    Response Schema

    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

    # Query supported borrowing and 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())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/loan/collateral/currencies \
      -H 'Accept: application/json'
    
    

    GET /loan/collateral/currencies

    Query supported borrowing and collateral currencies

    Parameters

    Name In Type Required Description
    loan_currency query string false The parameter loan_currency is used to specify the borrowing currency. If loan_currency is not provided, the API will return all supported borrowing currencies. If loan_currency is provided, the API will return an array of collateral currencies supported for the specified borrowing currency.

    Example responses

    200 Response

    [
      {
        "loan_currency": "BTC",
        "collateral_currency": [
          "BTC",
          "ETH",
          "GT"
        ]
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » None object Supported borrowing and collateral currencies
    »» loan_currency string Borrowed currency
    »» collateral_currency array List of supported collateral currencies

    # Multi-collateral-loan

    Multi-Collateral Loan

    # Create Multi-Collateral Order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/multi_collateral/orders'
    query_param = ''
    body='{"order_id":1721387470,"order_type":"fixed","fixed_type":"7d","fixed_rate":0.00001,"auto_renew":true,"auto_repay":true,"borrow_currency":"BTC","borrow_amount":"1","collateral_currencies":[{"currency":"USDT","amount":"1000"}]}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/loan/multi_collateral/orders"
    query_param=""
    body_param='{"order_id":1721387470,"order_type":"fixed","fixed_type":"7d","fixed_rate":0.00001,"auto_renew":true,"auto_repay":true,"borrow_currency":"BTC","borrow_amount":"1","collateral_currencies":[{"currency":"USDT","amount":"1000"}]}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /loan/multi_collateral/orders

    Create Multi-Collateral Order

    Body parameter

    {
      "order_id": 1721387470,
      "order_type": "fixed",
      "fixed_type": "7d",
      "fixed_rate": 0.00001,
      "auto_renew": true,
      "auto_repay": true,
      "borrow_currency": "BTC",
      "borrow_amount": "1",
      "collateral_currencies": [
        {
          "currency": "USDT",
          "amount": "1000"
        }
      ]
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » order_id body string false Order ID
    » order_type body string false current - current, fixed - fixed, if not specified, default to current
    » fixed_type body string false Fixed interest rate loan period: 7d - 7 days, 30d - 30 days. Must be provided for fixed
    » fixed_rate body string false Fixed interest rate, must be specified for fixed
    » auto_renew body boolean false Fixed interest rate, automatic renewal
    » auto_repay body boolean false Fixed interest rate, automatic repayment
    » borrow_currency body string true Borrowed currency
    » borrow_amount body string true Borrowing amount
    » collateral_currencies body array false Collateral currency and amount
    »» collateralCurrency body object false none
    »»» currency body string false Currency
    »»» amount body string false Size

    Example responses

    200 Response

    {
      "order_id": 10005578
    }
    

    Responses

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

    Response Schema

    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

    # List Multi-Collateral Orders

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/multi_collateral/orders'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/loan/multi_collateral/orders"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /loan/multi_collateral/orders

    List Multi-Collateral Orders

    Parameters

    Name In Type Required Description
    page query integer false Page number
    limit query integer false Maximum number of records to be returned in a single list
    sort query string false Sort types: time_desc - default sorting by creation time in descending order, ltv_asc - ascending order of ltv, ltv_desc - descending order of ltv.
    order_type query string false Order type, current - query current orders, fixed - query fixed orders. If not specified, default to querying current orders

    Example responses

    200 Response

    [
      {
        "order_id": "10005578",
        "order_type": "fixed",
        "fixed_type": "7d",
        "fixed_rate": 0.00001,
        "expire_time": 1703820105,
        "auto_renew": true,
        "auto_repay": true,
        "current_ltv": "0.0001004349664281",
        "status": "lent",
        "borrow_time": 1702615021,
        "total_left_repay_usdt": "106.491212982",
        "total_left_collateral_usdt": "1060300.18",
        "borrow_currencies": [
          {
            "currency": "GT",
            "index_price": "10.6491",
            "left_repay_principal": "10",
            "left_repay_interest": "0.00002",
            "left_repay_usdt": "106.491212982"
          }
        ],
        "collateral_currencies": [
          {
            "currency": "BTC",
            "index_price": "112794.7",
            "left_collateral": "9.4",
            "left_collateral_usdt": "1060270.18"
          },
          {
            "currency": "USDT",
            "index_price": "1",
            "left_collateral": "30",
            "left_collateral_usdt": "30"
          }
        ]
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Get Multi-Collateral Order Detail

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/multi_collateral/orders/12345'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/loan/multi_collateral/orders/12345"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /loan/multi_collateral/orders/{order_id}

    Get Multi-Collateral Order Detail

    Parameters

    Name In Type Required Description
    order_id path string true Order ID returned on successful order creation

    Example responses

    200 Response

    {
      "order_id": "10005578",
      "order_type": "fixed",
      "fixed_type": "7d",
      "fixed_rate": 0.00001,
      "expire_time": 1703820105,
      "auto_renew": true,
      "auto_repay": true,
      "current_ltv": "0.0001004349664281",
      "status": "lent",
      "borrow_time": 1702615021,
      "total_left_repay_usdt": "106.491212982",
      "total_left_collateral_usdt": "1060300.18",
      "borrow_currencies": [
        {
          "currency": "GT",
          "index_price": "10.6491",
          "left_repay_principal": "10",
          "left_repay_interest": "0.00002",
          "left_repay_usdt": "106.491212982"
        }
      ],
      "collateral_currencies": [
        {
          "currency": "BTC",
          "index_price": "112794.7",
          "left_collateral": "9.4",
          "left_collateral_usdt": "1060270.18"
        },
        {
          "currency": "USDT",
          "index_price": "1",
          "left_collateral": "30",
          "left_collateral_usdt": "30"
        }
      ]
    }
    

    Responses

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

    Response Schema

    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

    # Repay Multi-Collateral Loan

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/multi_collateral/repay'
    query_param = ''
    body='{"order_id":10005578,"repay_items":[{"currency":"btc","amount":"1","repaid_all":false}]}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/loan/multi_collateral/repay"
    query_param=""
    body_param='{"order_id":10005578,"repay_items":[{"currency":"btc","amount":"1","repaid_all":false}]}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /loan/multi_collateral/repay

    Repay Multi-Collateral Loan

    Body parameter

    {
      "order_id": 10005578,
      "repay_items": [
        {
          "currency": "btc",
          "amount": "1",
          "repaid_all": false
        }
      ]
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » order_id body integer(int64) true Order ID
    » repay_items body array true Repay Currency Item
    »» MultiLoanRepayItem body object false none
    »»» currency body string false Repayment currency
    »»» amount body string false Size
    »»» repaid_all body boolean false Repayment method, set to true for full repayment, false for partial repayment.

    Example responses

    200 Response

    {
      "order_id": 10005679,
      "repaid_currencies": [
        {
          "succeeded": false,
          "label": "INVALID_PARAM_VALUE",
          "message": "Invalid parameter value",
          "currency": "BTC",
          "repaid_principal": "1",
          "repaid_interest": "0.0001"
        },
        {
          "succeeded": true,
          "currency": "BTC",
          "repaid_principal": "1",
          "repaid_interest": "0.0001"
        }
      ]
    }
    

    Responses

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

    Response Schema

    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

    # List Multi-Collateral Repay Records

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/multi_collateral/repay'
    query_param = 'type=repay'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/loan/multi_collateral/repay"
    query_param="type=repay"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /loan/multi_collateral/repay

    List Multi-Collateral Repay Records

    Parameters

    Name In Type Required Description
    type query string true Operation type: repay - Regular repayment, liquidate - Liquidation
    borrow_currency query string false Borrowed currency
    page query integer false Page number
    limit query integer false Maximum number of records to be returned in a single list
    from query integer(int64) false Start timestamp of the query
    to query integer(int64) false Time range ending, default to current time

    Example responses

    200 Response

    [
      {
        "order_id": 10005679,
        "record_id": 1348,
        "init_ltv": "0.2141",
        "before_ltv": "0.215",
        "after_ltv": "0.312",
        "borrow_time": 1702995889,
        "repay_time": 1703053927,
        "borrow_currencies": [
          {
            "currency": "BAT",
            "index_price": "103.02",
            "before_amount": "1",
            "before_amount_usdt": "103.02",
            "after_amount": "0.999017",
            "after_amount_usdt": "102.91873134"
          }
        ],
        "collateral_currencies": [
          {
            "currency": "ETC",
            "index_price": "0.6014228107",
            "before_amount": "1000",
            "before_amount_usdt": "601.4228107",
            "after_amount": "1000",
            "after_amount_usdt": "601.4228107"
          }
        ],
        "repaid_currencies": [
          {
            "currency": "BAT",
            "index_price": "103.02",
            "repaid_amount": "0.001",
            "repaid_principal": "0.000983",
            "repaid_interest": "0.000017",
            "repaid_amount_usdt": "0.10302"
          }
        ],
        "total_interest_list": [
          {
            "currency": "BAT",
            "index_price": "103.02",
            "amount": "0.000017",
            "amount_usdt": "0.00175134"
          }
        ],
        "left_repay_interest_list": [
          {
            "currency": "BAT",
            "index_price": "103.02",
            "before_amount": "0.000017",
            "before_amount_usdt": "0.00175134",
            "after_amount": "0",
            "after_amount_usdt": "0"
          }
        ]
      }
    ]
    

    Responses

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

    Response Schema

    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
    »»» RepayRecordCurrency object none
    »»»» currency string Currency
    »»»» index_price string Currency Index Price
    »»»» before_amount string Amount before the operation
    »»»» before_amount_usdt string USDT Amount before the operation.
    »»»» after_amount string Amount after the operation.
    »»»» after_amount_usdt string USDT Amount after the operation.
    »»» collateral_currencies array List of collateral information
    »»»» RepayRecordCurrency object none
    »»»»» currency string Currency
    »»»»» index_price string Currency Index Price
    »»»»» before_amount string Amount before the operation
    »»»»» before_amount_usdt string Value in USDT before the operation
    »»»»» after_amount string Amount after the operation.
    »»»»» after_amount_usdt string Converted value to USDT after the operation.
    »»»» repaid_currencies array Repay Currency List
    »»»»» RepayRecordRepaidCurrency object none
    »»»»»» currency string Repayment currency
    »»»»»» index_price string Currency Index Price
    »»»»»» repaid_amount string Repayment amount
    »»»»»» repaid_principal string Principal
    »»»»»» repaid_interest string Interest
    »»»»»» repaid_amount_usdt string Value of the repayment amount in USDT
    »»»»» total_interest_list array Total Interest List
    »»»»»» RepayRecordTotalInterest object none
    »»»»»»» currency string Currency
    »»»»»»» index_price string Currency Index Price
    »»»»»»» amount string Interest Amount
    »»»»»»» amount_usdt string Interest amount converted to USDT
    »»»»»» left_repay_interest_list array List of left repay interest
    »»»»»»» RepayRecordLeftInterest object none
    »»»»»»»» currency string Currency
    »»»»»»»» index_price string Currency Index Price
    »»»»»»»» before_amount string Interest amount before repayment
    »»»»»»»» before_amount_usdt string Converted value of interest before repayment in USDT
    »»»»»»»» after_amount string Interest amount after repayment
    »»»»»»»» after_amount_usdt string Converted value of interest after repayment in USDT

    WARNING

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

    # Operate Multi-Collateral

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/multi_collateral/mortgage'
    query_param = ''
    body='{"order_id":10005578,"type":"append","collaterals":[{"currency":"btc","amount":"0.5"}]}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/loan/multi_collateral/mortgage"
    query_param=""
    body_param='{"order_id":10005578,"type":"append","collaterals":[{"currency":"btc","amount":"0.5"}]}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /loan/multi_collateral/mortgage

    Operate Multi-Collateral

    Body parameter

    {
      "order_id": 10005578,
      "type": "append",
      "collaterals": [
        {
          "currency": "btc",
          "amount": "0.5"
        }
      ]
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » order_id body integer(int64) true Order ID
    » type body string true Operation types: append - for adding collateral, redeem - for withdrawing collateral
    » collaterals body array false Collateral Currency List
    »» currency body string false Currency
    »» amount body string false Size

    Example responses

    200 Response

    {
      "order_id": 10005679,
      "collateral_currencies": [
        {
          "succeeded": true,
          "currency": "btc",
          "amount": "0.5"
        }
      ]
    }
    

    Responses

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

    Response Schema

    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

    # Query collateral adjustment records

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/multi_collateral/mortgage'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/loan/multi_collateral/mortgage"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /loan/multi_collateral/mortgage

    Query collateral adjustment records

    Parameters

    Name In Type Required Description
    page query integer false Page number
    limit query integer false Maximum number of records to be returned in a single list
    from query integer(int64) false Start timestamp of the query
    to query integer(int64) false Time range ending, default to current time
    collateral_currency query string false Collateral

    Example responses

    200 Response

    [
      {
        "order_id": 10000417,
        "record_id": 10000452,
        "before_ltv": "0.00039345555621480000",
        "after_ltv": "0.00019672777810740000",
        "operate_time": 1688461924,
        "borrow_currencies": [
          {
            "currency": "BTC",
            "index_price": "30000",
            "before_amount": "0.1",
            "before_amount_usdt": "1000",
            "after_amount": "0.6",
            "after_amount_usdt": "1006"
          }
        ],
        "collateral_currencies": [
          {
            "currency": "BTC",
            "index_price": "30000",
            "before_amount": "0.1",
            "before_amount_usdt": "1000",
            "after_amount": "0.6",
            "after_amount_usdt": "1006"
          }
        ]
      }
    ]
    

    Responses

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

    Response Schema

    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
    »»» CollateralRecordCurrency object none
    »»»» currency string Currency
    »»»» index_price string Currency Index Price
    »»»» before_amount string Amount before the operation
    »»»» before_amount_usdt string USDT Amount before the operation.
    »»»» after_amount string Amount after the operation.
    »»»» after_amount_usdt string USDT Amount after the operation.
    »»» collateral_currencies array Collateral Currency List
    »»»» CollateralRecordCurrency object none
    »»»»» currency string Currency
    »»»»» index_price string Currency Index Price
    »»»»» before_amount string Amount before the operation
    »»»»» before_amount_usdt string Value in USDT before the operation
    »»»»» after_amount string Amount after the operation.
    »»»»» after_amount_usdt string USDT Amount after the operation.

    WARNING

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

    # List User Currency Quota

    Code samples

    # coding: utf-8
    import 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&currency=BTC'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/loan/multi_collateral/currency_quota"
    query_param="type=collateral&currency=BTC"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /loan/multi_collateral/currency_quota

    List User Currency Quota

    Parameters

    Name In Type Required Description
    type query string true Currency types: collateral - collateral currency, borrow - borrowing currency.
    currency query string true When specifying collateral currencies, you can use commas to separate multiple currencies; for borrowing currencies, only one currency can be provided.

    Example responses

    200 Response

    [
      {
        "currency": "BTC",
        "index_price": "35306.1",
        "min_quota": "0",
        "left_quota": "2768152.4958445218723677",
        "left_quote_usdt": "97732668833.536273678"
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Query supported borrowing and collateral currencies in Multi-Collateral

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/multi_collateral/currencies'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/loan/multi_collateral/currencies \
      -H 'Accept: application/json'
    
    

    GET /loan/multi_collateral/currencies

    *Query supported borrowing and collateral currencies in Multi-Collateral *

    Example responses

    200 Response

    {
      "loan_currencies": [
        {
          "currency": "BTC",
          "price": "1212"
        },
        {
          "currency": "GT",
          "price": "12"
        }
      ],
      "collateral_currencies": [
        {
          "currency": "BTC",
          "index_price": "1212",
          "discount": "0.7"
        }
      ]
    }
    

    Responses

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

    Response Schema

    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

    # Get Multi-Collateral 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 = '/loan/multi_collateral/ltv'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/loan/multi_collateral/ltv \
      -H 'Accept: application/json'
    
    

    GET /loan/multi_collateral/ltv

    Get Multi-Collateral ratio

    The Multi-Collateral ratio is fixed, irrespective of the currency.

    Example responses

    200 Response

    {
      "init_ltv": "0.7",
      "alert_ltv": "0.8",
      "liquidate_ltv": "0.9"
    }
    

    Responses

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

    Response Schema

    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

    # Query fixed interest rates for the currency for 7 days and 30 days

    Code samples

    # coding: utf-8
    import requests
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/loan/multi_collateral/fixed_rate'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/loan/multi_collateral/fixed_rate \
      -H 'Accept: application/json'
    
    

    GET /loan/multi_collateral/fixed_rate

    Query fixed interest rates for the currency for 7 days and 30 days

    Example responses

    200 Response

    [
      {
        "currency": "BTC",
        "rate_7d": "0.000023",
        "rate_30d": "0.1",
        "update_time": 1703820105
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Earn

    earn

    # ETH2 swap

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/earn/staking/eth2/swap'
    query_param = ''
    body='{"side":"1","amount":"1.5"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/earn/staking/eth2/swap"
    query_param=""
    body_param='{"side":"1","amount":"1.5"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /earn/staking/eth2/swap

    ETH2 swap

    Body parameter

    {
      "side": "1",
      "amount": "1.5"
    }
    

    Parameters

    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

    Responses

    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

    # Dual Investment product 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 = '/earn/dual/investment_plan'
    query_param = ''
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/earn/dual/investment_plan \
      -H 'Accept: application/json'
    
    

    GET /earn/dual/investment_plan

    Dual Investment product list

    Example responses

    200 Response

    [
      {
        "id": 272,
        "instrument_name": "DOGE-17NOV23-0.067-P",
        "type": "put",
        "invest_currency": "USDT",
        "exercise_currency": "DOGE",
        "exercise_price": 0.067,
        "delivery_time": 1700208000,
        "min_copies": 1,
        "max_copies": 1000,
        "start_time": 1697685172,
        "end_time": 1697685172,
        "status": "ONGOING",
        "apy_display": "0.0114000000",
        "per_value": "1"
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Dual Investment order list

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/earn/dual/orders'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/earn/dual/orders"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /earn/dual/orders

    Dual Investment order list

    Example responses

    200 Response

    [
      {
        "id": 373,
        "plan_id": 176,
        "copies": "1.0000000000",
        "invest_amount": "0.0000000000",
        "settlement_amount": "0.0000000000",
        "create_time": 1697685172,
        "complete_time": 1697685172,
        "status": "CANCELED",
        "invest_currency": "USDT",
        "exercise_currency": "BTC",
        "settlement_currency": "",
        "exercise_price": "24500.0000000000",
        "settlement_price": "0.0000000000",
        "delivery_time": 1697685172,
        "apy_display": "0.6800000000",
        "apy_settlement": "0.0000000000"
      }
    ]
    

    Responses

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

    Response Schema

    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-INIT
    SETTLEMENT_SUCCESS-Settlement Success
    SETTLEMENT_PROCESSING-SEttlement Processing
    CANCELED-Canceled
    FAILED-Failed
    » invest_currency string Investment Currency
    » exercise_currency string Strike Currency
    » exercise_price string Strike price
    » settlement_price string settlement price
    » settlement_currency string Settle currency
    » apy_display string APY
    » apy_settlement string Settlement APY
    » delivery_time integer(int32) Settlement time

    WARNING

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

    # Place Dual Investment order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/earn/dual/orders'
    query_param = ''
    body='{"plan_id":"176","copies":"1"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/earn/dual/orders"
    query_param=""
    body_param='{"plan_id":"176","copies":"1"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /earn/dual/orders

    Place Dual Investment order

    Body parameter

    {
      "plan_id": "176",
      "copies": "1"
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » plan_id body string true Plan ID
    » copies body string true Copies

    Responses

    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

    # Structured Product 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 = '/earn/structured/products'
    query_param = 'status=in_process'
    r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    
    curl -X GET https://api.gateio.ws/api/v4/earn/structured/products?status=in_process \
      -H 'Accept: application/json'
    
    

    GET /earn/structured/products

    Structured Product List

    Parameters

    Name In Type Required Description
    type query string false Product Type (default all)
    status query string true Status (default: all)
    page query integer(int32) false Page number
    limit query integer false Maximum number of records to be returned in a single list

    # Detailed descriptions

    type: Product Type (default all)

    SharkFin2.0-SharkFin BullishSharkFin-BullishSharkFin BearishSharkFin-BearishSharkFin DoubleNoTouch-DoubleNoTouch RangeAccrual-RangeAccrual SnowBall-SnowBall

    status: Status (default: all)

    in_process-processing will_begin-unstarted wait_settlement-unsettled done-finish

    Example responses

    200 Response

    [
      {
        "id": 3700,
        "type": "BullishSharkFin",
        "name_en": "Bullish Sharkfin_USDT",
        "investment_period": 7,
        "min_annual_rate": "0.50",
        "mid_annual_rate": "7.50",
        "max_annual_rate": "13.00",
        "watch_market": "BTC_USDT",
        "investment_coin": "USDT",
        "start_time": 1698224400,
        "end_time": 1700902800,
        "status": "in_process"
      }
    ]
    

    Responses

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

    Response Schema

    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 Fin
    DoubleNoTouch-Double No-Touch
    RangeAccrual-Range Accrual
    SnowBall-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

    # Structured Product Order List

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/earn/structured/orders'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/earn/structured/orders"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /earn/structured/orders

    Structured Product Order List

    Parameters

    Name In Type Required Description
    from query integer(int64) false Start timestamp
    to query integer(int64) false End timestamp
    page query integer(int32) false Page number
    limit query integer false Maximum number of records to be returned in a single list

    Example responses

    200 Response

    [
      {
        "id": 35,
        "pid": "3691",
        "lock_coin": "ETH",
        "amount": "20",
        "status": "SUCCESS",
        "income": "0.000000",
        "create_time": 1697685172
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Place Structured Product Order

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/earn/structured/orders'
    query_param = ''
    body='{"pid":"1","amount":"0.5"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/earn/structured/orders"
    query_param=""
    body_param='{"pid":"1","amount":"0.5"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /earn/structured/orders

    Place Structured Product Order

    Body parameter

    {
      "pid": "1",
      "amount": "0.5"
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » pid body string false Plan ID
    » amount body string false Purchase Amount

    Responses

    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

    # Account

    Get account detail

    # Get account detail

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/account/detail'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/account/detail"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /account/detail

    Get account detail

    Example responses

    200 Response

    {
      "user_id": 1667201533,
      "ip_whitelist": [
        "127.0.0.1"
      ],
      "currency_pairs": [
        "USDT_BTC"
      ],
      "key": {
        "mode": 1
      },
      "tier": 2
    }
    

    Responses

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

    Response Schema

    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

    WARNING

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

    # Create STP Group

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/account/stp_groups'
    query_param = ''
    body='{"name":"stp_name"}'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/account/stp_groups"
    query_param=""
    body_param='{"name":"stp_name"}'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /account/stp_groups

    Create STP Group

    Only the main account is allowed to create a new STP user group

    Body parameter

    {
      "name": "stp_name"
    }
    

    Parameters

    Name In Type Required Description
    body body object true none
    » id body integer(int64) false STP Group ID
    » name body string true STP Group name
    » creator_id body integer(int64) false Creator ID
    » create_time body integer(int64) false Creation time

    Example responses

    200 Response

    {
      "id": 123435,
      "name": "group",
      "create_time": 1548000000,
      "creator_id": 10000
    }
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) User added successfully. Returning the current users within the STP group. Inline

    Response Schema

    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

    # List STP Groups

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/account/stp_groups'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/account/stp_groups"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /account/stp_groups

    List STP Groups

    Retrieve the list of STP groups created by the main account user only

    Parameters

    Name In Type Required Description
    name query string false Perform a fuzzy search based on the name

    Example responses

    200 Response

    [
      {
        "id": 123435,
        "name": "group",
        "create_time": 1548000000,
        "creator_id": 10000
      }
    ]
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    None array none
    » id 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

    # List users of the STP group

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/account/stp_groups/1/users'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/account/stp_groups/1/users"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /account/stp_groups/{stp_id}/users

    List users of the STP group

    Only the main account that created this STP group is allowed to list the user ID of the STP group

    Parameters

    Name In Type Required Description
    stp_id path integer(int64) true STP Group ID

    Example responses

    200 Response

    [
      {
        "user_id": 10000,
        "stp_id": 1,
        "create_time": 1548000000
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Add users to the STP group

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/account/stp_groups/1/users'
    query_param = ''
    body='[1,2,3]'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('POST', prefix + url, query_param, body)
    headers.update(sign_headers)
    r = requests.request('POST', host + prefix + url, headers=headers, data=body)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="POST"
    url="/account/stp_groups/1/users"
    query_param=""
    body_param='[1,2,3]'
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    POST /account/stp_groups/{stp_id}/users

    Add users to the STP group

    • Only the master account that created the STP user group is allowed to add users to the STP user group.- Only accounts under the main account are allowed to be added. Cross-account is not permitted

    Body parameter

    [
      1,
      2,
      3
    ]
    

    Parameters

    Name In Type Required Description
    stp_id path integer(int64) true STP Group ID
    body body array[integer] true User ID

    Example responses

    200 Response

    [
      {
        "user_id": 10000,
        "stp_id": 1,
        "create_time": 1548000000
      }
    ]
    

    Responses

    Status Meaning Description Schema
    200 OK (opens new window) User added successfully. Returning the current users within the STP group. [Inline]

    Response Schema

    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

    # Delete the user in the STP group

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/account/stp_groups/1/users'
    query_param = 'user_id=1'
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('DELETE', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="DELETE"
    url="/account/stp_groups/1/users"
    query_param="user_id=1"
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url?$query_param"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    DELETE /account/stp_groups/{stp_id}/users

    Delete the user in the STP group

    • Only the main account that created this STP group is allowed to delete users from the STP user group
    • Deletion is limited to accounts under the current main account; cross-account deletion is not permitted

    Parameters

    Name In Type Required Description
    stp_id path integer(int64) true STP Group ID
    user_id query integer(int64) true STP user ID, multiple can be separated by commas

    Example responses

    200 Response

    [
      {
        "user_id": 10000,
        "stp_id": 1,
        "create_time": 1548000000
      }
    ]
    

    Responses

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

    Response Schema

    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

    # Rebate

    broker rebate endpints

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/rebate/agency/transaction_history'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/rebate/agency/transaction_history"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /rebate/agency/transaction_history

    The agency obtains the transaction history of the recommended user

    Record time range cannot exceed 30 days

    Parameters

    Name In Type Required Description
    currency_pair query string false Specify the currency pair, if not specified, return all currency pairs
    user_id query integer(int64) false User ID. If not specified, all user records will be returned
    from query integer(int64) false Time range beginning, default to 7 days before current time
    to query integer(int64) false Time range ending, default to current time
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0

    Example responses

    200 Response

    {
      "total": 100,
      "list": [
        {
          "transaction_time": 1539852480,
          "user_id": 10000,
          "group_name": "gateio",
          "fee": "1",
          "fee_asset": "GT",
          "currency_pair": "GT_USDT",
          "amount": "1000",
          "source": "SPOT",
          "amount_asset": "GT"
        }
      ]
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » currency_pair string Currency pair
    » total integer(int64) Total
    » list array List of transaction history
    »» AgencyTransaction object none
    »»» transaction_time integer(int64) Transaction Time. (unix timestamp)
    »»» user_id integer(int64) User ID
    »»» group_name string Group name
    »»» fee string Fee
    »»» fee_asset string Fee currency
    »»» currency_pair string Currency pair
    »»» amount string Commission Amount
    »»» amount_asset string Commission Asset
    »»» source string Source. SPOT - SPOT Rebate, FUTURES - Futures Rebate

    WARNING

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

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/rebate/agency/commission_history'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/rebate/agency/commission_history"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /rebate/agency/commission_history

    The agency obtains the commission history of the recommended user

    Record time range cannot exceed 30 days

    Parameters

    Name In Type Required Description
    currency query string false Filter by currency. Return all currency records if not specified
    user_id query integer(int64) false User ID. If not specified, all user records will be returned
    from query integer(int64) false Time range beginning, default to 7 days before current time
    to query integer(int64) false Time range ending, default to current time
    limit query integer false Maximum number of records to be returned in a single list
    offset query integer false List offset, starting from 0

    Example responses

    200 Response

    {
      "total": 100,
      "list": [
        {
          "commission_time": 1539852480,
          "user_id": 10000,
          "group_name": "gateio",
          "commission_amount": "1000",
          "source": "SPOT",
          "commission_asset": "GT"
        }
      ]
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » currency_pair string Currency pair
    » total integer(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

    # The broker obtains the user's commission rebate records

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/rebate/broker/commission_history'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/rebate/broker/commission_history"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /rebate/broker/commission_history

    The broker obtains the user's commission rebate records

    Record time range cannot exceed 30 days

    Parameters

    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

    Example responses

    200 Response

    {
      "list": [
        {
          "user_id": 110285442,
          "group_name": "",
          "fee": "0.5000045000",
          "transaction_time": 1702545051,
          "amount": "-1000.00900000",
          "currency_pair": "DOGE_USDT",
          "source": "Futures",
          "fee_asset": "USDT"
        }
      ],
      "total": 47
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » total integer(int64) Total
    » list array List of comission history
    »» BrokerCommission object none
    »»» commission_time integer(int64) Commission Time. (unix timestamp)
    »»» user_id integer(int64) User ID
    »»» group_name string Group name
    »»» amount string The amount of commission rebates
    »»» fee string Fee
    »»» fee_asset string Fee currency
    »»» rebate_fee string The income from rebates, converted to USDT
    »»» source string Rebate Type: Spot、Futures、Options
    »»» currency_pair string Currency pair

    WARNING

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

    # The broker obtains the user's trading history

    Code samples

    # coding: utf-8
    import requests
    import time
    import hashlib
    import hmac
    
    host = "https://api.gateio.ws"
    prefix = "/api/v4"
    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
    
    url = '/rebate/broker/transaction_history'
    query_param = ''
    # for `gen_sign` implementation, refer to section `Authentication` above
    sign_headers = gen_sign('GET', prefix + url, query_param)
    headers.update(sign_headers)
    r = requests.request('GET', host + prefix + url, headers=headers)
    print(r.json())
    
    
    key="YOUR_API_KEY"
    secret="YOUR_API_SECRET"
    host="https://api.gateio.ws"
    prefix="/api/v4"
    method="GET"
    url="/rebate/broker/transaction_history"
    query_param=""
    body_param=''
    timestamp=$(date +%s)
    body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
    sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
    sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')
    
    full_url="$host$prefix$url"
    curl -X $method $full_url \
        -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"
    
    

    GET /rebate/broker/transaction_history

    The broker obtains the user's trading history

    Record time range cannot exceed 30 days

    Parameters

    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

    Example responses

    200 Response

    {
      "list": [
        {
          "user_id": 110285442,
          "group_name": "",
          "fee": "0.5000045000",
          "transaction_time": 1702545051,
          "amount": "-1000.00900000",
          "currency_pair": "DOGE_USDT",
          "source": "Futures",
          "fee_asset": "USDT"
        }
      ],
      "total": 47
    }
    

    Responses

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

    Response Schema

    Status Code 200

    Name Type Description
    » total integer(int64) Total
    » list array List of transaction history
    »» BrokerTransaction object none
    »»» transaction_time integer(int64) Transaction Time. (unix timestamp)
    »»» user_id integer(int64) User ID
    »»» group_name string Group name
    »»» fee string fee (usdt)
    »»» currency_pair string Currency pair
    »»» amount string Commission Amount
    »»» fee_asset string Fee currency
    »»» source string Rebate Type: Spot、Futures、Options

    WARNING

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

    # Schemas

    # SubAccountKey

    {
      "user_id": "string",
      "mode": 0,
      "name": "string",
      "perms": [
        {
          "name": "wallet",
          "read_only": true
        }
      ],
      "ip_whitelist": [
        "string"
      ],
      "key": "string",
      "state": 0,
      "created_at": "string",
      "updated_at": "string"
    }
    
    

    # Properties

    Name Type Required Restrictions Description
    user_id string false read-only User ID
    mode integer(int32) false none Mode: 1 - classic 2 - portfolio account
    name string false none API key name
    perms array false none none
    » name string false none Permission name (all permissions will be removed if no value is passed)

    - wallet: wallet
    - spot: spot/margin
    - futures: perpetual contract
    - delivery: delivery
    - earn: earn
    - options: options\m- account: Account
    - unified: unified
    - loan: Loan
    » 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 string false read-only Creation time
    updated_at string false read-only Last update time

    # Enumerated Values

    Property Value
    name wallet
    name spot
    name futures
    name delivery
    name earn
    name options
    name account
    name unified
    name loan

    # EstimateRate

    {
      "property1": "string",
      "property2": "string"
    }
    
    

    Estimate the current hourly lending rates, categorized by currency

    # Properties

    Name Type Required Restrictions Description
    additionalProperties string false none none

    # CurrencyPair

    {
      "id": "string",
      "base": "string",
      "quote": "string",
      "fee": "string",
      "min_base_amount": "string",
      "min_quote_amount": "string",
      "max_base_amount": "string",
      "max_quote_amount": "string",
      "amount_precision": 0,
      "precision": 0,
      "trade_status": "untradable",
      "sell_start": 0,
      "buy_start": 0
    }
    
    

    Spot currency pair

    # Properties

    Name Type Required Restrictions Description
    id string false none Currency pair
    base string false none Base currency
    quote string false none Quote currency
    fee string false none Trading fee
    min_base_amount string false none Minimum amount of base currency to trade, null means no limit
    min_quote_amount string false none Minimum amount of quote currency to trade, null means no limit
    max_base_amount string false none Maximum amount of base currency to trade, null means no limit
    max_quote_amount string false none Maximum amount of quote currency to trade, null means no limit
    amount_precision integer false none Amount scale
    precision integer false none Price scale
    trade_status string false none How currency pair can be traded

    - untradable: cannot be bought or sold
    - buyable: can be bought
    - sellable: can be sold
    - tradable: can be bought or sold
    sell_start integer(int64) false none Sell start unix timestamp in seconds
    buy_start integer(int64) false none Buy start unix timestamp in seconds

    # Enumerated Values

    Property Value
    trade_status untradable
    trade_status buyable
    trade_status sellable
    trade_status tradable

    # Order

    {
      "id": "string",
      "text": "string",
      "amend_text": "string",
      "create_time": "string",
      "update_time": "string",
      "create_time_ms": 0,
      "update_time_ms": 0,
      "status": "open",
      "currency_pair": "string",
      "type": "limit",
      "account": "spot",
      "side": "buy",
      "amount": "string",
      "price": "string",
      "time_in_force": "gtc",
      "iceberg": "string",
      "auto_borrow": true,
      "auto_repay": true,
      "left": "string",
      "filled_amount": "string",
      "fill_price": "string",
      "filled_total": "string",
      "avg_deal_price": "string",
      "fee": "string",
      "fee_currency": "string",
      "point_fee": "string",
      "gt_fee": "string",
      "gt_maker_fee": "string",
      "gt_taker_fee": "string",
      "gt_discount": true,
      "rebated_fee": "string",
      "rebated_fee_currency": "string",
      "stp_id": 0,
      "stp_act": "cn",
      "finish_as": "open",
      "action_mode": "string"
    }
    
    

    Spot order details

    # Properties

    Name Type Required Restrictions Description
    id string false read-only Order ID
    text string false none User defined information. If not empty, must follow the rules below:

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

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

    - 101: from android
    - 102: from IOS
    - 103: from IPAD
    - 104: from webapp
    - 3: from web
    - 2: from apiv2
    - apiv4: from apiv4
    amend_text string false read-only The custom data that the user remarked when amending the order
    create_time string false read-only Creation time of order
    update_time string false read-only Last modification time of order
    create_time_ms integer(int64) false read-only Creation time of order (in milliseconds)
    update_time_ms integer(int64) false read-only Last modification time of order (in milliseconds)
    status string false read-only Order status

    - open: to be filled
    - closed: filled
    - cancelled: cancelled
    currency_pair string true none Currency pair
    type string false none Order Type

    - limit : Limit Order
    - market : Market Order
    account string false none Account types, spot - spot account, margin - margin account, unified - unified account, cross_margin - cross margin account. Portfolio margin accounts can only be set to cross_margin
    side string true none Order side
    amount string true none When type is limit, it refers to base currency. For instance, BTC_USDT means BTC
    When type is market, it refers to different currency according to side
    - side : buy means quote currency, BTC_USDT means USDT
    - side : sell means base currency,BTC_USDT means BTC
    price string false none Price can't be empty when type= limit
    time_in_force string false none Time in force

    - gtc: GoodTillCancelled
    - ioc: ImmediateOrCancelled, taker only
    - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee
    - fok: FillOrKill, fill either completely or none
    Only ioc and fok are supported when type=market
    iceberg string false none Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported.
    auto_borrow boolean false write-only Used in margin or cross margin trading to allow automatic loan of insufficient amount if balance is not enough.
    auto_repay boolean false none Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that:

    1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders.
    2. auto_borrow and auto_repay cannot be both set to true in one order.
    left string false read-only Amount left to fill
    filled_amount string false read-only Amount traded to fill
    fill_price string false read-only Total filled in quote currency. Deprecated in favor of filled_total
    filled_total string false read-only Total filled in quote currency
    avg_deal_price string false read-only Average fill price
    fee string false read-only Fee deducted
    fee_currency string false read-only Fee currency unit
    point_fee string false read-only Points used to deduct fee
    gt_fee string false read-only GT used to deduct fee
    gt_maker_fee string false read-only GT used to deduct maker fee
    gt_taker_fee string false read-only GT used to deduct taker fee
    gt_discount boolean false read-only Whether GT fee discount is used
    rebated_fee string false read-only Rebated fee
    rebated_fee_currency string false read-only Rebated fee currency unit
    stp_id integer false read-only Orders between users in the same stp_id group are not allowed to be self-traded

    1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.
    2. stp_id returns 0 by default for orders that have not been set for STP group
    stp_act string false none Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies

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

    - cn: Cancel newest, Cancel new orders and keep old ones
    - co: Cancel oldest, Cancel old orders and keep new ones
    - cb: Cancel both, Both old and new orders will be cancelled
    finish_as string false read-only 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
    action_mode string false write-only Processing Mode:
    When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result
    ACK: Asynchronous mode, only returns key order fields
    RESULT: No clearing information
    FULL: Full mode (default)

    # Enumerated Values

    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

    # CancelBatchOrder

    {
      "currency_pair": "string",
      "id": "string",
      "account": "string",
      "action_mode": "string"
    }
    
    

    Info of order to be cancelled

    # Properties

    Name Type Required Restrictions Description
    currency_pair string true none Order currency pair
    id string true none Order ID or user custom ID.
    Custom ID are accepted only within 30 minutes after order creation
    account string false none If cancelled order is cross margin order or is portfolio margin account's API key, this field must be set and can only be cross_marginIf cancelled order is cross margin order, this field must be set and can only be cross_margin
    action_mode string false none Processing Mode:
    When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result
    ACK: Asynchronous mode, only returns key order fields
    RESULT: No clearing information
    FULL: Full mode (default)

    # Loan

    {
      "id": "string",
      "create_time": "string",
      "expire_time": "string",
      "status": "open",
      "side": "lend",
      "currency": "string",
      "rate": "string",
      "amount": "string",
      "days": 0,
      "auto_renew": false,
      "currency_pair": "string",
      "left": "string",
      "repaid": "string",
      "paid_interest": "string",
      "unpaid_interest": "string",
      "fee_rate": "string",
      "orig_id": "string",
      "text": "string"
    }
    
    

    Margin loan details

    # Properties

    Name Type Required Restrictions Description
    id string false read-only Loan ID
    create_time string false read-only Creation time
    expire_time string false read-only Repay time of the loan. No value will be returned for lending loan
    status string false read-only Loan status

    open - not fully loaned
    loaned - all loaned out for lending loan; loaned in for borrowing side
    finished - loan is finished, either being all repaid or cancelled by the lender
    auto_repaid - automatically repaid by the system
    side string true none Loan side
    currency string true none Loan currency
    rate string false none Loan rate. Only rates in [0.0001, 0.01] are supported.

    Not required in lending. Market rate calculated from recent rates will be used if not set
    amount string true none Loan amount
    days integer false none Loan days. Only 10 is supported for now
    auto_renew boolean false none Whether to auto renew the loan upon expiration
    currency_pair string false none Currency pair. Required if borrowing
    left string false read-only Amount not lent out yet
    repaid string false read-only Repaid amount
    paid_interest string false read-only Repaid interest
    unpaid_interest string false read-only Outstanding interest yet to be paid
    fee_rate string false none Loan fee rate
    orig_id string false none Original loan ID of the loan if auto-renewed, otherwise equals to id
    text string false none User defined custom ID

    # Enumerated Values

    Property Value
    status open
    status loaned
    status finished
    status auto_repaid
    side lend
    side borrow

    # LoanRecord

    {
      "id": "string",
      "loan_id": "string",
      "create_time": "string",
      "expire_time": "string",
      "status": "loaned",
      "borrow_user_id": "string",
      "currency": "string",
      "rate": "string",
      "amount": "string",
      "days": 0,
      "auto_renew": false,
      "repaid": "string",
      "paid_interest": "string",
      "unpaid_interest": "string"
    }
    
    

    Margin loaned record details

    # Properties

    Name Type Required Restrictions Description
    id string false none Loan record ID
    loan_id string false none Loan ID the record belongs to
    create_time string false none Loan time
    expire_time string false none Expiration time
    status string false none Loan record status
    borrow_user_id string false none Garbled user ID
    currency string false none Loan currency
    rate string false none Loan rate
    amount string false none Loan amount
    days integer false none Loan days
    auto_renew boolean false none Whether the record will auto renew on expiration
    repaid string false none Repaid amount
    paid_interest string false read-only Repaid interest
    unpaid_interest string false read-only Outstanding interest yet to be paid

    # Enumerated Values

    Property Value
    status loaned
    status finished

    # SpotPriceTriggeredOrder

    {
      "trigger": {
        "price": "string",
        "rule": ">=",
        "expiration": 0
      },
      "put": {
        "type": "limit",
        "side": "buy",
        "price": "string",
        "amount": "string",
        "account": "normal",
        "time_in_force": "gtc",
        "text": "string"
      },
      "id": 0,
      "user": 0,
      "market": "string",
      "ctime": 0,
      "ftime": 0,
      "fired_order_id": 0,
      "status": "string",
      "reason": "string"
    }
    
    

    Spot order detail

    # Properties

    Name Type Required Restrictions Description
    trigger object true none none
    » price string true none Trigger price
    » rule string true none Price trigger condition

    - >=: triggered when market price larger than or equal to price field
    - <=: triggered when market price less than or equal to price field
    » expiration integer true none How long (in seconds) to wait for the condition to be triggered before cancelling the order.
    put object true none none
    » type string false none Order type,default to limit

    - limit : Limit Order
    - market : Market Order
    » side string true none Order side

    - buy: buy side
    - sell: sell side
    » price string true none Order price
    » amount string true none When type is limit, it refers to base currency. For instance, BTC_USDT means BTC
    When type is market, it refers to different currency according to side
    - side : buy means quote currency, BTC_USDT means USDT
    - side : sell means base currency,BTC_USDT means BTC
    » account string true none Trading account type. Portfolio margin account must set to cross_margin

    - normal: spot trading
    - margin: margin trading
    - cross_margin: cross_margin trading
    » time_in_force string false none time_in_force

    - gtc: GoodTillCancelled
    - ioc: ImmediateOrCancelled, taker only
    » text string false none The source of the order, including:
    - web: web
    - api: api
    - app: app
    id integer(int64) false read-only Auto order ID
    user integer false read-only User ID
    market string true none Currency pair
    ctime integer(int64) false read-only Creation time
    ftime integer(int64) false read-only Finished time
    fired_order_id integer(int64) false read-only ID of the newly created order on condition triggered
    status string false read-only Status

    - open: open
    - cancelled: being manually cancelled
    - finish: successfully executed
    - failed: failed to execute
    - expired - expired
    reason string false read-only Additional remarks on how the order was finished

    # Enumerated Values

    Property Value
    rule >=
    rule <=
    type limit
    type market
    side buy
    side sell
    account normal
    account margin
    account cross_margin
    time_in_force gtc
    time_in_force ioc

    # Contract

    {
      "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,
      "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,
      "in_delisting": true,
      "orders_limit": 0,
      "enable_bonus": true,
      "enable_credit": true,
      "create_time": 0,
      "funding_cap_ratio": "string"
    }
    
    

    Futures contract details

    # Properties

    Name Type Required Restrictions Description
    name string false none Futures contract
    type string false none Futures contract type
    quanto_multiplier string false none Multiplier used in converting from invoicing to settlement currency
    leverage_min string false none Minimum leverage
    leverage_max string false none Maximum leverage
    maintenance_rate string false none Maintenance rate of margin
    mark_type string false none Mark price type, internal - based on internal trading, index - based on external index price
    mark_price string false none Current mark price
    index_price string false none Current index price
    last_price string false none Last trading price
    maker_fee_rate string false none Maker fee rate, where negative means rebate
    taker_fee_rate string false none Taker fee rate
    order_price_round string false none Minimum order price increment
    mark_price_round string false none Minimum mark price increment
    funding_rate string false none Current funding rate
    funding_interval integer false none Funding application interval, unit in seconds
    funding_next_apply number(double) false none Next funding time
    risk_limit_base string false none Risk limit base,deprecated
    risk_limit_step string false none Step of adjusting risk limit,deprecated
    risk_limit_max string false none Maximum risk limit the contract allowed,deprecated,It is recommended to use /futures/{settle}/risk_limit_tiers to query risk limits.
    order_size_min integer(int64) false none Minimum order size the contract allowed
    order_size_max integer(int64) false none Maximum order size the contract allowed
    order_price_deviate string false none deviation between order price and current index price. If price of an order is denoted as order_price, it must meet the following condition:

    abs(order_price - mark_price) <= mark_price * order_price_deviate
    ref_discount_rate string false none Referral fee rate discount
    ref_rebate_rate string false none Referrer commission rate
    orderbook_id integer(int64) false none Current orderbook ID
    trade_id integer(int64) false none Current trade ID
    trade_size integer(int64) false none Historical accumulated trade size
    position_size integer(int64) false none Current total long position size
    config_change_time number(double) false none Last changed time of configuration
    in_delisting boolean false none Contract is delisting
    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

    # Enumerated Values

    Property Value
    type inverse
    type direct
    mark_type internal
    mark_type index

    # Position

    {
      "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",
      "history_pnl": "string",
      "last_close_pnl": "string",
      "realised_point": "string",
      "history_point": "string",
      "adl_ranking": 0,
      "pending_orders": 0,
      "close_order": {
        "id": 0,
        "price": "string",
        "is_liq": true
      },
      "mode": "single",
      "cross_leverage_limit": "string",
      "update_time": 0,
      "open_time": 0
    }
    
    

    Futures position details

    # Properties

    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
    history_pnl string false read-only History realized PNL
    last_close_pnl string false read-only PNL of last position close
    realised_point string false read-only Realized POINT PNL
    history_point string false read-only History realized POINT PNL
    adl_ranking integer false read-only Ranking of auto deleveraging, a total of 1-5 grades, 1 is the highest, 5 is the lowest, and 6 is the special case when there is no position held or in liquidation
    pending_orders integer false read-only Current open orders
    close_order object|null false read-only Current close order if any, or null
    » id integer(int64) false none Close order ID
    » price string false none Close order price
    » is_liq boolean false none Is the close order from liquidation
    mode string false none Position mode, including:

    - single: dual mode is not enabled- dual_long: long position in dual mode- dual_short: short position in dual mode
    cross_leverage_limit string false none Cross margin leverage(valid only when leverage is 0)
    update_time integer(int64) false read-only Last update time
    open_time integer(int64) false none First Open Time

    # Enumerated Values

    Property Value
    mode single
    mode dual_long
    mode dual_short

    # FuturesOrder

    {
      "id": 0,
      "user": 0,
      "create_time": 0,
      "finish_time": 0,
      "finish_as": "filled",
      "status": "open",
      "contract": "string",
      "size": 0,
      "iceberg": 0,
      "price": "string",
      "close": false,
      "is_close": true,
      "reduce_only": false,
      "is_reduce_only": true,
      "is_liq": true,
      "tif": "gtc",
      "left": 0,
      "fill_price": "string",
      "text": "string",
      "tkfr": "string",
      "mkfr": "string",
      "refu": 0,
      "auto_size": "close_long",
      "stp_id": 0,
      "stp_act": "co",
      "amend_text": "string",
      "biz_info": "string"
    }
    
    

    Futures order details

    # Properties

    Name Type Required Restrictions Description
    id integer(int64) false read-only Futures order ID
    user integer false read-only User ID
    create_time number(double) false read-only Creation time of order
    finish_time number(double) false read-only Order finished time. Not returned if order is open
    finish_as string false read-only How the order was finished.

    - filled: all filled
    - cancelled: manually cancelled
    - liquidated: cancelled because of liquidation
    - ioc: time in force is IOC, finish immediately
    - auto_deleveraged: finished by ADL
    - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because of position close
    - stp: cancelled because self trade prevention
    status string false read-only Order status

    - open: waiting to be traded
    - finished: finished
    contract string true none Futures contract
    size integer(int64) true none Order size. Specify positive number to make a bid, and negative number to ask
    iceberg integer(int64) false none Display size for iceberg order. 0 for non-iceberg. Note that you will have to pay the taker fee for the hidden size
    price string false none Order price. 0 for market order with tif set as ioc
    close boolean false write-only Set as true to close the position, with size set to 0
    is_close boolean false read-only Is the order to close position
    reduce_only boolean false write-only Set as true to be reduce-only order
    is_reduce_only boolean false read-only Is the order reduce-only
    is_liq boolean false read-only Is the order for liquidation
    tif string false none Time in force

    - gtc: GoodTillCancelled
    - ioc: ImmediateOrCancelled, taker only
    - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee
    - fok: FillOrKill, fill either completely or none
    left integer(int64) false read-only Size left to be traded
    fill_price string false read-only Fill price of the order
    text string false none User defined information. If not empty, must follow the rules below:

    1. prefixed with t-
    2. no longer than 28 bytes without t- prefix
    3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.)
    Besides user defined information, reserved contents are listed below, denoting how the order is created:

    - web: from web
    - api: from API
    - app: from mobile phones
    - auto_deleveraging: from ADL
    - liquidation: from liquidation
    - insurance: from insurance
    tkfr string false read-only Taker fee
    mkfr string false read-only Maker fee
    refu integer false read-only Reference user ID
    auto_size string false write-only Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0
    stp_id integer false read-only Orders between users in the same stp_id group are not allowed to be self-traded

    1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.
    2. stp_id returns 0 by default for orders that have not been set for STP group
    stp_act string false none Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies

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

    - cn: Cancel newest, Cancel new orders and keep old ones
    - co: Cancel oldest, Cancel old orders and keep new ones
    - cb: Cancel both, Both old and new orders will be cancelled
    amend_text string false read-only The custom data that the user remarked when amending the order
    biz_info string false read-only Additional information

    # Enumerated Values

    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 -

    # FuturesPriceTriggeredOrder

    {
      "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,
      "finish_time": 0,
      "trade_id": 0,
      "status": "open",
      "finish_as": "cancelled",
      "reason": "string",
      "order_type": "string",
      "me_order_id": 0
    }
    
    

    Futures order details

    # Properties

    Name Type Required Restrictions Description
    initial object true none none
    » contract string true none Futures contract
    » size integer(int64) false none Order size. Positive size means to buy, while negative one means to sell. Set to 0 to close the position
    » price string true none Order price. Set to 0 to use market price
    » close boolean false write-only Set to true if trying to close the position
    » tif string false none Time in force. If using market price, only ioc is supported.

    - gtc: GoodTillCancelled
    - ioc: ImmediateOrCancelled
    » text string false none The source of the order, including:
    - web: web
    - api: api
    - app: app
    » reduce_only boolean false none Set to true to create a reduce-only order
    » auto_size string false write-only Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0
    » is_reduce_only boolean false read-only Is the order reduce-only
    » is_close boolean false read-only Is the order to close position
    trigger object true none none
    » strategy_type integer(int32) false none How the order will be triggered

    - 0: by price, which means the order will be triggered if price condition is satisfied
    - 1: by price gap, which means the order will be triggered if gap of recent two prices of specified price_type are satisfied.
    Only 0 is supported currently
    » price_type integer(int32) false none Price type. 0 - latest deal price, 1 - mark price, 2 - index price
    » price string false none Value of price on price triggered, or price gap on price gap triggered
    » rule integer(int32) false none Trigger condition type

    - 1: calculated price based on strategy_type and price_type >= price
    - 2: calculated price based on strategy_type and price_type <= price
    » expiration integer false none How long (in seconds) to wait for the condition to be triggered before cancelling the order.
    id integer(int64) false read-only Auto order ID
    user integer false read-only User ID
    create_time number(double) false read-only Creation time
    finish_time number(double) false read-only Finished time
    trade_id integer(int64) false read-only ID of the newly created order on condition triggered
    status string false read-only Auto order status

    - open: order is active
    - finished: order is finished
    - inactive: order is not active, only for close-long-order or close-short-order
    - invalid: order is invalid, only for close-long-order or close-short-order
    finish_as string false read-only How order is finished
    reason string false read-only Additional remarks on how the order was finished
    order_type string false none Take-profit/stop-loss types, which include:

    - close-long-order: order take-profit/stop-loss, close long position
    - close-short-order: order take-profit/stop-loss, close short position
    - close-long-position: position take-profit/stop-loss, close long position
    - close-short-position: position take-profit/stop-loss, close short position
    - plan-close-long-position: position planned take-profit/stop-loss, close long position
    - plan-close-short-position: position planned take-profit/stop-loss, close short position

    The order take-profit/stop-loss can not be passed by request. These two types are read only.
    me_order_id integer(int64) false read-only Corresponding order ID of order take-profit/stop-loss.

    # Enumerated Values

    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

    # DeliveryContract

    {
      "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,
      "in_delisting": true,
      "orders_limit": 0
    }
    
    

    Futures contract details

    # Properties

    Name Type Required Restrictions Description
    name string false none Futures contract
    underlying string false none Underlying
    cycle string false none Cycle type, e.g. WEEKLY, QUARTERLY
    type string false none Futures contract type
    quanto_multiplier string false none Multiplier used in converting from invoicing to settlement currency
    leverage_min string false none Minimum leverage
    leverage_max string false none Maximum leverage
    maintenance_rate string false none Maintenance rate of margin
    mark_type string false none Mark price type, internal - based on internal trading, index - based on external index price
    mark_price string false none Current mark price
    index_price string false none Current index price
    last_price string false none Last trading price
    maker_fee_rate string false none Maker fee rate, where negative means rebate
    taker_fee_rate string false none Taker fee rate
    order_price_round string false none Minimum order price increment
    mark_price_round string false none Minimum mark price increment
    basis_rate string false none Fair basis rate
    basis_value string false none Fair basis value
    basis_impact_value string false none Funding used for calculating impact bid, ask price
    settle_price string false none Settle price
    settle_price_interval integer false none Settle price update interval
    settle_price_duration integer false none Settle price update duration in seconds
    expire_time integer(int64) false none Contract expiry timestamp
    risk_limit_base string false none Risk limit base
    risk_limit_step string false none Step of adjusting risk limit
    risk_limit_max string false none Maximum risk limit the contract allowed
    order_size_min integer(int64) false none Minimum order size the contract allowed
    order_size_max integer(int64) false none Maximum order size the contract allowed
    order_price_deviate string false none deviation between order price and current index price. If price of an order is denoted as order_price, it must meet the following condition:

    abs(order_price - mark_price) <= mark_price * order_price_deviate
    ref_discount_rate string false none Referral fee rate discount
    ref_rebate_rate string false none Referrer commission rate
    orderbook_id integer(int64) false none Current orderbook ID
    trade_id integer(int64) false none Current trade ID
    trade_size integer(int64) false none Historical accumulated trade size
    position_size integer(int64) false none Current total long position size
    config_change_time number(double) false none Last changed time of configuration
    in_delisting boolean false none Contract is delisting
    orders_limit integer false none Maximum number of open orders

    # Enumerated Values

    Property Value
    cycle WEEKLY
    cycle BI-WEEKLY
    cycle QUARTERLY
    cycle BI-QUARTERLY
    type inverse
    type direct
    mark_type internal
    mark_type index