Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
Welcome to Gate API.
The APIv4 interface provides spot trading, margin trading, futures trading, including public interfaces to query market information, as well as private interfaces that require authentication to enable automated trading based on the API.
REST API BaseURL:
https://api.gateio.ws/api/v4https://api-testnet.gateapi.io/api/v4https://fx-api.gateio.ws/api/v4Available SDK:
Besides API examples, some SDK provides an additional demo application. The demo application is a relatively complete example demonstrating how to use the SDK. It can be built and run separately. Refer to corresponding repository for details.
Previously(before April 2020) futures APIv4 key are separated from spot one, but this is no longer the case anymore. You can create multiple keys with each key having multiple permissions now. e.g. you can create one key with spot read/write and futures read/write permission which can be used in both spot and futures trading.
History API keys will not be affected by this improvement. Previous spot key and futures key are now one key with only spot permissions enabled, another only futures permission enabled. You can reconfigure their permissions after migration.
APIv4 is a standalone brand-new HTTP REST API, currently used in parallel with APIv2. APIv4 provides complete trading operations, with more highly secured authentication method. What's more, APIv4 specification is written following OpenAPI Specification (opens new window). SDKs and documents are all generated from the same spec, which ensures consistency between documents and implementation.
The ways APIv4 and APIv2 differ are:
Which one to choose:
In order to further improve the platform's opening depth and trading liquidity, we will recruit institutional market makers in an open and transparent way, and provide a professional market maker's service rate scheme for professional institutional market makers according to their contribution to the platform's liquidity.
Provide the above content and submit to mm@gate.com , we will accept within 3 working days.
TIP
Vip11 and above need to open GT deduction in the personal center to enjoy the professional market rate.
If you have any questions or suggestions during the use, you can contact us in any of the following ways:
If you encounter API errors, it is recommended that you sort out the following content, so that we can quickly analyze the problem for you:
DANGER
Even if you submit a problem, you should not submit the API key information to customer service or others, otherwise there will be serious asset risk. If it has been accidentally leaked, please delete the existing API and rebuild it.
v4.106.86
2026-05-19
definitions/mercury/FuturesOrder.yaml / definitions/mercury/FuturesOrderTimerange.yaml / examples/mercury/FuturesOrder.json: add optional tpsl_tp_trigger_price / tpsl_sl_trigger_price (string) — take-profit / stop-loss trigger prices carried with futures orders for TP/SL placement workflowsv4.106.85
2026-05-19
tradfi-api.yaml: add optional query parameters page and page_size to GET /tradfi/positions/history (queryPositionHistoryList) for paginated historical positionsdefinitions/tradfi/PositionHistoryList.yaml / examples/tradfi/PositionHistoryList.json: response data includes total and total_pagedefinitions/mercury/FuturesOrder.yaml: add optional request field action_mode (string) — processing mode controlling which order fields are returned on placement; values ACK (async, key fields only), RESULT (no clearing/liquidation details), FULL (default, complete payload)futures-api.yaml / parameters.yaml (optional_delete_action_mode): add optional query action_mode to DELETE /futures/{settle}/orders (cancelFuturesOrders) and DELETE /futures/{settle}/orders/{order_id} (cancelFuturesOrder) so cancel responses follow the same field-profile semantics as createv4.106.84
2026-05-18
definitions/earn/DualGetPlans.yaml: add min_amount (string) — minimum investment amount for Dual Investment plans; extend examples/earn/DualGetPlans.json with the new fieldv4.106.83
2026-05-18
futures-auto-order-api.yaml: PUT /futures/{settle}/price_orders/amend no longer takes order_id as a path parameter — pass the target auto order ID in the JSON body as FuturesUpdatePriceTriggeredOrder.order_id (operationId updatePriceTriggeredOrder unchanged)definitions/mercury/FuturesPriceTriggeredOrder.yaml: document pos_margin_mode as position margin mode with enum isolated / cross; remove invalid enum placeholder textdefinitions/mercury/Order.yaml, OrderPatch.yaml, BatchOrder.yaml, and BatchAmendItem.yaml: distinct schema title values (SpotOrderStopProfit / SpotOrderStopLoss, PatchSpotOrderStopProfit / PatchSpotOrderStopLoss) for stable SDK/codegen; align stop_loss.order_price description to「止损委托价」v4.106.82
2026-05-14
futures-api.yaml: add Futures Chase Limit Order endpoints under /futures/{settle}/autoorder/v1/chase/*:
POST /futures/{settle}/autoorder/v1/chase/create (createChaseOrder) — create a chase limit order with contract, amount, price_limit (or offset_limit), optional reduce_only, text, is_dual_mode, price_type / price_gap_type / price_gap_value, pos_margin_mode, position_modePOST /futures/{settle}/autoorder/v1/chase/stop (stopChaseOrder) — stop a chase order by id or textPOST /futures/{settle}/autoorder/v1/chase/stop_all (stopAllChaseOrders) — stop chase orders in batch, optionally scoped by contract and pos_margin_modeGET /futures/{settle}/autoorder/v1/chase/list (getChaseOrders) — list chase orders with filters contract, is_finished, start_at / end_at, page_num / page_size, required sort_by (1 ORDER_SORT_CREATED_AT, 2 ORDER_SORT_FINISHED_AT), hide_cancel, reduce_only, sideGET /futures/{settle}/autoorder/v1/chase/detail (getChaseOrderDetail) — get a chase order detail by idCreateChaseOrderReq / CreateChaseOrderResp, StopChaseOrderReq / StopChaseOrderResp, StopAllChaseOrdersReq / StopAllChaseOrdersResp, GetChaseOrdersResp, GetChaseOrderDetailResp, and ChaseOrder (chase order detail / list item, exposing chase_price, interval_sec, suborder_*, price_type, price_gap_type / price_gap_value, etc.)v4.106.81
2026-05-13
stop_profit / stop_loss (object, title SpotOrderTPSL / PatchSpotOrderTPSL) to the spot order schemas in definitions/mercury/Order.yaml, definitions/mercury/OrderPatch.yaml, definitions/mercury/BatchOrder.yaml, and definitions/mercury/BatchAmendItem.yaml — limit-order take-profit / stop-loss: each carries trigger_price and order_price; pass {} to cancel the TP/SL, pass null to leave it unchanged. Examples in examples/mercury/ updated accordinglyv4.106.80
2026-05-10
crossex-api.yaml: add optional query parameter attributes on GET /crossex/history_orders (listCrossexHistoryOrders) — comma-separated order attribute filters (COMMON, LIQ, REDUCE, ADL, SETTLEMENT)crossex-api.yaml: clarify several query parameter descriptions (coin, symbol, etc.); document SETTLEMENT in CrossexOrder.attribute description; align CrossexTransferRecord.to_account_type with description (was title); narrow exchange_type description text to BINANCE / OKX / GATE / BYBIT (verify runtime values against product/backend)v4.106.78
2026-05-04
crossex-api.yaml: simplify the GET /crossex/coin_discount_rate (listCrossexCoinDiscountRate) summary to "Query Currency Discount Rate" — drop the "(isolated exchange mode, discount rate of margin currency)" parenthetical from the titlev4.106.75
2026-04-28
p2p-merchant-api.yaml: refresh examples with sanitized demo data (merchant/counterparty flows, payment methods including SWIFT); align sample field names (seller_realname, currency_type, etc.) with documented schemas; streamline lengthy legacy example blocksquant-api.yaml: set SpotGridStrategy.strategy_params_preview.additionalProperties to type: string; model SpotGridStrategyDetail.base_info, metrics, and position as dynamic maps (additionalProperties: string) instead of $ref to AIHubPortfolio* schemas, and drop the standalone AIHubPortfolioBaseInfo / AIHubPortfolioMetrics / AIHubPortfolioPosition components from this speccrossex-api.yaml: English descriptions for leverage-map responses; remove statement_type query parameter from the ledger-style list endpoint; rename response field statement_type to type and adjust its description; shorten CrossexSymbol / exchange / business / state field descriptionswallet-api.yaml: English description for page on GET /wallet/withdraw_status (“Page number”)messages.po translationsv4.106.73
2026-04-27
Contract model (definitions/mercury/Contract.yaml): add enable_circuit_breaker — whether a newly listed contract uses the mark price circuit breaker (platform may announce when enabling this for a market to reduce extreme post-listing volatility and liquidations)ContractStat model (definitions/mercury/ContractStat.yaml): add long_liq_usd_new and short_liq_usd_new (quote-currency liquidation notionals for USDT-settled contracts using long_liq_size / short_liq_size, multiplier, and mark_price); add top_long_size, top_short_size, long_taker_size, short_taker_size, top_long_account, top_short_account, long_users, and short_users for large-holder and taker / user-count statisticsv4.106.72
2026-04-27
slate/gate/widdershins-split.yaml and slate/gate/zh_CN/widdershins-split.yaml for tag-split Widdershins generation — omit includedDocs so each tag subpage only includes that tag's paths and related schemas (avoids repeating the shared changelog/general/api/errors/authentication/faq sections on every tag page); add tagGroups with a TradFi group title for the TradFi tagv4.106.71
2026-04-27
GET /unified/estimated_quick_repayment (getEstimatedQuickRepayment) — returns estimated quick repayment data (per-currency liabilities, balances available to repay, etc.).POST /unified/quick_repayment (createQuickRepayment) — executes quick repayment; request body uses string arrays debt_currencies and available_currencies. Both endpoints apply only to unified accounts in cross-currency margin or portfolio margin mode.definitions/unified/ with titles matching codegen (QuickEstimatedRepayment, QuickRepaymentInfo, QuickRepaymentResp; array item types UnifiedDebtCurrencies, UnifiedAvailableCurrencies, RepaidInfo, UsedInfo — files UnifiedQuickRepayDebtItem.yaml, UnifiedQuickRepayAvailableItem.yaml, UnifiedQuickRepayRepaidInfo.yaml, UnifiedQuickRepayUsedInfo.yaml). Examples live in examples/unified/.400 / 401 / 403 responses using definitions/GateErrorResponse.yaml.wallet-api.yaml: English description for the page query parameter on the sub-account balance listing endpointfutures-api.yaml: remove internal contract from FuturesOrderAmendment and simplify the amend-order request examplecrossex-api.yaml: refresh summaries/examples; align example fields (tif, fee_currency, avg_price, etc.); for the account-book style list, drop the statement_type query parameter and rename the response field to type, plus related example/copy updatesquant-api.yaml: quant/grid strategy schema and field documentation adjustmentsp2p-merchant-api.yaml: P2P merchant API path and schema updatesmessages.po for quick-repayment definitions and 4xx response copy, plus scope-text fixes for quick repayment; includes the quant API multi-line “trade size” description and related stringsv4.106.70
2026-04-21
150215, 150216, 150217, 150218, 150219 (Subaccount Transfer) to the BizType reference listassetswap-api.yaml: introduce dedicated response wrapper schemas ConfigResp (for GET /asset-swap/config) and OrderQueryV1Resp (for GET /asset-swap/orders/v1/{id}) and switch the corresponding response data $ref to the new wrappersquant-api.yaml (SpotGridStrategy.strategy_params_preview, SpotGridStrategyDetail.base_info / metrics / position): relax additionalProperties from forced type: string to free-form ({}); previously generated Map<String, String> will become Map<String, Object> in strongly-typed SDKsv4.106.61
2026-04-13
SubAccountBalance model: add locking field (locked amount by currency)id_string on FuturesPriceTriggeredOrder and TriggerOrderResponse: string form of the same auto order as numeric id (decimal string, int64-safe in JS); prefer for display or string keys; aligns with futures.orders / futures.autoorders payloads. Applies to futures price-trigger REST under /futures/{settle}/price_orders (create, list, batch cancel, get, cancel, amend).PartnerCommission and AgencyCommission list items in PartnerCommissionHistory / AgencyCommissionHistory: clarify commission_amount and commission_asset descriptions as rebate commission (not generic transaction amount)Contract model: add interest_rate (string ratio) for GET /futures/{settle}/contracts and GET /futures/{settle}/contracts/{contract} responsesgate-for-ai-agent pathsv4.106.60
2026-04-13
GET /earn/dual/project-recommend (getDualProjectRecommend)v4.106.59
2026-04-10
GET /earn/dual/order-refund-preview (getDualOrderRefundPreview) — dual-currency early redemption previewPOST /earn/dual/order-refund (placeDualOrderRefund) — dual-currency order early redemptionPOST /earn/dual/modify-order-reinvest (modifyDualOrderReinvest) — update dual-currency order reinvest settingsGET /earn/dual/project-recommend (getDualProjectRecommend) — dual-currency recommended projectsGET /earn/dual/investment_plan: add optional query parameters coin, type, quote_currency, sort, page, page_sizeGET /earn/dual/orders: add optional query parameters type, status, coinDualOrderRefundPreview, DualOrderRefundParams, DualModifyOrderReinvestParams, DualProjectRecommend and related examples under Earn dual-currency APIsv4.106.58
2026-04-03
Contract model: add contract_type field — contract classification type (e.g. stocks, metals, indices, forex, commodities)GET /wallet/sub_account_balances endpoint: add page and limit query parameters for pagination supportv4.106.57
2026-04-01
WithdrawalRecord model: clarify the final-state time field — when status is DONE, it represents withdrawal success time (no longer tied to block_number > 0)WithdrawalRecord and WithdrawalsDel models: simplify DONE status enum description (remove the note that completion required block_number > 0 for on-chain confirmation)GET /crossex/rule/risk_limits response: CrossexRiskLimitTier adds required string field quick_cal_amount (quick-calculation amount per risk tier)v4.106.56
2026-03-31
messages.po duplicate entries and a corrupted msgid; clear English msgstr for two oversized coupon-center Markdown blocks where JSON literals (%) caused gettext placeholder mismatch (full English translation to follow)v4.106.55
2026-03-30
GET /api/v4/rebate/partner/data/aggregated endpoint (getPartnerAgentDataAggregated) — aggregated partner agent statistics (rebate amount, volume, net fee, customer count, optional trading user count by business type)PartnerDataAggregated and PartnerDataAggregatedResponse model definitions for the aggregated rebate APIv4.106.54
2026-03-20
POST /api/v4/earn/autoinvest/plans/create endpoint - Create auto invest planPOST /api/v4/earn/autoinvest/plans/update endpoint - Update auto invest planPOST /api/v4/earn/autoinvest/plans/stop endpoint - Stop auto invest planPOST /api/v4/earn/autoinvest/plans/add_position endpoint - Add position immediatelyGET /api/v4/earn/autoinvest/coins endpoint - List currencies supporting auto investPOST /api/v4/earn/autoinvest/min_invest_amount endpoint - Get minimum investment amountGET /api/v4/earn/autoinvest/plans/records endpoint - List plan execution recordsGET /api/v4/earn/autoinvest/orders endpoint - List plan execution record details (order details)GET /api/v4/earn/autoinvest/config endpoint - List investment currency configurationGET /api/v4/earn/autoinvest/plans/detail endpoint - Get auto invest plan detailsGET /api/v4/earn/autoinvest/plans/list_info endpoint - List auto invest plansv4.106.52
2026-03-29
FuturesInitialOrder model: add optional amount field (string) for decimal contract size; when both size and amount are provided, amount takes precedenceFuturesUpdatePriceTriggeredOrder model: add optional amount field (string) with the same semantics as sizeSpotPricePutOrder model: add time_in_force to required fieldsv4.106.51
2026-03-27
v4.106.50
2026-03-26
POST /earn/staking/eth2/swap (swapETH2), GET /earn/staking/eth2/rate_records (rateListETH2)GET /earn/structured/products (listStructuredProducts), GET /earn/structured/orders (listStructuredOrders), POST /earn/structured/orders (placeStructuredOrder)definitions/earn/ and examples/earn/ for the above featuresv4.106.49
2026-03-25
FuturesOrderTimerange model; GET /futures/{settle}/orders_timerange response items now reference FuturesOrderTimerange instead of FuturesOrderFuturesOrder model: order_value and trade_value are read-only and marked x-external: false (excluded from public SDK output)GET /futures/{settle}/orders/{order_id}: clarify path parameter description for querying by order ID vs custom text fieldv4.106.48
2026-03-25
Currency model: add category field (array of strings for currency categories such as stocks, metals, indices, forex, commodities)v4.106.44
2026-03-19
BatchOrder model: clarify finish_as field ioc and poc enum descriptions to accurately reflect order cancellation reasons based on time-in-force settingsOrder model: clarify finish_as field ioc and poc enum descriptions to accurately reflect order cancellation reasons based on time-in-force settingsUnifiedAccount model: add mode field (account mode: classic/multi_currency/portfolio/single_currency)UnifiedAccount model: add balance_version field (balance version number)UnifiedAccount model: refine field descriptions for available, freeze, equity, iso_balance and other margin-related fieldsUidPushWithdrawalResp model: change id field type from integer (int64) to stringGET /crossex/fee endpoint: restructure response to array format to support multiple exchanges (BINANCE, OKX, GATE, BYBIT), add exchange_type field to identify exchange typePOST /crossex/convert endpoint: add order_id (order ID) and text (order ID text) fields to responsePERIODIC_ISOLATED enum value (hourly debt interest) to interest_type fieldv4.106.44
2026-03-20
GET /tradfi/symbols/detail (querySymbolDetail) now requires authenticationv4.106.43
2026-03-19
GET /earn/fixed-term/product (listEarnFixedTermProducts), GET /earn/fixed-term/product/{asset}/list (listEarnFixedTermProductsByAsset), POST /earn/fixed-term/user/lend (createEarnFixedTermLend), GET /earn/fixed-term/user/lend (listEarnFixedTermLends), POST /earn/fixed-term/user/pre-redeem (createEarnFixedTermPreRedeem), GET /earn/fixed-term/user/history (listEarnFixedTermHistory)FuturesUpdatePriceTriggeredOrder model: add format: int64 to order_id fieldfutures-auto-order-api.yaml: add format: int64 to price order response ID schemaparameters.yaml: change pos_margin_mode and dual_side parameters from optional to requiredv4.106.42
2026-03-19
UnifiedAccount model: add mode field (account mode: classic/multi_currency/portfolio/single_currency)UnifiedAccount model: add balance_version field (balance version number)UnifiedAccount model: refine field descriptions for available, freeze, equity, iso_balance and other margin-related fieldsv4.106.38
2026-03-14
amendOptionsOrder request body: add required contract field (options contract name)v4.106.36
2026-03-13
PUT /options/orders/{order_id} endpoint (amendOptionsOrder) for options order amendmentGET /tradfi/users/mt5-account now requires authentication (remove security: [])v4.106.34
2026-03-12
/alpha/orders list orders endpoint: change currency, side, status parameters from required to optionalv4.106.33
2026-03-10
BrokerCommission and BrokerTransaction models: add TradFi to source field (rebate transaction types: Spot, Futures, Options, Alpha, TradFi)v4.106.32
2026-03-05
multipart/form-data to application/json, extract request body schemas to separate definition filessecurity: [] from individual endpoints, now inheriting global apiv4 authenticationcomplete_rate_month, orders_buy_rate_month, transactions_month, transactions_all field types from integer to numberv4.106.31
2026-03-03
PUT /futures/{settle}/price_orders/{order_id} endpoint: move to new path PUT /futures/{settle}/price_orders/amend/{order_id}FuturesUpdatePriceTriggeredOrder model: change order_id field type from string to integerBatchOrder model: add new finish_as enum values: liquidate_cancelled, small, depth_not_enough, trader_not_enough, poc, fok, price_protect_cancelled, unknownOrder model: revise cancelled_reason field ioc enum description to clarify it also applies to poc/rvt/rat/rpi orders rejected as takerv4.106.30
2026-03-03
PUT /futures/{settle}/price_orders/{order_id} endpoint: move to new path PUT /futures/{settle}/price_orders/amend/{order_id}FuturesUpdatePriceTriggeredOrder model: change order_id field type from string to integerv4.106.29
2026-03-02
/crossex prefix to all endpoint pathsPOST /crossex/orders endpoint: add max pending order limit (1,000) to rate limit descriptionGET /crossex/positions/leverage response: change from array to map structureGET /crossex/margin_positions/leverage response: change from array to map structureDELETE /position to POST /crossex/position for close position operationPOST /unified/portfolio_calculator endpoint: revise description to reflect support for all underlying currencies with active options tradingMockSpotBalance model: remove currency restriction from equity field descriptionMockSpotOrder model: remove currency restriction from count field descriptionMockFuturesPosition and MockFuturesOrder models: update contract field description to support USDT perpetual contracts for all underlying currencies with active options tradingMockOptionsPosition and MockOptionsOrder models: update options_name field description to support all options contract marketsv4.106.28
2026-02-28
v4.106.27
2026-02-26
total_supply and market_cap field descriptions for currency endpointsContract model: add funding_impact_value field (funding rate depth impact value)FuturesBBOOrder model: remove limit_vip fieldv4.106.26
2026-02-12
POST /p2p/merchant/books/ads_list (get ads list)v4.106.25
2026-02-11
POST /earn/dual/orders endpoint: separate request and response modelsPlaceDualInvestmentOrderParams model for dual investment order request parametersPlaceDualInvestmentOrder model: add response fields (id, copies, invest_amount, settlement_amount, create_time, complete_time, status, invest_currency, exercise_currency, exercise_price, settlement_price, settlement_currency, apy_display, apy_settlement, delivery_time)DualGetPlans model: mark per_value field as deprecatedv4.106.24
2026-02-09
POST /otc/quote (create quote for fiat and stablecoin), POST /otc/order/create (create fiat order), POST /otc/stable_coin/order/create (create stablecoin order), GET /otc/get_user_def_bank (get user default bank info), GET /otc/bank_list (get user bank card list), POST /otc/order/paid (mark fiat order as paid), POST /otc/order/cancel (cancel fiat order), GET /otc/order/list (list fiat orders), GET /otc/stable_coin/order/list (list stablecoin orders), GET /otc/order/detail (get fiat order detail)v4.106.23
2026-02-06
OptionsOrder model: add x-is-bigint: true marker to id field for proper bigint handling in JavaScript SDKv4.106.22
2026-02-03
Order model: add price_protect_cancelled status to indicate orders cancelled due to price protectionv4.106.21
2026-02-03
amount field descriptions in sub-account transfers and transfer recordsv4.106.20
2026-02-02
POST /futures/{settle}/autoorder/v1/trail/create, POST /futures/{settle}/autoorder/v1/trail/stop, POST /futures/{settle}/autoorder/v1/trail/stop_all, GET /futures/{settle}/autoorder/v1/trail/list, GET /futures/{settle}/autoorder/v1/trail/detail, POST /futures/{settle}/autoorder/v1/trail/update, GET /futures/{settle}/autoorder/v1/trail/change_logTrailOrder and TrailChangeLog models for trailing ordersSwapCoin model: change side type to integer (0-pledge, 1-redeem) and remove pid int32 format constraintBatchFundingRatesRequest and BatchFundingRatesResponse models for batch funding rate queriesPOST /tradfi/users, GET /tradfi/users/assets, GET /tradfi/users/mt5-account, POST /tradfi/transactions, GET /tradfi/transactions and 14 moreFuturesAccount model: remove cross_settle fieldTotalBalance model: add new account types (meme_box, options, payment)UnifiedMarginTiers model: fix description formatv4.106.19
2026-01-27
Contract model: add enable_decimal field to indicate whether the contract supports decimal string type contract size. When this field is true, the contract supports decimal contract size (i.e., the size field can use decimal string type); when it is false, the contract does not support decimal contract size (i.e., the size field can only use integer type)v4.106.18
2026-01-26
POST /p2p/merchant/account/get_user_info (get account information), POST /p2p/merchant/account/get_counterparty_user_info (get counterparty information), POST /p2p/merchant/account/get_myself_payment (get payment methods list), POST /p2p/merchant/transaction/get_pending_transaction_list (get pending orders), POST /p2p/merchant/transaction/get_completed_transaction_list (get completed/historical orders), POST /p2p/merchant/transaction/get_transaction_details (get order details), POST /p2p/merchant/transaction/confirm-payment (confirm payment), POST /p2p/merchant/transaction/confirm-receipt (confirm receipt), POST /p2p/merchant/transaction/cancel (cancel order), POST /p2p/merchant/books/place_biz_push_order (place ad order), POST /p2p/merchant/books/ads_update_status (update ad status), POST /p2p/merchant/books/ads_detail (get ad details), POST /p2p/merchant/books/my_ads_list (get my ads list), POST /p2p/merchant/chat/get_chats_list (get chat history), POST /p2p/merchant/chat/send_chat_message (send text message), POST /p2p/merchant/chat/upload_chat_file (upload chat file)v4.106.17
2025-01-22
GET /loan/multi_collateral/currency_quota endpoint: add two new response fields in CurrencyQuota model - left_quota_fixed (remaining borrow/collateral limit for fixed-term currency) and left_quote_usdt_fixed (remaining currency limit converted to USDT for fixed-term currency)/loan/collateral/** ). These endpoints are no longer available.FuturesUpdatePriceTriggeredOrder model: change order_id type to string, add close fieldSpotPriceTrigger model: remove expiration from required fieldsv4.106.16
2025-01-20
v4.106.15
v4.106.14
Order model: add description in text field to clarify liquidation order scenarios (pm_liquidate, comb_margin_liquidate, scm_liquidate represent cross-margin liquidation orders, liquidate represents isolated margin liquidation orders)Trade model: add description in text field to clarify liquidation order scenarios (pm_liquidate, comb_margin_liquidate, scm_liquidate represent cross-margin liquidation orders, liquidate represents isolated margin liquidation orders)v4.106.13
POST /otc/quote (create quote for fiat and stablecoin), POST /otc/order/create (create fiat order), POST /otc/stable_coin/order/create (create stablecoin order), GET /otc/get_user_def_bank (get user default bank info), POST /otc/order/paid (mark order as paid), POST /otc/order/cancel (cancel order), GET /otc/order/list (list fiat orders), GET /otc/stable_coin/order/list (list stablecoin orders), GET /otc/order/detail (get fiat order detail), GET /otc/stable_coin/order/detail (get stablecoin order detail), GET /otc/get_api_order_uid (get API order users)operationId for all endpoints, update requestBody content type from multipart/form-data to application/json, add descriptions for all tags and responses, configure servers and security schemesv4.106.12
GET /earn/dual/balance endpoint to query dual investment balanceGET /futures/{settle}/get_leverage/{contract} endpoint to get leverage information for specified modePOST /futures/{settle}/positions/{contract}/set_leverage endpoint to update leverage for specified mode, simplifying the leverage interface logicPOST /futures/{settle}/set_position_mode endpoint to set position mode, replacing the dual_mode interfacePOST /futures/{settle}/positions/{contract}/reverse endpoint: add pos_margin_mode parameter (required for split position mode, values: isolated/cross)enable_dual_plus field in FuturesAccount model to indicate whether split position mode is supportedposition_mode field description in FuturesAccount model to clarify position modes: single (single position), dual (dual position), dual_plus (split position)pos_margin_mode field in FuturesOrder model to indicate position margin mode (isolated - isolated margin, cross - cross margin, only passed in simple split mode)pos_margin_mode field in Position model to indicate position margin mode (isolated - isolated margin, cross - cross margin)lever field in Position model to indicate current position leverage, gradually replacing the current leverage and cross_leverage_limit fieldsFuturesLeverage model definition for leverage query responsev4.106.11
slippage field description in BatchOrder, CurrencyPair, and Order models to clarify it represents the maximum slippage ratio supported for spot market orders, calculated based on the latest market price at the time of order placement (example: 0.03 means 3%)POST /spot/batch_orders endpoint: add response description indicating the response contains multiple order objects, with order object structure referencing the /spot/orders order placement endpointv4.106.10
GET /account/rate_limit endpoint: add description indicating the endpoint is not yet available for useGET /wallet/order_status endpoint: update summary and description to clarify it's for querying master-sub account transfer statusv4.106.9
PUT /futures/{settle}/price_orders/{order_id} endpoint: fix request body model FuturesUpdatePriceTriggeredOrder field name from contact to order_id, and mark order_id as required fieldPOST /loan/collateral/orders endpoint as deprecated/offlinev4.106.8
market_order_slip_ratio field in Contract model to indicate the maximum slippage ratio supported for market orders, with the slippage rate calculated based on the latest market pricemarket_order_size_max field in Contract model to indicate the maximum number of contracts supported for market orders, with a default value of 0. When the default value is used, the maximum number of contracts is limited by the order_size_max fieldmarket_order_slip_ratio field in FuturesOrder model to indicate custom maximum slippage rate for market orders. If not provided, the default contract settings will be usedmarket_order_slip_ratio field in BatchFuturesOrder model to indicate the maximum slippage ratio returned in order responsev4.106.7
GET /unified/batch_borrowable endpoint: add style: form and explode: false to currencies parameter for proper array parameter formattingGET /unified/estimate_rate endpoint: add style: form and explode: false to currencies parameter for proper array parameter formattingGET /loan/multi_collateral/current_rate endpoint: add style: form and explode: false to currencies parameter for proper array parameter formattingPOST /withdrawals/push endpoint (1r/10s) in Wallet private endpoints sectionv4.106.6
GET /options/order_book endpoint response model from FuturesOrderBook to OptionsOrderBook for better separation of Options and Futures APIsGET /options/trades endpoint response model from FuturesTrade to OptionsTrade for better separation of Options and Futures APIsGET /options/candlesticks endpoint response model from FuturesCandlestick to OptionsCandlestick for better separation of Options and Futures APIsOptionsOrderBook and OptionsTrade model definitions to provide dedicated models for Options API responsesv4.106.5
150102 (Currency Buyback-Debit), 150101 (Currency Buyback-Credit), 143 (Debit After Coin Name Change), 144 (Credit After Coin Name Change), 707 (Spot settlement in the same currency - transfer out), 708 (Spot settlement in the same currency - transfer in)v4.106.4
up_rate and down_rate fields in CurrencyPair model to display maximum price increase and decrease percentagesfunding_rate_limit field in Contract model to indicate funding rate cap valuev4.106.3
GET /futures/{settle}/accounts endpoint description to indicate support for querying both classic futures accounts and unified accountsPUT /futures/{settle}/accounts endpoint: enable_evolved_classic field marked as deprecatedGET /futures/{settle}/positions/{contract} endpoint summary to clarify dual-position query method when holding both long and short positions in the same contract marketPOST /futures/{settle}/positions/{contract}/margin endpoint summary with link to new risk limit rules, clarifying that leverage adjustment should be used instead of direct margin modificationPOST /futures/{settle}/positions/{contract}/leverage endpoint: clarify leverage parameter (for isolated margin, requires cross_leverage_limit to be empty) and cross_leverage_limit parameter (for cross margin, requires leverage to be set to 0)POST /futures/{settle}/dual_comp/positions/{contract}/risk_limit endpoint summary with link to risk limit rulesGET /options/accounts endpoint summary to indicate support for querying both classic options accounts and unified accountsPosition model field descriptions for better clarity on leverage and risk management: leverage (isolated margin leverage, 0 indicates cross margin mode), leverage_max (max leverage based on current position size), maintenance_rate (tiered maintenance margin rate calculation), liq_price (estimated liquidation price for reference only), initial_margin and maintenance_margin (expanded scope description), realised_pnl (detailed breakdown including settlement, funding fees, and trading fees), pnl_pnl (settlement P&L), pnl_fund (funding fee P&L), pnl_fee (total trading fees), history_pnl (all historical settlement P&L), and cross_leverage_limit (simplified description)FuturesAccount and DeliveryAccount models: total field updated to indicate "only applicable to classic futures accounts", position_margin marked as deprecated, order_margin updated to "initial margin for all pending orders", enable_evolved_classic and enable_new_dual_mode marked as deprecated, margin_mode enum expanded to include value 3 for single-currency margin modeOptionsAccount model: total and equity fields note added for unified account limitation, liq_triggered description updated to "whether account is in liquidation status", margin_mode enum expanded to include value 3, unrealised_pnl description enhanced with calculation formulaMarginAccount model: account_type description updated to remove "risk" option, risk field marked as deprecated, mmr description refinedContract and DeliveryContract models: quanto_multiplier renamed conceptually to "contract multiplier", maintenance_rate clarified as "first-tier maintenance margin rate requirement", mark_type and funding_cap_ratio marked as deprecated, mark_price_round simplified to "minimum unit of mark price"OptionsContract model: tag updated to "expiry period: day, week, month", multiplier updated to "option contract multiplier", underlying_price updated to "forward futures price for the delivery date", mark_price_round simplified, order_price_deviate and trade_id marked as deprecated, orders_limit refined to "maximum number of orders per user in this market"FuturesTicker and DeliveryTicker models: quanto_base_rate field marked as deprecatedOptionsTicker model: leverage calculation formula updated with reference noteFuturesTrade and DeliveryTrade models: is_internal field marked as deprecatedOptionsMyTrade and OptionsPosition models: underlying_price field updated to "forward futures price for the delivery date"PositionTimerange model: leverage_max and maintenance_rate descriptions refinedFuturesAutoDeleverage model: leverage and cross_leverage_limit descriptions clarified for better understanding of margin modesFuturesRiskLimitTier, FuturesLimitRiskTiers, DeliveryLimitRiskTiers): standardize maintenance_rate description as "first-tier maintenance margin rate requirement"MarginLeverageTier model: refine upper_limit (max borrowing limit based on leverage), mmr (maintenance margin rate as a comprehensive value under tiered requirements), and leverage (max leverage based on current debt size) descriptionsCreateUniLoan and UniLoanInterestRecord models: type field description updated to "lending type, margin indicates margin borrowing"v4.106.2
GET /wallet/getLowCapExchangeList endpoint to retrieve the list of low-liquidity or low-cap tokensv4.106.1
leverage and cross_leverage_limit field descriptions in Position and FuturesAutoDeleverage models for better clarity on cross/isolated margin mode usageleverage and cross_leverage_limit parameter descriptions in POST /futures/{settle}/positions/{contract}/leverage endpoint to clarify usage requirementsPUT /sub_accounts/{user_id}/keys/{key} endpoint summary to note that mode attribute cannot be modified via this endpointv4.106.0
integer type to string type. Affected models include: FuturesOrder (size, iceberg, left), BatchFuturesOrder (size, iceberg, left), Position (size, trade_long_size, trade_short_size), PositionTimerange (size), MyFuturesTrade (size, close_size), MyFuturesTradeTimeRange (size, close_size), FuturesTrade (size), FuturesOrderBook (size in asks and bids), FuturesCandlestick (v), FuturesLiquidate (size, order_size), FuturesLiqOrder (position_size, size, order_size), FuturesAutoDeleverage (size, entry_size), FuturesCollusionOrder (size, left), FuturesBatchAmendOrderRequest (size), Contract (order_size_min, order_size_max, trade_size, position_size), and ContractStat (long_liq_size, short_liq_size, open_interest)pid field in Position model for sub-position IDX-Gate-Size-Decimal: 1 default request header to ensure the server correctly handles size fieldsDeliveryAccount, DeliveryAccountBook, DeliveryOrder, DeliveryOrderBook, DeliveryPosition, DeliveryPositionClose, DeliveryTrade, DeliveryMyTrade, DeliveryLiquidate, DeliveryInsuranceRecord, DeliveryLimitRiskTiers, DeliveryCloseAllPositionsResponsev4.105.32
POST /futures/{settle}/positions/{contract}/leverage endpoint description with detailed position mode switching rules, usage examples, and risk warnings for better clarityv4.105.31
taker_fee and maker_fee field descriptions in TradeFee model to specify they are for spot tradingv4.105.29
deal field in GET /spot/my_trades endpoint response to display total deal amountoptions_order_loss field in GET /unified/accounts endpoint response to display options order loss in USDT, effective in portfolio margin modespot_order_loss field description in GET /unified/accounts endpoint response to clarify it represents spot order loss, effective in cross-currency margin mode and portfolio margin modecross_balance and iso_balance field descriptions in GET /unified/accounts endpoint response, now effective in both single-currency margin mode and cross-currency margin modev4.105.28
block_number field in DELETE /withdrawals/{withdrawal_id} endpoint response to display block numbercross_balance and iso_balance field descriptions in GET /unified/accounts endpoint response, now effective in both single-currency margin mode and cross-currency margin modev4.105.27
status field descriptions in DepositRecord, WithdrawalRecord, and WithdrawalsDel models for better clarityFINAL status from deposit status enum, optimize DONE status descriptionv4.105.24
GET /wallet/currency_chains endpoint description updated to indicate that currencies with extremely low liquidity or value are not supported via API and should be queried and processed through Web or AppGET /wallet/withdraw_status endpoint description updated to indicate that currencies with extremely low liquidity or value are not supported via API and should be queried and processed through Web or Appv4.105.20
DELETE /withdrawals/{withdrawal_id} endpoint response model updated to use WithdrawalsDel schemaBLOCKED, DEP_CREDITED, FINAL status values in GET /wallet/deposits endpoint responseis_deposit_disabled field in GET /wallet/currency_chains endpoint responsev4.105.19
GET /spot/currency_pairs and GET /spot/currency_pairs/{currency_pair} endpoints, fee field is now deprecatedPOST /earn/staking/eth2/swap endpoint summary updated from "ETH2 Swap" to "ETH Swap", ETH2 renamed to GTETHGET /earn/staking/eth2/rate_records endpoint summary updated to query historical rate of GTETHv4.105.18
PUT /futures/{settle}/price_orders endpoint to update a single price-triggered ordersettle, order_id, size, price, trigger_price, price_type, and auto_size parameters in update price-triggered order requestv4.105.11
GET /account/main_keys endpoint to query all main account API key informationGET /spot/currency_pairs and GET /spot/currency_pairs/{currency_pair} endpoints, fee field is now deprecatedv4.105.10
POST /futures/{settle}/bbo_orders endpoint for BBO level-based futures ordersPOST /futures/{settle}/price_orders endpoint, price and rule fields are now required in futures price trigger parametersv4.105.9
settlement_currency field in GET /futures/{settle}/positions response for multi-settlement supportauto_renew parameter in POST /earn/uni/lends request for automatic lending renewalGET /spot/trades endpoint with trade_type filter parameterv4.105.8
margin_mode field in GET /unified/accounts response to indicate account margin modefee_currency field in GET /spot/my_trades responsev4.105.7
liquidation_price field in GET /futures/{settle}/positions response for better risk managementPOST /spot/orders with stop_loss and take_profit parameters for advanced order typestotal_balance field in GET /unified/accounts responsev4.105.6
GET /wallet/saved_address endpoint to query saved withdrawal addressesnetwork_fee field in GET /wallet/withdrawals responsemin_amount and max_amount fields in GET /spot/currency_pairs responsev4.105.5
order_type field in GET /futures/{settle}/orders response to distinguish order typesGET /spot/candlesticks with support for 30s intervalavailable_balance field in GET /margin/accounts responsev4.105.4
funding_rate_next field in GET /futures/{settle}/tickers responsecross_leverage field in GET /unified/accounts responsev4.105.3
position_side parameter in GET /futures/{settle}/positions query for hedge mode supportGET /earn/dual/orders with investment_type filter parameterunrealized_pnl field in GET /futures/{settle}/accounts responsev4.105.2
maker_fee_rate and taker_fee_rate fields in GET /spot/fee responsesettle_currency field in GET /futures/{settle}/contracts responsev4.105.1
time_in_force parameter in POST /futures/{settle}/orders requestGET /wallet/deposits with network filter parameterv4.105.0
portfolio_margin field in GET /unified/accounts responseposition_mode parameter in POST /futures/{settle}/positions/mode requestv4.104.9
reduce_only parameter in POST /futures/{settle}/orders request for position reduction ordersGET /spot/orders with account_type filter parameterfunding_balance field in GET /futures/{settle}/accounts responsev4.104.8
apr field in GET /earn/uni/currencies responselock_period field in GET /earn/dual/investment_plan responsev4.104.7
order_book_id field in GET /spot/order_book response for order book versioningPOST /wallet/transfers with client_order_id parametertrading_fee_rate field in GET /spot/accounts responsev4.104.6
mark_price field in GET /futures/{settle}/tickers responseGET /futures/{settle}/insurance endpoint for insurance fund informationisolated_margin field in GET /futures/{settle}/positions responsev4.104.5
order_id field in GET /spot/my_trades response for trade-order mappingGET /unified/loans with currency filter parameterborrow_amount field in GET /unified/accounts responsev4.104.4
trigger_price field in GET /spot/price_orders responsemaintenance_rate field in GET /futures/{settle}/contracts responsev4.104.3
hedge_mode parameter in GET /futures/{settle}/positions queryGET /earn/dual/orders with status filter parametercross_margin_leverage field in GET /unified/accounts responsev4.104.2
settlement_size field in GET /futures/{settle}/my_trades responseGET /wallet/total_balance endpoint for total account balanceavailable_margin field in GET /margin/accounts responsev4.104.1
post_only parameter in POST /spot/orders request for maker-only ordersGET /futures/{settle}/orders with contract filter parameterfunding_time field in GET /futures/{settle}/funding_rate responsev4.104.0
GET /unified/risk_units endpoint for unified account risk unit calculationrisk_level field in GET /unified/accounts responseauto_borrow parameter in POST /unified/orders request for automatic borrowingv4.103.0
code field in GET /spot/account_book query parameter and response to filter account book entries by specific codetext parameter to closeAllPositions operation for order remarks when closing all positionsv4.102.6
SwapCoinStruct with additional fields: pid, subtype, exchange_amount, updateStamp, protocol_type, client_order_id, sourcev4.102.0
is_all_collateral field in GET /unified/accounts endpoint response to indicate if all currencies are used as collateralenabled_collateral field in balances array of unified accounts to show currency collateral statusPOST /unified/collateral_currencies endpoint, Set collateral currencies for cross-currency margin modev4.101.9
GET /futures/{settle}/risk_limit_table endpoint, Query risk limit tier table by table_idenable_tiered_mm field in futures account model for tiered maintenance margin calculationrisk_limit_table and average_maintenance_rate fields in position model for enhanced risk managementdeduction field in futures limit risk tiers for maintenance margin quick calculationFuturesRiskLimitTier and FuturesRiskLimitTierList for risk managementPOST /earn/staking/swap endpoint response structure with improved swap order detailsv4.100.0
GET /earn/staking/coins endpoint, Query on-chain staking coin typesPOST /earn/staking/swap endpoint, On-chain staking coin swapsub_broker_info object field in broker commission and transaction APIsv4.99.0
refresh_time field in GET /spot/accounts endpoint responsePUT /earn/uni/interest_reinvest endpointv4.98.0
/earn/uni/rate endpoint, Currency estimate annualized interest ratedelisting_time, trade_url fields in GET /spot/currency_pairs and GET /spot/currency_pairs/{currency_pair} endpointsv4.97.0
GET /unified/batch_borrowable endpoint, Batch query unified account can be borrowed up to a maximumGET /spot/candlesticks endpoint, interval supports 1s granularityGET /earn/uni/chart endpoint, UniLoan currency annualized trend chartPOST /futures/{settle}/positions/cross_mode endpoint, Switch to the full position-by-store modev4.96.0
cross_margin_balance,cross_mmr,cross_imr field in GET /futures/{settle}/accounts responsev4.95.0
code field in GET /spot/account_book query & responseGET /unified/transferables endpoint, Batch query unified account can be transferred up to a maximum ofGET /margin/user/loan_margin_tiers endpoint, Check the user's own leverage lending gradient in the
current marketGET /margin/loan_margin_tiers endpoint, Query the current market leverage lending gradientPOST /margin/leverage/user_market_setting endpoint, Set the user market leverage multipleGET /margin/user/account endpoint, Query the user's leverage account listv4.94.0
GET /unified/currencies endpoint, List of loan currencies supported by unified accountsub_uid field in GET /unified/accounts queryv4.93.0
plan_id field in GET /earn/dual/investment_plan queryfrom, to, page, limit fields in GET /earn/dual/orders querytext field in GET /earn/dual/orders responsetext field in POST /earn/dual/orders responseGET /earn/staking/eth2/rate_records endpoint, Query historical rate of GTETHv4.92.0
2025-02-24
name field in GET /spot/currencies querybase_name, quote_name fields in GET /spot/currency_pairs responseunified field in GET /spot/price_orders querysub_uid field in GET /unified/accounts queryv4.91.0
2025-02-10
2025-04-01 After that, we will remove the following interface, please migrate to the new interface as soon as possible
v4.90.0
2025-01-20
transaction_type field in GET /wallet/push queryGET /rebate/user/sub_relation endpoint, Query whether the specified user is in the systemorder_size field inGET /futures/{settle}/liq_orders responsetype field in GET /spot/currency_pairs responsev4.88.0
2024-12-24
GET /spot/insurance_history endpoint, Query spot insurance fund historical datacross_balance、iso_balance、im、mm、imr、mmr、margin_balance、available_margin field
in GET /unified/accounts responsePUT /unified/unified_mode endpoint，Added single-currency margin modev4.87.0
GET /unified/history_loan_rate endpoint, Get historical lending ratesv4.86.0
2024-12-02
GET /wallet/order_status endpoint. Transfer status queryupdate_id field in GET /futures/{settle}/positions responsev4.85.0
2024-11-11
x-gate-exptime field in POST /futures/{settle}/orders、POST /spot/batch_order header.Add cross_order_margin、cross_initial_margin、cross_maintenance_margin、cross_unrealised_pnl、cross_available、isolated_position_margin
field in POST /futures/{settle}/dual_mode response.
v4.84.0
2024-11-04
GET /loan/multi_collateral/current_rate endpoint, Query the current interest rate of the currencylowest_size、highest_size field in GET /spot/tickers responseamount field in POST /earn/dual/orders request bodyv4.83.0
2024-10-28
GET /unified/leverage/user_currency_config endpoint, Query the maximum and minimum leverage multiples
that users can set for a currencyGET /unified/leverage/user_currency_setting endpoint, Get the user's currency leveragePOST /unified/leverage/user_currency_setting endpoint, Set the currency leverage ratioid field in GET /futures/{settle}/account_book responseleverage field in GET /unified/currency_discount_tiers responsev4.82.0
2024-10-14
GET /account/rate_limit endpoint, Get user flow limit information. For details, please refer
to Trade Ratio Rate Limitingcopy_trading_role field in GET /account/detail responsev4.81.0
2024-09-30
POST /options/countdown_cancel_all endpoint, Countdown to cancel ordermessage field in GET /wallet/push responsefrom、to in GET /futures/{settle}/funding_rate queryis_max field in POST /earn/dual/orders responsev4.80.0
2024-09-09
GET /options/mmp endpoint, MMP QueryPOST /options/mmp endpoint, MMP SettingsPOST /options/mmp/reset endpoint, MMP Resetblock_number field in GET /wallet/withdrawals responsev4.79.0
2024-09-02
from、to field in GET /unified/interest_records queryoptions field in GET /unified/unified_mode responseoptions field in PUT /unified/unified_mode request bodyv4.78.0
2024-08-19
GET /wallet/push endpoint, Get RecordsPOST /withdrawals/push endpoint, Transfer between spot main accounts. Both parties cannot be
sub-accounts.GET /futures/{settle}/batch_amend_orders endpoint, Batch modify orders with specified IDsclose_size field in GET /futures/{settle}/my_trades responsetx_id field in POST /wallet/transfers responsev4.77.0
2024-08-05
GET /sub_accounts/unified_mode endpoint，Get sub-account modefrom、to field in GET /rebate/broker/commission_history queryfrom、to field in GET /rebate/broker/transaction_history queryv4.76.0
2024-07-22
GET /rebate/partner/sub_list endpoint，Partner subordinate listpage、limit field in GET /flash_swap/currency_pairs queryorder_id、currency_pair、account field in PATCH /spot/orders/{order_id}order_id、currency_pair、account field in DELETE /spot/orders/{order_id}v4.75.1
2024-07-08
GET /delivery/{settle}/risk_limit_tiers endpoint，querying risk limit levelsGET /rebate/partner/transaction_history endpoint，partners to get the transaction history of
recommended usersborrow_type field in GET /unified/loan_records responseaccum_size field in GET /futures/{settle}/position_close responsev4.75.0
2024-06-24
GET /account/debit_fee endpoint，query GT deduction configuration.POST /account/debit_fee endpoint, to enable or disable GT deduction for the current account.v4.74.1
2024-06-11
v4.74.0
2024-05-29
GET /unified/loan_margin_tiers endpoint, list loan margin tiersv4.73.0
2024-05-27
is_all parameter in POST /wallet/small_balance endpointtext field in POST /spot/cancel_batch_orders responsefunding、funding_version、use_funding field in GET /unified/accounts responsev4.72.0
2024-05-13
last_access field in GET /sub_accounts/{user_id}/keys responsecontract field in GET /futures/{settle}/risk_limit_tiers responsev4.71.0
2024-04-23
page parameter in GET /wallet/saved_address endpointGET /api/v4/rebate/user/info endpoint, retrieve user rebate informationPOST /unified/portfolio_calculator endpoint, portfolio margin calculatorGET /unified/risk_units endpoint, retrieve user risk unitPUT /unified/unified_mode endpoint, set unified account modeGET /unified/unified_mode endpoint, retrieve unified account modev4.70.0
2024-04-08
pnl_pnl、pnl_fund、pnl_fee field in GET /futures/{settle}/positions responsepnl_pnl、pnl_fund、pnl_fee field in GET /futures/{settle}/position_close responsev4.69.0
2024-03-25
text field in POST /delivery/{settle}/price_orders responsev4.68.0
2024-03-18
GET /unified/currency_discount_tiers endpoint, list currency discount tierstype parameter in GET /unified/loans endpointtype parameter in GET /unified/interest_records endpointv4.67.0
2024-03-11
filled_amount field in POST /spot/orders,POST /spot/batch_orders response10r/10s to 1r/3s(No modification to the original rate limiting behavior)v4.66.1
2024-02-19
GET /wallet/small_balance endpoint, list small balance.GET /wallet/small_balance_history endpoint, list small balance history.GET /unified/estimate_rate endpoint, get unified estimate rate.v4.65.0
2024-01-29
debit_fee field in GET /spot/batch_fee responseuser_id parameter in DELETE /account/stp_groups/{stp_id}/users endpointACK, RESULT, FULL. For details, please refer
to SPOT APIv4.64.0
2024-01-22
order_type parameter in GET /loan/multi_collateral/orders endpointorder_type,fixed_type,fixed_rate,expire_time,auto_renew,auto_repay field
in GET /loan/multi_collateral/orders responsebefore_ltv,after_ltv field in GET /loan/multi_collateral/repay responseGET /loan/multi_collateral/fixed_rate endpoint, query multi-collateral fix rate.unrealised_pnl,borrowed field in GET /wallet/total_balance responsev4.63.0
2024-01-15
decimal field in GET /wallet/currency_chains responseGET /futures/{settle}/risk_limit_tiers endpoint, list risk limit tiers.v4.62.0
2024-01-02
POST /futures/{settle}/batch_cancel_orders endpoint, users have the ability to batch cancel orders./loan/multi_collateral/**)v4.61.0
2023-12-18
GET /rebate/broker/commission_history
and GET /rebate/broker/commission_history endpointsv4.60.0
2023-12-01
/portfoli/* endpoints are deprecated./earn/**)trade_id field in GET /futures/{settle}/account_book responsev4.59.0
2023-11-22
funding_cap_ratio field in GET /futures/{settle}/contracts responsecontract field in GET /delivery/{settle}/account_book responsewithdraw_percent_on_chains field in GET /wallet/withdraw_status responseleverage field in GET /portfolio/accounts responsev4.58.0
2023-11-03
tier field in GET /account/detail responsemax_base_amount、max_quote_amount field in GET /spot/currency_pairs responsev4.57.0
2023-10-20
POST /spot/orders endpointPUT /earn/uni/interest_reinvest endpoint, users have the option to enable or disable interest
reinvestment.POST /spot/amend_batch_orders endpoint, users have the ability to batch modify orders.sequence_id field in GET /spot/trades responsetext field in GET /spot/account_book responsetext field in GET /spot/my_trades responseGET /portfolio/spot/orders、 GET /portfolio/spot/orders、GET /portfolio/spot/orders/{order_id}、DELETE /portfolio/spot/orders/{order_id}
and PATCH /portfolio/spot/orders/{order_id} have been deprecated. We will remove the endpoints by the end of October
2023. Please use /spot/orders instead.v4.56.0
2023-09-25
repayment_type field in GET /portfolio/loan_records endpoint.holding in GET /futures/{settle}/positions endpointrole in GET /futures/{settle}/my_trades_timerange endpointside and pnl in GET /futures/{settle}/position_close endpointv4.55.0
2023-09-12
POST /portfolio/account_mode endpoint, allow to change the mode.v4.54.0
2023-08-28
contract_address field in GET /wallet/currency_chains endpoint.GET /portfolio/spot/currency_pairs and GET /portfolio/spot/currency_pairs/{currency_pair} endpoints, list
portfolio spot's currency pairs.v4.53.0
2023-08-14
DELETE /account/stp_groups/{stp_id}/users endpointv4.52.0
2023-08-07
v4.51.0
2023-07-29
mode field in GET /account/detail edpoint.v4.50.0
2023-07-14
GET /flash_swap/currency_pairs, list all flash swap currency pairv4.49.0
2023-07-03
GET /futures/{settle}/orders API endpoint, the request field contract has been modified to be optional
instead of mandatory.v4.48.0
2023-06-16
client_order_id fields in GET /wallet/sub_account_transfers edpoint.v4.47.0
2023-05-23
GET /margin/uni/estimate_rate endpoint.GET /futures/{settle}/orders_timerange endpointunderlying、underlying_price、mark_iv、delta、gamma、vega、theta fields
in GET /options/positions/{contract} endpoint.v4.46.0
2023-05-08
GET /spot/account_book endpointGET /futures/{settle}/fee endpointv4.45.0
2023-04-21
Lend & Earn. For more information, please refer to
the Margin Migration InstructionsSelf-Trade Prevention feature in the POST /futures/{settle}/batch_orders endpoint.v4.44.0
2023-04-07
ORDER_BOOK_NOT_FOUND and FAILED_RETRIEVE_ASSETS error messages.v4.43.0
2023-03-27
Self-Trade Prevention feature in the POST /spot/orders endpoint. Fore more detail, please refer
to STP overviewGET /account/detail endpoint.amend_text in PATCH /spot/orders/{order_id} endpoint.v4.42.0
2023-03-13
Lend & Earn APISelf-Trade Prevention feature in the POST /futures/{settle}/orders endpoint. Fore more detail,
please refer to STP overviewdelivery account type in POST /wallet/sub_account_transfers endpointv4.41.0
2023-03-03
v4.40.0
2023-02-24
Get /futures/{settle}/auto_deleveragessum field in GET /futures/{settle}/candlesticks endpointv4.39.0
2023-02-09
GET /spot/batch_feeenable_bonus、enable_credit fields in GET /futures/{settle}/contracts endpointv4.38.0
2023-02-04
GET /futures/{settle}/my_trades_timerangewithdraw_order_id field in POST /withdrawals endpointv4.37.0
2023-01-20
v4.36.0
2022-12-23
iceberg in POST /spot/orders and POST /spot/batch_orders
endpointsv4.35.0
2022-12-09
/spot/orders/{order_id}avg_deal_price field in GET /spot/orders responsePOST /spot/batch_orders endpointv4.34.0
2022-11-25
POST /spot/orders endpointv4.33.0
2022-11-11
GET /futures/{settle}/premium_indexv4.32.0
2022-10-28
v4.31.0
2022-10-14
POST /wallet/sub_account_to_sub_account
endpointv4.30.0
2022-09-23
POST /wallet/sub_account_to_sub_account endpointv4.29.0
2022-09-09
settle parameter in GET /wallet/fee endpointrefr field in option orderv4.28.0
2022-08-12
offset parameter in GET /futures/{settle}/tradesv4.27.0
2022-07-29
X-Client-Request-Id http header for tracking requestPOST /futures/{settle}/batch_ordersFOK tif type for futures orderv4.26.0
2022-07-15
GET /wallet/saved_address to list saved addressPOST /wallet/transfers returns tx_id fieldGET /wallet/sub_account_cross_margin_balances to query subaccount's cross_margin accountstatus field in GET /margin/currency_pairs responsev4.25.1
2022-07-06
GET /spot/time endpoint which get system's time info.GET /options/my_settlements endpoint which list my selttlements.change_utc0, change_utc8 fields in GET /spot/tickers endpointv4.25.0
2022-06-24
POST /spot/cross_liquidate_orders spot trading endpoint that close position when the
cross-currency is disabledbouns and history fields in GET /futures/{settle}/accounts endpointtext、fee and point_fee fields in GET /futures/{settle}/my_trades endpointcancel a price-triggered order endpointsPOST /wallet/sub_account_transfers supports transferring to cross_marginv4.24.0
2022-05-20
/flash_swap. Spot operation permission is
required.GET /wallet/sub_account_margin_balances
and GET /wallet/sub_account_futures_balances to help main account retrieving sub accounts'
margin and perpetual contract balancesGET /futures/{settle}/index_constituents/{index} to retrieve index
price constituentsorder_type in FuturesPriceTriggeredOrderv4.23.4
2022-04-25
30d intervalv4.23.3
2022-04-01
chain field.GET /wallet/currency_chains responsecross_leverage_limit in perpetual contract's dual mode position leverage update APIv4.23.2
2022-01-21
fee in withdrawal and deposit historyCurrencyv4.23.1
2021-12-23
time_in_force FOKFOK_NOT_FILL error labelv4.23.0
2021-12-09
GET /wallet/currency_chains to retrieve chains supported by currencyv4.22.4
2021-11-01
ctime and ftime in SpotPriceTriggeredOrder should be int64v4.22.3
2021-10-27
GET /spot/trades supports time range based query using from and to.v4.22.2
2021-09-29
auto_size in FuturesOrder to support closing dual mode position.v4.22.1
2021-09-07
GET /wallet/total_balance to retrieve all user's estimate balance.locked and risk in margin account responsev4.22.0
2021-08-13
GET /spot/orders and GET /spot/my_trades supports query by time rangev4.21.6
2021-08-12
GET /wallet/deposit_addressv4.21.5
2021-06-30
GET /spot/orders, GET /spot/orders/{order_id} and GET /spot/my_trades allow empty
currency_pair if operated against finished ordersGET /wallet/withdraw_status responseGET /margin/transferable to retrieve maximum transferable amount from margin accountfrom and to parameter to specify time range for futures position closes history APIv4.21.4
2021-06-23
GET /margin/account_book responsev4.21.3
2021-06-17
v4.21.2
2021-06-07
/margin/crosscreate_time_ms and update_time_ms in spot orders.DELETE /withdrawals/{withdrawal_id} to cancel withdrawal operationv4.20.1
2021-04-14
v4.20.0
2021-03-25
/spot/price_ordersv4.19.6
2021-03-22
v4.19.5
2021-03-18
v4.19.4
2021-03-10
/wallet/sub_account_transfers supports transferals with sub user's perpetual contract accountv4.19.3
2021-03-04
/margin/auto_repaymultichain_address in /wallet/deposit_address for currencies with multiple deposit
addressesv4.19.2
2021-03-01
/wallet/fee API to retrieve trading fee. Previous /spot/fee is deprecated in favour of
this one.chain in withdrawal operation.with_id in /futures/{settle}/order_book API and id field in its responseoffset in API /futures/{settle}/position_close to retrieve position close history with
pagination.Contract model for details.v4.18.4
2021-01-22
create_time_ms in spot Trade modelv4.18.1
2021-01-07
/futures/{settle}/contract_statsv4.18.0
2020-12-21
/spot/currencies and /spot/currencies/{currency} to retrieve currency infotop_lsr_account, top_lsr_size, in futures ContractStat model.v4.17.1
2020-12-16
limit in /spot/order_book to 100v4.17.0
2020-12-15
/wallet/sub_account_balances to retrieve sub accounts' balances.v4.16.1
2020-12-10
dual_mode in futures position model which should be mode instead.v4.16.0
2020-12-09
Spot
POST /spot/batch_ordersreverse in GET /spot/trades to trace back trading historyFutures
/futures/{settle}/dual_mode to set
position's dual mode. For dual mode position operations, refer
to /futures/{settle}/dual_comp/positions API groupin_dual_mode in futures account response model;
dual_mode in position response model./futures/{settle}/liq_orders to query liquidated orders in
marketsv4.15.5
2020-11-04
/futures/{settle}/contract_stats API to retrieve contract stats/margin/{currency_pair} to retrieve single margin currency pair detailv4.15.4
2020-09-01
point_type in GET /spot/fee responseGET /wallet/withdraw_status APIv4.15.2
2020-08-12
GET /spot/fee to retrieve spot order trading fee ratesv4.15.1
2020-08-04
GET /spot/open_orders to retrieve all open orders in spot tradingGET /margin/account_book to retrieve margin account balance historyv4.14.1
2020-07-08
text field in order extends to 28(prefix excluded)v4.14.0
2020-07-06
/deliveryv4.13.1
2020-06-28
GET /wallet/sub_account_transfers to list sub account transfer recordsv4.13.0
2020-05-20
POST /withdrawals and "Authentication"
section for details.POST /wallet/transfers supports transferring between spot and futures accountoffset fieldContract model add new field in_delistingv4.12.0
2020-04-08
POST /wallet/sub_account_transfers to support transferring between main and sub accountGET /spot/candlesticks adds query parameters from and to to support retrieving history data
pointsv4.11.2
2020-03-29
filled_total in Order to replace fill_price (the latter is badly named)POC_FILL_IMMEDIATELYv4.11.1
2020-03-23
role in GET /spot/my_trades responseGET /margin/funding_accountsv4.11.0
2020-03-20
pocv4.10.1
2020-02-24
trade_status in spot currency pairv4.10.0
2020-02-17
auto_borrow(write only) to borrow
the insufficient part by the system if balance is not enoughPOST /spot/cancel_batch_orders to support batch cancellation
with specified order IDsv4.9.1
2020-01-07
Order and BatchOrderGET /spot/my_trades responsev4.9.0
2019-12-17
last_id in GET /futures/{settle}/trades is deprecated. Use from and to to retrieve trading
historyv4.8.2
2019-12-02
/spot/batch_orders to support creating a bundle of spot or margin ordersLoan add new fields fee_rate(fee rate of lending loan)
and orig_id(original loan ID if loan is auto renewed)v4.8.1
2019-11-27
settle in GET /futures/{settle}/positions docs and code snippetv4.8.0
2019-11-07
/futures to /futures/{settle} in ALL futures API to support
futures operations in different settle currency.currency field in /futures/{settle}/accounts response adds new value: USDT
response to replace volume_24h_btc and volume_24h_usd. The latter two are still
preserved for compatibility usage, but are NOT recommended for any futures operations.To use USDT futures, just replace /futures with /futures/usdt, e.g.
use GET /futures/usdt/accounts to retrieve futures accounts settled in USDT,
while GET /futures/btc/accounts returns accounts in BTC.
For compatibility, GET /futures/xxx defaults to GET /futures/btc/xxx, e.g.
GET /futures/accounts will be treated as GET /futures/btc/accounts
v4.7.3
2019-07-18
text in /spot/orders and /futures/orders to support user defined order informationv4.6.3
2019-06-11
v4.7.2
2019-05-29
rate in Loan as non-required for lending side.v4.7.1
2019-04-17
GET /margin/loans can sort by rate and support an optional parameter currency_pairv4.6.2
2019-04-24
GET /futures/orders/{order_id} and DELETE /futures/orders/{order_id}v4.6.1
2019-04-02
high_24h, low_24h and funding_rate_indicative in futures tickerv4.6.0
2019-03-21
SDK related only
v4.5.2
2019-03-14
currency_pair in /spot/order_book should be a required parameterv4.5.1
2019-03-11
v4.5.0
2019-03-05
To avoid version confusion, all versions in APIv4 (documents and SDKs are both included) will start
with 4 from now on
/futures/price_orders for detailshttps://api.gateio.ws/api/v4v1.3.0
2019-02-13
Important update
fx-api.gateio.ws and fx-api-testnet.gateio.ws
respectively, *.gateio.io is deprecated and will soon be out of service.v1.2.1
2019-02-13
volumn_24h_usd and volume_24h_btc in GET /futures/tickers responsev1.2.0
2019-01-17
GET /futures/contracts/{contract} to get one single contractGET /futures/positions/{contract} to get one single positionGET /futures/account_book to retrieve user account balance historyconfig_change_time in Contract modelv1.1.0
2019-01-08
Contract, Position, FuturesOrderGET /futures/position_close to retrieve position close historyorder_id support for API GET /futures/my_tradesDELETE /futures/orders and DELETE /futures/orders/{order_id} from
204 to 200,
with cancelled order details returned on success.DELETE /futures/orders/{order_id} with invalid order ID or order
that has been finished will return 404 instead of ignoring the errorPOST /futures/orders now supports POC, icebergv1.0.0
2018-12-30
Gate Order matching follows Price Priority > Time priority principle.
Suppose that the order book is as follows：
| Order | Order time | Ask/Selling price |
|---|---|---|
| A | 10:00 | 100 |
| B | 10:00 | 102 |
| C | 10:01 | 100 |
If the current price of 10:02 pays 102, the final transaction order is: A, C, B
A valid order sent to the matching engine is immediately confirmed and executed with existing orders, with the executing result sent back to the client.
If an order is fully executed, then it is closed. If any part of the order is not executed
immediately, orders with TimeInForce set to IOC will be cancelled, while others will be appended
to the price list, waiting for subsequent filling or being cancelled.
Gate data center is located in AWS Japan's ap-northeast-1 region.
| API Classification | Category Links | Overview |
|---|---|---|
host + /api/v4/spot/* | Spot Trading | Including currency status, market information, order, transaction records and other functions |
host + /api/v4/margin/* | Margin Trading | Margin account management, lending, repayment, etc |
host + /api/v4/wallet/* | Wallet Management | Charge and withdrawal records, balance inquiries, fund transfers, etc. |
host + /api/v4/withdrawals/* | Withdrawal | Withdrawal of digital currency |
Between 14:00 (UTC+8) on April 13, 2023 and 14:00 (UTC+8) on April 23, 2023, the platform will gradually migrate the assets that have not been borrowed in the lending market to the Lend & Earn through an automated system process. At the same time, assets that have already been borrowed will be cancelled for automatic lending. After the migration is complete, you can check your investment details in the Lend & Earn. During this period, borrowing funds through the lending market will be temporarily suspended. You can also manually transfer your assets from the lending market to the Lend & Earn to obtain investment returns in advance.
After the automatic migration, the old version of the borrowing and lending endpoint will be deprecated, and the new version of the endpoint can be found in the /margin/uni endpoint group. For detailed endpoint migration, please refer to the following table:"
Margin account related endpoints：
| Name | Path | Deprecated | New Path |
|---|---|---|---|
| Margin account list | GET /margin/accounts | No | - |
| List margin account balance change history | GET /margin/account_book | No | - |
| Funding account list | GET /margin/funding_accounts | No | - |
| Update user's auto repayment setting | POST /margin/auto_repay | No | - |
| Querying user's automatic repayment settings | GET /margin/auto_repay | No | - |
| Get the max transferable amount for a specific margin currency | GET /margin/transferable | No | - |
The margin lending and borrowing related APIs have been migrated to the /margin/uni API group：
| Name | Old Path | Deprecated | New Path |
|---|---|---|---|
| List all supported currency pairs supported in margin trading | GET /margin/currency_pairs | Yes | GET /margin/uni/currency_pairs |
| Query one single margin currency pair | GET /margin/currency_pairs/{currency_pair} | Yes | GET /margin/uni/currency_pairs/{currency_pair} |
| Lend or borrow | POST /margin/loans | Yes | POST /margin/uni/loans |
| Retrieve one single loan detail | GET /margin/loans/{loan_id} | Yes | - |
| List all loans | GET /margin/loans | Yes | GET /margin/uni/loans |
| Repay a loan | POST /margin/loans/{loan_id}/repayment | Yes | POST /margin/uni/loans |
| List loan repayment records | GET /margin/loans/{loan_id}/repayment | Yes | GET /margin/uni/loan_records |
| Get the max borrowable amount for a specific margin currency | GET /margin/borrowable | Yes | GET /margin/uni/borrowable |
| List interest records | - | - | GET /margin/uni/interest_records |
The earn related APIs have been migrated to the /earn/uni API group):
| Name | Old Path | Deprecated | New Path |
|---|---|---|---|
| List all supported currency pairs supported in margin trading | GET /margin/currency_pairs | Yes | GET /earn/uni/currencies |
| Query one single margin currency pair | GET /margin/currency_pairs/{currency_pair} | Yes | GET /earn/uni/currencies/{currency} |
| Lend or borrow | POST /margin/loans | Yes | POST /earn/uni/lends |
| List all loans | GET /margin/loans | Yes | GET /earn/uni/lends |
| Order book of lending loans | GET /margin/funding_book | Yes | - |
| Merge multiple lending loans | POST /margin/merged_loans | Yes | - |
| Modify a loan | PATCH /margin/loans/{loan_id} | Yes | PATCH /earn/uni/lends |
| Cancel lending loan | DELETE /margin/loans/{loan_id} | Yes | POST /earn/uni/lends |
| List repayment records of a specific loan | GET /margin/loan_records | Yes | GET /earn/uni/lend_records |
| Get one single loan record | GET /margin/loan_records/{loan_record_id} | Yes | - |
| Modify a loan record | PATCH /margin/loan_records/{loan_record_id} | Yes | - |
| List interest records | - | - | GET /earn/uni/interest_records |
GET method. They accept only request parameters. No request body will be
read.DELETE methods remove resources(like orders), but not all removing operation using DELETE,
as DELETEs don't read request body either. For complex removing operations, POST method is
used with parameters filled in request body.POST, PUT or PATCH method. Their parameters are either in body or
request parameters for different endpoints. Refer to endpoint detail for how to send the request.2xx on success. 401 is returned on authentication
failure. Other 4xx codes mean the request is malformed. 5xx means the server encounter some
critical error on processing the request. Commit issues if 5xx is met.All time related fields are unix timestamp in seconds if no extra note, but they may differ in formats(int64, number or string). Possible values like the following may be returned:
The best way to handle time fields is parsing them as a number with decimal places. If higher precision is not needed, you can safely cast them to integer(or long). Our SDKs listed above has already taken proper deserialization to handle them
In every API request, the response header will always include the following fields:
X-In-Time: The timestamp when the API gateway receives a request, in Unix timestamp format, measured in microseconds.
X-Out-Time: The timestamp when the API gateway returns a response, in Unix timestamp format, measured in microseconds.
For example:
X-In-Time: 1695715091540163
X-Out-Time: 1695715091551905
Pagination is achieved using one of the following method
page-limitlimit-offsetIn both method, limit limits the maximum number of records returned in one request. If no
additional explanation, it defaults to 100 if not provided and its maximum value is limited
to 1000.
page starts from 1, mimicking common paging used in web pages. To iterate the whole list, use
the same limit and increment page by 1 until the records' length is shorter than the
limit
offset starts from 0, behaving like common DB search. To iterate the whole list, increment
offset by limit until the records' length is shorter than the limit.
For example, if the total number of orders is 201. Using page-limit method, send request parameters like the following:
page=1&limit=100page=2&limit=100page=3&limit=100Using limit-offset method, send request parameters like:
limit=100&offset=0limit=100&offset=100limit=100&offset=200Some endpoints may return additional pagination metadata. If present, they are sent back through the
response header. Take GET /futures/{settle}/orders as an example, following headers will be
returned
X-Pagination-Limit: request limitX-Pagination-Offset: request offsetX-Pagination-Total: total record number satisfying the request| Markets | Endpoints | Limits | Based On | Include |
|---|---|---|---|---|
| All public endpoints | Public endpoints | 200r/10s per endpoint | IP | Orderbook, Candlestick, Ticker, etc. |
| Wallet | Private endpoints |
Withdrawal(POST /withdrawals) : 1r/3s UID transfer(POST /withdrawals/push) 1r/10s Transfer between trading accounts (POST /wallet/transfers) 80r/10s Transfer between main and sub accounts (POST /wallet/sub_account_transfers) 80r/10s Transfer from a sub-account to another sub-account (POST /wallet/sub_account_to_sub_account) 80r/10s Retrieve user's total balances (GET /wallet/total_balance) 80r/10s Retrieve sub account balances (GET /wallet/sub_account_balances) 80r/10s Query sub accounts' margin balances (GET /wallet/sub_account_margin_balances) 80r/10s Query sub accounts' futures account balances (GET /wallet/sub_account_futures_balances) 80r/10s Query subaccount's cross_margin account info(GET /wallet/sub_account_cross_margin_balances) 80r/10s The Others: 200r/10s per endpoint | UID |
Withdrawal. Query personal account balance. Query subaccount balance. |
| Spot | Private endpoints |
The rate limit for batch/single order placement and amend an order are total of 10r/s (UID+Market) The rate limit for batch/single order cancellation is total of 200r/s The Others: 200r/10s per endpoint | UID |
Spot order placement and cancellation. Trade history and fee rates. |
| Perpetual Futures | Private endpoints |
The rate limit for batch/single order placement and amend an order are total of 100r/s The maximum rate limit for the order cancellation (bulk/single) is 200r/s The Others: 200r/10s per endpoint | UID |
Futures order placement and cancellation Trade history and fee rates |
| Delivery | Private endpoints |
The maximum rate limit for the order placement (bulk/single) is 500r/10s The maximum rate limit for the order cancellation (bulk/single) is 500r/10s The Others: 200r/10s per endpoint | UID |
Order placement and cancellation |
| Options | Private endpoints |
The maximum rate limit for the order placement (bulk/single) is 200r/s The maximum rate limit for the order cancellation (bulk/single) is 200r/s The Others: 200r/10s per endpoint | UID |
Order placement and cancellation |
| Subaccount | Private endpoints | 80r/10s per endpoint | UID |
Create a sub-account. Retrieve the list of sub-accounts. Disable or enable API key for a sub-account. |
| Unified | Private endpoints | Borrow or repay 15/10s | UID |
Borrow or repay(POST /unified/loans) |
| Other Private endpoints | Private endpoints | 150r/10s per endpoint | UID | Earning, collateral etc |
The rate limit is counted against each sub-account or main account.
Rate Limit
Each request to the API response header will contain the following fields:：
WebSocket:
In order to enhance trading efficiency, we have decided to implement more favorable sub-account rate limits for clients with a higher fill ratio. This assessment will be based on trading data from the past seven days and will be calculated daily at 00:00 UTC. Please note that this rule applies only to clients at VIP level 14 and above.
To facilitate a more refined management of the impact of different trading products on the fill ratio, we have introduced the concept of the symbol multiplier. This multiplier allows us to adjust the influence of each product on the overall trading volume based on its characteristics. For products with a multiplier of less than 1, they typically involve smaller contract sizes and therefore require more trading orders to achieve the same trading volume. Generally, all trading products come with a default multiplier; however, certain products are assigned independent multipliers based on their specific characteristics. For detailed information regarding the multipliers of relevant products, please refer to the provided table.
| Product Typee | Based On | Independnet Symbol Multiplier | Default Symbol Multiplier |
|---|---|---|---|
| USDT-Margined Perpetural Futures | Contract Symbol |
1 Contract Symbol: BTC-USDT ETH-USDT | 0.4 |
| Spot | Currency Pairst |
1 Currency Pairs: BTC-USDT ETH-USDT | 0.4 |
Please note: The spot trading rate limits will not be launched this time.
We will assess the behavior patterns of makers and takers based on market fluctuations and design the trading volume weight ratios accordingly. Additionally, we will regularly evaluate these weights and make synchronized adjustments when necessary.
Current weight of the maker trading volume: 100%, current weight of the taker trading volume: 90%.
The system will take a snapshot of the data at 00:00 UTC daily and, based on this information, will select the higher value between the fill ratio of the sub-account and the overall fill ratio of the main account to determine the future trading rate limit for the sub-account. For exchange brokers, the system will only consider the fill ratio of their sub-accounts. It is important to note that the main account is also considered a "sub-account."
The rate limit for batch/single order placement and order modification is a total of 10r/s (UID+Market)
The platform will implement rate limiting for trading behaviors that frequently place orders, cancel orders, or modify orders within a short period but exhibit a low fill ratio. The specific rules are as follows:
1. Statistics Period
2. Request Types
3. Rate Limit Standards
4. Unlock Mechanism
Note:
Fill Ratio = USDT Trading Amount / (Total Number of Order Placement, Cancellation, and Modification Requests)
| Contract Frequency Limitation Rules | ||
|---|---|---|
| Tier | Ratio | Rate Limit (uid) |
| Tier 1 | [0,1) | 100r/s |
| Tier 2 | [1,3) | 150r/s |
| Tier 3 | [3,5) | 200r/s |
| Tier 4 | [5,10) | 250r/s |
| Tier 5 | [10,20) | 300r/s |
| Tier 6 | [20,50) | 350r/s |
| Tier 7 | >= 50 | 400r/s |
Please stay tuned for the rate limits for spot trading.
Assuming the client has three accounts, with the symbol multipliers for trading perpetual contract products BTC-USDT and SOL-USDT being 1 and 0.4, respectively.
All API responses are in JSON format, and users need to transform and extract data by themselves.
The HTTP status code 2XX will be returned when all operations are successful. 401 indicates that there is a problem with the certification. Other 4xx status codes indicate that the request is invalid. If it is a 5xx error, the server has encountered an unknown serious error when processing the request. Please give feedback as soon as possible。
Return Status
| Status Code | Description |
|---|---|
| 200/201 | Request succeeded |
| 202 | Request accepted by the server, but processing is not done yet |
| 204 | Request succeeded, but the server doesn't return body |
| 400 | Invalid request |
| 401 | Authentication failed |
| 404 | Not found |
| 429 | Too many requests |
| 5xx | Server error |
| Type | Description |
|---|---|
string | String type, in double quotation marks. Price and amount are also formatted in string format |
integer | 32-bit integer，Mainly related to status codes, size, times, etc. |
integer(int64) | 64-bit integer，Mainly involves ID and higher precision timestamp |
float | Floating point number. Some time and stat fields use float. |
object | Object，Contains a child object{} |
array | List，Includes multiple groups of content |
boolean | true is true，false is false |
TIP
The Portfolio Margin Account is no longer maintained, please refer to the new version of the Unified Account
Since version 4.25.0, we start supporting portfolio margin account. Gate's Portfolio Margin
Account is a new feature of Gate's trading system. Its main function is to break the capital
isolation between cross-margin leverage account and USD cross-margin perpetual contract account
inside a Classic Account and achieve the multi-currency margin sharing among multi-product lines.
Thanks to the margin sharing, users don't need to transfer funds between the two accounts, and the
profit and loss of positions among different trading products can offset each other and effectively
improve the capital utilization rate. See more details in the
Help Center
Before using the portfolio margin account's API key, you should create the API key on the API management page. The API key supports spot and perpetual contracts trading only.
If permissions of the API key can't be checked, ensure your cross-margin account has available balance first.
The classic account and portfolio margin account are two different capital isolation accounts. If you want to achieve multi-currency margin sharing among multi-product lines, use the portfolio margin account please.
The funds of the portfolio margin account come from the classic account. Due to the change of funds in the classic account, the transfer of funds can only be performed using the API Key of the classic account.
The portfolio margin account is upgraded based on the cross-margin account of the original classic account, so the classic account only needs to transfer its spot funds to the cross-margin account to deposit the portfolio margin account. Similarly, withdrawals from portfolio margin account can be achieved by the classic account performing transferals from the cross margin to its spot account.
The API Key of the portfolio margin account can only perform transferals among its own multiple accounts. Due to the sharing of margin, the portfolio margin account does not need to transfer funds to its futures account (we also restrict doing so). If the futures account has PNL funds that need to be withdrawn, it must be transferred by the portfolio margin account's API key to its cross-margin account first, so that the classic account can perform withdrawals from portfolio margin account.
The spot trading of the portfolio margin account is almost the same as the classic account, except
that cross_margin must be specified in the account parameter when placing orders. For example,
if you want to place a buy order for the BTC_USDT currency pair, the order request will be similar
to
POST /spot/orders
{
"currency_pair": "BTC_USDT",
"account": "cross_margin",
"side": "buy",
...
}
For other related restrictions, please refer to the document of the API endpoint directly.
TIP
It should be noted that the portfolio margin account is upgraded from the classic account's cross-margin account. The API Key of the classic account originally supports the operation of the cross-margin account. In order not to affect the existing operations of the classic account, we still retain this function of the classic account. So whether it is the API Key of the classic account or the portfolio margin account, both can operate the same the cross margin account (note that the futures accounts are separate)
The API operation of the perpetual contract of the portfolio margin account is exactly the same as that of the classic account, but currently only supports USD settlement
TIP
In the futures trading, it should be noted that there is no compatibility for cross-margin accounts
like using the API Key of the classic account in spot trading. Therefore, when using the API Key of
the classic account for futures trading, assets are kept under classic account-futures, and when
using portfolio margin account API Key for futures trading, assets are kept
under portfolio margin account-futures. These two are different futures accounts. In addition,
funds under classic account-spot cannot share margin with classic account-futures.
The API response will carry the header: X-Gate-Trace-ID . This header is used for tracking.
Self-Trade Prevention: STP will prevent any user's orders from being matched with each other.
CN: Cancel new, Cancel new orders and keep old ones.
CO: Cancel old, Cancel old orders and keep new ones.
CB: Cancel both, Both old and new orders will be cancelled.
We support three STP strategies, which are CN , CO and CB.
STP is achieved by adding users to one STP trading group.
When a user in a STP group place orders, and trading could happen with existing orders of users in the same group, orders will be cancelled.
The prevention strategy depends on the stp_act parameter specified when placing the order as taker.
If not specified, the CN strategy will be used by default.
A user has to be added to a STP trading group before using STP.
When a user does not belong to any STP trading group, and place orders with the stp_act parameter, the orders will be rejected.
Take placing futures order as an example:
POST /futures/{settle}/orders
New request body parameter:
| Name | Position | Type | Required | Description |
|---|---|---|---|---|
| stp_act | body | string | No | STP Strategies, including: - cn - co - cb |
New response fields:
| Name | Type | Required | Restriction | Description |
|---|---|---|---|---|
| stp_act | string | No | none | STP Strategies, including： - cn - co - cb |
| stp_id | integer(int64) | No | readonly | The ID of the STP trading group to which user belongs. |
| finish_as | string | No | readonly | order finish type: - stp: The order has been canceled due to the STP |
There are multiple accounts under Organization A, and the IDs of several accounts are 101, 102, and 103
In order to prevent self-trading of orders placed by internal accounts of the organization, the administrator created a STP trading group with group ID 100,
and added accounts 101 and 102 to the STP trading group.
In this case, the members in the group are [101,102].
T1: The STP strategy version released.
T2: After the organization A account 101 places a short order, there is no matching order in the market order book to match the transaction.
At this time, the role of the order is maker, and the order status is open.
The key response fields returned are:
{
"status":"open",
"stp_act":"cn",
"stp_id":100
}
T3: Organization A account 101/102 places a long order, and it can reach a trade with account 101’s short order.
The match engine finds both two orders' stp_id are 100, so it applies the STP strategy of the taker order, which defaults to cn , and cancels the long order.
Order's finish_as will be set to stp.
The key response fields returned are:
{
"status":"finished",
"stp_act":"cn",
"stp_id":100,
"finish_as":"stp"
}
If stp_act is co , the order placed by taker will be retained, the order status will be open,
and the system will cancel the order of maker.
If stp_act is cb, both the long and short orders will be cancelled. Orders' finish_as will be set to stp.
The key response fields returned are:
{
"status":"finished",
"stp_act":"cb",
"stp_id":100,
"finish_as":"stp"
}
T3': If account 103 places a long order, and it can reach a trade with account 101’s short order, the transaction will be made since account 103 has not been added to account 101’s STP group. The key response fields returned are:
{
"status":"finished",
"stp_id":0,
"finish_as":"filled"
}
Once a user upgrades their account to the unified account, they can utilize the assets from their spot account as collateral for trading. The assets in the account, denominated in various currencies, will be adjusted based on their liquidity and converted to USD for consistent calculation of the account's assets and position value.
The maximum borrowing limit for margin trading represents the maximum amount that a user can borrow for a given trading market. The platform calculates the user's maximum borrowing limit based on factors such as available margin and platform risk control rules. Once the margin trading generates automatic borrowing, the platform immediately starts accruing interest on the borrowed digital assets.
Currently, the ability to switch to cross_margin orusdt_futures mode is available. In the future, we will gradually introduce support for various combination margin accounts, including Futures, Delivery, Options and more. Stay tuned for further updates.
Please refer to the documentation for unified API. Once you have upgraded your account, you will be able to make use of these endpoints.
Related endpoint can be found in the Unified Account API doc. After enabling the Unified Account, you can proceed to call them. For more detailed information, please refer to here
API KEY or update the permissions of an existing API KEY, checking the unified permissionAPI KEY to call the PUT /unified/unified_mode endpoint, or upgrade from the WEB page to the Unified Account/api/v4/spot/** API for spot-related operations (ordering, modifying orders, querying orders), with the account=unified option/api/v4/futures/** API for perpetual futures-related operations (ordering, modifying orders, querying orders)/api/v4/unified/** API for Unified Account-related operations (account querying, loan querying)The spot trading in the Unified Account is consistent with that in the classical account. In order operations, specify account=unified, or specify account=spot and the system will automatically handle the order as a unified account order when detecting the account as a unified account. For example, to place a buy order for the BTC_USDT currency pair, the order creation request would be similar to
POST /spot/orders
{
"currency_pair": "BTC_USDT",
"account": "unified",
"side": "buy",
...
}
For other related restrictions, please refer to the document of the API endpoint directly.
| Name | Cross Margin |
|---|---|
| portfolio_margin_total_equity | Account Equity = ∑(Equity * Index Price） |
| total_margin_balance | Account Margin Balance = ∑(Positive Equity x Index Price x Adjustment Factor) + ∑(Negative Equity x Index Price) - Haircut Loss |
| total_initial_margin_rate | Account Initial Margin Level = Account Margin Balance / Account Initial Margin |
| total_maintenance_margin_rate | Account Maintenance Margin Level = Account Margin Balance / Account Maintenance Margin |
| total_initial_margin | Account Initial Margin = Total Liabilities x Spot Initial Margin Rate |
| total_maintenance_margin | Account Maintenance Margin = Total Liabilities x Spot Maintenance Margin Rate |
| equity | Equity = Coin Balance - Borrowed |
| available | Available Balance = Principal + Borrowed |
| freeze | Occupied = Assets Occupied by Spot Open Orders |
For all abnormal requests, APIv4 will return non-2xx status code, with a response body in JSON format to explain the error.
The error response body follows a format like:
{
"label": "INVALID_PARAM_VALUE",
"message": "Invalid parameter `text` with value: abc"
}
label: denotes error type in string format. Its value are chosen from a certain list(see
below).
Programs can use label to identify and catch a specific error.message(or detail): detailed error message. A longer explanation showing why the error is
generated
or how to avoid it. Its purpose is helping to better understand the API. Error handling
mechanism with this field is highly NOT recommended.Take Python requests (opens new window) for example, error handling can be written like:
Following examples only deal with business-related errors. Network timeout or other common errors need to be handled separately:
import requests
r = requests.get("https://api.gateio.ws/api/v4/futures/btc/contracts/BTC_USD")
try:
r.raise_for_status()
except requests.HTTPError:
# catch 2xx errors, parse error message in body, and do something based on `label`
if r.json()['label'] == 'xxx':
print(r.json())
or with Python SDK (opens new window):
import json
from gate_api import FuturesApi
from gate_api.rest import ApiException
api = FuturesApi()
try:
api.get_futures_contract(settle='btc', contract="BTC_USD")
except ApiException as e: # ApiException wraps whole error information, see implementation for details
detail = json.loads(e.value.body)
if detail['label'] == 'xxx':
print(detail)
label listlabel | Meaning |
|---|---|
| INVALID_PARAM_VALUE | Invalid parameter value |
| INVALID_PROTOCOL | Invalid parameter value |
| INVALID_ARGUMENT | Invalid argument |
| INVALID_REQUEST_BODY | Invalid request body |
| MISSING_REQUIRED_PARAM | Missing required parameter |
| BAD_REQUEST | Invalid request |
| INVALID_CONTENT_TYPE | Invalid Content-Type header |
| NOT_ACCEPTABLE | Invalid Accept- Header |
| METHOD_NOT_ALLOWED | Request method is not allowed |
| NOT_FOUND | Request URL not exists |
label | Meaning |
|---|---|
| INVALID_CREDENTIALS | Invalid credentials provided |
| INVALID_KEY | Invalid API Key |
| IP_FORBIDDEN | Request IP not in whitelist |
| READ_ONLY | API key is read-only |
| INVALID_SIGNATURE | Invalid signature |
| MISSING_REQUIRED_HEADER | Missing required authentication header |
| REQUEST_EXPIRED | Request Timestamp is far from the server time |
| ACCOUNT_LOCKED | Account is locked |
| FORBIDDEN | Account has no permission to request operation |
label | Meaning |
|---|---|
| SUB_ACCOUNT_NOT_FOUND | Sub account not found |
| SUB_ACCOUNT_LOCKED | Sub account is locked |
| MARGIN_BALANCE_EXCEPTION | Abnormal margin account |
| MARGIN_TRANSFER_FAILED | Failed to transfer with margin account |
| TOO_MUCH_FUTURES_AVAILABLE | Futures balance exceeds max allowed |
| FUTURES_BALANCE_NOT_ENOUGH | Futures balance not enough |
| ACCOUNT_EXCEPTION | Abnormal account |
| SUB_ACCOUNT_TRANSFER_FAILED | Failed to transfer with sub account |
| ADDRESS_NOT_USED | Address never being used in web console |
| TOO_FAST | Withdrawing request exceeds frequency limit |
| WITHDRAWAL_OVER_LIMIT | Withdrawal limit exceeded |
| API_WITHDRAW_DISABLED | API withdrawal operation is disabled temporarily |
| INVALID_WITHDRAW_ID | Invalid withdraw ID |
| INVALID_WITHDRAW_CANCEL_STATUS | Cancelling withdrawal not allowed with current status |
| DUPLICATE_REQUEST | Duplicate request |
| ORDER_EXISTS | Order already exists, do not resubmit |
| INVALID_CLIENT_ORDER_ID | The client_order_id is invalid |
label | Meaning |
|---|---|
| INVALID_PRECISION | Invalid precision |
| INVALID_CURRENCY | Invalid currency |
| INVALID_CURRENCY_PAIR | Invalid currency pair |
| POC_FILL_IMMEDIATELY | Order would match and take immediately so it's cancelled |
| ORDER_NOT_FOUND | Order not found |
| ORDER_CLOSED | Order already closed |
| ORDER_CANCELLED | Order already cancelled |
| QUANTITY_NOT_ENOUGH | Amount is not enough |
| BALANCE_NOT_ENOUGH | Balance is not enough |
| MARGIN_NOT_SUPPORTED | Request currency pair doesn't provide margin trading |
| MARGIN_BALANCE_NOT_ENOUGH | Margin balance is not enough |
| AMOUNT_TOO_LITTLE | Amount does not reach minimum required |
| AMOUNT_TOO_MUCH | Amount exceeds maximum allowed |
| REPEATED_CREATION | Repeated creation |
| LOAN_NOT_FOUND | Margin loan is not found |
| LOAN_RECORD_NOT_FOUND | Margin loan record is not found |
| NO_MATCHED_LOAN | No loan can match request borrow requirement |
| NOT_MERGEABLE | Request loans cannot be merged |
| NO_CHANGE | No change is made |
| REPAY_TOO_MUCH | Repay more than required |
| TOO_MANY_CURRENCY_PAIRS | Too many currency pairs in batch orders creation |
| TOO_MANY_ORDERS | Too many orders in one currency pair in batch orders creation |
| MIXED_ACCOUNT_TYPE | More than one account type is used in batch orders creation |
| AUTO_BORROW_TOO_MUCH | Auto borrow exceeds maximum allowed |
| TRADE_RESTRICTED | Trading is restricted due to high debt ratio |
| FOK_NOT_FILL | FOK order cannot be filled completely |
| INITIAL_MARGIN_TOO_LOW | User's total initial margin rate is too low |
| NO_MERGEABLE_ORDERS | Orders can be merged not found |
| ORDER_BOOK_NOT_FOUND | Insufficient liquidity |
| FAILED_RETRIEVE_ASSETS | Failed to retrieve account assets |
| CANCEL_FAIL | Order cancel failed |
label | Meaning |
|---|---|
| USER_NOT_FOUND | User has no futures account |
| CONTRACT_NO_COUNTER | No counter order found |
| CONTRACT_NOT_FOUND | Contract not found |
| RISK_LIMIT_EXCEEDED | Risk limit exceeded |
| INSUFFICIENT_AVAILABLE | Balance is not enough |
| LIQUIDATE_IMMEDIATELY | Operation may cause liquidation |
| LEVERAGE_TOO_HIGH | leverage too high |
| LEVERAGE_TOO_LOW | leverage too low |
| ORDER_NOT_FOUND | Order not found |
| ORDER_NOT_OWNED | Order not owned |
| ORDER_FINISHED | Order already finished |
| TOO_MANY_ORDERS | Too many open orders |
| POSITION_CROSS_MARGIN | margin updating is not allowed in cross margin |
| POSITION_IN_LIQUIDATION | Position is being liquidated |
| POSITION_IN_CLOSE | Position is closing |
| POSITION_EMPTY | Position is empty |
| REMOVE_TOO_MUCH | Changed margin exceeds allowed |
| RISK_LIMIT_NOT_MULTIPLE | Risk limit is not a multiple of step |
| RISK_LIMIT_TOO_HIGH | Risk limit too high |
| RISK_LIMIT_TOO_lOW | Risk limit too low |
| PRICE_TOO_DEVIATED | Order price deviates too much from mark price |
| SIZE_TOO_LARGE | Order size exceeds maximum |
| SIZE_TOO_SMALL | Order size does not reach minimum |
| PRICE_OVER_LIQUIDATION | Price to increase position can not exceeds liquidation price |
| PRICE_OVER_BANKRUPT | Price to decrease position cannot exceeds bankrupting price |
| ORDER_POC_IMMEDIATE | POC order will be finished immediately |
| INCREASE_POSITION | POC order will increase position |
| CONTRACT_IN_DELISTING | Contract is delisting, only reduce-only order or close order is allowed |
| POSITION_NOT_FOUND | Position not found |
| POSITION_DUAL_MODE | Operation forbidden in dual-mode |
| ORDER_PENDING | Operation forbidden with pending orders |
| POSITION_HOLDING | Operation forbidden with holding position |
| REDUCE_EXCEEDED | Reduce order would exceed position in dual-mode |
| NO_CHANGE | No change is made |
| AMEND_WITH_STOP | Amend forbidden with stop order |
| ORDER_FOK | Killed for FOK |
label | Meaning |
|---|---|
| COL_NOT_ENOUGH | Collateral balance not enough |
| COL_TOO_MUCH | Exceed collateral currency quota |
| INIT_LTV_TOO_HIGH | Init ltv too high |
| REDEEMED_LTV_TOO_HIGH | Ltv too high after redeem |
| BORROWABLE_NOT_ENOUGH | Left borrowable not enough |
| ORDER_TOO_MANY_TOTAL | Exceed platform order count one day |
| ORDER_TOO_MANY_DAILY | Exceed single user order count one day |
| ORDER_TOO_MANY_USER | Exceed single user order count total |
| ORDER_NOT_EXIST | Order id not exist |
| ORDER_FINISHED | Order id finished |
| ORDER_NO_PAY | Order unpaid amount is zero |
| ORDER_EXIST | Order exist |
| ORDER_HISTORY_EXIST | Order history exist |
| ORDER_REPAYING | Order is repaying |
| ORDER_LIQUIDATING | Order is liquidating |
| BORROW_TOO_LITTLE | Less than currency min borrow amount |
| BORROW_TOO_LARGE | Greater than total max borrow amount quantity |
| REPAY_AMOUNT_INVALID | Repay request amount invalid |
| REPAY_GREATER_THAN_AVAILABLE | Repay greater than available |
| POOL_BALANCE_NOT_ENOUGH | Pool balance not enough |
| CURRENCY_SETTLING | Currency settlement in progress |
| RISK_REJECT | Risk reject, please try again later |
| LOAN_FAILED | Loan failed, you can borrow again |
label | Meaning |
|---|---|
| USER_LIAB | User has liab |
| USER_PENDING_ORDERS | User has pending orders |
| MODE_SET | already set portfolio_margin mode |
label | Meaning |
|---|---|
| ERR_BALANCE_NOT_ENOUGH | balance not enough |
| ERR_PRODUCT_SELL_OUT | Target quota reached |
| ERR_PRODUCT_BUY | The project is not yet open for purchase |
| ERR_CREATE_ORDER | Put order fail |
| ERR_QUOTA_LOWER_LIMIT | Not meeting the minimum order amount |
| ERR_QUOTA_SUPERIOR_LIMIT | The maximum order limit has been reached |
| ERR_ORDER_NUMBER_LIMIT | The maximum order quantity has been reached |
| ERR_PRODUCT_CLOSE | Project closed |
| COPIES_NOT_ENOUGH | Not enough shares available to subscribe |
| COPIES_TOO_SMALL | Investment share is too small |
| COPIES_TOO_BIG | The number of investment shares exceeds the upper limit |
| TOTAL_AMOUNT_24 | The total amount of pledge and redemption within 24 hours exceeds the limit |
| TOTAL_BUYCOUNT_24 | Pledge and redemption times exceeding the limit within 24 hours |
| REDEEM_24_LIMIT | Redemption are allowed 24 hours after the last staking |
label | Meaning |
|---|---|
| INTERNAL | Internal server error |
| SERVER_ERROR | Internal server error |
| INTERNAL_SERVER_ERROR | Operation failed, please try again later. (same as SERVER_ERROR) |
| TOO_BUSY | Server is too busy at the moment |
label | Meaning |
|---|---|
| INVALID_PARAM_VALUE | Invalid request parameter |
| INVALID_CURRENCY | Invalid currency |
| INVALID_CURRENCY_PAIR | Invalid currency pair |
| PRICE_OBSOLETE | The price was obsoleted |
| ORDER_NOT_FOUND | Order not found |
| ORDER_BOOK_NOT_FOUND | Order book not found |
| BALANCE_NOT_ENOUGH | Not enough balance/balance transfer fail |
| TOO_MANY_REQUESTS | Request rate exceeds limits |
| QUOTA_NOT_ENOUGH | Quota not enough,please reduce the amount or try again later |
| SERVER_TIMEOUT | Service timeout |
| MISSING_REQUIRED_PARAM | Missing required parameter |
| REQUEST_FORBIDDEN | Asset management product is under liquidation; only USDT purchases are allowed |
| CONVERT_PREVIEW_EXPIRED | The result of preview is expired |
| CONVERT_PREVIEW_NOT_MATCH | The result of preview is not match |
| AMOUNT_TOO_LITTLE | Under minimum transaction amount |
| AMOUNT_TOO_MUCH | Over maximum transaction amount |
Before calling the private API interface, the API key of the account needs to be generated to verify the identity. You can log in on the website and generate it in [account management] - > [APIv4 keys], or click here to generate API keys.
Each account can create 20 API keys, and the permission configuration of each key is independent of each other. It is recommended to set a note name for each key to indicate its purpose.
Key Access Key
Secret Key The key used for signature authentication encryption
Besides, you can attach an IP whitelist, which requires the server only accept requests from specified IPs. Each key can have at most 20 IPs formatted in IPv4(not supporting IP range though). If IP whitelist is not set, the server will skip client IP validation.
Each user can create at most 5 keys with separate permissions. It is recommended to set a name for key denoting how the key will be used.
TIP
Note: If the key is named with spot or futures, then it could be the default name after
APIv4 migration. For details refer to About APIv4 key improvement section
Created key can also be updated or deleted, but any modification(s) can take up to 5 minutes to take effect.
Please note that futures TestNet trading is a separate environment from futures real trading. Real trading API keys cannot be used in TestNet. If you want to test futures API with TestNet, you need to log into the console to generate TestNet API keys(in "Futures TestNet APIKeys" tab on " APIv4Keys" page). Making futures requests are identical between real and TestNet trading, with the only exceptions are different base URLs and different API keys.
When creating a Key, you can configure whether to enable spot, margin, contract, wallet, or withdrawal permissions for the Key, and whether to enable read-write or read-only permissions.
| Products | Permissions |
|---|---|
spot/margin | Read-only query orders Read-write query orders & place orders |
perpetual contract | Read-only query orders Read-write query orders & place orders |
delivery contract | Read-only query orders Read-write query orders & place orders |
wallet | Read-only Query for withdrawal transfer records Read-write Query for account records & fund transfers |
withdrawal | Read-only Query cash withdrawal records Read-write Query cash withdrawal records & withdrawals |
All GET operations are read requests, while others are write requests. Each permission group can
be set to disabled, read-only or read-write.
Please note that even though withdrawal API has only one operation(i.e.
POST /withdrawals), for general concern, it is still separated from wallet API into a standalone
permission group, while withdrawal history retrieving API stays inside wallet operations(
i.e., GET /wallet/withdrawals).
KEY to the key.Timestamp to current time formatted in Unix time in seconds. Pay
attention that the gap between its value and current time cannot exceed 60 seconds.SIGN to encrypted request signature. Refer to next section for how signature
string is generated. Signature generation method is
HexEncode(HMAC_SHA512(secret, signature_string)), i.e., the hexadecimal digest output of
HMAC-SHA512 with APIv4 secret as secret and signature string as message,In APIv4, signature string is concatenated as the following way:
Request Method + "\n" + Request URL + "\n" + Query String + "\n" + HexEncode(SHA512(Request Payload)) + "\n" + Timestamp
Request method in UPPERCASE, e.g. POST, GET
Request url. Protocol, host and port are not included, e.g. /api/v4/futures/orders
Request query string without URL encode. query parameters order should be the
same as how they are concatenated in the request URL, e.g. status=finished&limit=50. Use empty string("") if no query parameters.
Hash the request body with SHA512 and output its Hex encoded form. If no request body, use empty string's hashed result, i.e.
cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
Timestamp request header value.
Examples
Note: all example signature string are broken into multiple lines for displaying purpose only.
Only the \n character in signature string is reserved in reality.
Suppose the key we used is key, while the secret is secret.
GET /api/v4/futures/orders?contract=BTC_USD&status=finished&limit=50 HTTP/1.1
Signature string：
GET\n
/api/v4/futures/orders\n
contract=BTC_USD&status=finished&limit=50\n
cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e\n
1541993715
Explanation：
/api/v4/futures/orders: request urlcontract=BTC_USD&status=finished&limit=50: keep the query string as it is in the request url1541993715: Unix timestamp in secondsSignature generated
55f84ea195d6fe57ce62464daaa7c3c02fa9d1dde954e4c898289c9a2407a3d6fb3faf24deff16790d726b66ac9f74526668b13bd01029199cc4fcc522418b8a
POST /api/v4/futures/orders HTTP/1.1
{"contract":"BTC_USD","type":"limit","size":100,"price":6800,"time_in_force":"gtc"}
Signature string：
POST\n
/api/v4/futures/orders\n
\n
ad3c169203dc3026558f01b4df307641fa1fa361f086b2306658886d5708767b1854797c68d9e62fef2f991645aa82673622ebf417e091d0bd22bafe5d956cca\n
1541993715
Explanation：
Signature generated
eae42da914a590ddf727473aff25fc87d50b64783941061f47a3fdb92742541fc4c2c14017581b4199a1418d54471c269c03a38d788d802e2c306c37636389f0
# example authentication implementation in Python
"""
Python SDK is recommended as it has already implemented the authentication process for every API:
"""
import time
import hashlib
import hmac
import requests
import json
def gen_sign(method, url, query_string=None, payload_string=None):
key = '' # api_key
secret = '' # api_secret
t = time.time()
m = hashlib.sha512()
m.update((payload_string or "").encode('utf-8'))
hashed_payload = m.hexdigest()
s = '%s\n%s\n%s\n%s\n%s' % (method, url, query_string or "", hashed_payload, t)
sign = hmac.new(secret.encode('utf-8'), s.encode('utf-8'), hashlib.sha512).hexdigest()
return {'KEY': key, 'Timestamp': str(t), 'SIGN': sign}
if __name__ == "__main__":
host = "https://api.gateio.ws"
prefix = "/api/v4"
common_headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/orders'
body = {"contract": "BTC_USD", "size": 100, "price": "30", "tif": "gtc"}
request_content = json.dumps(body)
sign_headers = gen_sign('POST', prefix + url, "", request_content)
sign_headers.update(common_headers)
print('signature headers: %s' % sign_headers)
res = requests.post(host + prefix + url, headers=sign_headers, data=request_content)
print(res.status_code)
print(res.content)
How to retrieve POST /wallet/transfers history?
Records of transfers generated through POST /wallet/transfers has multiple methods to be
retrieved based on account, including:
GET /margin/account_book to retrieve transferals from or to margin account.GET /futures/{settle}/account_book?type=dnw to retrieve perpetual contract account historyGET /delivery/{settle}/account_book?type=dnw to retrieve delivery contract account historyHow to create margin orders?
Margin order creation has been merged into spot order APIs. In POST /spot/orders or
POST /spot/batch_orders, set account to margin to create margin orders.
Futures operation returns error USER_NOT_FOUND
Futures account is not initialized yet. Making a deposit to your futures account will help. Note that each settle currency is associated with an independent futures account.
Futures operation returns error CONTRACT_NOT_FOUND
Every settle currency has its own contract list. Make sure the contract you specified is supported by the settle currency. You can query the list with
GET /futures/{settle}/contracts or GET /delivery/{settle}/contracts
Difference between sub account and main account
POST /wallet/sub_account_transfersPOST /withdrawalsI have other question(s) not covered above
Contact support for the issue. If the problem is related to one of the SDKs, you can also open an issue in the corresponding GitHub repository.
When submitting an issue, please include the following information to help identify the problem:
Spot trading
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /spot/currencies \
-H 'Accept: application/json'
GET /spot/currencies
Query all currency information
When a currency corresponds to multiple chains, you can query the information of multiple chains through the chains field, such as the charging and recharge status, identification, etc. of the chain
Example responses
200 Response
[
{
"currency": "GT",
"name": "GateToken",
"delisted": false,
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"trade_disabled": false,
"chain": "GT",
"chains": [
{
"name": "GT",
"addr": "",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false
},
{
"name": "ETH",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"addr": "0xE66747a101bFF2dBA3697199DCcE5b743b454759"
},
{
"name": "GTEVM",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"addr": ""
}
],
"total_supply": "2100000",
"market_cap": "18880000",
"category": []
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » currency | string | Currency symbol |
| » name | string | Currency name |
| » delisted | boolean | Whether currency is de-listed |
| » withdraw_disabled | boolean | Whether currency's withdrawal is disabled (deprecated) |
| » withdraw_delayed | boolean | Whether currency's withdrawal is delayed (deprecated) |
| » deposit_disabled | boolean | Whether currency's deposit is disabled (deprecated) |
| » trade_disabled | boolean | Whether currency's trading is disabled |
| » fixed_rate | string | Fixed fee rate. Only for fixed rate currencies, not valid for normal currencies |
| » chain | string | The main chain corresponding to the coin |
| » chains | array | All links corresponding to coins |
| »» SpotCurrencyChain | object | none |
| »»» name | string | Blockchain name |
| »»» addr | string | token address |
| »»» withdraw_disabled | boolean | Whether currency's withdrawal is disabled |
| »»» withdraw_delayed | boolean | Whether currency's withdrawal is delayed |
| »»» deposit_disabled | boolean | Whether currency's deposit is disabled |
| »» total_supply | string | Total supply |
| »» market_cap | string | Market cap |
| »» category | array | 币种分类 - stocks: 股票 - metals: 金属 - indices: 指数 - forex: 外汇 - commodities: 大宗商品 |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /spot/currencies/GT \
-H 'Accept: application/json'
GET /spot/currencies/{currency}
Query single currency information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | true | Currency name |
Example responses
200 Response
{
"currency": "GT",
"name": "GateToken",
"delisted": false,
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"trade_disabled": false,
"chain": "GT",
"chains": [
{
"name": "GT",
"addr": "",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false
},
{
"name": "ETH",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"addr": "0xE66747a101bFF2dBA3697199DCcE5b743b454759"
},
{
"name": "GTEVM",
"withdraw_disabled": false,
"withdraw_delayed": false,
"deposit_disabled": false,
"addr": ""
}
],
"total_supply": "2100000",
"market_cap": "18880000",
"category": []
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency symbol |
| » name | string | Currency name |
| » delisted | boolean | Whether currency is de-listed |
| » withdraw_disabled | boolean | Whether currency's withdrawal is disabled (deprecated) |
| » withdraw_delayed | boolean | Whether currency's withdrawal is delayed (deprecated) |
| » deposit_disabled | boolean | Whether currency's deposit is disabled (deprecated) |
| » trade_disabled | boolean | Whether currency's trading is disabled |
| » fixed_rate | string | Fixed fee rate. Only for fixed rate currencies, not valid for normal currencies |
| » chain | string | The main chain corresponding to the coin |
| » chains | array | All links corresponding to coins |
| »» SpotCurrencyChain | object | none |
| »»» name | string | Blockchain name |
| »»» addr | string | token address |
| »»» withdraw_disabled | boolean | Whether currency's withdrawal is disabled |
| »»» withdraw_delayed | boolean | Whether currency's withdrawal is delayed |
| »»» deposit_disabled | boolean | Whether currency's deposit is disabled |
| »» total_supply | string | Total supply |
| »» market_cap | string | Market cap |
| »» category | array | 币种分类 - stocks: 股票 - metals: 金属 - indices: 指数 - forex: 外汇 - commodities: 大宗商品 |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /spot/currency_pairs \
-H 'Accept: application/json'
GET /spot/currency_pairs
Query all supported currency pairs
Example responses
200 Response
[
{
"id": "ETH_USDT",
"base": "ETH",
"base_name": "Ethereum",
"quote": "USDT",
"quote_name": "Tether",
"fee": "0.2",
"min_base_amount": "0.001",
"min_quote_amount": "1.0",
"max_base_amount": "10000",
"max_quote_amount": "10000000",
"amount_precision": 3,
"precision": 6,
"trade_status": "tradable",
"sell_start": 1516378650,
"buy_start": 1516378650,
"delisting_time": 0,
"trade_url": "https://www.gate.io/trade/ETH_USDT",
"st_tag": false,
"up_rate": "0.05",
"down_rate": "0.02",
"slippage": "0.05",
"max_market_order_stock": "100000",
"max_market_order_money": "1000000"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | All currency pairs retrieved | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Spot currency pair] |
| » None | object | Spot currency pair |
| »» id | string | Currency pair |
| »» base | string | Base currency |
| »» base_name | string | Base currency name |
| »» quote | string | Quote currency |
| »» quote_name | string | Quote currency name |
| »» fee | string | Trading fee rate(deprecated) |
| »» min_base_amount | string | Minimum amount of base currency to trade, null means no limit |
| »» min_quote_amount | string | Minimum amount of quote currency to trade, null means no limit |
| »» max_base_amount | string | Maximum amount of base currency to trade, null means no limit |
| »» max_quote_amount | string | Maximum amount of quote currency to trade, null means no limit |
| »» amount_precision | integer | Amount scale |
| »» precision | integer | Price scale |
| »» trade_status | string | Trading status - untradable: cannot be traded - buyable: can be bought - sellable: can be sold - tradable: can be bought and sold |
| »» sell_start | integer(int64) | Sell start unix timestamp in seconds |
| »» buy_start | integer(int64) | Buy start unix timestamp in seconds |
| »» delisting_time | integer(int64) | Expected time to remove the shelves, Unix timestamp in seconds |
| »» type | string | Trading pair type, normal: normal, premarket: pre-market |
| »» trade_url | string | Transaction link |
| »» st_tag | boolean | Whether the trading pair is in ST risk assessment, false - No, true - Yes |
| »» up_rate | string | Maximum Quote Rise Percentage |
| »» down_rate | string | Maximum Quote Decline Percentage |
| »» slippage | string | Maximum supported slippage ratio for Spot Market Order Placement, calculated based on the latest market price at the time of order placement as the benchmark (Example: 0.03 means 3%) |
| »» market_order_max_stock | string | Maximum Market Order Quantity |
| »» market_order_max_money | string | Maximum Market Order Amount |
| Property | Value |
|---|---|
| trade_status | untradable |
| trade_status | buyable |
| trade_status | sellable |
| trade_status | tradable |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /spot/currency_pairs/ETH_BTC \
-H 'Accept: application/json'
GET /spot/currency_pairs/{currency_pair}
Query single currency pair details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | path | string | true | Currency pair |
Example responses
200 Response
{
"id": "ETH_USDT",
"base": "ETH",
"base_name": "Ethereum",
"quote": "USDT",
"quote_name": "Tether",
"fee": "0.2",
"min_base_amount": "0.001",
"min_quote_amount": "1.0",
"max_base_amount": "10000",
"max_quote_amount": "10000000",
"amount_precision": 3,
"precision": 6,
"trade_status": "tradable",
"sell_start": 1516378650,
"buy_start": 1516378650,
"delisting_time": 0,
"trade_url": "https://www.gate.io/trade/ETH_USDT",
"st_tag": false,
"up_rate": "0.05",
"down_rate": "0.02",
"slippage": "0.05",
"max_market_order_stock": "100000",
"max_market_order_money": "1000000"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
Spot currency pair
| Name | Type | Description |
|---|---|---|
| » id | string | Currency pair |
| » base | string | Base currency |
| » base_name | string | Base currency name |
| » quote | string | Quote currency |
| » quote_name | string | Quote currency name |
| » fee | string | Trading fee rate(deprecated) |
| » min_base_amount | string | Minimum amount of base currency to trade, null means no limit |
| » min_quote_amount | string | Minimum amount of quote currency to trade, null means no limit |
| » max_base_amount | string | Maximum amount of base currency to trade, null means no limit |
| » max_quote_amount | string | Maximum amount of quote currency to trade, null means no limit |
| » amount_precision | integer | Amount scale |
| » precision | integer | Price scale |
| » trade_status | string | Trading status - untradable: cannot be traded - buyable: can be bought - sellable: can be sold - tradable: can be bought and sold |
| » sell_start | integer(int64) | Sell start unix timestamp in seconds |
| » buy_start | integer(int64) | Buy start unix timestamp in seconds |
| » delisting_time | integer(int64) | Expected time to remove the shelves, Unix timestamp in seconds |
| » type | string | Trading pair type, normal: normal, premarket: pre-market |
| » trade_url | string | Transaction link |
| » st_tag | boolean | Whether the trading pair is in ST risk assessment, false - No, true - Yes |
| » up_rate | string | Maximum Quote Rise Percentage |
| » down_rate | string | Maximum Quote Decline Percentage |
| » slippage | string | Maximum supported slippage ratio for Spot Market Order Placement, calculated based on the latest market price at the time of order placement as the benchmark (Example: 0.03 means 3%) |
| » market_order_max_stock | string | Maximum Market Order Quantity |
| » market_order_max_money | string | Maximum Market Order Amount |
| Property | Value |
|---|---|
| trade_status | untradable |
| trade_status | buyable |
| trade_status | sellable |
| trade_status | tradable |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /spot/tickers \
-H 'Accept: application/json'
GET /spot/tickers
Get currency pair ticker information
If currency_pair is specified, only query that currency pair; otherwise return all information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Currency pair |
| timezone | query | string | false | Timezone |
| Parameter | Value |
|---|---|
| timezone | utc0 |
| timezone | utc8 |
| timezone | all |
Example responses
200 Response
[
{
"currency_pair": "BTC3L_USDT",
"last": "2.46140352",
"lowest_ask": "2.477",
"highest_bid": "2.4606821",
"change_percentage": "-8.91",
"change_utc0": "-8.91",
"change_utc8": "-8.91",
"base_volume": "656614.0845820589",
"quote_volume": "1602221.66468375534639404191",
"high_24h": "2.7431",
"low_24h": "1.9863",
"etf_net_value": "2.46316141",
"etf_pre_net_value": "2.43201848",
"etf_pre_timestamp": 1611244800,
"etf_leverage": "2.2803019447281203"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency_pair | string | Currency pair |
| » last | string | Last trading price |
| » lowest_ask | string | Recent lowest ask |
| » lowest_size | string | Latest seller's lowest price quantity; not available for batch queries; available for single queries, empty if no data |
| » highest_bid | string | Recent highest bid |
| » highest_size | string | Latest buyer's highest price quantity; not available for batch queries; available for single queries, empty if no data |
| » change_percentage | string | 24h price change percentage (negative for decrease, e.g., -7.45) |
| » change_utc0 | string | UTC+0 timezone, 24h price change percentage, negative for decline (e.g., -7.45) |
| » change_utc8 | string | UTC+8 timezone, 24h price change percentage, negative for decline (e.g., -7.45) |
| » base_volume | string | Base currency trading volume in the last 24h |
| » quote_volume | string | Quote currency trading volume in the last 24h |
| » high_24h | string | 24h High |
| » low_24h | string | 24h Low |
| » etf_net_value | string | ETF net value |
| » etf_pre_net_value | string|null | ETF net value at previous rebalancing point |
| » etf_pre_timestamp | integer(int64)|null | ETF previous rebalancing time |
| » etf_leverage | string|null | ETF current leverage |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /spot/order_book?currency_pair=BTC_USDT \
-H 'Accept: application/json'
GET /spot/order_book
Get market depth information
Market depth buy orders are sorted by price from high to low, sell orders are reversed
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | true | Currency pair |
| interval | query | string | false | Price precision for merged depth. 0 means no merging. If not specified, defaults to 0 |
| limit | query | integer | false | Number of depth levels |
| with_id | query | boolean | false | Return order book update ID |
Example responses
200 Response
{
"id": 123456,
"current": 1623898993123,
"update": 1623898993121,
"asks": [
[
"1.52",
"1.151"
],
[
"1.53",
"1.218"
]
],
"bids": [
[
"1.17",
"201.863"
],
[
"1.16",
"725.464"
]
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Order book ID, which is updated whenever the order book is changed. Valid only when with_id is set to true |
| » current | integer(int64) | The timestamp of the response data being generated (in milliseconds) |
| » update | integer(int64) | The timestamp of when the orderbook last changed (in milliseconds) |
| » asks | array | Ask Depth |
| »» None | array | Price and Quantity Pair |
| » bids | array | Bid Depth |
| »» None | array | Price and Quantity Pair |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /spot/trades?currency_pair=BTC_USDT \
-H 'Accept: application/json'
GET /spot/trades
Query market transaction records
Supports querying by time range using from and to parameters or pagination based on last_id. By default, queries the last 30 days.
Pagination based on last_id is no longer recommended. If last_id is specified, the time range query parameters will be ignored.
When using limit&page pagination to retrieve data, the maximum number of pages is 100,000, that is, limit * (page - 1) <= 100,000.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | true | Currency pair |
| limit | query | integer(int32) | false | Maximum number of items returned in list. Default: 100, minimum: 1, maximum: 1000 |
| last_id | query | string | false | Use the ID of the last record in the previous list as the starting point for the next list |
| reverse | query | boolean | false | Whether to retrieve data less than last_id. Default returns records greater than last_id. |
| from | query | integer(int64) | false | Start timestamp for the query |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| page | query | integer(int32) | false | Page number |
last_id: Use the ID of the last record in the previous list as the starting point for the next list
Operations based on custom IDs can only be checked when orders are pending. After orders are completed (filled/cancelled), they can be checked within 1 hour after completion. After expiration, only order IDs can be used
reverse: Whether to retrieve data less than last_id. Default returns records greater than last_id.
Set to true to trace back market trade records, false to get latest trades.
No effect when last_id is not set.
Example responses
200 Response
[
{
"id": "1232893232",
"create_time": "1548000000",
"create_time_ms": "1548000000123.456",
"order_id": "4128442423",
"side": "buy",
"role": "maker",
"amount": "0.15",
"price": "0.03",
"fee": "0.0005",
"fee_currency": "ETH",
"point_fee": "0",
"gt_fee": "0",
"sequence_id": "588018",
"text": "t-test",
"deal": "0.0045"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | string | Fill ID |
| » create_time | string | Fill Time |
| » create_time_ms | string | Trading time, with millisecond precision |
| » currency_pair | string | Currency pair |
| » side | string | Buy or sell order |
| » role | string | Trade role, not returned in public endpoints |
| » amount | string | Trade amount |
| » price | string | Order price |
| » order_id | string | Related order ID, not returned in public endpoints |
| » fee | string | Fee deducted, not returned in public endpoints |
| » fee_currency | string | Fee currency unit, not returned in public endpoints |
| » point_fee | string | Points used to deduct fee, not returned in public endpoints |
| » gt_fee | string | GT used to deduct fee, not returned in public endpoints |
| » amend_text | string | The custom data that the user remarked when amending the order |
| » sequence_id | string | Consecutive trade ID within a single market. Used to track and identify trades in the specific market |
| » text | string | Order's Custom Information. This field is not returned by public interfaces. The scenarios pm_liquidate, comb_margin_liquidate, and scm_liquidate represent full-account forced liquidation orders. liquidate represents isolated-account forced liquidation orders. |
| » deal | string | Total Executed Value |
| Property | Value |
|---|---|
| side | buy |
| side | sell |
| role | taker |
| role | maker |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /spot/candlesticks?currency_pair=BTC_USDT \
-H 'Accept: application/json'
GET /spot/candlesticks
Market K-line chart
K-line chart data returns a maximum of 1000 points per request. When specifying from, to, and interval, ensure the number of points is not excessive
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | true | Currency pair |
| limit | query | integer | false | Maximum number of recent data points to return. limit conflicts with from and to. If either from or to is specified, request will be rejected. |
| from | query | integer(int64) | false | Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified |
| to | query | integer(int64) | false | Specify the end time of the K-line chart, defaults to current time if not specified, note that the time format is Unix timestamp with second precision |
| interval | query | string | false | Time interval between data points. Note that 30d represents a calendar month, not aligned to 30 days |
| Parameter | Value |
|---|---|
| interval | 1s |
| interval | 10s |
| interval | 1m |
| interval | 5m |
| interval | 15m |
| interval | 30m |
| interval | 1h |
| interval | 4h |
| interval | 8h |
| interval | 1d |
| interval | 7d |
| interval | 30d |
Example responses
200 Response
[
[
"1539852480",
"971519.677",
"0.0021724",
"0.0021922",
"0.0021724",
"0.0021737",
"true"
]
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [[string]] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | array | Candlestick data for each time granularity, from left to right: - Unix timestamp with second precision - Trading volume in quote currency - Closing price - Highest price - Lowest price - Opening price - Trading volume in base currency - Whether window is closed; true means this candlestick data segment is complete, false means not yet complete |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/fee'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /spot/fee \
-H 'Accept: application/json'
GET /spot/fee
Query account fee rates
This API is deprecated. The new fee query API is /wallet/fee
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Specify currency pair to get more accurate fee settings. |
currency_pair: Specify currency pair to get more accurate fee settings.
This field is optional. Usually fee settings are the same for all currency pairs.
Example responses
200 Response
{
"user_id": 10001,
"taker_fee": "0.002",
"maker_fee": "0.002",
"gt_discount": false,
"gt_taker_fee": "0",
"gt_maker_fee": "0",
"loan_fee": "0.18",
"point_type": "1",
"currency_pair": "BTC_USDT",
"debit_fee": 3
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » user_id | integer(int64) | User ID |
| » taker_fee | string | taker fee rate |
| » maker_fee | string | maker fee rate |
| » rpi_maker_fee | string | RPI MM maker fee rate |
| » gt_discount | boolean | Whether GT deduction discount is enabled |
| » gt_taker_fee | string | Taker fee rate if using GT deduction. It will be 0 if GT deduction is disabled |
| » gt_maker_fee | string | Maker fee rate with GT deduction. Returns 0 if GT deduction is disabled |
| » loan_fee | string | Loan fee rate of margin lending |
| » point_type | string | Point card type: 0 - Original version, 1 - New version since 202009 |
| » currency_pair | string | Currency pair |
| » debit_fee | integer | Deduction types for rates, 1 - GT deduction, 2 - Point card deduction, 3 - VIP rates |
| » rpi_mm | integer | RPI MM Level |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/batch_fee'
query_param = 'currency_pairs=BTC_USDT,ETH_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /spot/batch_fee?currency_pairs=BTC_USDT%2CETH_USDT \
-H 'Accept: application/json'
GET /spot/batch_fee
Batch query account fee rates
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pairs | query | string | true | Maximum 50 currency pairs per request |
Example responses
200 Response
{
"BTC_USDT": {
"user_id": 10001,
"taker_fee": "0.002",
"maker_fee": "0.002",
"rpi_maker_fee": "-0.00175",
"gt_discount": false,
"gt_taker_fee": "0",
"gt_maker_fee": "0",
"loan_fee": "0.18",
"point_type": "1",
"currency_pair": "BTC_USDT",
"debit_fee": 3,
"rpi_mm": 2
},
"GT_USDT": {
"user_id": 10001,
"taker_fee": "0.002",
"maker_fee": "0.002",
"rpi_maker_fee": "-0.00175",
"gt_discount": false,
"gt_taker_fee": "0",
"gt_maker_fee": "0",
"loan_fee": "0.18",
"point_type": "1",
"currency_pair": "GT_USDT",
"debit_fee": 3,
"rpi_mm": 2
},
"ETH_USDT": {
"user_id": 10001,
"taker_fee": "0.002",
"maker_fee": "0.002",
"rpi_maker_fee": "-0.00175",
"gt_discount": false,
"gt_taker_fee": "0",
"gt_maker_fee": "0",
"loan_fee": "0.18",
"point_type": "1",
"currency_pair": "ETH_USDT",
"debit_fee": 3,
"rpi_mm": 2
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » additionalProperties | object | none |
| »» user_id | integer(int64) | User ID |
| »» taker_fee | string | taker fee rate |
| »» maker_fee | string | maker fee rate |
| »» rpi_maker_fee | string | RPI MM maker fee rate |
| »» gt_discount | boolean | Whether GT deduction discount is enabled |
| »» gt_taker_fee | string | Taker fee rate if using GT deduction. It will be 0 if GT deduction is disabled |
| »» gt_maker_fee | string | Maker fee rate with GT deduction. Returns 0 if GT deduction is disabled |
| »» loan_fee | string | Loan fee rate of margin lending |
| »» point_type | string | Point card type: 0 - Original version, 1 - New version since 202009 |
| »» currency_pair | string | Currency pair |
| »» debit_fee | integer | Deduction types for rates, 1 - GT deduction, 2 - Point card deduction, 3 - VIP rates |
| »» rpi_mm | integer | RPI MM Level |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/accounts'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /spot/accounts \
-H 'Accept: application/json'
GET /spot/accounts
List spot trading accounts
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
Example responses
200 Response
[
{
"currency": "ETH",
"available": "968.8",
"locked": "0",
"update_id": 98
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency detail |
| » available | string | Available amount |
| » locked | string | Locked amount, used in trading |
| » update_id | integer(int64) | Version number |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/account_book'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /spot/account_book \
-H 'Accept: application/json'
GET /spot/account_book
Query spot account transaction history
Record query time range cannot exceed 30 days.
When using limit&page pagination to retrieve data, the maximum number of pages is 100,000, that is, limit * (page - 1) <= 100,000.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
| from | query | integer(int64) | false | Start timestamp for the query |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records returned in a single list |
| type | query | string | false | Query by specified account change type. If not specified, all change types will be included. |
| code | query | string | false | Specify account change code for query. If not specified, all change types are included. This parameter has higher priority than type |
Example responses
200 Response
[
{
"id": "123456",
"time": 1547633726123,
"currency": "BTC",
"change": "1.03",
"balance": "4.59316525194",
"type": "margin_in",
"text": "3815099"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | string | Balance change record ID |
| » time | integer(int64) | The timestamp of the change (in milliseconds) |
| » currency | string | Currency changed |
| » change | string | Amount changed. Positive value means transferring in, while negative out |
| » balance | string | Balance after change |
| » type | string | Account change type; deprecated (see code for account change type encoding) |
| » code | string | Account change code, see [Asset Record Code] (Asset Record Code) |
| » text | string | Additional information |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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","slippage":"0.05","stop_profit":{"trigger_price":"67000","order_price":"67000"},"stop_loss":{"trigger_price":"63000","order_price":"63000"}}]'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /spot/batch_orders \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-gate-exptime: 1689560679123'
POST /spot/batch_orders
Batch place orders
Batch order requirements:
text must be specifiedaccount fields in the same request must be identicalBody parameter
[
{
"text": "t-abc123",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"slippage": "0.05",
"stop_profit": {
"trigger_price": "67000",
"order_price": "67000"
},
"stop_loss": {
"trigger_price": "63000",
"order_price": "63000"
}
}
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | array | true | none |
Example responses
200 Response
[
{
"order_id": "12332324",
"amend_text": "t-123456",
"text": "t-123456",
"succeeded": true,
"label": "",
"message": "",
"id": "12332324",
"create_time": "1548000000",
"update_time": "1548000100",
"create_time_ms": 1548000000123,
"update_time_ms": 1548000100123,
"currency_pair": "ETC_BTC",
"status": "cancelled",
"type": "limit",
"account": "spot",
"side": "buy",
"amount": "1",
"price": "5.00032",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0.5",
"filled_amount": "1.242",
"filled_total": "2.50016",
"avg_deal_price": "5.00032",
"fee": "0.005",
"fee_currency": "ETH",
"point_fee": "0",
"gt_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "BTC",
"stp_act": "cn",
"finish_as": "stp",
"stp_id": 10240
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request execution completed | [Inline] |
Status Code 200
Contains multiple order objects; for the specific structure of the order object, refer to the structure of the /spot/orders order placement interface
| Name | Type | Description |
|---|---|---|
| None | array | Contains multiple order objects; for the specific structure of the order object, refer to the structure of the /spot/orders order placement interface |
| » None | object | Batch order details |
| »» order_id | string | Order ID |
| »» amend_text | string | The custom data that the user remarked when amending the order |
| »» text | string | Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: 1. Must start with t-2. Excluding t-, length cannot exceed 28 bytes3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.) |
| »» succeeded | boolean | Request execution result |
| »» label | string | Error label, if any, otherwise an empty string |
| »» message | string | Detailed error message, if any, otherwise an empty string |
| »» id | string | Order ID |
| »» create_time | string | Creation time of order |
| »» update_time | string | Last modification time of order |
| »» create_time_ms | integer(int64) | Creation time of order (in milliseconds) |
| »» update_time_ms | integer(int64) | Last modification time of order (in milliseconds) |
| »» status | string | Order status - open: to be filled- closed: closed order- cancelled: cancelled |
| »» currency_pair | string | Currency pair |
| »» type | string | Order Type - limit : Limit Order - market : Market Order |
| »» account | string | Account type, spot - spot account, margin - leveraged account, unified - unified account |
| »» side | string | Buy or sell order |
| »» amount | string | Trade amount |
| »» price | string | Order price |
| »» time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none |
| »» iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported |
| »» auto_repay | boolean | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order |
| »» left | string | Amount left to fill |
| »» filled_amount | string | Amount filled |
| »» fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total |
| »» filled_total | string | Total filled in quote currency |
| »» avg_deal_price | string | Average fill price |
| »» fee | string | Fee deducted |
| »» fee_currency | string | Fee currency unit |
| »» point_fee | string | Points used to deduct fee |
| »» gt_fee | string | GT used to deduct fee |
| »» gt_discount | boolean | Whether GT fee deduction is enabled |
| »» rebated_fee | string | Rebated fee |
| »» rebated_fee_currency | string | Rebated fee currency unit |
| »» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
| »» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group, he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy。2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter。3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled |
| »» finish_as | string | How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only / maker requirement not met (e.g. related TIF such as poc/rvt/rat/rpi would take liquidity as taker) - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown |
| »» stop_profit | object | Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged. |
| »»» trigger_price | string | Take profit trigger price When side == "buy", trigger_price must be greater than priceWhen side == "sell", trigger_price must be less than price |
| »»» order_price | string | Take profit order price |
| »» stop_loss | object | Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged. |
| »»» trigger_price | string | Stop loss trigger price When side == "buy", trigger_price must be less than priceWhen side == "sell", trigger_price must be greater than price |
| »»» order_price | string | Stop-loss order price |
| 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 | liquidate_cancelled |
| finish_as | depth_not_enough |
| finish_as | trader_not_enough |
| finish_as | small |
| finish_as | ioc |
| finish_as | poc |
| finish_as | fok |
| finish_as | stp |
| finish_as | price_protect_cancelled |
| finish_as | unknown |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/open_orders'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /spot/open_orders \
-H 'Accept: application/json'
GET /spot/open_orders
List all open orders
Query the current order list of all trading pairs. Please note that the paging parameter controls the number of pending orders in each trading pair. There is no paging control trading pairs. All trading pairs with pending orders will be returned.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records returned in one page in each currency pair |
| account | query | string | false | Specify query account |
Example responses
200 Response
[
{
"currency_pair": "ETH_BTC",
"total": 1,
"orders": [
{
"id": "12332324",
"text": "t-123456",
"create_time": "1548000000",
"update_time": "1548000100",
"currency_pair": "ETH_BTC",
"status": "open",
"type": "limit",
"account": "spot",
"side": "buy",
"amount": "1",
"price": "5.00032",
"time_in_force": "gtc",
"left": "0.5",
"filled_total": "2.50016",
"fee": "0.005",
"fee_currency": "ETH",
"point_fee": "0",
"gt_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "BTC"
}
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency_pair | string | Currency pair |
| » total | integer | Total number of open orders for this trading pair on the current page |
| » orders | array | none |
| »» None | object | Spot order details |
| »»» id | string | Order ID |
| »»» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders liquidate represents isolated-margin liquidation orders |
| »»» 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: closed order- cancelled: cancelled |
| »»» currency_pair | string | Currency pair |
| »»» type | string | Order Type - limit : Limit Order - market : Market Order |
| »»» account | string | Account type, spot - spot account, margin - leveraged account, unified - unified account |
| »»» side | string | Buy or sell order |
| »»» amount | string | Trade amount When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT.When type is market, the meaning depends on the side:- side: buy refers to the quote currency, e.g. USDT in BTC_USDT- side: sell refers to the base currency, e.g. BTC in BTC_USDT |
| »»» price | string | Trading price, required when type=limit |
| »»» time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market |
| »»» iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported |
| »»» auto_repay | boolean | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order |
| »»» left | string | Amount left to fill |
| »»» filled_amount | string | Amount filled |
| »»» fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total |
| »»» filled_total | string | Total filled in quote currency |
| »»» avg_deal_price | string | Average fill price |
| »»» fee | string | Fee deducted |
| »»» fee_currency | string | Fee currency unit |
| »»» point_fee | string | Points used to deduct fee |
| »»» gt_fee | string | GT used to deduct fee |
| »»» gt_maker_fee | string | GT amount used to deduct maker fee |
| »»» gt_taker_fee | string | GT amount used to deduct taker fee |
| »»» gt_discount | boolean | Whether GT fee deduction is enabled |
| »»» rebated_fee | string | Rebated fee |
| »»» rebated_fee_currency | string | Rebated fee currency unit |
| »»» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
| »»» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy.2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter.3. If the user did not use stp_act when placing the order, stp_act will return '-'- cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled |
| »»» finish_as | string | How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only / maker requirement not met (e.g. related TIF such as poc/rvt/rat/rpi would take liquidity as taker) - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown |
| »»» stop_profit | object | Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged. |
| »»»» trigger_price | string | Take profit trigger price When side == "buy", trigger_price must be greater than priceWhen side == "sell", trigger_price must be less than price |
| »»»» order_price | string | Take profit order price |
| »»» stop_loss | object | Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged. |
| »»»» trigger_price | string | Stop loss trigger price When side == "buy", trigger_price must be less than priceWhen side == "sell", trigger_price must be greater than price |
| »»»» order_price | string | Stop-loss order price |
| Property | Value |
|---|---|
| status | open |
| status | closed |
| status | cancelled |
| type | limit |
| type | market |
| side | buy |
| side | sell |
| time_in_force | gtc |
| time_in_force | ioc |
| time_in_force | poc |
| time_in_force | fok |
| stp_act | cn |
| stp_act | co |
| stp_act | cb |
| stp_act | - |
| finish_as | open |
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidate_cancelled |
| finish_as | depth_not_enough |
| finish_as | trader_not_enough |
| finish_as | small |
| finish_as | ioc |
| finish_as | poc |
| finish_as | fok |
| finish_as | stp |
| finish_as | price_protect_cancelled |
| finish_as | unknown |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /spot/cross_liquidate_orders \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /spot/cross_liquidate_orders
Close position when cross-currency is disabled
Currently, only cross-margin accounts are supported to place buy orders for disabled currencies. Maximum buy quantity = (unpaid principal and interest - currency balance - the amount of the currency in pending orders) / 0.998
Body parameter
{
"currency_pair": "GT_USDT",
"amount": "12",
"price": "10.15",
"text": "t-34535"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » text | body | string | false | Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: |
| » currency_pair | body | string | true | Currency pair |
| » amount | body | string | true | Trade amount |
| » price | body | string | true | Order price |
| » action_mode | body | string | false | Processing mode: |
» text: Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions:
t-t-, length cannot exceed 28 bytes» action_mode: Processing mode:
Different fields are returned when placing an order based on action_mode. This field is only valid during the request and is not included in the response
ACK: Asynchronous mode, only returns key order fields
RESULT: No liquidation information
FULL: Full mode (default)
Example responses
201 Response
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled",
"stop_profit": {
"trigger_price": "67000",
"order_price": "67000"
},
"stop_loss": {
"trigger_price": "63000",
"order_price": "63000"
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order created successfully | Inline |
Status Code 201
Spot order details
| Name | Type | Description |
|---|---|---|
| » id | string | Order ID |
| » text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders liquidate represents isolated-margin liquidation orders |
| » 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: closed order- cancelled: cancelled |
| » currency_pair | string | Currency pair |
| » type | string | Order Type - limit : Limit Order - market : Market Order |
| » account | string | Account type, spot - spot account, margin - leveraged account, unified - unified account |
| » side | string | Buy or sell order |
| » amount | string | Trade amount When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT.When type is market, the meaning depends on the side:- side: buy refers to the quote currency, e.g. USDT in BTC_USDT- side: sell refers to the base currency, e.g. BTC in BTC_USDT |
| » price | string | Trading price, required when type=limit |
| » time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market |
| » iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported |
| » auto_repay | boolean | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order |
| » left | string | Amount left to fill |
| » filled_amount | string | Amount filled |
| » fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total |
| » filled_total | string | Total filled in quote currency |
| » avg_deal_price | string | Average fill price |
| » fee | string | Fee deducted |
| » fee_currency | string | Fee currency unit |
| » point_fee | string | Points used to deduct fee |
| » gt_fee | string | GT used to deduct fee |
| » gt_maker_fee | string | GT amount used to deduct maker fee |
| » gt_taker_fee | string | GT amount used to deduct taker fee |
| » gt_discount | boolean | Whether GT fee deduction is enabled |
| » rebated_fee | string | Rebated fee |
| » rebated_fee_currency | string | Rebated fee currency unit |
| » stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
| » stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy.2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter.3. If the user did not use stp_act when placing the order, stp_act will return '-'- cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled |
| » finish_as | string | How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only / maker requirement not met (e.g. related TIF such as poc/rvt/rat/rpi would take liquidity as taker) - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown |
| » stop_profit | object | Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged. |
| »» trigger_price | string | Take profit trigger price When side == "buy", trigger_price must be greater than priceWhen side == "sell", trigger_price must be less than price |
| »» order_price | string | Take profit order price |
| » stop_loss | object | Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged. |
| »» trigger_price | string | Stop loss trigger price When side == "buy", trigger_price must be less than priceWhen side == "sell", trigger_price must be greater than price |
| »» order_price | string | Stop-loss order price |
| Property | Value |
|---|---|
| status | open |
| status | closed |
| status | cancelled |
| type | limit |
| type | market |
| side | buy |
| side | sell |
| time_in_force | gtc |
| time_in_force | ioc |
| time_in_force | poc |
| time_in_force | fok |
| stp_act | cn |
| stp_act | co |
| stp_act | cb |
| stp_act | - |
| finish_as | open |
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidate_cancelled |
| finish_as | depth_not_enough |
| finish_as | trader_not_enough |
| finish_as | small |
| finish_as | ioc |
| finish_as | poc |
| finish_as | fok |
| finish_as | stp |
| finish_as | price_protect_cancelled |
| finish_as | unknown |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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","slippage":"0.05","stop_profit":{"trigger_price":"67000","order_price":"67000"},"stop_loss":{"trigger_price":"63000","order_price":"63000"}}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /spot/orders \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-gate-exptime: 1689560679123'
POST /spot/orders
Create an order
Supports spot, margin, leverage, and cross-margin leverage orders. Use different accounts through the account field. Default is spot, which means using the spot account to place orders. If the user has a unified account, the default is to place orders with the unified account.
When using leveraged account trading (i.e., when account is set to margin), you can set auto_borrow to true.
In case of insufficient account balance, the system will automatically execute POST /margin/uni/loans to borrow the insufficient amount.
Whether assets obtained after leveraged order execution are automatically used to repay borrowing orders of the isolated margin account depends on the automatic repayment settings of the user's isolated margin account.
Account automatic repayment settings can be queried and set through /margin/auto_repay.
When using unified account trading (i.e., when account is set to unified), auto_borrow can also be enabled to realize automatic borrowing of insufficient amounts. However, unlike the isolated margin account, whether unified account orders are automatically repaid depends on the auto_repay setting when placing the order. This setting only applies to the current order, meaning only assets obtained after order execution will be used to repay borrowing orders of the cross-margin account.
Unified account ordering currently supports enabling both auto_borrow and auto_repay simultaneously.
Auto repayment will be triggered when the order ends, i.e., when status is cancelled or closed.
Order Status
The order status in pending orders is open, which remains open until all quantity is filled. If fully filled, the order ends and status becomes closed.
If the order is cancelled before all transactions are completed, regardless of partial fills, the status will become cancelled.
Iceberg Orders
iceberg is used to set the displayed quantity of iceberg orders and does not support complete hiding. Note that hidden portions are charged according to the taker's fee rate.
Self-Trade Prevention
Set stp_act to determine the self-trade prevention strategy to use
Body parameter
{
"text": "t-abc123",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"slippage": "0.05",
"stop_profit": {
"trigger_price": "67000",
"order_price": "67000"
},
"stop_loss": {
"trigger_price": "63000",
"order_price": "63000"
}
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | object | true | none |
| » text | body | string | false | User defined information. If not empty, must follow the rules below: |
| » currency_pair | body | string | true | Currency pair |
| » type | body | string | false | Order Type |
| » account | body | string | false | Account type, spot - spot account, margin - leveraged account, unified - unified account |
| » side | body | string | true | Buy or sell order |
| » amount | body | string | true | Trade amount |
| » price | body | string | false | Trading price, required when type=limit |
| » time_in_force | body | string | false | Time in force |
| » iceberg | body | string | false | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported |
| » auto_borrow | body | boolean | false | Used in margin or cross margin trading to allow automatic loan of insufficient amount if balance is not enough |
| » auto_repay | body | boolean | false | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: |
| » stp_act | body | string | false | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies |
| » action_mode | body | string | false | Processing Mode: |
| » slippage | body | string | false | Maximum supported slippage ratio for Spot Market Order Placement, calculated based on the latest market price at the time of order placement as the benchmark (Example: 0.03 means 3%) |
| » stop_profit | body | object | false | Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged. |
| »» trigger_price | body | string | false | Take profit trigger price |
| »» order_price | body | string | false | Take profit order price |
| » stop_loss | body | object | false | Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged. |
| »» trigger_price | body | string | false | Stop loss trigger price |
| »» order_price | body | string | false | Stop-loss order price |
» text: User defined information. If not empty, must follow the rules below:
t-t- prefixBesides user defined information, reserved contents are listed below, denoting how the order is created:
» type: Order Type
» amount: Trade amount
When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT.
When type is market, the meaning depends on the side:
side: buy refers to the quote currency, e.g. USDT in BTC_USDTside: sell refers to the base currency, e.g. BTC in BTC_USDT» time_in_force: Time in force
ioc and fok are supported when type=market» auto_repay: Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that:
auto_borrow and auto_repay can be both set to true in one order» stp_act: Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies
STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy.STP group, an error will be returned when passing the stp_act parameter.stp_act when placing the order, stp_act will return '-'» action_mode: Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)
»» trigger_price: Take profit trigger price
When side == "buy", trigger_price must be greater than price
When side == "sell", trigger_price must be less than price
»» trigger_price: Stop loss trigger price
When side == "buy", trigger_price must be less than price
When side == "sell", trigger_price must be greater than price
| 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",
"slippage": "0.05",
"stop_profit": {
"trigger_price": "67000",
"order_price": "67000"
},
"stop_loss": {
"trigger_price": "63000",
"order_price": "63000"
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order created | Inline |
Status Code 201
Spot order details
| Name | Type | Description |
|---|---|---|
| » id | string | Order ID |
| » text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders liquidate represents isolated-margin liquidation orders |
| » 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: closed order- cancelled: cancelled |
| » currency_pair | string | Currency pair |
| » type | string | Order Type - limit : Limit Order - market : Market Order |
| » account | string | Account type, spot - spot account, margin - leveraged account, unified - unified account |
| » side | string | Buy or sell order |
| » amount | string | Trade amount When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT.When type is market, the meaning depends on the side:- side: buy refers to the quote currency, e.g. USDT in BTC_USDT- side: sell refers to the base currency, e.g. BTC in BTC_USDT |
| » price | string | Trading price, required when type=limit |
| » time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market |
| » iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported |
| » auto_borrow | boolean | Used in margin or cross margin trading to allow automatic loan of insufficient amount if balance is not enough |
| » auto_repay | boolean | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order |
| » left | string | Amount left to fill |
| » filled_amount | string | Amount filled |
| » fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total |
| » filled_total | string | Total filled in quote currency |
| » avg_deal_price | string | Average fill price |
| » fee | string | Fee deducted |
| » fee_currency | string | Fee currency unit |
| » point_fee | string | Points used to deduct fee |
| » gt_fee | string | GT used to deduct fee |
| » gt_maker_fee | string | GT amount used to deduct maker fee |
| » gt_taker_fee | string | GT amount used to deduct taker fee |
| » gt_discount | boolean | Whether GT fee deduction is enabled |
| » rebated_fee | string | Rebated fee |
| » rebated_fee_currency | string | Rebated fee currency unit |
| » stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
| » stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy.2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter.3. If the user did not use stp_act when placing the order, stp_act will return '-'- cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled |
| » finish_as | string | How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only / maker requirement not met (e.g. related TIF such as poc/rvt/rat/rpi would take liquidity as taker) - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown |
| » action_mode | string | Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default) |
| » slippage | string | Maximum supported slippage ratio for Spot Market Order Placement, calculated based on the latest market price at the time of order placement as the benchmark (Example: 0.03 means 3%) |
| » stop_profit | object | Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged. |
| »» trigger_price | string | Take profit trigger price When side == "buy", trigger_price must be greater than priceWhen side == "sell", trigger_price must be less than price |
| »» order_price | string | Take profit order price |
| » stop_loss | object | Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged. |
| »» trigger_price | string | Stop loss trigger price When side == "buy", trigger_price must be less than priceWhen side == "sell", trigger_price must be greater than price |
| »» order_price | string | Stop-loss order price |
| Property | Value |
|---|---|
| status | open |
| status | closed |
| status | cancelled |
| type | limit |
| type | market |
| side | buy |
| side | sell |
| time_in_force | gtc |
| time_in_force | ioc |
| time_in_force | poc |
| time_in_force | fok |
| stp_act | cn |
| stp_act | co |
| stp_act | cb |
| stp_act | - |
| finish_as | open |
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidate_cancelled |
| finish_as | depth_not_enough |
| finish_as | trader_not_enough |
| finish_as | small |
| finish_as | ioc |
| finish_as | poc |
| finish_as | fok |
| finish_as | stp |
| finish_as | price_protect_cancelled |
| finish_as | unknown |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/orders'
query_param = 'currency_pair=BTC_USDT&status=open'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /spot/orders?currency_pair=BTC_USDT&status=open \
-H 'Accept: application/json'
GET /spot/orders
List orders
Note that query results default to spot order lists for spot, unified account, and isolated margin accounts.
When status is set to open (i.e., when querying pending order lists), only page and limit pagination controls are supported. limit can only be set to a maximum of 100.
The side parameter and time range query parameters from and to are not supported.
When status is set to finished (i.e., when querying historical orders), in addition to pagination queries, from and to time range queries are also supported.
Additionally, the side parameter can be set to filter one-sided history.
Time range filter parameters are processed according to the order end time.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | true | Query by specified currency pair. Required for open orders, optional for filled orders |
| status | query | string | true | List orders based on status |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records to be returned. If status is open, maximum of limit is 100 |
| account | query | string | false | Specify query account |
| from | query | integer(int64) | false | Start timestamp for the query |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| side | query | string | false | Specify all bids or all asks, both included if not specified |
status: List orders based on status
open - order is waiting to be filled
finished - order has been filled or cancelled
Example responses
200 Response
[
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled",
"stop_profit": {
"trigger_price": "67000",
"order_price": "67000"
},
"stop_loss": {
"trigger_price": "63000",
"order_price": "63000"
}
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Spot order details] |
| » None | object | Spot order details |
| »» id | string | Order ID |
| »» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders liquidate represents isolated-margin liquidation orders |
| »» 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: closed order- cancelled: cancelled |
| »» currency_pair | string | Currency pair |
| »» type | string | Order Type - limit : Limit Order - market : Market Order |
| »» account | string | Account type, spot - spot account, margin - leveraged account, unified - unified account |
| »» side | string | Buy or sell order |
| »» amount | string | Trade amount When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT.When type is market, the meaning depends on the side:- side: buy refers to the quote currency, e.g. USDT in BTC_USDT- side: sell refers to the base currency, e.g. BTC in BTC_USDT |
| »» price | string | Trading price, required when type=limit |
| »» time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market |
| »» iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported |
| »» auto_repay | boolean | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order |
| »» left | string | Amount left to fill |
| »» filled_amount | string | Amount filled |
| »» fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total |
| »» filled_total | string | Total filled in quote currency |
| »» avg_deal_price | string | Average fill price |
| »» fee | string | Fee deducted |
| »» fee_currency | string | Fee currency unit |
| »» point_fee | string | Points used to deduct fee |
| »» gt_fee | string | GT used to deduct fee |
| »» gt_maker_fee | string | GT amount used to deduct maker fee |
| »» gt_taker_fee | string | GT amount used to deduct taker fee |
| »» gt_discount | boolean | Whether GT fee deduction is enabled |
| »» rebated_fee | string | Rebated fee |
| »» rebated_fee_currency | string | Rebated fee currency unit |
| »» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
| »» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy.2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter.3. If the user did not use stp_act when placing the order, stp_act will return '-'- cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled |
| »» finish_as | string | How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only / maker requirement not met (e.g. related TIF such as poc/rvt/rat/rpi would take liquidity as taker) - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown |
| »» stop_profit | object | Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged. |
| »»» trigger_price | string | Take profit trigger price When side == "buy", trigger_price must be greater than priceWhen side == "sell", trigger_price must be less than price |
| »»» order_price | string | Take profit order price |
| »» stop_loss | object | Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged. |
| »»» trigger_price | string | Stop loss trigger price When side == "buy", trigger_price must be less than priceWhen side == "sell", trigger_price must be greater than price |
| »»» order_price | string | Stop-loss order price |
| Property | Value |
|---|---|
| status | open |
| status | closed |
| status | cancelled |
| type | limit |
| type | market |
| side | buy |
| side | sell |
| time_in_force | gtc |
| time_in_force | ioc |
| time_in_force | poc |
| time_in_force | fok |
| stp_act | cn |
| stp_act | co |
| stp_act | cb |
| stp_act | - |
| finish_as | open |
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidate_cancelled |
| finish_as | depth_not_enough |
| finish_as | trader_not_enough |
| finish_as | small |
| finish_as | ioc |
| finish_as | poc |
| finish_as | fok |
| finish_as | stp |
| finish_as | price_protect_cancelled |
| finish_as | unknown |
open orders in specified currency pairCode samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/orders'
query_param = ''
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
curl -X DELETE /spot/orders \
-H 'Accept: application/json' \
-H 'x-gate-exptime: 1689560679123'
DELETE /spot/orders
Cancel all open orders in specified currency pair
When the account parameter is not specified, all pending orders including spot, unified account, and isolated margin will be cancelled.
When currency_pair is not specified, all trading pair pending orders will be cancelled.
You can specify a particular account to cancel all pending orders under that account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Currency pair |
| side | query | string | false | Specify all bids or all asks, both included if not specified |
| account | query | string | false | Specify account type |
| action_mode | query | string | false | Processing Mode |
| x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
account: Specify account type
Classic account: All are included if not specified
Unified account: Specify unified
action_mode: Processing Mode
When placing an order, different fields are returned based on the action_mode
ACK: Asynchronous mode, returns only key order fieldsRESULT: No clearing informationFULL: Full mode (default)Example responses
200 Response
[
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"succeeded": true,
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancel request is received and processed. Success is determined based on the order list | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Spot order details |
| »» id | string | Order ID |
| »» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 |
| »» amend_text | string | The custom data that the user remarked when amending the order |
| »» succeeded | boolean | Request execution result |
| »» label | string | Error label, if any, otherwise an empty string |
| »» message | string | Detailed error message, if any, otherwise an empty string |
| »» create_time | string | Creation time of order |
| »» update_time | string | Last modification time of order |
| »» create_time_ms | integer(int64) | Creation time of order (in milliseconds) |
| »» update_time_ms | integer(int64) | Last modification time of order (in milliseconds) |
| »» status | string | Order status - open: to be filled- closed: closed order- cancelled: cancelled |
| »» currency_pair | string | Currency pair |
| »» type | string | Order Type - limit : Limit Order - market : Market Order |
| »» account | string | Account type, spot - spot account, margin - leveraged account, unified - unified account |
| »» side | string | Buy or sell order |
| »» amount | string | Trading quantity When type is limit, it refers to the base currency (the currency being traded), such as BTC in BTC_USDTWhen type is market, it refers to different currencies based on the side:- side: buy refers to quote currency, BTC_USDT means USDT- side: sell refers to base currency, BTC_USDT means BTC |
| »» price | string | Trading price, required when type=limit |
| »» time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market |
| »» iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported |
| »» auto_repay | boolean | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order |
| »» left | string | Amount left to fill |
| »» filled_amount | string | Amount filled |
| »» fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total |
| »» filled_total | string | Total filled in quote currency |
| »» avg_deal_price | string | Average fill price |
| »» fee | string | Fee deducted |
| »» fee_currency | string | Fee currency unit |
| »» point_fee | string | Points used to deduct fee |
| »» gt_fee | string | GT used to deduct fee |
| »» gt_maker_fee | string | GT amount used to deduct maker fee |
| »» gt_taker_fee | string | GT amount used to deduct taker fee |
| »» gt_discount | boolean | Whether GT fee deduction is enabled |
| »» rebated_fee | string | Rebated fee |
| »» rebated_fee_currency | string | Rebated fee currency unit |
| »» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
| »» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy.2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter.3. If the user did not use stp_act when placing the order, stp_act will return '-'- cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled |
| »» finish_as | string | How the order was finished. - open: processing - filled: filled totally - cancelled: manually cancelled - ioc: time in force is IOC, finish immediately- stp: cancelled because self trade prevention |
| Property | Value |
|---|---|
| status | open |
| status | closed |
| status | cancelled |
| type | limit |
| type | market |
| side | buy |
| side | sell |
| time_in_force | gtc |
| time_in_force | ioc |
| time_in_force | poc |
| time_in_force | fok |
| stp_act | cn |
| stp_act | co |
| stp_act | cb |
| stp_act | - |
| finish_as | open |
| finish_as | filled |
| finish_as | cancelled |
| finish_as | ioc |
| finish_as | stp |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/cancel_batch_orders'
query_param = ''
body='[{"currency_pair":"BTC_USDT","id":"123456"}]'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /spot/cancel_batch_orders \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-gate-exptime: 1689560679123'
POST /spot/cancel_batch_orders
Cancel batch orders by specified ID list
Multiple currency pairs can be specified, but maximum 20 orders are allowed per request
Body parameter
[
{
"currency_pair": "BTC_USDT",
"id": "123456"
}
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | array[object] | true | none |
Example responses
200 Response
[
{
"currency_pair": "BTC_USDT",
"id": "123456",
"text": "123456",
"succeeded": true,
"label": null,
"message": null
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation completed | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » CancelOrderResult | object | Order cancellation result |
| »» currency_pair | string | Order currency pair |
| »» id | string | Order ID |
| »» text | string | Custom order information |
| »» succeeded | boolean | Whether cancellation succeeded |
| »» label | string | Error label when failed to cancel the order; emtpy if succeeded |
| »» message | string | Error description when cancellation fails, empty if successful |
| »» account | string | Default is empty (deprecated) |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/orders/12345'
query_param = 'currency_pair=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /spot/orders/12345?currency_pair=BTC_USDT \
-H 'Accept: application/json'
GET /spot/orders/{order_id}
Query single order details
By default, queries orders for spot, unified account, and isolated margin accounts.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | string | true | The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field). |
| currency_pair | query | string | true | Specify the trading pair to query. This field is required when querying pending order records. This field can be omitted when querying filled order records. |
| account | query | string | false | Specify query account |
order_id: The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field).
Operations based on custom IDs can only be checked in pending orders. Only order ID can be used after the order is finished (transaction/cancel)
Example responses
200 Response
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled",
"stop_profit": {
"trigger_price": "67000",
"order_price": "67000"
},
"stop_loss": {
"trigger_price": "63000",
"order_price": "63000"
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Detail retrieved | Inline |
Status Code 200
Spot order details
| Name | Type | Description |
|---|---|---|
| » id | string | Order ID |
| » text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders liquidate represents isolated-margin liquidation orders |
| » 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: closed order- cancelled: cancelled |
| » currency_pair | string | Currency pair |
| » type | string | Order Type - limit : Limit Order - market : Market Order |
| » account | string | Account type, spot - spot account, margin - leveraged account, unified - unified account |
| » side | string | Buy or sell order |
| » amount | string | Trade amount When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT.When type is market, the meaning depends on the side:- side: buy refers to the quote currency, e.g. USDT in BTC_USDT- side: sell refers to the base currency, e.g. BTC in BTC_USDT |
| » price | string | Trading price, required when type=limit |
| » time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market |
| » iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported |
| » auto_repay | boolean | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order |
| » left | string | Amount left to fill |
| » filled_amount | string | Amount filled |
| » fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total |
| » filled_total | string | Total filled in quote currency |
| » avg_deal_price | string | Average fill price |
| » fee | string | Fee deducted |
| » fee_currency | string | Fee currency unit |
| » point_fee | string | Points used to deduct fee |
| » gt_fee | string | GT used to deduct fee |
| » gt_maker_fee | string | GT amount used to deduct maker fee |
| » gt_taker_fee | string | GT amount used to deduct taker fee |
| » gt_discount | boolean | Whether GT fee deduction is enabled |
| » rebated_fee | string | Rebated fee |
| » rebated_fee_currency | string | Rebated fee currency unit |
| » stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
| » stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy.2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter.3. If the user did not use stp_act when placing the order, stp_act will return '-'- cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled |
| » finish_as | string | How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only / maker requirement not met (e.g. related TIF such as poc/rvt/rat/rpi would take liquidity as taker) - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown |
| » stop_profit | object | Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged. |
| »» trigger_price | string | Take profit trigger price When side == "buy", trigger_price must be greater than priceWhen side == "sell", trigger_price must be less than price |
| »» order_price | string | Take profit order price |
| » stop_loss | object | Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged. |
| »» trigger_price | string | Stop loss trigger price When side == "buy", trigger_price must be less than priceWhen side == "sell", trigger_price must be greater than price |
| »» order_price | string | Stop-loss order price |
| Property | Value |
|---|---|
| status | open |
| status | closed |
| status | cancelled |
| type | limit |
| type | market |
| side | buy |
| side | sell |
| time_in_force | gtc |
| time_in_force | ioc |
| time_in_force | poc |
| time_in_force | fok |
| stp_act | cn |
| stp_act | co |
| stp_act | cb |
| stp_act | - |
| finish_as | open |
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidate_cancelled |
| finish_as | depth_not_enough |
| finish_as | trader_not_enough |
| finish_as | small |
| finish_as | ioc |
| finish_as | poc |
| finish_as | fok |
| finish_as | stp |
| finish_as | price_protect_cancelled |
| finish_as | unknown |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/orders/12345'
query_param = ''
body='{"currency_pair":"BTC_USDT","account":"spot","amount":"1","stop_profit":{"trigger_price":"67000","order_price":"67000"},"stop_loss":{"trigger_price":"63000","order_price":"63000"}}'
r = requests.request('PATCH', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X PATCH /spot/orders/12345 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-gate-exptime: 1689560679123'
PATCH /spot/orders/{order_id}
Amend single order
Modify orders in spot, unified account and isolated margin account by default.
Currently both request body and query support currency_pair and account parameters, but request body has higher priority.
currency_pair must be filled in one of the request body or query parameters.
About rate limit: Order modification and order creation share the same rate limit rules.
About matching priority: Only reducing the quantity does not affect the matching priority. Modifying the price or increasing the quantity will adjust the priority to the end of the new price level.
Note: Modifying the quantity to be less than the filled quantity will trigger a cancellation and isolated margin account by default.
Currently both request body and query support currency_pair and account parameters, but request body has higher priority.
currency_pair must be filled in one of the request body or query parameters.
About rate limit: Order modification and order creation share the same rate limit rules.
About matching priority: Only reducing the quantity does not affect the matching priority. Modifying the price or increasing the quantity will adjust the priority to the end of the new price level.
Note: Modifying the quantity to be less than the filled quantity will trigger a cancellation operation.
Body parameter
{
"currency_pair": "BTC_USDT",
"account": "spot",
"amount": "1",
"stop_profit": {
"trigger_price": "67000",
"order_price": "67000"
},
"stop_loss": {
"trigger_price": "63000",
"order_price": "63000"
}
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | string | true | The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field). |
| currency_pair | query | string | false | Currency pair |
| account | query | string | false | Specify query account |
| x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | object | true | none |
| » currency_pair | body | string | false | Currency pair |
| » account | body | string | false | Specify query account |
| » amount | body | string | false | Trading quantity. Either amount or price must be specified |
| » price | body | string | false | Trading price. Either amount or price must be specified |
| » amend_text | body | string | false | Custom info during order amendment |
| » action_mode | body | string | false | Processing Mode: |
| » stop_profit | body | object | false | Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged. |
| »» trigger_price | body | string | false | Take profit trigger price |
| »» order_price | body | string | false | Take profit order price |
| » stop_loss | body | object | false | Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged. |
| »» trigger_price | body | string | false | Stop loss trigger price |
| »» order_price | body | string | false | Stop-loss order price |
order_id: The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field).
Operations based on custom IDs can only be checked in pending orders. Only order ID can be used after the order is finished (transaction/cancel)
» action_mode: Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)
»» trigger_price: Take profit trigger price
When side == "buy", trigger_price must be greater than price
When side == "sell", trigger_price must be less than price
»» trigger_price: Stop loss trigger price
When side == "buy", trigger_price must be less than price
When side == "sell", trigger_price must be greater than price
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",
"stop_profit": {
"trigger_price": "67000",
"order_price": "67000"
},
"stop_loss": {
"trigger_price": "63000",
"order_price": "63000"
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Updated successfully | Inline |
Status Code 200
Spot order details
| Name | Type | Description |
|---|---|---|
| » id | string | Order ID |
| » text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders liquidate represents isolated-margin liquidation orders |
| » 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: closed order- cancelled: cancelled |
| » currency_pair | string | Currency pair |
| » type | string | Order Type - limit : Limit Order - market : Market Order |
| » account | string | Account type, spot - spot account, margin - leveraged account, unified - unified account |
| » side | string | Buy or sell order |
| » amount | string | Trade amount When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT.When type is market, the meaning depends on the side:- side: buy refers to the quote currency, e.g. USDT in BTC_USDT- side: sell refers to the base currency, e.g. BTC in BTC_USDT |
| » price | string | Trading price, required when type=limit |
| » time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market |
| » iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported |
| » auto_repay | boolean | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order |
| » left | string | Amount left to fill |
| » filled_amount | string | Amount filled |
| » fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total |
| » filled_total | string | Total filled in quote currency |
| » avg_deal_price | string | Average fill price |
| » fee | string | Fee deducted |
| » fee_currency | string | Fee currency unit |
| » point_fee | string | Points used to deduct fee |
| » gt_fee | string | GT used to deduct fee |
| » gt_maker_fee | string | GT amount used to deduct maker fee |
| » gt_taker_fee | string | GT amount used to deduct taker fee |
| » gt_discount | boolean | Whether GT fee deduction is enabled |
| » rebated_fee | string | Rebated fee |
| » rebated_fee_currency | string | Rebated fee currency unit |
| » stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
| » stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy.2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter.3. If the user did not use stp_act when placing the order, stp_act will return '-'- cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled |
| » finish_as | string | How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only / maker requirement not met (e.g. related TIF such as poc/rvt/rat/rpi would take liquidity as taker) - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown |
| » stop_profit | object | Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged. |
| »» trigger_price | string | Take profit trigger price When side == "buy", trigger_price must be greater than priceWhen side == "sell", trigger_price must be less than price |
| »» order_price | string | Take profit order price |
| » stop_loss | object | Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged. |
| »» trigger_price | string | Stop loss trigger price When side == "buy", trigger_price must be less than priceWhen side == "sell", trigger_price must be greater than price |
| »» order_price | string | Stop-loss order price |
| Property | Value |
|---|---|
| status | open |
| status | closed |
| status | cancelled |
| type | limit |
| type | market |
| side | buy |
| side | sell |
| time_in_force | gtc |
| time_in_force | ioc |
| time_in_force | poc |
| time_in_force | fok |
| stp_act | cn |
| stp_act | co |
| stp_act | cb |
| stp_act | - |
| finish_as | open |
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidate_cancelled |
| finish_as | depth_not_enough |
| finish_as | trader_not_enough |
| finish_as | small |
| finish_as | ioc |
| finish_as | poc |
| finish_as | fok |
| finish_as | stp |
| finish_as | price_protect_cancelled |
| finish_as | unknown |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/orders/12345'
query_param = 'currency_pair=BTC_USDT'
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X DELETE /spot/orders/12345?currency_pair=BTC_USDT \
-H 'Accept: application/json' \
-H 'x-gate-exptime: 1689560679123'
DELETE /spot/orders/{order_id}
Cancel single order
By default, orders for spot, unified accounts and leveraged accounts are revoked.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| order_id | path | string | true | The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field). |
| currency_pair | query | string | true | Currency pair |
| account | query | string | false | Specify query account |
| action_mode | query | string | false | Processing Mode |
| x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
order_id: The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field).
Operations based on custom IDs can only be checked in pending orders. Only order ID can be used after the order is finished (transaction/cancel)
action_mode: Processing Mode
When placing an order, different fields are returned based on the action_mode
ACK: Asynchronous mode, returns only key order fieldsRESULT: No clearing informationFULL: Full mode (default)Example responses
200 Response
{
"id": "1852454420",
"text": "t-abc123",
"amend_text": "-",
"create_time": "1710488334",
"update_time": "1710488334",
"create_time_ms": 1710488334073,
"update_time_ms": 1710488334074,
"status": "closed",
"currency_pair": "BTC_USDT",
"type": "limit",
"account": "unified",
"side": "buy",
"amount": "0.001",
"price": "65000",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0",
"filled_amount": "0.001",
"fill_price": "63.4693",
"filled_total": "63.4693",
"avg_deal_price": "63469.3",
"fee": "0.00000022",
"fee_currency": "BTC",
"point_fee": "0",
"gt_fee": "0",
"gt_maker_fee": "0",
"gt_taker_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "USDT",
"finish_as": "filled",
"stop_profit": {
"trigger_price": "67000",
"order_price": "67000"
},
"stop_loss": {
"trigger_price": "63000",
"order_price": "63000"
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order cancelled | Inline |
Status Code 200
Spot order details
| Name | Type | Description |
|---|---|---|
| » id | string | Order ID |
| » text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders liquidate represents isolated-margin liquidation orders |
| » 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: closed order- cancelled: cancelled |
| » currency_pair | string | Currency pair |
| » type | string | Order Type - limit : Limit Order - market : Market Order |
| » account | string | Account type, spot - spot account, margin - leveraged account, unified - unified account |
| » side | string | Buy or sell order |
| » amount | string | Trade amount When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT.When type is market, the meaning depends on the side:- side: buy refers to the quote currency, e.g. USDT in BTC_USDT- side: sell refers to the base currency, e.g. BTC in BTC_USDT |
| » price | string | Trading price, required when type=limit |
| » time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market |
| » iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported |
| » auto_repay | boolean | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order |
| » left | string | Amount left to fill |
| » filled_amount | string | Amount filled |
| » fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total |
| » filled_total | string | Total filled in quote currency |
| » avg_deal_price | string | Average fill price |
| » fee | string | Fee deducted |
| » fee_currency | string | Fee currency unit |
| » point_fee | string | Points used to deduct fee |
| » gt_fee | string | GT used to deduct fee |
| » gt_maker_fee | string | GT amount used to deduct maker fee |
| » gt_taker_fee | string | GT amount used to deduct taker fee |
| » gt_discount | boolean | Whether GT fee deduction is enabled |
| » rebated_fee | string | Rebated fee |
| » rebated_fee_currency | string | Rebated fee currency unit |
| » stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
| » stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy.2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter.3. If the user did not use stp_act when placing the order, stp_act will return '-'- cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled |
| » finish_as | string | How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only / maker requirement not met (e.g. related TIF such as poc/rvt/rat/rpi would take liquidity as taker) - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown |
| » stop_profit | object | Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged. |
| »» trigger_price | string | Take profit trigger price When side == "buy", trigger_price must be greater than priceWhen side == "sell", trigger_price must be less than price |
| »» order_price | string | Take profit order price |
| » stop_loss | object | Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged. |
| »» trigger_price | string | Stop loss trigger price When side == "buy", trigger_price must be less than priceWhen side == "sell", trigger_price must be greater than price |
| »» order_price | string | Stop-loss order price |
| Property | Value |
|---|---|
| status | open |
| status | closed |
| status | cancelled |
| type | limit |
| type | market |
| side | buy |
| side | sell |
| time_in_force | gtc |
| time_in_force | ioc |
| time_in_force | poc |
| time_in_force | fok |
| stp_act | cn |
| stp_act | co |
| stp_act | cb |
| stp_act | - |
| finish_as | open |
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidate_cancelled |
| finish_as | depth_not_enough |
| finish_as | trader_not_enough |
| finish_as | small |
| finish_as | ioc |
| finish_as | poc |
| finish_as | fok |
| finish_as | stp |
| finish_as | price_protect_cancelled |
| finish_as | unknown |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/my_trades'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /spot/my_trades \
-H 'Accept: application/json'
GET /spot/my_trades
Query personal trading records
By default query of transaction records for spot, unified account and warehouse-by-site leverage accounts.
The history within a specified time range can be queried by specifying from or (and) to.
from or to is specified, only 7-day data from the start (or end) of the specified time is returned.The parameters of the time range filter are processed according to the order end time.
The maximum number of pages when searching data using limit&page paging function is 100,000, that is, limit * (page - 1) <= 100,000.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Retrieve results with specified currency pair |
| limit | query | integer | false | Maximum number of items returned in list. Default: 100, minimum: 1, maximum: 1000 |
| page | query | integer(int32) | false | Page number |
| order_id | query | string | false | Filter trades with specified order ID. currency_pair is also required if this field is present |
| account | query | string | false | The accountparameter has been deprecated. The interface supports querying all transaction records of the account. |
| from | query | integer(int64) | false | Start timestamp for the query |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
Example responses
200 Response
[
{
"id": "1232893232",
"create_time": "1548000000",
"create_time_ms": "1548000000123.456",
"order_id": "4128442423",
"side": "buy",
"role": "maker",
"amount": "0.15",
"price": "0.03",
"fee": "0.0005",
"fee_currency": "ETH",
"point_fee": "0",
"gt_fee": "0",
"sequence_id": "588018",
"text": "t-test",
"deal": "0.0045"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | string | Fill ID |
| » create_time | string | Fill Time |
| » create_time_ms | string | Trading time, with millisecond precision |
| » currency_pair | string | Currency pair |
| » side | string | Buy or sell order |
| » role | string | Trade role, not returned in public endpoints |
| » amount | string | Trade amount |
| » price | string | Order price |
| » order_id | string | Related order ID, not returned in public endpoints |
| » fee | string | Fee deducted, not returned in public endpoints |
| » fee_currency | string | Fee currency unit, not returned in public endpoints |
| » point_fee | string | Points used to deduct fee, not returned in public endpoints |
| » gt_fee | string | GT used to deduct fee, not returned in public endpoints |
| » amend_text | string | The custom data that the user remarked when amending the order |
| » sequence_id | string | Consecutive trade ID within a single market. Used to track and identify trades in the specific market |
| » text | string | Order's Custom Information. This field is not returned by public interfaces. The scenarios pm_liquidate, comb_margin_liquidate, and scm_liquidate represent full-account forced liquidation orders. liquidate represents isolated-account forced liquidation orders. |
| » deal | string | Total Executed Value |
| Property | Value |
|---|---|
| side | buy |
| side | sell |
| role | taker |
| role | maker |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /spot/time \
-H 'Accept: application/json'
GET /spot/time
Get server current time
Example responses
200 Response
{
"server_time": 1597026383085
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | SystemTime |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/countdown_cancel_all'
query_param = ''
body='{"timeout":30,"currency_pair":"BTC_USDT"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /spot/countdown_cancel_all \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /spot/countdown_cancel_all
Countdown cancel orders
Spot order heartbeat detection. If there is no "cancel existing countdown" or "set new countdown" when the user-set timeout time is reached, the related spot pending orders will be automatically cancelled.
This interface can be called repeatedly to set a new countdown or cancel the countdown.
Usage example: Repeat this interface at 30s intervals, setting the countdown timeout to 30 (seconds) each time.
If this interface is not called again within 30 seconds, all pending orders on the market you specified will be automatically cancelled. If no market is specified, all market cancelled.
If the timeout is set to 0 within 30 seconds, the countdown timer will be terminated and the automatic order cancellation function will be cancelled.
Body parameter
{
"timeout": 30,
"currency_pair": "BTC_USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | CountdownCancelAllSpotTask | true | none |
| » timeout | body | integer(int32) | true | Countdown time in seconds |
| » currency_pair | body | string | false | Currency pair |
» timeout: Countdown time in seconds At least 5 seconds, 0 means cancel countdown
Example responses
200 Response
{
"triggerTime": "1660039145000"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Countdown set successfully | TriggerTime |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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","stop_profit":{"trigger_price":"67000","order_price":"67000"},"stop_loss":{"trigger_price":"63000","order_price":"63000"}}]'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /spot/amend_batch_orders \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-gate-exptime: 1689560679123'
POST /spot/amend_batch_orders
Batch modification of orders
Modify orders in spot, unified account and isolated margin account by default. Modify uncompleted orders, up to 5 orders can be modified at a time. Request parameters should be passed in array format. If there are order modification failures during the batch modification process, the modification of the next order will continue to be executed, and the execution will return with the corresponding order failure information. The call order of batch modification orders is consistent with the order list order. The return content order of batch modification orders is consistent with the order list order.
Body parameter
[
{
"order_id": "121212",
"currency_pair": "BTC_USDT",
"account": "spot",
"amount": "1",
"amend_text": "test",
"stop_profit": {
"trigger_price": "67000",
"order_price": "67000"
},
"stop_loss": {
"trigger_price": "63000",
"order_price": "63000"
}
}
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | array[object] | true | none |
Example responses
200 Response
[
{
"order_id": "12332324",
"amend_text": "t-123456",
"text": "t-123456",
"succeeded": true,
"label": "",
"message": "",
"id": "12332324",
"create_time": "1548000000",
"update_time": "1548000100",
"create_time_ms": 1548000000123,
"update_time_ms": 1548000100123,
"currency_pair": "ETC_BTC",
"status": "cancelled",
"type": "limit",
"account": "spot",
"side": "buy",
"amount": "1",
"price": "5.00032",
"time_in_force": "gtc",
"iceberg": "0",
"left": "0.5",
"filled_amount": "1.242",
"filled_total": "2.50016",
"avg_deal_price": "5.00032",
"fee": "0.005",
"fee_currency": "ETH",
"point_fee": "0",
"gt_fee": "0",
"gt_discount": false,
"rebated_fee": "0",
"rebated_fee_currency": "BTC",
"stp_act": "cn",
"finish_as": "stp",
"stp_id": 10240
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order modification executed successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Batch order details] |
| » None | object | Batch order details |
| »» order_id | string | Order ID |
| »» amend_text | string | The custom data that the user remarked when amending the order |
| »» text | string | Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: 1. Must start with t-2. Excluding t-, length cannot exceed 28 bytes3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.) |
| »» succeeded | boolean | Request execution result |
| »» label | string | Error label, if any, otherwise an empty string |
| »» message | string | Detailed error message, if any, otherwise an empty string |
| »» id | string | Order ID |
| »» create_time | string | Creation time of order |
| »» update_time | string | Last modification time of order |
| »» create_time_ms | integer(int64) | Creation time of order (in milliseconds) |
| »» update_time_ms | integer(int64) | Last modification time of order (in milliseconds) |
| »» status | string | Order status - open: to be filled- closed: closed order- cancelled: cancelled |
| »» currency_pair | string | Currency pair |
| »» type | string | Order Type - limit : Limit Order - market : Market Order |
| »» account | string | Account type, spot - spot account, margin - leveraged account, unified - unified account |
| »» side | string | Buy or sell order |
| »» amount | string | Trade amount |
| »» price | string | Order price |
| »» time_in_force | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none |
| »» iceberg | string | Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported |
| »» auto_repay | boolean | Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order |
| »» left | string | Amount left to fill |
| »» filled_amount | string | Amount filled |
| »» fill_price | string | Total filled in quote currency. Deprecated in favor of filled_total |
| »» filled_total | string | Total filled in quote currency |
| »» avg_deal_price | string | Average fill price |
| »» fee | string | Fee deducted |
| »» fee_currency | string | Fee currency unit |
| »» point_fee | string | Points used to deduct fee |
| »» gt_fee | string | GT used to deduct fee |
| »» gt_discount | boolean | Whether GT fee deduction is enabled |
| »» rebated_fee | string | Rebated fee |
| »» rebated_fee_currency | string | Rebated fee currency unit |
| »» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
| »» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group, he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy。2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter。3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled |
| »» finish_as | string | How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only / maker requirement not met (e.g. related TIF such as poc/rvt/rat/rpi would take liquidity as taker) - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown |
| »» stop_profit | object | Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged. |
| »»» trigger_price | string | Take profit trigger price When side == "buy", trigger_price must be greater than priceWhen side == "sell", trigger_price must be less than price |
| »»» order_price | string | Take profit order price |
| »» stop_loss | object | Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged. |
| »»» trigger_price | string | Stop loss trigger price When side == "buy", trigger_price must be less than priceWhen side == "sell", trigger_price must be greater than price |
| »»» order_price | string | Stop-loss order price |
| 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 | liquidate_cancelled |
| finish_as | depth_not_enough |
| finish_as | trader_not_enough |
| finish_as | small |
| finish_as | ioc |
| finish_as | poc |
| finish_as | fok |
| finish_as | stp |
| finish_as | price_protect_cancelled |
| finish_as | unknown |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/spot/insurance_history'
query_param = 'business=margin¤cy=BTC&from=1547706332&to=1547706332'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /spot/insurance_history?business=margin¤cy=BTC&from=1547706332&to=1547706332 \
-H 'Accept: application/json'
GET /spot/insurance_history
Query spot insurance fund historical data
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| business | query | string | true | Leverage business, margin - position by position; unified - unified account |
| currency | query | string | true | Currency |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | The maximum number of items returned in the list, the default value is 30 |
| from | query | integer(int64) | true | Start timestamp in seconds |
| to | query | integer(int64) | true | End timestamp in seconds |
Example responses
200 Response
[
{
"currency": "BTC",
"balance": "1021.21",
"time": 1727054547
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency |
| » balance | string | Balance |
| » time | integer(int64) | Creation time, timestamp, milliseconds |
Withdrawal API
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /withdrawals \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /withdrawals
Withdraw
If the recipient's on-chain address is also Gate, no transaction fee will be charged
Body parameter
{
"withdraw_order_id": "order_123456",
"currency": "USDT",
"address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
"amount": "222.61",
"memo": "",
"chain": "TRX"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » withdraw_order_id | body | string | false | User-defined order number for withdrawal. Default is empty. When not empty, the specified user-defined order number record will be queried |
| » amount | body | string | true | Token amount |
| » currency | body | string | true | Currency name |
| » address | body | string | false | Withdrawal address. Required for withdrawals |
| » memo | body | string | false | Additional remarks with regards to the withdrawal |
| » withdraw_id | body | string | false | Withdrawal record ID starts with 'w', such as: w1879219868. When withdraw_id is not empty, only this specific withdrawal record will be queried, and time-based querying will be disabled |
| » asset_class | body | string | false | Withdrawal record currency type, empty by default. Supports users to query withdrawal records in main area and innovation area on demand. |
| » chain | body | string | true | Name of the chain used in withdrawals |
» asset_class: Withdrawal record currency type, empty by default. Supports users to query withdrawal records in main area and innovation area on demand. Valid values: SPOT, PILOT
SPOT: Main area PILOT: Innovation area
Example responses
200 Response
{
"id": "210496",
"timestamp": "1542000000",
"withdraw_order_id": "order_123456",
"currency": "USDT",
"address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
"txid": "128988928203223323290",
"amount": "222.61",
"memo": "",
"status": "DONE",
"chain": "TRX"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Withdrawal request accepted. Check withdrawal record status for processing result | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | string | Record ID |
| » txid | string | Hash record of the withdrawal |
| » withdraw_order_id | string | User-defined order number for withdrawal. Default is empty. When not empty, the specified user-defined order number record will be queried |
| » timestamp | string | Operation time |
| » amount | string | Token amount |
| » currency | string | Currency name |
| » address | string | Withdrawal address. Required for withdrawals |
| » memo | string | Additional remarks with regards to the withdrawal |
| » withdraw_id | string | Withdrawal record ID starts with 'w', such as: w1879219868. When withdraw_id is not empty, only this specific withdrawal record will be queried, and time-based querying will be disabled |
| » asset_class | string | Withdrawal record currency type, empty by default. Supports users to query withdrawal records in main area and innovation area on demand. Valid values: SPOT, PILOT SPOT: Main area PILOT: Innovation area |
| » status | string | Transaction status - DONE: Completed - CANCEL: Cancelled - REQUEST: Requesting - MANUAL: Pending manual review - BCODE: GateCode operation - EXTPEND: Sent, waiting for confirmation - FAIL: Failed on chain, waiting for confirmation - INVALID: Invalid order - VERIFY: Verifying - PROCES: Processing - PEND: Processing - DMOVE: Pending manual review - REVIEW: Under review |
| » chain | string | Name of the chain used in withdrawals |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/withdrawals/push'
query_param = ''
body='{"receive_uid":12233,"currency":"USDT","amount":"1.1"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /withdrawals/push \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /withdrawals/push
UID transfer
Transfers between main spot accounts. Both parties cannot be sub-accounts
Body parameter
{
"receive_uid": 12233,
"currency": "USDT",
"amount": "1.1"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » receive_uid | body | integer(int64) | true | Recipient UID |
| » currency | body | string | true | Currency name |
| » amount | body | string | true | Transfer amount |
Example responses
200 Response
{
"id": "111"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request accepted. Check withdrawal record status for processing result | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | string | Order ID |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/withdrawals/210496'
query_param = ''
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
curl -X DELETE /withdrawals/210496 \
-H 'Accept: application/json'
DELETE /withdrawals/{withdrawal_id}
Cancel withdrawal with specified ID
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| withdrawal_id | path | string | true | none |
Example responses
202 Response
{
"id": "210496",
"timestamp": "1542000000",
"currency": "USDT",
"address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
"txid": "128988928203223323290",
"amount": "222.61",
"memo": "",
"block_number": "18217349",
"status": "DONE",
"chain": "TRX"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 202 | Accepted (opens new window) | Cancellation request accepted. Check record status for cancellation result | Inline |
Status Code 202
| Name | Type | Description |
|---|---|---|
| » id | string | Record ID |
| » txid | string | Hash record of the withdrawal |
| » timestamp | string | Operation time |
| » amount | string | Token amount |
| » currency | string | Currency name |
| » address | string | Withdrawal address. Required for withdrawals |
| » memo | string | Additional remarks with regards to the withdrawal |
| » block_number | string | Block Number |
| » status | string | Transaction Status - BCODE: Deposit Code Operation - CANCEL: Cancelled - CANCELPEND: Withdrawal Cancellation Pending - DMOVE: Pending Manual Review - DONE: Completed (Only considered truly on-chain when block_number > 0) - EXTPEND: Sent and Waiting for Confirmation - FAIL: On-Chain Failure Pending Confirmation - FVERIFY: Facial Verification in Progress - LOCKED: Wallet-Side Order Locked - MANUAL: Pending Manual Review - REJECT: Rejected - REQUEST: Request in Progress - REVIEW: Under Review |
| » chain | string | Name of the chain used in withdrawals |
Wallet API
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /wallet/currency_chains?currency=GT \
-H 'Accept: application/json'
GET /wallet/currency_chains
Query chains supported for specified currency
API operations are not supported for tokens with low liquidity or extremely low value. Please use the Web or App interface to query and process.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Currency name |
Example responses
200 Response
[
{
"chain": "ETH",
"name_cn": "以太坊ERC20",
"name_en": "ETH/ERC20",
"contract_address": "",
"is_disabled": 0,
"is_deposit_disabled": 0,
"is_withdraw_disabled": 0,
"is_tag": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » chain | string | Chain name |
| » name_cn | string | Chain name in Chinese |
| » name_en | string | Chain name in English |
| » contract_address | string | Smart contract address for the currency; if no address is available, it will be an empty string |
| » is_disabled | integer(int32) | If it is disabled. 0 means NOT being disabled |
| » is_deposit_disabled | integer(int32) | Is deposit disabled. 0 means not disabled |
| » is_withdraw_disabled | integer(int32) | Is withdrawal disabled. 0 means not disabled |
| » decimal | string | Withdrawal precision |
| » is_tag | integer | Whether to Include Tag |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/deposit_address'
query_param = 'currency=USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /wallet/deposit_address?currency=USDT \
-H 'Accept: application/json'
GET /wallet/deposit_address
Generate currency deposit address
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Currency name |
Example responses
200 Response
{
"currency": "USDT",
"address": "LPXtk1kWHioP62SzfqwKbYE3Z7Wt2ujYEc",
"multichain_addresses": [
{
"chain": "TRX",
"address": "LPXtk1kWHioP62SzfqwKbYE3Z7Wt2ujYEc",
"payment_id": "",
"payment_name": "",
"obtain_failed": 0,
"min_confirms": 1
}
],
"min_deposit_amount": "0.000006"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Address successfully generated | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency detail |
| » address | string | Deposit address |
| » min_deposit_amount | string | Minimum Deposit Amount |
| » multichain_addresses | array | none |
| »» MultiChainAddressItem | object | none |
| »»» chain | string | Name of the chain |
| »»» address | string | Deposit address |
| »»» payment_id | string | Notes that some currencies required(e.g., Tag, Memo) when depositing |
| »»» payment_name | string | Note type, Tag or Memo |
| »»» obtain_failed | integer | The obtain failed status- 0: address successfully obtained- 1: failed to obtain address |
| »»» min_confirms | integer | Minimum Confirmation Count |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/withdrawals'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /wallet/withdrawals \
-H 'Accept: application/json'
GET /wallet/withdrawals
Get withdrawal records
Record query time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Specify the currency. If not specified, returns all currencies |
| withdraw_id | query | string | false | Withdrawal record ID starts with 'w', such as: w1879219868. When withdraw_id is not empty, only this specific withdrawal record will be queried, and time-based querying will be disabled |
| asset_class | query | string | false | Currency type of withdrawal record, empty by default. Supports querying withdrawal records in main zone and innovation zone on demand. |
| withdraw_order_id | query | string | false | User-defined order number for withdrawal. Default is empty. When not empty, the specified user-defined order number record will be queried |
| from | query | integer(int64) | false | Start time for querying records. If not specified, defaults to 7 days before current time |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
asset_class: Currency type of withdrawal record, empty by default. Supports querying withdrawal records in main zone and innovation zone on demand. Value range: SPOT, PILOT
SPOT: Main Zone PILOT: Innovation Zone
Example responses
200 Response
[
[
{
"id": "w1879219868",
"currency": "USDT",
"address": "THISISTESTADDRESSFORGATEPAY",
"amount": "4.023",
"fee": "0",
"txid": "Internal transaction 260594131",
"chain": "BSC",
"timestamp": "1745220149",
"status": "DONE",
"withdraw_order_id": "202504211521368538928",
"block_number": "1000",
"fail_reason": "",
"type": "appbankgp",
"timestamp2": "1745220149",
"memo": ""
}
]
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | string | Record ID |
| » txid | string | Hash record of the withdrawal |
| » block_number | string | Block Number |
| » withdraw_order_id | string | Client order id, up to 32 length and can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) |
| » timestamp | string | Operation time |
| » amount | string | Token amount |
| » fee | string | fee |
| » currency | string | Currency name |
| » address | string | Withdrawal address |
| » type | string | Business Type |
| » fail_reason | string | Reason for withdrawal failure. Has a value when status = CANCEL, empty for all other statuses |
| » timestamp2 | string | Withdrawal final time, i.e.: withdrawal cancellation time or withdrawal success time When status = CANCEL, corresponds to cancellation time When status = DONE, it is the withdrawal success time |
| » memo | string | Additional remarks with regards to the withdrawal |
| » status | string | Transaction Status - BCODE: Deposit Code Operation - CANCEL: Cancelled - CANCELPEND: Withdrawal Cancellation Pending - DONE: Completed - EXTPEND: Sent and Waiting for Confirmation - FAIL: On-Chain Failure Pending Confirmation - FVERIFY: Facial Verification in Progress - LOCKED: Wallet-Side Order Locked - MANUAL: Pending Manual Review - REJECT: Rejected - REQUEST: Request in Progress - REVIEW: Under Review |
| » chain | string | Name of the chain used in withdrawals |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/deposits'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /wallet/deposits \
-H 'Accept: application/json'
GET /wallet/deposits
Get deposit records
Record query time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Specify the currency. If not specified, returns all currencies |
| from | query | integer(int64) | false | Start time for querying records. If not specified, defaults to 7 days before current time |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| limit | query | integer | false | Maximum number of entries returned in the list, limited to 500 transactions |
| offset | query | integer | false | List offset, starting from 0 |
Example responses
200 Response
[
{
"id": "210496",
"timestamp": "1542000000",
"currency": "USDT",
"address": "1HkxtBAMrA3tP5ENnYY2CZortjZvFDH5Cs",
"txid": "128988928203223323290",
"amount": "222.61",
"memo": "",
"status": "DONE",
"chain": "TRX"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | string | Record ID |
| » txid | string | Hash record of the withdrawal |
| » timestamp | string | Operation time |
| » amount | string | Token amount |
| » currency | string | Currency name |
| » address | string | Withdrawal address. Required for withdrawals |
| » memo | string | Additional remarks with regards to the withdrawal |
| » status | string | Transaction Status - BLOCKED: Deposit Blocked - DEP_CREDITED: Deposit Credited, Withdrawal Pending Unlock - DONE: Funds Credited to Spot Account - INVALID: Invalid Transaction - MANUAL: Manual Review Required - PEND: Processing - REVIEW: Under Compliance Review - TRACK: Tracking Block Confirmations, Pending Spot Account Credit |
| » chain | string | Name of the chain used in withdrawals |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/transfers'
query_param = ''
body='{"currency":"BTC","from":"spot","to":"margin","amount":"1","currency_pair":"BTC_USDT","settle":""}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /wallet/transfers \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /wallet/transfers
Transfer between trading accounts
Balance transfers between personal trading accounts. Currently supports the following transfer operations:
Body parameter
{
"currency": "BTC",
"from": "spot",
"to": "margin",
"amount": "1",
"currency_pair": "BTC_USDT",
"settle": ""
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Transfer currency name. For contract accounts, currency can be set to POINT (points) or supported settlement currencies (e.g., BTC, USDT) |
| » from | body | string | true | Account to transfer from |
| » to | body | string | true | Account to transfer to |
| » amount | body | string | true | Transfer Amount, supports up to 8 decimal places, must be greater than 0 |
| » currency_pair | body | string | false | Margin trading pair. Required when transferring to or from margin account |
| » settle | body | string | false | Contract settlement currency. Required when transferring to or from contract account |
| Parameter | Value |
|---|---|
| » from | spot |
| » from | margin |
| » from | futures |
| » from | delivery |
| » from | options |
| » to | spot |
| » to | margin |
| » to | futures |
| » to | delivery |
| » to | options |
Example responses
200 Response
{
"tx_id": 59636381286
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Transfer operation successful | TransactionID |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/sub_account_transfers'
query_param = ''
body='{"sub_account":"10002","sub_account_type":"spot","currency":"BTC","amount":"1","direction":"to","client_order_id":"da3ce7a088c8b0372b741419c7829033"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /wallet/sub_account_transfers \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /wallet/sub_account_transfers
Transfer between main and sub accounts
Supports transfers to/from sub-account's spot or futures accounts. Note that regardless of which sub-account is operated, only the main account's spot account is used
Body parameter
{
"sub_account": "10002",
"sub_account_type": "spot",
"currency": "BTC",
"amount": "1",
"direction": "to",
"client_order_id": "da3ce7a088c8b0372b741419c7829033"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » sub_account | body | string | true | Sub account user ID |
| » sub_account_type | body | string | false | Target sub-account trading account: spot - spot account, futures - perpetual contract account, delivery - delivery contract account, options - options account |
| » currency | body | string | true | Transfer currency name |
| » amount | body | string | true | Transfer Amount, supports up to 8 decimal places, must be greater than 0 |
| » direction | body | string | true | Transfer direction: to - transfer into sub-account, from - transfer out from sub-account |
| » client_order_id | body | string | false | Customer-defined ID to prevent duplicate transfers. Can be a combination of letters (case-sensitive), numbers, hyphens '-', and underscores '_'. Can be pure letters or pure numbers with length between 1-64 characters |
Example responses
200 Response
{
"tx_id": 59636381286
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Transfer operation successful | TransactionID |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/sub_account_transfers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /wallet/sub_account_transfers \
-H 'Accept: application/json'
GET /wallet/sub_account_transfers
Get transfer records between main and sub accounts
Record query time range cannot exceed 30 days
Note: Only records after 2020-04-10 can be retrieved
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sub_uid | query | string | false | Sub-account user ID, you can query multiple records separated by ,. If not specified, it will return records of all sub-accounts |
| from | query | integer(int64) | false | Start time for querying records. If not specified, defaults to 7 days before current time |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
Example responses
200 Response
[
{
"timest": "1592809000",
"uid": "10001",
"sub_account": "10002",
"sub_account_type": "spot",
"currency": "BTC",
"amount": "1",
"direction": "to",
"source": "web",
"client_order_id": "da3ce7a088c8b0372b741419c7829033",
"status": "success"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » timest | string | Transfer timestamp |
| » uid | string | Main account user ID |
| » sub_account | string | Sub account user ID |
| » sub_account_type | string | Target sub-account trading account: spot - spot account, futures - perpetual contract account, delivery - delivery contract account, options - options account |
| » currency | string | Transfer currency name |
| » amount | string | Transfer Amount |
| » direction | string | Transfer direction: to - transfer into sub-account, from - transfer out from sub-account |
| » source | string | Source of the transfer operation |
| » client_order_id | string | Customer-defined ID to prevent duplicate transfers. Can be a combination of letters (case-sensitive), numbers, hyphens '-', and underscores '_'. Can be pure letters or pure numbers with length between 1-64 characters |
| » status | string | Sub-account transfer record status, currently only 'success' |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /wallet/sub_account_to_sub_account \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /wallet/sub_account_to_sub_account
Transfer between sub-accounts
Supports balance transfers between two sub-accounts under the same main account. You can use either the main account's API Key or the source sub-account's API Key to perform the operation
Body parameter
{
"currency": "usdt",
"sub_account_from": "10001",
"sub_account_from_type": "spot",
"sub_account_to": "10002",
"sub_account_to_type": "spot",
"amount": "1"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Transfer currency name |
| » sub_account_type | body | string | false | Transfer from account (deprecated, use sub_account_from_type and sub_account_to_type instead) |
| » sub_account_from | body | string | true | Transfer from the user id of the sub-account |
| » sub_account_from_type | body | string | true | Source sub-account trading account: spot - spot account, futures - perpetual contract account, delivery - delivery contract account |
| » sub_account_to | body | string | true | Transfer to the user id of the sub-account |
| » sub_account_to_type | body | string | true | Target sub-account trading account: spot - spot account, futures - perpetual contract account, delivery - delivery contract account |
| » amount | body | string | true | Transfer Amount, supports up to 8 decimal places, must be greater than 0 |
Example responses
200 Response
{
"tx_id": 59636381286
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Transfer operation successful | TransactionID |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/order_status'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /wallet/order_status \
-H 'Accept: application/json'
GET /wallet/order_status
Main-Sub Account Transfer Status Query
Supports querying Main-Sub Account Transfer Status based on user-defined client_order_id or tx_id returned by the transfer interface
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| client_order_id | query | string | false | Customer-defined ID to prevent duplicate transfers. Can be a combination of letters (case-sensitive), numbers, hyphens '-', and underscores '_'. Can be pure letters or pure numbers with length between 1-64 characters |
| tx_id | query | string | false | Transfer operation number, cannot be empty at the same time as client_order_id |
Example responses
200 Response
{
"tx_id": "59636381286",
"status": "SUCCESS"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Main-Sub Account Transfer Status Retrieval Successful | TransferOrderStatus |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/withdraw_status'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /wallet/withdraw_status \
-H 'Accept: application/json'
GET /wallet/withdraw_status
Query withdrawal status
API operations are not supported for tokens with low liquidity or extremely low value. Please use the Web or App interface to query and process.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
Example responses
200 Response
[
{
"currency": "GT",
"name": "GateToken",
"name_cn": "GateToken",
"deposit": "0",
"withdraw_percent": "0%",
"withdraw_fix": "0.01",
"withdraw_day_limit": "20000",
"withdraw_day_limit_remain": "20000",
"withdraw_amount_mini": "0.11",
"withdraw_eachtime_limit": "20000",
"withdraw_fix_on_chains": {
"BTC": "20",
"ETH": "15",
"TRX": "0",
"EOS": "2.5"
},
"withdraw_percent_on_chains": {
"ETH": "0%",
"GTEVM": "0%"
}
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency |
| » name | string | Currency name |
| » name_cn | string | Currency Chinese name |
| » deposit | string | Deposit fee |
| » withdraw_percent | string | Withdrawal fee rate percentage |
| » withdraw_fix | string | Fixed withdrawal fee |
| » withdraw_day_limit | string | Daily allowed withdrawal amount |
| » withdraw_amount_mini | string | Minimum withdrawal amount |
| » withdraw_day_limit_remain | string | Daily withdrawal amount left |
| » withdraw_eachtime_limit | string | Maximum amount for each withdrawal |
| » withdraw_fix_on_chains | object | Fixed withdrawal fee on multiple chains |
| »» additionalProperties | string | none |
| » withdraw_percent_on_chains | object | Percentage withdrawal fee on multiple chains |
| »» additionalProperties | string | none |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/sub_account_balances'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /wallet/sub_account_balances \
-H 'Accept: application/json'
GET /wallet/sub_account_balances
Query sub-account balance information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sub_uid | query | string | false | Sub-account user ID, you can query multiple records separated by ,. If not specified, it will return records of all sub-accounts |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum number of records returned. Default 20, max 100. |
Example responses
200 Response
[
{
"uid": "10003",
"available": {
"BTC": "0.1",
"GT": "2000",
"USDT": "10"
},
"locking": {
"BTC": "0",
"GT": "0",
"USDT": "0"
}
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » uid | string | User ID |
| » available | object | Available balances of currencies |
| »» additionalProperties | string | none |
| » locking | object | Locked amount by currency |
| »» additionalProperties | string | none |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/sub_account_margin_balances'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /wallet/sub_account_margin_balances \
-H 'Accept: application/json'
GET /wallet/sub_account_margin_balances
Query sub-account isolated margin account balance information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sub_uid | query | string | false | Sub-account user ID, you can query multiple records separated by ,. If not specified, it will return records of all sub-accounts |
Example responses
200 Response
[
{
"uid": "10000",
"available": [
{
"locked": false,
"currency_pair": "BTC_USDT",
"risk": "9999.99",
"base": {
"available": "0.1",
"borrowed": "0",
"interest": "0",
"currency": "BTC",
"locked": "0"
},
"quote": {
"available": "0",
"borrowed": "0",
"interest": "0",
"currency": "USDT",
"locked": "0"
}
}
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » uid | string | User ID |
| » available | array | Margin account balances |
| »» None | object | Margin account information for a trading pair. base corresponds to base currency account information, quote corresponds to quote currency account information |
| »»» currency_pair | string | Currency pair |
| »»» account_type | string | Account Type mmr: maintenance margin rate account;inactive: market not activated |
| »»» leverage | string | User's current market leverage multiplier |
| »»» locked | boolean | Whether the account is locked |
| »»» risk | string | Deprecated |
| »»» mmr | string | Current Maintenance Margin Rate of the account |
| »»» base | object | Currency account information |
| »»»» currency | string | Currency name |
| »»»» available | string | Amount available for margin trading, available = margin + borrowed |
| »»»» locked | string | Frozen funds, such as amounts already placed in margin market for order trading |
| »»»» borrowed | string | Borrowed funds |
| »»»» interest | string | Unpaid interest |
| »»» quote | object | Currency account information |
| »»»» currency | string | Currency name |
| »»»» available | string | Amount available for margin trading, available = margin + borrowed |
| »»»» locked | string | Frozen funds, such as amounts already placed in margin market for order trading |
| »»»» borrowed | string | Borrowed funds |
| »»»» interest | string | Unpaid interest |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/sub_account_futures_balances'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /wallet/sub_account_futures_balances \
-H 'Accept: application/json'
GET /wallet/sub_account_futures_balances
Query sub-account perpetual futures account balance information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sub_uid | query | string | false | Sub-account user ID, you can query multiple records separated by ,. If not specified, it will return records of all sub-accounts |
| settle | query | string | false | Query balance of specified settlement currency |
Example responses
200 Response
[
[
{
"available": {
"btc": {
"available": "0.0009",
"bonus": "0",
"cross_available": "0.0009",
"cross_initial_margin": "0",
"cross_maintenance_margin": "0",
"cross_order_margin": "0",
"cross_unrealised_pnl": "0",
"currency": "BTC",
"enable_credit": false,
"enable_evolved_classic": true,
"enable_new_dual_mode": false,
"history": {
"bonus_dnw": "0",
"bonus_offset": "0",
"cross_settle": "0",
"dnw": "0.0009",
"fee": "0",
"fund": "0",
"pnl": "0",
"point_dnw": "0",
"point_fee": "0",
"point_refr": "0",
"refr": "0"
},
"in_dual_mode": false,
"isolated_position_margin": "0",
"maintenance_margin": "0",
"margin_mode": 0,
"margin_mode_name": "classic",
"order_margin": "0",
"point": "0",
"position_initial_margin": "0",
"position_margin": "0",
"total": "0.0009",
"unrealised_pnl": "0",
"update_id": 11,
"update_time": 1741766400,
"user": 10003
},
"usd": {},
"usdt": {
"available": "500.7",
"bonus": "0",
"cross_available": "500.7",
"cross_initial_margin": "0",
"cross_maintenance_margin": "0",
"cross_order_margin": "0",
"cross_unrealised_pnl": "0",
"currency": "USDT",
"enable_credit": true,
"enable_evolved_classic": true,
"enable_new_dual_mode": true,
"history": {
"bonus_dnw": "0",
"bonus_offset": "0",
"cross_settle": "-1.854650083",
"dnw": "1.89047097",
"fee": "-0.141010882",
"fund": "0",
"pnl": "0.10519",
"point_dnw": "0",
"point_fee": "0",
"point_refr": "0",
"refr": "0"
},
"in_dual_mode": true,
"isolated_position_margin": "0",
"maintenance_margin": "0",
"margin_mode": 1,
"margin_mode_name": "multi_currency",
"order_margin": "0",
"point": "0",
"position_initial_margin": "0",
"position_margin": "0",
"total": "0.000000005",
"unrealised_pnl": "0",
"update_id": 37,
"update_time": 1741766400,
"user": 10003
}
},
"uid": "10003"
}
]
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » uid | string | User ID |
| » available | object | Futures account balances |
| »» additionalProperties | object | none |
| »»» total | string | Balance, only applicable to classic contract account.The balance is the sum of all historical fund flows, including historical transfers in and out, closing settlements, and transaction fee expenses, but does not include upl of positions.total = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund) |
| »»» unrealised_pnl | string | Unrealized PNL |
| »»» position_margin | string | Deprecated |
| »»» order_margin | string | initial margin of all open orders |
| »»» available | string | Refers to the available withdrawal or trading amount in per-position, specifically the per-position available balance under the unified account that includes the credit line (which incorporates trial funds; since trial funds cannot be withdrawn, the actual withdrawal amount needs to deduct the trial fund portion when processing withdrawals) |
| »»» point | string | Point card amount |
| »»» currency | string | Settlement currency |
| »»» in_dual_mode | boolean | Whether Hedge Mode is enabled |
| »»» enable_credit | boolean | Whether portfolio margin account mode is enabled |
| »»» position_initial_margin | string | Initial margin occupied by positions, applicable to unified account mode |
| »»» maintenance_margin | string | Maintenance margin occupied by positions, applicable to new classic account margin mode and unified account mode |
| »»» bonus | string | Bonus |
| »»» enable_evolved_classic | boolean | Deprecated |
| »»» cross_order_margin | string | Cross margin order margin, applicable to new classic account margin mode |
| »»» cross_initial_margin | string | Cross margin initial margin, applicable to new classic account margin mode |
| »»» cross_maintenance_margin | string | Cross margin maintenance margin, applicable to new classic account margin mode |
| »»» cross_unrealised_pnl | string | Cross margin unrealized P&L, applicable to new classic account margin mode |
| »»» cross_available | string | Cross margin available balance, applicable to new classic account margin mode |
| »»» cross_margin_balance | string | Cross margin balance, applicable to new classic account margin mode |
| »»» cross_mmr | string | Cross margin maintenance margin rate, applicable to new classic account margin mode |
| »»» cross_imr | string | Cross margin initial margin rate, applicable to new classic account margin mode |
| »»» isolated_position_margin | string | Isolated position margin, applicable to new classic account margin mode |
| »»» enable_new_dual_mode | boolean | Deprecated |
| »»» margin_mode | integer | Margin mode of the account 0: classic future account or Classic Spot Margin Mode of unified account; 1: Multi-Currency Margin Mode; 2: Portoforlio Margin Mode; 3: Single-Currency Margin Mode |
| »»» enable_tiered_mm | boolean | Whether to enable tiered maintenance margin calculation |
| »»» enable_dual_plus | boolean | Whether to Support Split Position Mode |
| »»» position_mode | string | Position Holding Mode single - Single Direction Position, dual - Dual Direction Position, dual_plus - Split Position |
| »»» 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 |
| »»»» cross_settle | string | Represents the value of profit settlement from the futures account to the spot account under Unified Account Mode. Negative values indicate settlement from futures to spot, while positive values indicate settlement from spot to futures. This value is cumulative. |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/sub_account_cross_margin_balances'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /wallet/sub_account_cross_margin_balances \
-H 'Accept: application/json'
GET /wallet/sub_account_cross_margin_balances
Query sub-account cross margin account balance information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sub_uid | query | string | false | Sub-account user ID, you can query multiple records separated by ,. If not specified, it will return records of all sub-accounts |
Example responses
200 Response
[
{
"uid": "100000",
"available": {
"user_id": 100003,
"locked": false,
"total": "20.000000",
"borrowed": "0.000000",
"interest": "0",
"borrowed_net": "0",
"net": "20",
"leverage": "3",
"risk": "9999.99",
"total_initial_margin": "0.00",
"total_margin_balance": "20.00",
"total_maintenance_margin": "0.00",
"total_initial_margin_rate": "9999.9900",
"total_maintenance_margin_rate": "9999.9900",
"total_available_margin": "20.00",
"balances": {
"USDT": {
"available": "20.000000",
"freeze": "0.000000",
"borrowed": "0.000000",
"interest": "0.000000"
}
}
}
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » uid | string | User ID |
| » available | object | none |
| »» user_id | integer(int64) | Cross margin account user ID. 0 means this sub-account has not yet opened a cross margin account |
| »» locked | boolean | Whether the account is locked |
| »» balances | object | none |
| »»» CrossMarginBalance | object | none |
| »»»» available | string | Available balance |
| »»»» freeze | string | Locked balance |
| »»»» borrowed | string | Borrowed balance |
| »»»» interest | string | Unpaid interest |
| »»» total | string | Total account value in USDT, i.e., the sum of all currencies' (available+freeze)*price*discount |
| »»» borrowed | string | Total borrowed value in USDT, i.e., the sum of all currencies' borrowed*price*discount |
| »»» borrowed_net | string | Total borrowed value in USDT * leverage factor |
| »»» net | string | Total net assets in USDT |
| »»» leverage | string | Position leverage |
| »»» interest | string | Total unpaid interest in USDT, i.e., the sum of all currencies' interest*price*discount |
| »»» risk | string | Risk rate. When it falls below 110%, liquidation will be triggered. Calculation formula: total / (borrowed+interest) |
| »»» total_initial_margin | string | Total initial margin |
| »»» total_margin_balance | string | Total margin balance |
| »»» total_maintenance_margin | string | Total maintenance margin |
| »»» total_initial_margin_rate | string | Total initial margin rate |
| »»» total_maintenance_margin_rate | string | Total maintenance margin rate |
| »»» total_available_margin | string | Total available margin |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/saved_address'
query_param = 'currency=USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /wallet/saved_address?currency=USDT \
-H 'Accept: application/json'
GET /wallet/saved_address
Query withdrawal address whitelist
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Currency |
| chain | query | string | false | Chain name |
| limit | query | string | false | Maximum number returned, up to 100 |
| page | query | integer | false | page number |
Example responses
200 Response
[
{
"currency": "usdt",
"chain": "TRX",
"address": "TWYirLzw2RARB2jfeFcfRPmeuU3rC7rakT",
"name": "gate",
"tag": "",
"verified": "1"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency |
| » chain | string | Chain name |
| » address | string | Address |
| » name | string | Name |
| » tag | string | Tag |
| » verified | string | Whether to pass the verification 0-unverified, 1-verified |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/fee'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /wallet/fee \
-H 'Accept: application/json'
GET /wallet/fee
Query personal trading fees
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Specify currency pair to get more accurate fee settings. |
| settle | query | string | false | Specify the settlement currency of the contract to get more accurate fee settings. |
currency_pair: Specify currency pair to get more accurate fee settings.
This field is optional. Usually fee settings are the same for all currency pairs.
settle: Specify the settlement currency of the contract to get more accurate fee settings.
This field is optional. Generally, the fee settings for all settlement currencies are the same.
| Parameter | Value |
|---|---|
| settle | BTC |
| settle | USDT |
| settle | USD |
Example responses
200 Response
{
"user_id": 10001,
"taker_fee": "0.002",
"maker_fee": "0.002",
"rpi_maker_fee": "-0.00175",
"futures_taker_fee": "-0.00025",
"futures_maker_fee": "0.00075",
"futures_rpi_maker_fee": "-0.00175",
"gt_discount": false,
"gt_taker_fee": "0",
"gt_maker_fee": "0",
"loan_fee": "0.18",
"point_type": "1",
"delivery_taker_fee": "0.00016",
"delivery_maker_fee": "-0.00015",
"debit_fee": 3,
"rpi_mm": 2
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » user_id | integer(int64) | User ID |
| » taker_fee | string | spot taker fee rate |
| » maker_fee | string | spot maker fee rate |
| » rpi_maker_fee | string | spot RPI MM maker fee rate |
| » gt_discount | boolean | Whether GT deduction discount is enabled |
| » gt_taker_fee | string | Taker fee rate if using GT deduction. It will be 0 if GT deduction is disabled |
| » gt_maker_fee | string | Maker fee rate with GT deduction. Returns 0 if GT deduction is disabled |
| » loan_fee | string | Loan fee rate of margin lending |
| » point_type | string | Point card type: 0 - Original version, 1 - New version since 202009 |
| » futures_taker_fee | string | Perpetual contract taker fee rate |
| » futures_maker_fee | string | Perpetual contract maker fee rate |
| » futures_rpi_maker_fee | string | contract RPI MM maker fee rate |
| » delivery_taker_fee | string | Delivery contract taker fee rate |
| » delivery_maker_fee | string | Delivery contract maker fee rate |
| » debit_fee | integer | Deduction types for rates, 1 - GT deduction, 2 - Point card deduction, 3 - VIP rates |
| » rpi_mm | integer | RPI MM Level |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/total_balance'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /wallet/total_balance \
-H 'Accept: application/json'
GET /wallet/total_balance
Query personal account totals
This query endpoint returns the total estimated value of all currencies in each account converted to the input currency. Exchange rates and related account balance information may be cached for up to 1 minute. It is not recommended to use this interface data for real-time calculations.
For real-time calculations, query the corresponding balance interface based on account type, such as:
GET /spot/accounts to query spot accountGET /margin/accounts to query margin accountGET /futures/{settle}/accounts to query futures account| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Target currency type for statistical conversion. Accepts BTC, CNY, USD, and USDT. USDT is the default value |
Example responses
200 Response
{
"details": {
"cross_margin": {
"amount": "0",
"currency": "USDT"
},
"spot": {
"currency": "USDT",
"amount": "42264489969935775.5160259954878034182418"
},
"finance": {
"amount": "662714381.70310327810191647181",
"currency": "USDT"
},
"margin": {
"amount": "1259175.664137668554329559",
"currency": "USDT",
"borrowed": "0.00"
},
"quant": {
"amount": "591702859674467879.6488202650892478553852",
"currency": "USDT"
},
"futures": {
"amount": "2384175.5606114082065",
"currency": "USDT",
"unrealised_pnl": "0.00"
},
"delivery": {
"currency": "USDT",
"amount": "1519804.9756702",
"unrealised_pnl": "0.00"
},
"warrant": {
"amount": "0",
"currency": "USDT"
},
"cbbc": {
"currency": "USDT",
"amount": "0"
},
"meme_box": {
"currency": "USDT",
"amount": "0"
},
"options": {
"currency": "USDT",
"amount": "0"
},
"payment": {
"currency": "USDT",
"amount": "0"
}
},
"total": {
"currency": "USDT",
"amount": "633967350312281193.068368815439797304437",
"unrealised_pnl": "0.00",
"borrowed": "0.00"
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request is valid and successfully returned | Inline |
Status Code 200
User's total balance information
| Name | Type | Description |
|---|---|---|
| » total | object | Total balances calculated with specified currency unit |
| »» amount | string | Account total balance amount |
| »» currency | string | Currency |
| »» unrealised_pnl | string | Unrealised_pnl, this field will only appear in futures, options, delivery, and total accounts |
| »» borrowed | string | Total borrowed amount, this field will only appear in margin and cross_margin accounts |
| » details | object | Total Balances of All Accounts - cross_margin: Cross Margin Account - spot: Spot Account - finance: Finance Account - margin: Margin Account - quant: Quantitative Account - futures: Futures Account (Perpetual Contracts) - delivery: Delivery Account (Delivery Contracts) - warrant: Warrant Account - cbbc: CBBC Account (Covered Bull/Bear Contract) - meme_box: Alpha Account - options: Options Account - payment: Payment Account |
| »» additionalProperties | object | Total balances calculated with specified currency unit |
| »»» amount | string | Account total balance amount |
| »»» currency | string | Currency |
| »»» unrealised_pnl | string | Unrealised_pnl, this field will only appear in futures, options, delivery, and total accounts |
| »»» borrowed | string | Total borrowed amount, this field will only appear in margin and cross_margin accounts |
| Property | Value |
|---|---|
| currency | BTC |
| currency | CNY |
| currency | USD |
| currency | USDT |
| currency | BTC |
| currency | CNY |
| currency | USD |
| currency | USDT |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/small_balance'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /wallet/small_balance \
-H 'Accept: application/json'
GET /wallet/small_balance
Get list of convertible small balance currencies
Example responses
200 Response
[
[
{
"currency": "FLOKI",
"available_balance": "182.29400000",
"estimated_as_btc": "0.00000012",
"convertible_to_gt": "0.001080"
},
{
"currency": "MBLK",
"available_balance": "0.91723337",
"estimated_as_btc": "0.00000102",
"convertible_to_gt": "0.009188"
}
]
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Small Balance Conversion |
| »» currency | string | Currency |
| »» available_balance | string | Available balance |
| »» estimated_as_btc | string | Estimated as BTC |
| »» convertible_to_gt | string | Estimated conversion to GT |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/small_balance'
query_param = ''
body='{"currency":["FLOKI","MBLK"],"is_all":true}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /wallet/small_balance \
-H 'Content-Type: application/json'
POST /wallet/small_balance
Convert small balance currency
Body parameter
{
"currency": [
"FLOKI",
"MBLK"
],
"is_all": true
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | array | false | Currency to be converted |
| » is_all | body | boolean | false | Whether to convert all |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | None |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/small_balance_history'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /wallet/small_balance_history \
-H 'Accept: application/json'
GET /wallet/small_balance_history
Get convertible small balance currency history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Currency to convert |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum number of items returned. Default: 100, minimum: 1, maximum: 100 |
Example responses
200 Response
[
[
{
"id": "28583810",
"create_time": 1706670777,
"currency": "FLOKI",
"amount": "182.29400000",
"gt_amount": "0.001079"
}
]
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Small Balance Conversion |
| »» id | string | Order ID |
| »» currency | string | Currency |
| »» amount | string | Swap Amount |
| »» gt_amount | string | GT amount |
| »» create_time | integer(int64) | Exchange time (in seconds) |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/push'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /wallet/push \
-H 'Accept: application/json'
GET /wallet/push
Get UID transfer history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | query | integer(int32) | false | Order ID |
| from | query | integer(int32) | false | Start time for querying records. If not specified, defaults to 7 days before the current time. Unix timestamp in seconds |
| to | query | integer(int32) | false | End time for querying records. If not specified, defaults to the current time. Unix timestamp in seconds |
| limit | query | integer(int32) | false | Maximum number of items returned in the list, default value is 100 |
| offset | query | integer(int32) | false | List offset, starting from 0 |
| transaction_type | query | string | false | Order type returned in the list: withdraw, deposit. Default is withdraw. |
Example responses
200 Response
[
{
"id": 111,
"push_uid": 1132,
"receive_uid": 12324,
"currency": "BTC",
"amount": "1.2",
"status": "PENDING",
"create_time": 1706670777,
"message": "The other party has not completed KYC,There is a security risk in your account, please contact customer service",
"transaction_type": "withdraw"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Order ID |
| » push_uid | integer(int64) | Initiator User ID |
| » receive_uid | integer(int64) | Recipient User ID |
| » currency | string | Currency name |
| » amount | string | Transfer amount |
| » create_time | integer(int64) | Created time |
| » status | string | Withdrawal status: - CREATING: Creating - PENDING: Waiting for recipient (Please contact the recipient to accept the transfer on Gate official website) - CANCELLING: Cancelling - CANCELLED: Cancelled - REFUSING: Refusing - REFUSED: Refused - RECEIVING: Receiving - RECEIVED: Success |
| » message | string | PENDING reason tips |
| » transaction_type | string | Order Type |
Code samples
# coding: utf-8
import requests
import time
import hashlib
import hmac
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/wallet/getLowCapExchangeList'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="//"
prefix="//"
method="GET"
url="/wallet/getLowCapExchangeList"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$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/getLowCapExchangeList
Retrieve the list of low-liquidity or low-cap tokens
Example responses
Returns a string array on success
[
"0DOG",
"100X",
"1ART",
"1INCH3L",
"1INCH3S",
"10N8",
"20EX",
"3AC",
"3AC_OLD",
"3KM",
"4"
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Returns a string array on success | [string] |
WARNING
To perform this operation, you must be authenticated by API key and secret
Sub-account management
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts'
query_param = ''
body='{"remark":"remark","login_name":"sub_account_for_trades"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /sub_accounts \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /sub_accounts
Create a new sub-account
Body parameter
{
"remark": "remark",
"login_name": "sub_account_for_trades"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » remark | body | string | false | Remark |
| » login_name | body | string | true | Sub-account login name: Only letters, numbers and underscores are supported, cannot contain other invalid characters |
| » password | body | string | false | The sub-account's password. (Default: the same as main account's password) |
| body | string | false | The sub-account's email address. (Default: the same as main account's email address) |
Example responses
201 Response
{
"remark": "remark",
"login_name": "sub_account_for_trades",
"user_id": 10001,
"state": 1,
"create_time": 168888888
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Created successfully | Inline |
Status Code 201
| Name | Type | Description |
|---|---|---|
| » remark | string | Remark |
| » login_name | string | Sub-account login name: Only letters, numbers and underscores are supported, cannot contain other invalid characters |
| » password | string | The sub-account's password. (Default: the same as main account's password) |
| string | The sub-account's email address. (Default: the same as main account's email address) | |
| » state | integer(int32) | Sub-account status: 1-normal, 2-locked |
| » type | integer(int32) | Sub-account type: 1-Regular sub-account, 3-Cross margin sub-account |
| » user_id | integer(int64) | Sub-account user ID |
| » create_time | integer(int64) | Created time |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /sub_accounts \
-H 'Accept: application/json'
GET /sub_accounts
List sub-accounts
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| type | query | string | false | Enter 0 to list all types of sub-accounts (currently supporting cross-margin sub-accounts and regular sub-accounts). |
type: Enter 0 to list all types of sub-accounts (currently supporting cross-margin sub-accounts and regular sub-accounts).
Enter 1 to query regular sub-accounts only. If no parameter is passed, only regular sub-accounts will be queried by default.
Example responses
200 Response
[
{
"remark": "remark",
"login_name": "sub_account_for_trades",
"user_id": 10001,
"state": 1,
"create_time": 168888888
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » remark | string | Remark |
| » login_name | string | Sub-account login name: Only letters, numbers and underscores are supported, cannot contain other invalid characters |
| » password | string | The sub-account's password. (Default: the same as main account's password) |
| string | The sub-account's email address. (Default: the same as main account's email address) | |
| » state | integer(int32) | Sub-account status: 1-normal, 2-locked |
| » type | integer(int32) | Sub-account type: 1-Regular sub-account, 3-Cross margin sub-account |
| » user_id | integer(int64) | Sub-account user ID |
| » create_time | integer(int64) | Created time |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts/0'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /sub_accounts/0 \
-H 'Accept: application/json'
GET /sub_accounts/{user_id}
Get sub-account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer(int64) | true | Sub-account user ID |
Example responses
200 Response
{
"remark": "remark",
"login_name": "sub_account_for_trades",
"user_id": 10001,
"state": 1,
"create_time": 168888888
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » remark | string | Remark |
| » login_name | string | Sub-account login name: Only letters, numbers and underscores are supported, cannot contain other invalid characters |
| » password | string | The sub-account's password. (Default: the same as main account's password) |
| string | The sub-account's email address. (Default: the same as main account's email address) | |
| » state | integer(int32) | Sub-account status: 1-normal, 2-locked |
| » type | integer(int32) | Sub-account type: 1-Regular sub-account, 3-Cross margin sub-account |
| » user_id | integer(int64) | Sub-account user ID |
| » create_time | integer(int64) | Created time |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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"]}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /sub_accounts/0/keys \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /sub_accounts/{user_id}/keys
Create new sub-account API key pair
Body parameter
{
"mode": 1,
"name": "spot",
"perms": [
{
"read_only": false,
"name": "options"
},
{
"read_only": false,
"name": "spot"
},
{
"read_only": false,
"name": "delivery"
},
{
"read_only": false,
"name": "wallet"
},
{
"read_only": false,
"name": "futures"
}
],
"ip_whitelist": [
"127.0.0.1",
"127.0.0.2"
]
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer(int64) | true | Sub-account user ID |
| body | body | SubAccountKey | true | none |
| » mode | body | integer(int32) | false | Mode: 1 - classic 2 - portfolio account |
| » name | body | string | false | API Key Name |
| » perms | body | array | false | none |
| »» name | body | string | false | Permission function name (no value will be cleared) |
| »» read_only | body | boolean | false | Read Only |
| » ip_whitelist | body | array | false | IP whitelist (list will be cleared if no value is passed) |
»» name: Permission function name (no value will be cleared)
Example responses
200 Response
{
"state": 1,
"name": "spot",
"user_id": 100000,
"perms": [
{
"name": "options",
"read_only": false
},
{
"name": "spot",
"read_only": false
},
{
"name": "delivery",
"read_only": false
},
{
"name": "wallet",
"read_only": false
},
{
"name": "futures",
"read_only": false
}
],
"ip_whitelist": [
"127.0.0.1",
"127.0.0.2"
],
"mode": 1,
"secret": "cddcc6e5e78060e013860bdbe5e737830b96821c027664586fb38b411808f4fd",
"key": "eb8815bf99d7bb5f8ad6497bdc4774a8",
"created_at": 1663683330,
"updated_at": 1663683330
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Created successfully | SubAccountKey |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts/0/keys'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /sub_accounts/0/keys \
-H 'Accept: application/json'
GET /sub_accounts/{user_id}/keys
List all API key pairs of the sub-account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer | true | Sub-account user ID |
Example responses
200 Response
[
{
"state": 1,
"name": "spot",
"user_id": 1000000,
"perms": [
{
"name": "futures",
"read_only": false
},
{
"name": "wallet",
"read_only": false
},
{
"name": "delivery",
"read_only": false
},
{
"name": "options",
"read_only": false
},
{
"name": "spot",
"read_only": false
}
],
"mode": 1,
"ip_whitelist": [
"127.0.0.1",
"127.0.0.2"
],
"key": "75c3264105b74693d8cb5c7f1a8e2420",
"created_at": 1663642892,
"last_access": 1663642892,
"update_at": 1663642892
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [SubAccountKey] |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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"]}'
r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X PUT /sub_accounts/0/keys/string \
-H 'Content-Type: application/json'
PUT /sub_accounts/{user_id}/keys/{key}
Update sub-account API key pair
Modify Sub-account API Key Pair (Note: This interface cannot modify the mode account type attribute)
Body parameter
{
"mode": 1,
"name": "spot",
"perms": [
{
"read_only": false,
"name": "options"
},
{
"read_only": false,
"name": "spot"
},
{
"read_only": false,
"name": "delivery"
},
{
"read_only": false,
"name": "wallet"
},
{
"read_only": false,
"name": "futures"
}
],
"ip_whitelist": [
"127.0.0.1",
"127.0.0.2"
]
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer | true | Sub-account user ID |
| key | path | string | true | Sub-account API key |
| body | body | SubAccountKey | true | none |
| » mode | body | integer(int32) | false | Mode: 1 - classic 2 - portfolio account |
| » name | body | string | false | API Key Name |
| » perms | body | array | false | none |
| »» name | body | string | false | Permission function name (no value will be cleared) |
| »» read_only | body | boolean | false | Read Only |
| » ip_whitelist | body | array | false | IP whitelist (list will be cleared if no value is passed) |
»» name: Permission function name (no value will be cleared)
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Updated successfully | None |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts/0/keys/string'
query_param = ''
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
curl -X DELETE /sub_accounts/0/keys/string
DELETE /sub_accounts/{user_id}/keys/{key}
Delete sub-account API key pair
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer | true | Sub-account user ID |
| key | path | string | true | Sub-account API key |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Deleted successfully | None |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts/0/keys/string'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /sub_accounts/0/keys/string \
-H 'Accept: application/json'
GET /sub_accounts/{user_id}/keys/{key}
Get specific API key pair of the sub-account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer | true | Sub-account user ID |
| key | path | string | true | Sub-account API key |
Example responses
200 Response
{
"state": 1,
"name": "spot",
"user_id": 1000000,
"perms": [
{
"name": "futures",
"read_only": false
},
{
"name": "wallet",
"read_only": false
},
{
"name": "delivery",
"read_only": false
},
{
"name": "options",
"read_only": false
},
{
"name": "spot",
"read_only": false
}
],
"mode": 1,
"ip_whitelist": [
"127.0.0.1",
"127.0.0.2"
],
"key": "75c3264105b74693d8cb5c7f1a8e2420",
"created_at": 1663642892,
"last_access": 1663642892,
"update_at": 1663642892
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | SubAccountKey |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts/0/lock'
query_param = ''
r = requests.request('POST', host + prefix + url, headers=headers)
print(r.json())
curl -X POST /sub_accounts/0/lock
POST /sub_accounts/{user_id}/lock
Lock sub-account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer(int64) | true | Sub-account user ID |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Locked successfully | None |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts/0/unlock'
query_param = ''
r = requests.request('POST', host + prefix + url, headers=headers)
print(r.json())
curl -X POST /sub_accounts/0/unlock
POST /sub_accounts/{user_id}/unlock
Unlock sub-account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user_id | path | integer(int64) | true | Sub-account user ID |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Unlocked successfully | None |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/sub_accounts/unified_mode'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /sub_accounts/unified_mode \
-H 'Accept: application/json'
GET /sub_accounts/unified_mode
Get sub-account mode
Unified account mode:
classic: Classic account modemulti_currency: Cross-currency margin modeportfolio: Portfolio margin modesingle_currency: Single-currency margin modeExample responses
200 Response
[
{
"user_id": 110285555,
"is_unified": true,
"mode": "multi_currency"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » user_id | integer(int64) | User ID |
| » is_unified | boolean | Whether it is a unified account |
| » mode | string | Unified account mode: - classic: Classic account mode- multi_currency: Cross-currency margin mode- portfolio: Portfolio margin mode- single_currency: Single-currency margin mode |
Perpetual futures
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /futures/usdt/contracts \
-H 'Accept: application/json'
GET /futures/{settle}/contracts
Query all futures contracts
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"name": "BTC_USDT",
"type": "direct",
"quanto_multiplier": "0.0001",
"ref_discount_rate": "0",
"order_price_deviate": "0.5",
"maintenance_rate": "0.005",
"mark_type": "index",
"last_price": "38026",
"mark_price": "37985.6",
"index_price": "37954.92",
"funding_rate_indicative": "0.000219",
"mark_price_round": "0.01",
"funding_offset": 0,
"in_delisting": false,
"risk_limit_base": "1000000",
"interest_rate": "0.0003",
"order_price_round": "0.1",
"order_size_min": "1",
"enable_decimal": false,
"ref_rebate_rate": "0.2",
"funding_interval": 28800,
"risk_limit_step": "1000000",
"leverage_min": "1",
"leverage_max": "100",
"risk_limit_max": "8000000",
"maker_fee_rate": "-0.00025",
"taker_fee_rate": "0.00075",
"funding_rate": "0.002053",
"order_size_max": "1000000",
"funding_next_apply": 1610035200,
"short_users": 977,
"config_change_time": 1609899548,
"trade_size": "28530850594",
"position_size": "5223816",
"long_users": 455,
"funding_impact_value": "60000",
"orders_limit": 50,
"trade_id": 10851092,
"orderbook_id": 2129638396,
"enable_bonus": true,
"enable_credit": true,
"create_time": 1669688556,
"funding_cap_ratio": "0.75",
"status": "trading",
"launch_time": 1609899548,
"delisting_time": 1609899548,
"delisted_time": 1609899548,
"market_order_slip_ratio": "0.05",
"market_order_size_max": "0",
"funding_rate_limit": "0.003",
"contract_type": "indices",
"enable_circuit_breaker": false
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Contract] |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /futures/usdt/contracts/BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/contracts/{contract}
Query single contract information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"name": "BTC_USDT",
"type": "direct",
"quanto_multiplier": "0.0001",
"ref_discount_rate": "0",
"order_price_deviate": "0.5",
"maintenance_rate": "0.005",
"mark_type": "index",
"last_price": "38026",
"mark_price": "37985.6",
"index_price": "37954.92",
"funding_rate_indicative": "0.000219",
"mark_price_round": "0.01",
"funding_offset": 0,
"in_delisting": false,
"risk_limit_base": "1000000",
"interest_rate": "0.0003",
"order_price_round": "0.1",
"order_size_min": "1",
"enable_decimal": false,
"ref_rebate_rate": "0.2",
"funding_interval": 28800,
"risk_limit_step": "1000000",
"leverage_min": "1",
"leverage_max": "100",
"risk_limit_max": "8000000",
"maker_fee_rate": "-0.00025",
"taker_fee_rate": "0.00075",
"funding_rate": "0.002053",
"order_size_max": "1000000",
"funding_next_apply": 1610035200,
"short_users": 977,
"config_change_time": 1609899548,
"trade_size": "28530850594",
"position_size": "5223816",
"long_users": 455,
"funding_impact_value": "60000",
"orders_limit": 50,
"trade_id": 10851092,
"orderbook_id": 2129638396,
"enable_bonus": true,
"enable_credit": true,
"create_time": 1669688556,
"funding_cap_ratio": "0.75",
"status": "trading",
"launch_time": 1609899548,
"delisting_time": 1609899548,
"delisted_time": 1609899548,
"market_order_slip_ratio": "0.05",
"market_order_size_max": "0",
"funding_rate_limit": "0.003",
"contract_type": "indices",
"enable_circuit_breaker": false
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Contract information | Contract |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /futures/usdt/order_book?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/order_book
Query futures market depth information
Bids will be sorted by price from high to low, while asks sorted reversely
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| interval | query | string | false | Price precision for merged depth. 0 means no merging. If not specified, defaults to 0 |
| limit | query | integer | false | Number of depth levels |
| with_id | query | boolean | false | Whether to return depth update ID. This ID increments by 1 each time the depth changes |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"id": 123456,
"current": 1623898993.123,
"update": 1623898993.121,
"asks": [
{
"p": "1.52",
"s": "100"
},
{
"p": "1.53",
"s": "40"
}
],
"bids": [
{
"p": "1.17",
"s": "150"
},
{
"p": "1.16",
"s": "203"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Depth query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Order Book ID. Increases by 1 on every order book change. Set with_id=true to include this field in response |
| » current | number(double) | Response data generation timestamp |
| » update | number(double) | Order book changed timestamp |
| » asks | array | Ask Depth |
| »» FuturesOrderBookItem | object | none |
| »»» p | string | Price (quote currency) |
| »»» s | string | Size |
| »» bids | array | Bid Depth |
| »»» FuturesOrderBookItem | object | none |
| »»»» p | string | Price (quote currency) |
| »»»» s | string | Size |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /futures/usdt/trades?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/trades
Futures market transaction records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| last_id | query | string | false | Specify the starting point for this list based on a previously retrieved id |
| from | query | integer(int64) | false | Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items. |
| to | query | integer(int64) | false | Specify end time in Unix seconds, default to current time. |
last_id: Specify the starting point for this list based on a previously retrieved id
This parameter is deprecated. Use from and to instead to limit time range
from: Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items.
If items between from and to are more than limit, only limit number will be returned.
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800,
"contract": "BTC_USDT",
"size": "-100",
"price": "100.123"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Fill ID |
| » create_time | number(double) | Fill Time |
| » create_time_ms | number(double) | Trade time, with millisecond precision to 3 decimal places |
| » contract | string | Futures contract |
| » size | string | Trading size |
| » price | string | Trade price (quote currency) |
| » is_internal | boolean | Deprecated |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /futures/usdt/candlesticks?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/candlesticks
Futures market K-line chart
Return specified contract candlesticks.
If prefix contract with mark_, the contract's mark price candlesticks are returned;
if prefix with index_, index price candlesticks will be returned.
Maximum of 2000 points are returned in one query. Be sure not to exceed the limit when specifying from, to and interval
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| from | query | integer(int64) | false | Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified |
| to | query | integer(int64) | false | Specify the end time of the K-line chart, defaults to current time if not specified, note that the time format is Unix timestamp with second precision |
| limit | query | integer | false | Maximum number of recent data points to return. limit conflicts with from and to. If either from or to is specified, request will be rejected. |
| interval | query | string | false | Time interval for data points. Note: 1w represents a natural week, 7d is aligned with Unix epoch time, 30d represents a natural month |
| timezone | query | string | false | Time zone: all/utc0/utc8, default utc0 |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| interval | 10s |
| interval | 1m |
| interval | 5m |
| interval | 15m |
| interval | 30m |
| interval | 1h |
| interval | 4h |
| interval | 8h |
| interval | 1d |
| interval | 7d |
Example responses
200 Response
[
{
"t": 1539852480,
"v": "97151",
"c": "1.032",
"h": "1.032",
"l": "1.032",
"o": "1.032",
"sum": "3580"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | data point in every timestamp |
| »» t | number(double) | Unix timestamp in seconds |
| »» v | string | size volume (contract size). Only returned if contract is not prefixed |
| »» c | string | Close price (quote currency) |
| »» h | string | Highest price (quote currency) |
| »» l | string | Lowest price (quote currency) |
| »» o | string | Open price (quote currency) |
| »» sum | string | Trading volume (unit: Quote currency) |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /futures/usdt/premium_index?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/premium_index
Premium Index K-line chart
K-line chart data returns a maximum of 1000 points per request. When specifying from, to, and interval, ensure the number of points is not excessive
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| from | query | integer(int64) | false | Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified |
| to | query | integer(int64) | false | Specify the end time of the K-line chart, defaults to current time if not specified, note that the time format is Unix timestamp with second precision |
| limit | query | integer | false | Maximum number of recent data points to return. limit conflicts with from and to. If either from or to is specified, request will be rejected. |
| interval | query | string | false | Time interval between data points |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| interval | 1m |
| interval | 5m |
| interval | 15m |
| interval | 30m |
| interval | 1h |
| interval | 4h |
| interval | 8h |
| interval | 1d |
| interval | 7d |
Example responses
200 Response
[
{
"t": 1539852480,
"c": "0",
"h": "0.00023",
"l": "0",
"o": "0"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | data point in every timestamp |
| »» t | number(double) | Unix timestamp in seconds |
| »» c | string | Close price |
| »» h | string | Highest price |
| »» l | string | Lowest price |
| »» o | string | Open price |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /futures/usdt/tickers \
-H 'Accept: application/json'
GET /futures/{settle}/tickers
Get all futures trading statistics
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"contract": "BTC_USDT",
"last": "6432",
"low_24h": "6278",
"high_24h": "6790",
"change_percentage": "4.43",
"total_size": "32323904",
"volume_24h": "184040233284",
"volume_24h_btc": "28613220",
"volume_24h_usd": "184040233284",
"volume_24h_base": "28613220",
"volume_24h_quote": "184040233284",
"volume_24h_settle": "28613220",
"mark_price": "6534",
"funding_rate": "0.0001",
"funding_rate_indicative": "0.0001",
"index_price": "6531",
"highest_bid": "34089.7",
"highest_size": "100",
"lowest_ask": "34217.9",
"lowest_size": "1000"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » contract | string | Futures contract |
| » last | string | Last trading price |
| » change_percentage | string | Price change percentage. Negative values indicate price decrease, e.g. -7.45 |
| » total_size | string | Contract total size |
| » low_24h | string | 24-hour lowest price |
| » high_24h | string | 24-hour highest price |
| » volume_24h | string | 24-hour trading volume |
| » volume_24h_btc | string | 24-hour trading volume in BTC (deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead) |
| » volume_24h_usd | string | 24-hour trading volume in USD (deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead) |
| » volume_24h_base | string | 24-hour trading volume in base currency |
| » volume_24h_quote | string | 24-hour trading volume in quote currency |
| » volume_24h_settle | string | 24-hour trading volume in settle currency |
| » mark_price | string | Recent mark price |
| » funding_rate | string | Funding rate |
| » funding_rate_indicative | string | Indicative Funding rate in next period. (deprecated. use funding_rate) |
| » index_price | string | Index price |
| » quanto_base_rate | string | Deprecated |
| » lowest_ask | string | Recent lowest ask |
| » lowest_size | string | The latest seller's lowest price order quantity |
| » highest_bid | string | Recent highest bid |
| » highest_size | string | The latest buyer's highest price order volume |
| » change_utc0 | string | Percentage change at utc0. Negative values indicate a drop, e.g., -7.45% |
| » change_utc8 | string | Percentage change at utc8. Negative values indicate a drop, e.g., -7.45% |
| » change_price | string | 24h change amount. Negative values indicate a drop, e.g., -7.45 |
| » change_utc0_price | string | Change amount at utc0. Negative values indicate a drop, e.g., -7.45 |
| » change_utc8_price | string | Change amount at utc8. Negative values indicate a drop, e.g., -7.45 |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /futures/usdt/funding_rate?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/funding_rate
Futures market historical funding rate
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| limit | query | integer | false | Maximum number of records returned in a single list |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"t": 1543968000,
"r": "0.000157"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | History query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » t | integer(int64) | Unix timestamp in seconds |
| » r | string | Funding rate |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/funding_rates'
query_param = ''
body='{"contracts":["BTC_USDT","ETH_USDT"]}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /futures/usdt/funding_rates \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /futures/{settle}/funding_rates
Batch Query Historical Funding Rate Data for Perpetual Contracts
Body parameter
{
"contracts": [
"BTC_USDT",
"ETH_USDT"
]
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| body | body | BatchFundingRatesRequest | true | none |
| » contracts | body | array | true | Array of Contract Names |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
[
{
"contract": "BTC_USDT",
"data": [
{
"t": 1543968000,
"r": "0.000157"
},
{
"t": 1544054400,
"r": "0.000145"
}
]
}
]
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch Query Successful | [BatchFundingRatesResponse] |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /futures/usdt/insurance \
-H 'Accept: application/json'
GET /futures/{settle}/insurance
Futures market insurance fund history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| limit | query | integer | false | Maximum number of records returned in a single list |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"t": 1543968000,
"b": "83.0031"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » t | integer(int64) | Unix timestamp in seconds |
| » b | string | Insurance balance |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /futures/usdt/contract_stats?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/contract_stats
Futures statistics
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| from | query | integer(int64) | false | Start timestamp |
| interval | query | string | false | none |
| limit | query | integer | false | none |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"time": 1603865400,
"lsr_taker": 100,
"lsr_account": 0.5,
"long_liq_size": "0",
"short_liq_size": "0",
"open_interest": "124724",
"short_liq_usd": 0,
"mark_price": "8865",
"top_lsr_size": "1.02",
"short_liq_amount": 0,
"long_liq_amount": 0,
"open_interest_usd": 1511,
"top_lsr_account": 1.5,
"long_liq_usd": 0
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | integer(int64) | Stat timestamp |
| » lsr_taker | number(double) | Long/short taker ratio |
| » lsr_account | number(double) | Long/short position user ratio |
| » long_liq_size | string | Long liquidation size (contracts) |
| » long_liq_amount | number(double) | Long liquidation amount (base currency) |
| » long_liq_usd | number(double) | Long liquidation volume (quote currency) |
| » long_liq_usd_new | number(double) | Long liquidations in quote currency; USDT settlement: long_liq_size × multiplier × mark price |
| » short_liq_size | string | Short liquidation size (contracts) |
| » short_liq_amount | number(double) | Short liquidation amount (base currency) |
| » short_liq_usd | number(double) | Short liquidation volume (quote currency) |
| » short_liq_usd_new | number(double) | Short liquidations in quote currency; USDT settlement: short_liq_size × multiplier × mark price |
| » open_interest | string | Total open interest size (contracts) |
| » open_interest_usd | number(double) | Total open interest volume (quote currency) |
| » top_lsr_account | number(double) | Top trader long/short account ratio |
| » top_lsr_size | string | Top trader long/short position ratio |
| » mark_price | number(double) | Mark price |
| » top_long_size | string | Top long open interest (contracts) |
| » top_short_size | string | Top short open interest (contracts) |
| » long_taker_size | string | Long taker trade volume (contracts) |
| » short_taker_size | string | Short taker trade volume (contracts) |
| » top_long_account | string | Number of top long accounts (large holders) |
| » top_short_account | string | Number of top short accounts (large holders) |
| » long_users | string | Number of users holding long positions |
| » short_users | string | Number of users holding short positions |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /futures/usdt/index_constituents/BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/index_constituents/{index}
Query index constituents
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| index | path | string | true | Index name |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"index": "BTC_USDT",
"constituents": [
{
"exchange": "Binance",
"symbols": [
"BTC_USDT"
]
},
{
"exchange": "Gate.com",
"symbols": [
"BTC_USDT"
]
},
{
"exchange": "Huobi",
"symbols": [
"BTC_USDT"
]
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » index | string | Index name |
| » constituents | array | Constituents |
| »» IndexConstituent | object | none |
| »»» exchange | string | Exchange |
| »»» symbols | array | Symbol list |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /futures/usdt/liq_orders \
-H 'Accept: application/json'
GET /futures/{settle}/liq_orders
Query liquidation order history
The time interval between from and to is maximum 3600. Some private fields are not returned by public interfaces, refer to field descriptions for details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
| limit | query | integer | false | Maximum number of records returned in a single list |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"time": 1548654951,
"contract": "BTC_USDT",
"size": "600",
"order_size": "-600",
"order_price": "3405",
"fill_price": "3424",
"left": "0"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | integer(int64) | Liquidation time |
| » contract | string | Futures contract |
| » size | string | User position size |
| » order_size | string | Number of forced liquidation orders |
| » order_price | string | Liquidation order price |
| » fill_price | string | Liquidation order average taker price |
| » left | string | System liquidation order maker size |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/risk_limit_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /futures/usdt/risk_limit_tiers \
-H 'Accept: application/json'
GET /futures/{settle}/risk_limit_tiers
Query risk limit tiers
When the 'contract' parameter is not passed, the default is to query the risk limits for the top 100 markets. 'Limit' and 'offset' correspond to pagination queries at the market level, not to the length of the returned array. This only takes effect when the contract parameter is empty.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"maintenance_rate": "0.01",
"tier": 1,
"initial_rate": "0.02",
"leverage_max": "50",
"risk_limit": "20000",
"contract": "ZTX_USDT",
"deduction": "0"
},
{
"maintenance_rate": "0.013",
"tier": 2,
"initial_rate": "0.025",
"leverage_max": "40",
"risk_limit": "30000",
"contract": "ZTX_USDT",
"deduction": "60"
},
{
"maintenance_rate": "0.015",
"tier": 3,
"initial_rate": "0.02857",
"leverage_max": "35",
"risk_limit": "50000",
"contract": "ZTX_USDT",
"deduction": "120"
},
{
"maintenance_rate": "0.02",
"tier": 4,
"initial_rate": "0.03333",
"leverage_max": "30",
"risk_limit": "70000",
"contract": "ZTX_USDT",
"deduction": "370"
},
{
"maintenance_rate": "0.025",
"tier": 5,
"initial_rate": "0.04",
"leverage_max": "25",
"risk_limit": "100000",
"contract": "ZTX_USDT",
"deduction": "720"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | 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 | The maintenance margin rate of the first tier of risk limit sheet |
| »» leverage_max | string | Maximum leverage |
| »» contract | string | Market, only visible when market pagination is requested |
| »» deduction | string | Maintenance margin quick calculation deduction amount |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/accounts'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /futures/usdt/accounts \
-H 'Accept: application/json'
GET /futures/{settle}/accounts
Get futures account
Query account information for classic future account and unified account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 1666,
"currency": "USDT",
"total": "9707.803567115145",
"unrealised_pnl": "3371.248828",
"position_margin": "38.712189181",
"order_margin": "0",
"available": "9669.091377934145",
"point": "0",
"bonus": "0",
"in_dual_mode": false,
"enable_evolved_classic": false,
"cross_initial_margin": "61855.56788525",
"cross_maintenance_margin": "682.04678105",
"cross_order_margin": "0",
"cross_unrealised_pnl": "1501.178222634128",
"cross_available": "27549.406108813951",
"cross_margin_balance": "10371.77306201952",
"cross_mmr": "797.2134",
"cross_imr": "116.6097",
"isolated_position_margin": "0",
"history": {
"dnw": "10000",
"pnl": "68.3685",
"fee": "-1.645812875",
"refr": "0",
"fund": "-358.919120009855",
"point_dnw": "0",
"point_fee": "0",
"point_refr": "0",
"bonus_dnw": "0",
"bonus_offset": "0"
},
"enable_tiered_mm": true,
"position_mode": "dual_plus",
"enable_dual_plus": true
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » total | string | Balance, only applicable to classic contract account.The balance is the sum of all historical fund flows, including historical transfers in and out, closing settlements, and transaction fee expenses, but does not include upl of positions.total = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund) |
| » unrealised_pnl | string | Unrealized PNL |
| » position_margin | string | Deprecated |
| » order_margin | string | initial margin of all open orders |
| » available | string | Refers to the available withdrawal or trading amount in per-position, specifically the per-position available balance under the unified account that includes the credit line (which incorporates trial funds; since trial funds cannot be withdrawn, the actual withdrawal amount needs to deduct the trial fund portion when processing withdrawals) |
| » point | string | Point card amount |
| » currency | string | Settlement currency |
| » in_dual_mode | boolean | Whether Hedge Mode is enabled |
| » enable_credit | boolean | Whether portfolio margin account mode is enabled |
| » position_initial_margin | string | Initial margin occupied by positions, applicable to unified account mode |
| » maintenance_margin | string | Maintenance margin occupied by positions, applicable to new classic account margin mode and unified account mode |
| » bonus | string | Bonus |
| » enable_evolved_classic | boolean | Deprecated |
| » cross_order_margin | string | Cross margin order margin, applicable to new classic account margin mode |
| » cross_initial_margin | string | Cross margin initial margin, applicable to new classic account margin mode |
| » cross_maintenance_margin | string | Cross margin maintenance margin, applicable to new classic account margin mode |
| » cross_unrealised_pnl | string | Cross margin unrealized P&L, applicable to new classic account margin mode |
| » cross_available | string | Cross margin available balance, applicable to new classic account margin mode |
| » cross_margin_balance | string | Cross margin balance, applicable to new classic account margin mode |
| » cross_mmr | string | Cross margin maintenance margin rate, applicable to new classic account margin mode |
| » cross_imr | string | Cross margin initial margin rate, applicable to new classic account margin mode |
| » isolated_position_margin | string | Isolated position margin, applicable to new classic account margin mode |
| » enable_new_dual_mode | boolean | Deprecated |
| » margin_mode | integer | Margin mode of the account 0: classic future account or Classic Spot Margin Mode of unified account; 1: Multi-Currency Margin Mode; 2: Portoforlio Margin Mode; 3: Single-Currency Margin Mode |
| » enable_tiered_mm | boolean | Whether to enable tiered maintenance margin calculation |
| » enable_dual_plus | boolean | Whether to Support Split Position Mode |
| » position_mode | string | Position Holding Mode single - Single Direction Position, dual - Dual Direction Position, dual_plus - Split Position |
| » 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 |
| »» cross_settle | string | Represents the value of profit settlement from the futures account to the spot account under Unified Account Mode. Negative values indicate settlement from futures to spot, while positive values indicate settlement from spot to futures. This value is cumulative. |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/account_book'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /futures/usdt/account_book \
-H 'Accept: application/json'
GET /futures/{settle}/account_book
Query futures account change history
If the contract field is passed, only records containing this field after 2023-10-30 can be filtered。
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
| type | query | string | false | Change types: |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
type: Change types:
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"time": 1682294400.123456,
"change": "0.000010152188",
"balance": "4.59316525194",
"text": "ETH_USD:6086261",
"type": "fee",
"contract": "ETH_USD",
"trade_id": "1",
"id": "1"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | number(double) | Change time |
| » change | string | Change amount |
| » balance | string | Balance after change |
| » type | string | Change types: - dnw: Deposit and withdrawal - pnl: Profit and loss from position reduction - fee: Trading fees - refr: Referrer rebates - fund: Funding fees - point_dnw: Point card deposit and withdrawal - point_fee: Point card trading fees - point_refr: Point card referrer rebates - bonus_offset: Trial fund deduction |
| » text | string | Comment |
| » contract | string | Futures contract, the field is only available for data after 2023-10-30 |
| » trade_id | string | trade id |
| » id | string | Account change record ID |
| Property | Value |
|---|---|
| type | dnw |
| type | pnl |
| type | fee |
| type | refr |
| type | fund |
| type | point_dnw |
| type | point_fee |
| type | point_refr |
| type | bonus_offset |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /futures/usdt/positions \
-H 'Accept: application/json'
GET /futures/{settle}/positions
Get user position list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| holding | query | boolean | false | Return only real positions - true, return all - false |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": "-9440",
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005",
"pos_margin_mode": "isolated",
"lever": "30"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Position] |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions_timerange'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /futures/usdt/positions_timerange?contract=BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/positions_timerange
Get user's historical position information list by time
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | true | Futures contract |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": "-9440",
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005",
"pos_margin_mode": "isolated",
"lever": "30"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [PositionTimerange] |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /futures/usdt/positions/BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/positions/{contract}
Get single position information
Get single position information from a contract. If you hold two postions in one contract market, please use this API: /futures/{settle}/dual_comp/positions/{contract}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": "-9440",
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005",
"pos_margin_mode": "isolated",
"lever": "30"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/get_leverage/BTC_USDT'
query_param = 'pos_margin_mode=isolated&dual_side=dual_long'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /futures/usdt/get_leverage/BTC_USDT?pos_margin_mode=isolated&dual_side=dual_long \
-H 'Accept: application/json'
GET /futures/{settle}/get_leverage/{contract}
Get Leverage Information for Specified Mode
Get Leverage Information for Specified Mode
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| pos_margin_mode | query | string | true | Position Margin Mode, required for split position mode, values: isolated/cross. |
| dual_side | query | string | true | dual_long - Long, dual_short - Short |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"Lever": "10"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | query leverage success | Inline |
Status Code 200
Return result includes Lever field
| Name | Type | Description |
|---|---|---|
| » Lever | string | leverage |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions/BTC_USDT/margin'
query_param = 'change=0.01'
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X POST /futures/usdt/positions/BTC_USDT/margin?change=0.01 \
-H 'Accept: application/json'
POST /futures/{settle}/positions/{contract}/margin
Update position margin
Under the new risk limit rules(https://www.gate.com/en/help/futures/futures-logic/22162), the position limit is related to the leverage you set; a lower leverage will result in a higher position limit. Please use the leverage adjustment api to adjust the position limit.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| change | query | string | true | Margin change amount, positive number increases, negative number decreases |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": "-9440",
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005",
"pos_margin_mode": "isolated",
"lever": "30"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions/BTC_USDT/leverage'
query_param = 'leverage=10'
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X POST /futures/usdt/positions/BTC_USDT/leverage?leverage=10 \
-H 'Accept: application/json'
POST /futures/{settle}/positions/{contract}/leverage
Update position leverage
⚠️ Position Mode Switching Rules:
Examples:
⚠️ Warning: Incorrect settings may cause unexpected position mode switching, affecting risk management.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| leverage | query | string | true | Set the leverage for isolated margin. When setting isolated margin leverage, the cross_leverage_limit must be empty. |
| cross_leverage_limit | query | string | false | Set the leverage for cross margin. When setting cross margin leverage, the leverage must be set to 0. |
| pid | query | integer(int32) | false | Product ID |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": "-9440",
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005",
"pos_margin_mode": "isolated",
"lever": "30"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions/BTC_USDT/set_leverage'
query_param = 'leverage=10&margin_mode=cross'
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X POST /futures/usdt/positions/BTC_USDT/set_leverage?leverage=10&margin_mode=cross \
-H 'Accept: application/json'
POST /futures/{settle}/positions/{contract}/set_leverage
Update Leverage for Specified Mode
To simplify the complex logic of the leverage interface, added a new interface for modifying leverage
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| leverage | query | string | true | Position Leverage Multiple |
| margin_mode | query | string | true | Margin Mode isolated/cross |
| dual_side | query | string | false | dual_long - Long, dual_short - Short |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": "-9440",
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005",
"pos_margin_mode": "isolated",
"lever": "30"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions/cross_mode'
query_param = ''
body='{"mode":"ISOLATED","contract":"BTC_USDT"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /futures/usdt/positions/cross_mode \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /futures/{settle}/positions/cross_mode
Switch Position Margin Mode
Body parameter
{
"mode": "ISOLATED",
"contract": "BTC_USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| body | body | FuturesPositionCrossMode | true | none |
| » mode | body | string | true | Cross/isolated margin mode. ISOLATED - isolated margin, CROSS - cross margin |
| » contract | body | string | true | Futures market |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": "-9440",
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005",
"pos_margin_mode": "isolated",
"lever": "30"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_comp/positions/cross_mode'
query_param = ''
body='{"mode":"ISOLATED","contract":"BTC_USDT"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /futures/usdt/dual_comp/positions/cross_mode \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /futures/{settle}/dual_comp/positions/cross_mode
Switch Between Cross and Isolated Margin Modes Under Hedge Mode
Body parameter
{
"mode": "ISOLATED",
"contract": "BTC_USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| body | body | UpdateDualCompPositionCrossModeRequest | true | none |
| » mode | body | string | true | Cross/isolated margin mode. ISOLATED - isolated margin, CROSS - cross margin |
| » contract | body | string | true | Futures market |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": "-9440",
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005",
"pos_margin_mode": "isolated",
"lever": "30"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Position] |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/positions/BTC_USDT/risk_limit'
query_param = 'risk_limit=1000000'
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X POST /futures/usdt/positions/BTC_USDT/risk_limit?risk_limit=1000000 \
-H 'Accept: application/json'
POST /futures/{settle}/positions/{contract}/risk_limit
Update position risk limit
Under the new risk limit rules(https://www.gate.com/en/help/futures/futures-logic/22162), the position limit is related to the leverage you set; a lower leverage will result in a higher position limit. Please use the leverage adjustment api to adjust the position limit.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| risk_limit | query | string | true | New risk limit value |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 10000,
"contract": "BTC_USDT",
"size": "-9440",
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005",
"pos_margin_mode": "isolated",
"lever": "30"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Position information | Position |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_mode'
query_param = 'dual_mode=true'
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X POST /futures/usdt/dual_mode?dual_mode=true \
-H 'Accept: application/json'
POST /futures/{settle}/dual_mode
Set position mode
The prerequisite for changing mode is that all positions have no holdings and no pending orders
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| dual_mode | query | boolean | true | Whether to enable Hedge Mode |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 1666,
"currency": "USDT",
"total": "9707.803567115145",
"unrealised_pnl": "3371.248828",
"position_margin": "38.712189181",
"order_margin": "0",
"available": "9669.091377934145",
"point": "0",
"bonus": "0",
"in_dual_mode": false,
"enable_evolved_classic": false,
"cross_initial_margin": "61855.56788525",
"cross_maintenance_margin": "682.04678105",
"cross_order_margin": "0",
"cross_unrealised_pnl": "1501.178222634128",
"cross_available": "27549.406108813951",
"cross_margin_balance": "10371.77306201952",
"cross_mmr": "797.2134",
"cross_imr": "116.6097",
"isolated_position_margin": "0",
"history": {
"dnw": "10000",
"pnl": "68.3685",
"fee": "-1.645812875",
"refr": "0",
"fund": "-358.919120009855",
"point_dnw": "0",
"point_fee": "0",
"point_refr": "0",
"bonus_dnw": "0",
"bonus_offset": "0"
},
"enable_tiered_mm": true,
"position_mode": "dual_plus",
"enable_dual_plus": true
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Updated successfully | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » total | string | Balance, only applicable to classic contract account.The balance is the sum of all historical fund flows, including historical transfers in and out, closing settlements, and transaction fee expenses, but does not include upl of positions.total = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund) |
| » unrealised_pnl | string | Unrealized PNL |
| » position_margin | string | Deprecated |
| » order_margin | string | initial margin of all open orders |
| » available | string | Refers to the available withdrawal or trading amount in per-position, specifically the per-position available balance under the unified account that includes the credit line (which incorporates trial funds; since trial funds cannot be withdrawn, the actual withdrawal amount needs to deduct the trial fund portion when processing withdrawals) |
| » point | string | Point card amount |
| » currency | string | Settlement currency |
| » in_dual_mode | boolean | Whether Hedge Mode is enabled |
| » enable_credit | boolean | Whether portfolio margin account mode is enabled |
| » position_initial_margin | string | Initial margin occupied by positions, applicable to unified account mode |
| » maintenance_margin | string | Maintenance margin occupied by positions, applicable to new classic account margin mode and unified account mode |
| » bonus | string | Bonus |
| » enable_evolved_classic | boolean | Deprecated |
| » cross_order_margin | string | Cross margin order margin, applicable to new classic account margin mode |
| » cross_initial_margin | string | Cross margin initial margin, applicable to new classic account margin mode |
| » cross_maintenance_margin | string | Cross margin maintenance margin, applicable to new classic account margin mode |
| » cross_unrealised_pnl | string | Cross margin unrealized P&L, applicable to new classic account margin mode |
| » cross_available | string | Cross margin available balance, applicable to new classic account margin mode |
| » cross_margin_balance | string | Cross margin balance, applicable to new classic account margin mode |
| » cross_mmr | string | Cross margin maintenance margin rate, applicable to new classic account margin mode |
| » cross_imr | string | Cross margin initial margin rate, applicable to new classic account margin mode |
| » isolated_position_margin | string | Isolated position margin, applicable to new classic account margin mode |
| » enable_new_dual_mode | boolean | Deprecated |
| » margin_mode | integer | Margin mode of the account 0: classic future account or Classic Spot Margin Mode of unified account; 1: Multi-Currency Margin Mode; 2: Portoforlio Margin Mode; 3: Single-Currency Margin Mode |
| » enable_tiered_mm | boolean | Whether to enable tiered maintenance margin calculation |
| » enable_dual_plus | boolean | Whether to Support Split Position Mode |
| » position_mode | string | Position Holding Mode single - Single Direction Position, dual - Dual Direction Position, dual_plus - Split Position |
| » 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 |
| »» cross_settle | string | Represents the value of profit settlement from the futures account to the spot account under Unified Account Mode. Negative values indicate settlement from futures to spot, while positive values indicate settlement from spot to futures. This value is cumulative. |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/set_position_mode'
query_param = 'position_mode=dual_plus'
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X POST /futures/usdt/set_position_mode?position_mode=dual_plus \
-H 'Accept: application/json'
POST /futures/{settle}/set_position_mode
Set Position Holding Mode, replacing the dual_mode interface
The prerequisite for changing mode is that all positions have no holdings and no pending orders
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| position_mode | query | string | true | Optional Values: single, dual, dual_plus, representing Single Direction, Dual Direction, Split Position respectively |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"user": 1666,
"currency": "USDT",
"total": "9707.803567115145",
"unrealised_pnl": "3371.248828",
"position_margin": "38.712189181",
"order_margin": "0",
"available": "9669.091377934145",
"point": "0",
"bonus": "0",
"in_dual_mode": false,
"enable_evolved_classic": false,
"cross_initial_margin": "61855.56788525",
"cross_maintenance_margin": "682.04678105",
"cross_order_margin": "0",
"cross_unrealised_pnl": "1501.178222634128",
"cross_available": "27549.406108813951",
"cross_margin_balance": "10371.77306201952",
"cross_mmr": "797.2134",
"cross_imr": "116.6097",
"isolated_position_margin": "0",
"history": {
"dnw": "10000",
"pnl": "68.3685",
"fee": "-1.645812875",
"refr": "0",
"fund": "-358.919120009855",
"point_dnw": "0",
"point_fee": "0",
"point_refr": "0",
"bonus_dnw": "0",
"bonus_offset": "0"
},
"enable_tiered_mm": true,
"position_mode": "dual_plus",
"enable_dual_plus": true
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Updated successfully | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » total | string | Balance, only applicable to classic contract account.The balance is the sum of all historical fund flows, including historical transfers in and out, closing settlements, and transaction fee expenses, but does not include upl of positions.total = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund) |
| » unrealised_pnl | string | Unrealized PNL |
| » position_margin | string | Deprecated |
| » order_margin | string | initial margin of all open orders |
| » available | string | Refers to the available withdrawal or trading amount in per-position, specifically the per-position available balance under the unified account that includes the credit line (which incorporates trial funds; since trial funds cannot be withdrawn, the actual withdrawal amount needs to deduct the trial fund portion when processing withdrawals) |
| » point | string | Point card amount |
| » currency | string | Settlement currency |
| » in_dual_mode | boolean | Whether Hedge Mode is enabled |
| » enable_credit | boolean | Whether portfolio margin account mode is enabled |
| » position_initial_margin | string | Initial margin occupied by positions, applicable to unified account mode |
| » maintenance_margin | string | Maintenance margin occupied by positions, applicable to new classic account margin mode and unified account mode |
| » bonus | string | Bonus |
| » enable_evolved_classic | boolean | Deprecated |
| » cross_order_margin | string | Cross margin order margin, applicable to new classic account margin mode |
| » cross_initial_margin | string | Cross margin initial margin, applicable to new classic account margin mode |
| » cross_maintenance_margin | string | Cross margin maintenance margin, applicable to new classic account margin mode |
| » cross_unrealised_pnl | string | Cross margin unrealized P&L, applicable to new classic account margin mode |
| » cross_available | string | Cross margin available balance, applicable to new classic account margin mode |
| » cross_margin_balance | string | Cross margin balance, applicable to new classic account margin mode |
| » cross_mmr | string | Cross margin maintenance margin rate, applicable to new classic account margin mode |
| » cross_imr | string | Cross margin initial margin rate, applicable to new classic account margin mode |
| » isolated_position_margin | string | Isolated position margin, applicable to new classic account margin mode |
| » enable_new_dual_mode | boolean | Deprecated |
| » margin_mode | integer | Margin mode of the account 0: classic future account or Classic Spot Margin Mode of unified account; 1: Multi-Currency Margin Mode; 2: Portoforlio Margin Mode; 3: Single-Currency Margin Mode |
| » enable_tiered_mm | boolean | Whether to enable tiered maintenance margin calculation |
| » enable_dual_plus | boolean | Whether to Support Split Position Mode |
| » position_mode | string | Position Holding Mode single - Single Direction Position, dual - Dual Direction Position, dual_plus - Split Position |
| » 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 |
| »» cross_settle | string | Represents the value of profit settlement from the futures account to the spot account under Unified Account Mode. Negative values indicate settlement from futures to spot, while positive values indicate settlement from spot to futures. This value is cumulative. |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_comp/positions/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /futures/usdt/dual_comp/positions/BTC_USDT \
-H 'Accept: application/json'
GET /futures/{settle}/dual_comp/positions/{contract}
Get position information in Hedge Mode
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": "-9440",
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005",
"pos_margin_mode": "isolated",
"lever": "30"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Position] |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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'
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X POST /futures/usdt/dual_comp/positions/BTC_USDT/margin?change=0.01&dual_side=dual_long \
-H 'Accept: application/json'
POST /futures/{settle}/dual_comp/positions/{contract}/margin
Update position margin in Hedge Mode
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| change | query | string | true | Margin change amount, positive number increases, negative number decreases |
| dual_side | query | string | true | Long or short position |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": "-9440",
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005",
"pos_margin_mode": "isolated",
"lever": "30"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Position] |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_comp/positions/BTC_USDT/leverage'
query_param = 'leverage=10'
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X POST /futures/usdt/dual_comp/positions/BTC_USDT/leverage?leverage=10 \
-H 'Accept: application/json'
POST /futures/{settle}/dual_comp/positions/{contract}/leverage
Update position leverage in Hedge Mode
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| leverage | query | string | true | New position leverage |
| cross_leverage_limit | query | string | false | Cross margin leverage (valid only when leverage is 0) |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": "-9440",
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005",
"pos_margin_mode": "isolated",
"lever": "30"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Position] |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/dual_comp/positions/BTC_USDT/risk_limit'
query_param = 'risk_limit=1000000'
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X POST /futures/usdt/dual_comp/positions/BTC_USDT/risk_limit?risk_limit=1000000 \
-H 'Accept: application/json'
POST /futures/{settle}/dual_comp/positions/{contract}/risk_limit
Update position risk limit in Hedge Mode
Under the new risk limit rules(https://www.gate.com/en/help/futures/futures-logic/22162), the position limit is related to the leverage you set; a lower leverage will result in a higher position limit. Please use the leverage adjustment api to adjust the position limit.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | path | string | true | Futures contract |
| risk_limit | query | string | true | New risk limit value |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"user": 10000,
"contract": "BTC_USDT",
"size": "-9440",
"leverage": "0",
"risk_limit": "100",
"leverage_max": "100",
"maintenance_rate": "0.005",
"value": "3568.62",
"margin": "4.431548146258",
"entry_price": "3779.55",
"liq_price": "99999999",
"mark_price": "3780.32",
"unrealised_pnl": "-0.000507486844",
"realised_pnl": "0.045543982432",
"pnl_pnl": "0.045543982432",
"pnl_fund": "0",
"pnl_fee": "0",
"history_pnl": "0",
"last_close_pnl": "0",
"realised_point": "0",
"history_point": "0",
"adl_ranking": 5,
"pending_orders": 16,
"close_order": {
"id": 232323,
"price": "3779",
"is_liq": false
},
"mode": "single",
"update_time": 1684994406,
"update_id": 1,
"cross_leverage_limit": "0",
"risk_limit_table": "BIG_HOT_COIN_50X_V2",
"average_maintenance_rate": "0.005",
"pos_margin_mode": "isolated",
"lever": "30"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Position] |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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":"-","order_value":"64112.2099000000005","trade_value":"64112.2099000000005","market_order_slip_ratio":"0.03","pos_margin_mode":"isolated","tpsl_tp_trigger_price":"3800","tpsl_sl_trigger_price":"3700"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /futures/usdt/orders \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-gate-exptime: 1689560679123'
POST /futures/{settle}/orders
Place futures order
size, not the number of coins. The number of coins corresponding to each contract is returned in the contract details interface
quanto_multiplierreduce_only to true can prevent the position from being penetrated when reducing the positionsize to 0 and close to truereduce_only to true
at the same time - reduce_only: Make sure to only perform position reduction operations to prevent increased positionsstp_act to determine the use of a strategy that restricts user transactions. For detailed usage, refer to the body parameter stp_actBody parameter
{
"contract": "BTC_USDT",
"size": "6024",
"iceberg": "0",
"price": "3765",
"tif": "gtc",
"text": "t-my-custom-id",
"stp_act": "-",
"order_value": "64112.2099000000005",
"trade_value": "64112.2099000000005",
"market_order_slip_ratio": "0.03",
"pos_margin_mode": "isolated",
"tpsl_tp_trigger_price": "3800",
"tpsl_sl_trigger_price": "3700"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | FuturesOrder | true | none |
| » contract | body | string | true | Futures contract |
| » size | body | string | true | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| » iceberg | body | string | false | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| » price | body | string | true | Required. Order Price; a price of 0 with tif as ioc represents a market order. |
| » close | body | boolean | false | Set as true to close the position, with size set to 0 |
| » reduce_only | body | boolean | false | Set as true to be reduce-only order |
| » tif | body | string | false | Time in force |
| » text | body | string | false | Custom order information. If not empty, must follow the rules below: |
| » auto_size | body | string | false | Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0 |
| » stp_act | body | string | false | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies |
| » pid | body | integer(int64) | false | Position ID |
| » market_order_slip_ratio | body | string | false | Custom maximum slippage rate for market orders. If not provided, the default contract settings will be used |
| » pos_margin_mode | body | string | false | Position Margin Mode isolated - Isolated Margin, cross - Cross Margin, only passed in simple split position mode |
| » action_mode | body | string | false | Processing Mode |
| » tpsl_tp_trigger_price | body | string | false | Take profit price |
| » tpsl_sl_trigger_price | body | string | false | Stop loss price |
| settle | path | string | true | Settle currency |
» tif: Time in force
» text: Custom order information. If not empty, must follow the rules below:
t-t- prefixIn addition to user-defined information, the following are internal reserved fields that identify the order source:
» stp_act: Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies
STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy.STP group, an error will be returned when passing the stp_act parameter.stp_act when placing the order, stp_act will return '-'» action_mode: Processing Mode
When placing an order, different fields are returned based on the action_mode
ACK: Asynchronous mode, returns only key order fieldsRESULT: No clearing informationFULL: Full mode (default)| Parameter | Value |
|---|---|
| » tif | gtc |
| » tif | ioc |
| » tif | poc |
| » tif | fok |
| » auto_size | close_long |
| » auto_size | close_short |
| » stp_act | co |
| » stp_act | cn |
| » stp_act | cb |
| » stp_act | - |
| settle | btc |
| settle | usdt |
Example responses
201 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": "6024",
"iceberg": "0",
"left": "6024",
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-",
"order_value": "64112.2099000000005",
"trade_value": "64112.2099000000005",
"market_order_slip_ratio": "0.03",
"pos_margin_mode": "isolated",
"tpsl_tp_trigger_price": "3800",
"tpsl_sl_trigger_price": "3700"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order details | FuturesOrder |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders'
query_param = 'status=open'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /futures/usdt/orders?status=open \
-H 'Accept: application/json'
GET /futures/{settle}/orders
Query futures order list
GET /futures/{settle}/orders_timerange.| Name | In | Type | Required | Description |
|---|---|---|---|---|
| contract | query | string | false | Futures contract, return related data only if specified |
| status | query | string | true | Query order list based on status |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| last_id | query | string | false | Use the ID of the last record in the previous list as the starting point for the next list |
| settle | path | string | true | Settle currency |
last_id: Use the ID of the last record in the previous list as the starting point for the next list
Operations based on custom IDs can only be checked when orders are pending. After orders are completed (filled/cancelled), they can be checked within 1 hour after completion. After expiration, only order IDs can be used
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": "6024",
"iceberg": "0",
"left": "6024",
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-",
"order_value": "64112.2099000000005",
"trade_value": "64112.2099000000005",
"market_order_slip_ratio": "0.03",
"pos_margin_mode": "isolated",
"tpsl_tp_trigger_price": "3800",
"tpsl_sl_trigger_price": "3700"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [FuturesOrder] |
| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | X-Pagination-Limit | integer | Limit specified for pagination | |
| 200 | X-Pagination-Offset | integer | Offset specified for pagination |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders'
query_param = ''
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
curl -X DELETE /futures/usdt/orders \
-H 'Accept: application/json' \
-H 'x-gate-exptime: 1689560679123'
DELETE /futures/{settle}/orders
Cancel all orders with 'open' status
Zero-fill orders cannot be retrieved 10 minutes after order cancellation
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| contract | query | string | false | Contract Identifier; if specified, only cancel pending orders related to this contract |
| action_mode | query | string | false | Processing Mode |
| side | query | string | false | Specify all buy orders or all sell orders, both are included if not specified. Set to bid to cancel all buy orders, set to ask to cancel all sell orders |
| exclude_reduce_only | query | boolean | false | Whether to exclude reduce-only orders |
| text | query | string | false | Remark for order cancellation |
| settle | path | string | true | Settle currency |
action_mode: Processing Mode
When placing an order, different fields are returned based on the action_mode
ACK: Asynchronous mode, returns only key order fieldsRESULT: No clearing informationFULL: Full mode (default)| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": "6024",
"iceberg": "0",
"left": "6024",
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-",
"order_value": "64112.2099000000005",
"trade_value": "64112.2099000000005",
"market_order_slip_ratio": "0.03",
"pos_margin_mode": "isolated",
"tpsl_tp_trigger_price": "3800",
"tpsl_sl_trigger_price": "3700"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Batch cancellation successful | [FuturesOrder] |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders_timerange'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /futures/usdt/orders_timerange \
-H 'Accept: application/json'
GET /futures/{settle}/orders_timerange
Query futures order list by time range
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": "6024",
"iceberg": "0",
"left": "6024",
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-",
"order_value": "64112.2099000000005",
"trade_value": "64112.2099000000005",
"market_order_slip_ratio": "0.03",
"pos_margin_mode": "isolated",
"tpsl_tp_trigger_price": "3800",
"tpsl_sl_trigger_price": "3700"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [FuturesOrderTimerange] |
| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | X-Pagination-Limit | integer | Limit specified for pagination | |
| 200 | X-Pagination-Offset | integer | Offset specified for pagination |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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":"-","order_value":"64112.2099000000005","trade_value":"64112.2099000000005","market_order_slip_ratio":"0.03","pos_margin_mode":"isolated","tpsl_tp_trigger_price":"3800","tpsl_sl_trigger_price":"3700"}]'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /futures/usdt/batch_orders \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-gate-exptime: 1689560679123'
POST /futures/{settle}/batch_orders
Place batch futures orders
succeeded field of type bool indicates whether the execution was successful or notlabel field is included to indicate the cause of the errorBody parameter
[
{
"contract": "BTC_USDT",
"size": "6024",
"iceberg": "0",
"price": "3765",
"tif": "gtc",
"text": "t-my-custom-id",
"stp_act": "-",
"order_value": "64112.2099000000005",
"trade_value": "64112.2099000000005",
"market_order_slip_ratio": "0.03",
"pos_margin_mode": "isolated",
"tpsl_tp_trigger_price": "3800",
"tpsl_sl_trigger_price": "3700"
}
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | array[FuturesOrder] | true | none |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"succeeded": true,
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": "6024",
"iceberg": "0",
"left": "6024",
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-",
"market_order_slip_ratio": "0.03"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request execution completed | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Futures order details] |
| » None | object | Futures order details |
| »» succeeded | boolean | Request execution result |
| »» label | string | Error label, only exists if execution fails |
| »» detail | string | Error detail, only present if execution failed and details need to be given |
| »» id | integer(int64) | Futures order ID |
| »» user | integer | User ID |
| »» create_time | number(double) | Creation time of order |
| »» finish_time | number(double) | Order finished time. Not returned if order is open |
| »» finish_as | string | How the order was finished: - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC, finish immediately- auto_deleveraged: finished by ADL - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because the position was closed - reduce_out: only reduce positions by excluding hard-to-fill orders - stp: cancelled because self trade prevention |
| »» status | string | Order status - open: Pending- finished: Completed |
| »» contract | string | Futures contract |
| »» size | string | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| »» iceberg | string | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| »» price | string | Order price. Price of 0 with tif set to ioc represents a market order. |
| »» is_close | boolean | Is the order to close position |
| »» is_reduce_only | boolean | Is the order reduce-only |
| »» is_liq | boolean | Is the order for liquidation |
| »» tif | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none |
| »» left | string | Unfilled quantity |
| »» fill_price | string | Fill price |
| »» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance |
| »» tkfr | string | Taker fee |
| »» mkfr | string | Maker fee |
| »» refu | integer | Referrer user ID |
| »» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy.2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter.3. If the user did not use stp_act when placing the order, stp_act will return '-'- cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled |
| »» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
| »» market_order_slip_ratio | string | The maximum slippage ratio |
| 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 | - |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders/12345'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /futures/usdt/orders/12345 \
-H 'Accept: application/json'
GET /futures/{settle}/orders/{order_id}
Query single order details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| order_id | path | string | true | The order ID returned when the order is created successfully, or the custom ID specified by the user when creating the order (i.e. the text field). When using the custom text field: |
order_id: The order ID returned when the order is created successfully, or the custom ID specified by the user when creating the order (i.e. the text field). When using the custom text field:
text; continuing to use text returns error ORDER_NOT_FOUND.text indefinitely.| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": "6024",
"iceberg": "0",
"left": "6024",
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-",
"order_value": "64112.2099000000005",
"trade_value": "64112.2099000000005",
"market_order_slip_ratio": "0.03",
"pos_margin_mode": "isolated",
"tpsl_tp_trigger_price": "3800",
"tpsl_sl_trigger_price": "3700"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order details | FuturesOrder |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders/12345'
query_param = ''
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())
curl -X DELETE /futures/usdt/orders/12345 \
-H 'Accept: application/json' \
-H 'x-gate-exptime: 1689560679123'
DELETE /futures/{settle}/orders/{order_id}
Cancel single order
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| action_mode | query | string | false | Processing Mode |
| settle | path | string | true | Settle currency |
| order_id | path | string | true | The order ID returned when the order is created successfully, or the custom ID specified by the user when creating the order (i.e. the text field). When using the custom text field: |
action_mode: Processing Mode
When placing an order, different fields are returned based on the action_mode
ACK: Asynchronous mode, returns only key order fieldsRESULT: No clearing informationFULL: Full mode (default)order_id: The order ID returned when the order is created successfully, or the custom ID specified by the user when creating the order (i.e. the text field). When using the custom text field:
text; continuing to use text returns error ORDER_NOT_FOUND.text indefinitely.| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": "6024",
"iceberg": "0",
"left": "6024",
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-",
"order_value": "64112.2099000000005",
"trade_value": "64112.2099000000005",
"market_order_slip_ratio": "0.03",
"pos_margin_mode": "isolated",
"tpsl_tp_trigger_price": "3800",
"tpsl_sl_trigger_price": "3700"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order details | FuturesOrder |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/orders/12345'
query_param = ''
body='{"size":"100","price":"54321","contract":"BTC_USDT"}'
r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X PUT /futures/usdt/orders/12345 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-gate-exptime: 1689560679123'
PUT /futures/{settle}/orders/{order_id}
Amend single order
Body parameter
{
"size": "100",
"price": "54321",
"contract": "BTC_USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | FuturesOrderAmendment | true | none |
| » size | body | string | false | New order size, including filled part. |
| » price | body | string | false | New order price |
| » amend_text | body | string | false | Custom info during order amendment |
| » text | body | string | false | Internal users can modify information in the text field. |
| » action_mode | body | string | false | Processing Mode |
| settle | path | string | true | Settle currency |
| order_id | path | string | true | The order ID returned when the order is created successfully, or the custom ID specified by the user when creating the order (i.e. the text field). When using the custom text field: |
» size: New order size, including filled part.
» action_mode: Processing Mode
When placing an order, different fields are returned based on the action_mode
ACK: Asynchronous mode, returns only key order fieldsRESULT: No clearing informationFULL: Full mode (default)order_id: The order ID returned when the order is created successfully, or the custom ID specified by the user when creating the order (i.e. the text field). When using the custom text field:
text; continuing to use text returns error ORDER_NOT_FOUND.text indefinitely.| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": "6024",
"iceberg": "0",
"left": "6024",
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-",
"order_value": "64112.2099000000005",
"trade_value": "64112.2099000000005",
"market_order_slip_ratio": "0.03",
"pos_margin_mode": "isolated",
"tpsl_tp_trigger_price": "3800",
"tpsl_sl_trigger_price": "3700"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order details | FuturesOrder |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/my_trades'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /futures/usdt/my_trades \
-H 'Accept: application/json'
GET /futures/{settle}/my_trades
Query personal trading records
By default, only supports querying data within 6 months. For older data, use GET /futures/{settle}/my_trades_timerange
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| order | query | integer(int64) | false | Futures order ID, return related data only if specified |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| last_id | query | string | false | Specify the starting point for this list based on a previously retrieved id |
last_id: Specify the starting point for this list based on a previously retrieved id
This parameter is deprecated. If you need to iterate through and retrieve more records, we recommend using 'GET /futures/{settle}/my_trades_timerange'.
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"id": 121234231,
"create_time": 1514764800.123,
"contract": "BTC_USDT",
"order_id": "21893289839",
"size": "100",
"price": "100.123",
"text": "t-123456",
"fee": "0.01",
"point_fee": "0",
"role": "taker",
"close_size": "0",
"trade_value": "28601.83"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | Fill ID |
| » create_time | number(double) | Fill Time |
| » contract | string | Futures contract |
| » order_id | string | Related order ID |
| » size | string | Trading size |
| » close_size | string | Number of closed positions: close_size=0 && size＞0 Open long position close_size=0 && size＜0 Open short position close_size>0 && size>0 && size <= close_size Close short position close_size>0 && size>0 && size > close_size Close short position and open long position close_size<0 && size<0 && size >= close_size Close long position close_size<0 && size<0 && size < close_size Close long position and open short position |
| » price | string | Fill Price |
| » role | string | Trade role. taker - taker, maker - maker |
| » text | string | Order custom information |
| » fee | string | Trade fee |
| » point_fee | string | Points used to deduct trade fee |
| » trade_value | string | trade value |
| Property | Value |
|---|---|
| role | taker |
| role | maker |
| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | X-Pagination-Limit | integer | Limit specified for pagination | |
| 200 | X-Pagination-Offset | integer | Offset specified for pagination |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/my_trades_timerange'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /futures/usdt/my_trades_timerange \
-H 'Accept: application/json'
GET /futures/{settle}/my_trades_timerange
Query personal trading records by time range
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| role | query | string | false | Query role, maker or taker |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"trade_id": "121234231",
"create_time": 1514764800.123,
"contract": "BTC_USDT",
"order_id": "21893289839",
"size": "100",
"price": "100.123",
"text": "t-123456",
"fee": "0.01",
"point_fee": "0",
"role": "taker",
"close_size": "0"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » trade_id | string | Fill ID |
| » create_time | number(double) | Fill Time |
| » contract | string | Futures contract |
| » order_id | string | Related order ID |
| » size | string | Trading size |
| » close_size | string | Number of closed positions: close_size=0 && size＞0 Open long position close_size=0 && size＜0 Open short position close_size>0 && size>0 && size <= close_size Close short position close_size>0 && size>0 && size > close_size Close short position and open long position close_size<0 && size<0 && size >= close_size Close long position close_size<0 && size<0 && size < close_size Close long position and open short position |
| » price | string | Fill Price |
| » role | string | Trade role. taker - taker, maker - maker |
| » text | string | Order custom information |
| » fee | string | Trade fee |
| » point_fee | string | Points used to deduct trade fee |
| Property | Value |
|---|---|
| role | taker |
| role | maker |
| Status | Header | Type | Format | Description |
|---|---|---|---|---|
| 200 | X-Pagination-Limit | integer | Limit specified for pagination | |
| 200 | X-Pagination-Offset | integer | Offset specified for pagination |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/position_close'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /futures/usdt/position_close \
-H 'Accept: application/json'
GET /futures/{settle}/position_close
Query position close history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
| side | query | string | false | Query side. long or shot |
| pnl | query | string | false | Query profit or loss |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"time": 1546487347,
"pnl": "0.00013",
"pnl_pnl": "0.00011",
"pnl_fund": "0.00001",
"pnl_fee": "0.00001",
"side": "long",
"contract": "BTC_USDT",
"text": "web",
"max_size": "100",
"accum_size": "100",
"first_open_time": 1546487347,
"long_price": "2026.87",
"short_price": "2544.4"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | number(double) | Position close time |
| » contract | string | Futures contract |
| » side | string | Position side - long: Long position- short: Short position |
| » pnl | string | PnL |
| » pnl_pnl | string | PNL - Position P/L |
| » pnl_fund | string | PNL - Funding Fees |
| » pnl_fee | string | PNL - Transaction Fees |
| » text | string | Source of close order. See order.text field for specific values |
| » max_size | string | Max Trade Size |
| » accum_size | string | Cumulative closed position volume |
| » first_open_time | integer(int64) | First Open Time |
| » long_price | string | When side is 'long', it indicates the opening average price; when side is 'short', it indicates the closing average price |
| » short_price | string | When side is 'long', it indicates the closing average price; when side is 'short', it indicates the opening average price |
| Property | Value |
|---|---|
| side | long |
| side | short |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/liquidates'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /futures/usdt/liquidates \
-H 'Accept: application/json'
GET /futures/{settle}/liquidates
Query liquidation history
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
| at | query | integer | false | Specify liquidation timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"time": 1548654951,
"contract": "BTC_USDT",
"size": "600",
"leverage": "25",
"margin": "0.006705256878",
"entry_price": "3536.123",
"liq_price": "3421.54",
"mark_price": "3420.27",
"order_id": 317393847,
"order_price": "3405",
"fill_price": "3424",
"left": "0"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | integer(int64) | Liquidation time |
| » contract | string | Futures contract |
| » leverage | string | Position leverage. Not returned in public endpoints |
| » size | string | 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 | string | Liquidation order maker size |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/auto_deleverages'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /futures/usdt/auto_deleverages \
-H 'Accept: application/json'
GET /futures/{settle}/auto_deleverages
Query ADL auto-deleveraging order information
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| limit | query | integer | false | Maximum number of records returned in a single list |
| offset | query | integer | false | List offset, starting from 0 |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
| at | query | integer | false | Specify auto-deleveraging timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"time": 1675841679,
"contract": "ACH_USDT",
"order_id": 73873128,
"user": 1666,
"cross_leverage_limit": "0",
"leverage": "0",
"entry_price": "2649.648633636364",
"fill_price": "2790.8082",
"position_size": "1",
"trade_size": "-10"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » time | integer(int64) | Automatic deleveraging time |
| » user | integer(int64) | User ID |
| » order_id | integer(int64) | Order ID. Order IDs before 2023-02-20 are null |
| » contract | string | Futures contract |
| » leverage | string | leverage for isolated margin. 0 means cross margin. For leverage of cross margin, please refer to cross_leverage_limit. |
| » cross_leverage_limit | string | leverage for cross margin |
| » entry_price | string | Average entry price |
| » fill_price | string | Average fill price |
| » trade_size | string | Trading size |
| » position_size | string | Positions after auto-deleveraging |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/countdown_cancel_all'
query_param = ''
body='{"timeout":30,"contract":"BTC_USDT"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /futures/usdt/countdown_cancel_all \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /futures/{settle}/countdown_cancel_all
Countdown cancel orders
Heartbeat detection for contract orders: When the user-set timeout time is reached, if neither the existing countdown is canceled nor a new countdown is set, the relevant contract orders will be automatically canceled.
This API can be called repeatedly to or cancel the countdown.
Usage example: Repeatedly call this API at 30-second intervals, setting the timeout to 30 (seconds) each time.
If this API is not called again within 30 seconds, all open orders on your specified market will be automatically canceled.
If the timeout is set to 0 within 30 seconds, the countdown timer will terminate, and the automatic order cancellation function will be disabled.
Body parameter
{
"timeout": 30,
"contract": "BTC_USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | CountdownCancelAllFuturesTask | true | none |
| » timeout | body | integer(int32) | true | Countdown time in seconds |
| » contract | body | string | false | Futures contract |
| settle | path | string | true | Settle currency |
» timeout: Countdown time in seconds At least 5 seconds, 0 means cancel countdown
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"triggerTime": "1660039145000"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Countdown set successfully | TriggerTime |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/fee'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /futures/usdt/fee \
-H 'Accept: application/json'
GET /futures/{settle}/fee
Query futures market trading fee rates
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Futures contract, return related data only if specified |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"1INCH_USDT": {
"taker_fee": "0.00025",
"maker_fee": "-0.00010"
},
"AAVE_USDT": {
"taker_fee": "0.00025",
"maker_fee": "-0.00010"
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
FuturesFee
| Name | Type | Description |
|---|---|---|
| » additionalProperties | object | The returned result is a map type, where the key represents the market and taker and maker fee rates |
| »» taker_fee | string | Taker fee |
| »» maker_fee | string | maker fee |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/batch_cancel_orders'
query_param = ''
body='["1","2","3"]'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /futures/usdt/batch_cancel_orders \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-gate-exptime: 1689560679123'
POST /futures/{settle}/batch_cancel_orders
Cancel batch orders by specified ID list
Multiple different order IDs can be specified. A maximum of 20 records can be cancelled in one request
Body parameter
[
"1",
"2",
"3"
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | CancelBatchFutureOrdersRequest | true | none |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"user_id": 111,
"id": "123456",
"succeeded": true,
"message": ""
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Order cancellation operation completed | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » FutureCancelOrderResult | object | Order cancellation result |
| »» id | string | Order ID |
| »» user_id | integer(int64) | User ID |
| »» succeeded | boolean | Whether cancellation succeeded |
| »» message | string | Error description when cancellation fails, empty if successful |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/batch_amend_orders'
query_param = ''
body='[{"order_id":121212,"amend_text":"batch amend text","size":"100","price":"54321"}]'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /futures/usdt/batch_amend_orders \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-gate-exptime: 1689560679123'
POST /futures/{settle}/batch_amend_orders
Batch modify orders by specified IDs
Multiple different order IDs can be specified. A maximum of 10 orders can be modified in one request
Body parameter
[
{
"order_id": 121212,
"amend_text": "batch amend text",
"size": "100",
"price": "54321"
}
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | array[BatchAmendOrderReq] | true | none |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"succeeded": true,
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": "6024",
"iceberg": "0",
"left": "6024",
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-",
"market_order_slip_ratio": "0.03"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Request execution completed | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Futures order details] |
| » None | object | Futures order details |
| »» succeeded | boolean | Request execution result |
| »» label | string | Error label, only exists if execution fails |
| »» detail | string | Error detail, only present if execution failed and details need to be given |
| »» id | integer(int64) | Futures order ID |
| »» user | integer | User ID |
| »» create_time | number(double) | Creation time of order |
| »» finish_time | number(double) | Order finished time. Not returned if order is open |
| »» finish_as | string | How the order was finished: - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC, finish immediately- auto_deleveraged: finished by ADL - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because the position was closed - reduce_out: only reduce positions by excluding hard-to-fill orders - stp: cancelled because self trade prevention |
| »» status | string | Order status - open: Pending- finished: Completed |
| »» contract | string | Futures contract |
| »» size | string | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| »» iceberg | string | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| »» price | string | Order price. Price of 0 with tif set to ioc represents a market order. |
| »» is_close | boolean | Is the order to close position |
| »» is_reduce_only | boolean | Is the order reduce-only |
| »» is_liq | boolean | Is the order for liquidation |
| »» tif | string | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none |
| »» left | string | Unfilled quantity |
| »» fill_price | string | Fill price |
| »» text | string | User defined information. If not empty, must follow the rules below: 1. prefixed with t-2. no longer than 28 bytes without t- prefix3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance |
| »» tkfr | string | Taker fee |
| »» mkfr | string | Maker fee |
| »» refu | integer | Referrer user ID |
| »» stp_act | string | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy.2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter.3. If the user did not use stp_act when placing the order, stp_act will return '-'- cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled |
| »» stp_id | integer | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
| »» market_order_slip_ratio | string | The maximum slippage ratio |
| 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 | - |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/risk_limit_table'
query_param = 'table_id=CYBER_USDT_20241122'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /futures/usdt/risk_limit_table?table_id=CYBER_USDT_20241122 \
-H 'Accept: application/json'
GET /futures/{settle}/risk_limit_table
Query risk limit table by table_id
Just pass table_id
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| table_id | query | string | true | Risk limit table ID |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
[
{
"tier": 1,
"risk_limit": "10000",
"initial_rate": "0.025",
"maintenance_rate": "0.015",
"leverage_max": "40",
"deduction": "0"
},
{
"tier": 2,
"risk_limit": "30000",
"initial_rate": "0.03333",
"maintenance_rate": "0.02",
"leverage_max": "30",
"deduction": "50"
},
{
"tier": 3,
"risk_limit": "50000",
"initial_rate": "0.04545",
"maintenance_rate": "0.03",
"leverage_max": "22",
"deduction": "350"
},
{
"tier": 4,
"risk_limit": "70000",
"initial_rate": "0.05555",
"maintenance_rate": "0.04",
"leverage_max": "18",
"deduction": "850"
},
{
"tier": 5,
"risk_limit": "100000",
"initial_rate": "0.1",
"maintenance_rate": "0.085",
"leverage_max": "10",
"deduction": "4000"
},
{
"tier": 6,
"risk_limit": "150000",
"initial_rate": "0.333",
"maintenance_rate": "0.3",
"leverage_max": "3",
"deduction": "25500"
},
{
"tier": 7,
"risk_limit": "200000",
"initial_rate": "0.5",
"maintenance_rate": "0.45",
"leverage_max": "2",
"deduction": "48000"
},
{
"tier": 8,
"risk_limit": "300000",
"initial_rate": "1",
"maintenance_rate": "0.95",
"leverage_max": "1",
"deduction": "148000"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Information for each tier of the gradient risk limit table |
| »» tier | integer(int) | Tier |
| »» risk_limit | string | Position risk limit |
| »» initial_rate | string | Initial margin rate |
| »» maintenance_rate | string | The maintenance margin rate of the first tier of risk limit sheet |
| »» leverage_max | string | Maximum leverage |
| »» deduction | string | Maintenance margin quick calculation deduction amount |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/bbo_orders'
query_param = ''
body='{"contract":"PI_USDT","level":8,"direction":"sell","size":1}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /futures/usdt/bbo_orders \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-gate-exptime: 1689560679123'
POST /futures/{settle}/bbo_orders
Level-based BBO Contract Order Placement
Compared to the futures trading order placement interface (futures/{settle}/orders), it adds the level and direction parameters.
Body parameter
{
"contract": "PI_USDT",
"level": 8,
"direction": "sell",
"size": 1
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| x-gate-exptime | header | string | false | Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected |
| body | body | FuturesBBOOrder | true | none |
| » contract | body | string | true | Futures contract |
| » size | body | integer(int64) | true | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| » direction | body | string | true | Direction: 'sell' fetches the bid side, 'buy' fetches the ask side. |
| » iceberg | body | integer(int64) | false | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| » level | body | integer(int64) | true | Level: maximum 20 levels |
| » close | body | boolean | false | Set as true to close the position, with size set to 0 |
| » reduce_only | body | boolean | false | Set as true to be reduce-only order |
| » tif | body | string | false | Time in force |
| » text | body | string | false | Order Custom Information: Users can set custom IDs via this field. Custom fields must meet the following conditions: |
| » auto_size | body | string | false | Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0 |
| » stp_act | body | string | false | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies |
| » pid | body | integer(int64) | false | Position ID |
| settle | path | string | true | Settle currency |
» tif: Time in force
» text: Order Custom Information: Users can set custom IDs via this field. Custom fields must meet the following conditions:
t-t-, length cannot exceed 28 bytesIn addition to user custom information, the following are internal reserved fields identifying order sources:
» stp_act: Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies
STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy.STP group, an error will be returned when passing the stp_act parameter.stp_act when placing the order, stp_act will return '-'| Parameter | Value |
|---|---|
| » tif | gtc |
| » tif | ioc |
| » tif | poc |
| » tif | fok |
| » auto_size | close_long |
| » auto_size | close_short |
| » stp_act | co |
| » stp_act | cn |
| » stp_act | cb |
| » stp_act | - |
| settle | btc |
| settle | usdt |
Example responses
201 Response
{
"id": 15675394,
"user": 100000,
"contract": "BTC_USDT",
"create_time": 1546569968,
"size": "6024",
"iceberg": "0",
"left": "6024",
"price": "3765",
"fill_price": "0",
"mkfr": "-0.00025",
"tkfr": "0.00075",
"tif": "gtc",
"refu": 0,
"is_reduce_only": false,
"is_close": false,
"is_liq": false,
"text": "t-my-custom-id",
"status": "finished",
"finish_time": 1514764900,
"finish_as": "cancelled",
"stp_id": 0,
"stp_act": "-",
"amend_text": "-",
"order_value": "64112.2099000000005",
"trade_value": "64112.2099000000005",
"market_order_slip_ratio": "0.03",
"pos_margin_mode": "isolated",
"tpsl_tp_trigger_price": "3800",
"tpsl_sl_trigger_price": "3700"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Order details | FuturesOrder |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/autoorder/v1/trail/create'
query_param = ''
body='{"contract":"BTC_USDT","amount":"10","activation_price":"50000","is_gte":true,"price_type":1,"price_offset":"0.1%","reduce_only":false,"text":"apiv4"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /futures/usdt/autoorder/v1/trail/create \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /futures/{settle}/autoorder/v1/trail/create
Create trail order
Body parameter
{
"contract": "BTC_USDT",
"amount": "10",
"activation_price": "50000",
"is_gte": true,
"price_type": 1,
"price_offset": "0.1%",
"reduce_only": false,
"text": "apiv4"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | CreateTrailOrder | true | none |
| » contract | body | string | true | Contract name |
| » amount | body | string | true | Trading quantity in contracts, positive for buy, negative for sell |
| » activation_price | body | string | false | Activation price, 0 means trigger immediately |
| » is_gte | body | boolean | false | true: activate when market price >= activation price, false: <= activation price |
| » price_type | body | integer(int32) | false | Activation price type: 1-latest price, 2-index price, 3-mark price |
| » price_offset | body | string | false | Callback ratio or price distance, e.g., 0.1 or 0.1% |
| » reduce_only | body | boolean | false | Whether reduce only |
| » position_related | body | boolean | false | Whether bound to a position (if position_related = true (position-related), then reduce_only must also be true) |
| » text | body | string | false | Order custom information, optional field. Used to identify the order source or set a user-defined ID. |
| » pos_margin_mode | body | string | false | Position margin mode: isolated/cross |
| » position_mode | body | string | false | Position mode: single, dual, and dual_plus |
| settle | path | string | true | Settle currency |
» text: Order custom information, optional field. Used to identify the order source or set a user-defined ID.
If non-empty, it must meet one of the following rules:
apiv4: API callt-t- must not exceed 28 bytes in lengtht-my-order-001, t-trail_2024.01Note: User-defined fields must not conflict with internal reserved fields.
| Parameter | Value |
|---|---|
| » price_type | 1 |
| » price_type | 2 |
| » price_type | 3 |
| settle | btc |
| settle | usdt |
Example responses
201 Response
{
"code": 0,
"message": "ok",
"data": {
"id": "63648"
},
"timestamp": 1769583885680
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created (opens new window) | Created successfully | CreateTrailOrderResponse |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/autoorder/v1/trail/stop'
query_param = ''
body='{"id":123456789}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /futures/usdt/autoorder/v1/trail/stop \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /futures/{settle}/autoorder/v1/trail/stop
Terminate trail order
Body parameter
{
"id": 123456789
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | StopTrailOrder | true | none |
| » id | body | integer(int64) | false | Order ID, if ID is specified, text is not needed |
| » text | body | string | false | Custom text, if ID is not specified, terminate based on user_id and text |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"id": "63585",
"user_id": "2124438083",
"contract": "BTC_USDT",
"settle": "usdt",
"amount": "10",
"is_gte": false,
"activation_price": "0",
"price_type": 1,
"price_offset": "5%",
"text": "apiv4",
"reduce_only": false,
"position_related": false,
"created_at": "1769569837",
"activated_at": "1769569837",
"finished_at": "1769578529",
"reason": "",
"suborder_text": "apiv4-auto-trail-o-1d29",
"is_dual_mode": false,
"trigger_price": "91047.4",
"suborder_id": "94294117233225616",
"side_label": "买入",
"original_status": 4,
"status": "finished",
"user": "2124438083",
"create_time": "1769569837",
"active_time": "1769569837",
"finish_time": "1769578529",
"position_side_output": "买入",
"updated_at": "1769578529",
"extremum_price": "86711.9",
"status_code": "success",
"created_at_precise": "1769569837778000",
"finished_at_precise": "1769578529853294",
"activated_at_precise": "1769569837976010",
"status_label": "已完成",
"pos_margin_mode": "",
"position_mode": "single",
"error_label": "",
"leverage": ""
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Termination successful | Inline |
Status Code 200
TrailOrderResponse
| Name | Type | Description |
|---|---|---|
| » order | object | Trail order details |
| »» id | integer(int64) | Order ID |
| »» user_id | integer(int64) | User ID |
| »» user | integer(int64) | User ID |
| »» contract | string | Contract name |
| »» settle | string | Settle currency |
| »» amount | string | Trading quantity in contracts, positive for buy, negative for sell |
| »» is_gte | boolean | true: activate when market price >= activation price, false: <= activation price |
| »» activation_price | string | Activation price, 0 means trigger immediately |
| »» price_type | integer(int32) | Activation price type: 0-unknown, 1-latest price, 2-index price, 3-mark price |
| »» price_offset | string | Callback ratio or price distance, e.g., 0.1 or 0.1% |
| »» text | string | Custom field |
| »» reduce_only | boolean | Reduce Position Only |
| »» position_related | boolean | Whether bound to position |
| »» created_at | integer(int64) | Created time |
| »» activated_at | integer(int64) | Activation time |
| »» finished_at | integer(int64) | End time |
| »» create_time | integer(int64) | Created time |
| »» active_time | integer(int64) | Activation time |
| »» finish_time | integer(int64) | End time |
| »» reason | string | End reason |
| »» suborder_text | string | Sub-order text field |
| »» is_dual_mode | boolean | Whether dual position mode when creating order |
| »» trigger_price | string | Trigger price |
| »» suborder_id | integer(int64) | Sub-order ID |
| »» side_label | string | Order direction label: long/short/open long/open short/close long/close short |
| »» original_status | integer(int32) | Order status |
| »» status | string | Simplified order status: open/finished |
| »» position_side_output | string | Same as side_label, client requires consistency with other order types |
| »» updated_at | integer(int64) | Update time |
| »» extremum_price | string | Extremum price |
| »» status_code | string | Status code value |
| »» created_at_precise | string | Creation time (high precision, seconds.microseconds format) |
| »» finished_at_precise | string | End time (high precision, seconds.microseconds format) |
| »» activated_at_precise | string | Activation time (high precision, seconds.microseconds format) |
| »» status_label | string | Status internationalization label (translated status text) |
| »» pos_margin_mode | string | Position margin mode: isolated/cross |
| »» position_mode | string | Position mode: single, dual, and dual_plus |
| »» error_label | string | Error label |
| »» leverage | string | leverage |
| Property | Value |
|---|---|
| price_type | 0 |
| price_type | 1 |
| price_type | 2 |
| price_type | 3 |
| status | open |
| status | finished |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/autoorder/v1/trail/stop_all'
query_param = ''
body='{"contract":"BTC_USDT"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /futures/usdt/autoorder/v1/trail/stop_all \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /futures/{settle}/autoorder/v1/trail/stop_all
Batch terminate trail orders
Body parameter
{
"contract": "BTC_USDT"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | StopAllTrailOrders | true | none |
| » contract | body | string | false | Contract name |
| » related_position | body | integer(int32) | false | Associated position, if provided, only cancel orders associated with this position, 1-long, 2-short |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| » related_position | 1 |
| » related_position | 2 |
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"orders": [
{
"id": "123456789",
"user_id": "100000",
"user": "100000",
"contract": "BTC_USDT",
"settle": "usdt",
"amount": "10",
"is_gte": true,
"activation_price": "50000",
"price_type": 1,
"price_offset": "0.1%",
"text": "t-my-trail-order-1",
"reduce_only": false,
"position_related": false,
"created_at": "1546569968",
"create_time": "1546569968",
"activated_at": "1546570000",
"active_time": "1546570000",
"finished_at": "0",
"finish_time": "0",
"reason": "",
"suborder_text": "",
"is_dual_mode": false,
"trigger_price": "50000",
"suborder_id": "0",
"side_label": "开多",
"position_side_output": "开多",
"original_status": 1,
"status": "open",
"updated_at": "1546569968",
"extremum_price": "50100",
"status_code": "pending",
"created_at_precise": "1546569968.123456",
"finished_at_precise": "",
"activated_at_precise": "",
"status_label": "待激活",
"pos_margin_mode": "isolated",
"position_mode": "single",
"error_label": "",
"leverage": "10"
},
{
"id": "123456790",
"user_id": "100000",
"user": "100000",
"contract": "ETH_USDT",
"settle": "usdt",
"amount": "-5",
"is_gte": false,
"activation_price": "3000",
"price_type": 2,
"price_offset": "0.2%",
"text": "t-my-trail-order-2",
"reduce_only": true,
"position_related": true,
"created_at": "1546569970",
"create_time": "1546569970",
"activated_at": "1546570100",
"active_time": "1546570100",
"finished_at": "1546571000",
"finish_time": "1546571000",
"reason": "success",
"suborder_text": "t-suborder-1",
"is_dual_mode": true,
"trigger_price": "3000",
"suborder_id": "987654321",
"side_label": "平空",
"position_side_output": "平空",
"original_status": 4,
"status": "finished",
"updated_at": "1546571000",
"extremum_price": "2990",
"status_code": "success",
"created_at_precise": "1546569970.654321",
"finished_at_precise": "1546571000.123456",
"activated_at_precise": "1546570100.789012",
"status_label": "完成全部委托量",
"pos_margin_mode": "cross",
"position_mode": "dual",
"error_label": "",
"leverage": "20"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Termination successful | Inline |
Status Code 200
TrailOrderListResponse
| Name | Type | Description |
|---|---|---|
| » orders | array | none |
| »» TrailOrder | object | Trail order details |
| »»» id | integer(int64) | Order ID |
| »»» user_id | integer(int64) | User ID |
| »»» user | integer(int64) | User ID |
| »»» contract | string | Contract name |
| »»» settle | string | Settle currency |
| »»» amount | string | Trading quantity in contracts, positive for buy, negative for sell |
| »»» is_gte | boolean | true: activate when market price >= activation price, false: <= activation price |
| »»» activation_price | string | Activation price, 0 means trigger immediately |
| »»» price_type | integer(int32) | Activation price type: 0-unknown, 1-latest price, 2-index price, 3-mark price |
| »»» price_offset | string | Callback ratio or price distance, e.g., 0.1 or 0.1% |
| »»» text | string | Custom field |
| »»» reduce_only | boolean | Reduce Position Only |
| »»» position_related | boolean | Whether bound to position |
| »»» created_at | integer(int64) | Created time |
| »»» activated_at | integer(int64) | Activation time |
| »»» finished_at | integer(int64) | End time |
| »»» create_time | integer(int64) | Created time |
| »»» active_time | integer(int64) | Activation time |
| »»» finish_time | integer(int64) | End time |
| »»» reason | string | End reason |
| »»» suborder_text | string | Sub-order text field |
| »»» is_dual_mode | boolean | Whether dual position mode when creating order |
| »»» trigger_price | string | Trigger price |
| »»» suborder_id | integer(int64) | Sub-order ID |
| »»» side_label | string | Order direction label: long/short/open long/open short/close long/close short |
| »»» original_status | integer(int32) | Order status |
| »»» status | string | Simplified order status: open/finished |
| »»» position_side_output | string | Same as side_label, client requires consistency with other order types |
| »»» updated_at | integer(int64) | Update time |
| »»» extremum_price | string | Extremum price |
| »»» status_code | string | Status code value |
| »»» created_at_precise | string | Creation time (high precision, seconds.microseconds format) |
| »»» finished_at_precise | string | End time (high precision, seconds.microseconds format) |
| »»» activated_at_precise | string | Activation time (high precision, seconds.microseconds format) |
| »»» status_label | string | Status internationalization label (translated status text) |
| »»» pos_margin_mode | string | Position margin mode: isolated/cross |
| »»» position_mode | string | Position mode: single, dual, and dual_plus |
| »»» error_label | string | Error label |
| »»» leverage | string | leverage |
| Property | Value |
|---|---|
| price_type | 0 |
| price_type | 1 |
| price_type | 2 |
| price_type | 3 |
| status | open |
| status | finished |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/autoorder/v1/trail/list'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /futures/usdt/autoorder/v1/trail/list \
-H 'Accept: application/json'
GET /futures/{settle}/autoorder/v1/trail/list
Get trail order list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Contract name |
| is_finished | query | boolean | false | Whether historical order |
| start_at | query | integer(int64) | false | Start time of time range |
| end_at | query | integer(int64) | false | End time of time range |
| page_num | query | integer(int32) | false | Page number, starting from 1 |
| page_size | query | integer(int32) | false | Number of items per page |
| sort_by | query | integer(int32) | false | Common sort field, 1-creation time, 2-end time |
| hide_cancel | query | boolean | false | Hide cancelled orders |
| related_position | query | integer(int32) | false | Associated position, if provided, only return orders associated with this position, 1-long, 2-short |
| sort_by_trigger | query | boolean | false | Sort by trigger price and activation price, easy to trigger or activate first, only for current orders associated with positions |
| reduce_only | query | integer(int32) | false | Whether reduce only, 1-yes, 2-no |
| side | query | integer(int32) | false | Direction, 1-long position, 2-short position |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| sort_by | 1 |
| sort_by | 2 |
| related_position | 1 |
| related_position | 2 |
| reduce_only | 1 |
| reduce_only | 2 |
| side | 1 |
| side | 2 |
Example responses
200 Response
{
"orders": [
{
"id": "123456789",
"user_id": "100000",
"user": "100000",
"contract": "BTC_USDT",
"settle": "usdt",
"amount": "10",
"is_gte": true,
"activation_price": "50000",
"price_type": 1,
"price_offset": "0.1%",
"text": "t-my-trail-order-1",
"reduce_only": false,
"position_related": false,
"created_at": "1546569968",
"create_time": "1546569968",
"activated_at": "1546570000",
"active_time": "1546570000",
"finished_at": "0",
"finish_time": "0",
"reason": "",
"suborder_text": "",
"is_dual_mode": false,
"trigger_price": "50000",
"suborder_id": "0",
"side_label": "开多",
"position_side_output": "开多",
"original_status": 1,
"status": "open",
"updated_at": "1546569968",
"extremum_price": "50100",
"status_code": "pending",
"created_at_precise": "1546569968.123456",
"finished_at_precise": "",
"activated_at_precise": "",
"status_label": "待激活",
"pos_margin_mode": "isolated",
"position_mode": "single",
"error_label": "",
"leverage": "10"
},
{
"id": "123456790",
"user_id": "100000",
"user": "100000",
"contract": "ETH_USDT",
"settle": "usdt",
"amount": "-5",
"is_gte": false,
"activation_price": "3000",
"price_type": 2,
"price_offset": "0.2%",
"text": "t-my-trail-order-2",
"reduce_only": true,
"position_related": true,
"created_at": "1546569970",
"create_time": "1546569970",
"activated_at": "1546570100",
"active_time": "1546570100",
"finished_at": "1546571000",
"finish_time": "1546571000",
"reason": "success",
"suborder_text": "t-suborder-1",
"is_dual_mode": true,
"trigger_price": "3000",
"suborder_id": "987654321",
"side_label": "平空",
"position_side_output": "平空",
"original_status": 4,
"status": "finished",
"updated_at": "1546571000",
"extremum_price": "2990",
"status_code": "success",
"created_at_precise": "1546569970.654321",
"finished_at_precise": "1546571000.123456",
"activated_at_precise": "1546570100.789012",
"status_label": "完成全部委托量",
"pos_margin_mode": "cross",
"position_mode": "dual",
"error_label": "",
"leverage": "20"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
TrailOrderListResponse
| Name | Type | Description |
|---|---|---|
| » orders | array | none |
| »» TrailOrder | object | Trail order details |
| »»» id | integer(int64) | Order ID |
| »»» user_id | integer(int64) | User ID |
| »»» user | integer(int64) | User ID |
| »»» contract | string | Contract name |
| »»» settle | string | Settle currency |
| »»» amount | string | Trading quantity in contracts, positive for buy, negative for sell |
| »»» is_gte | boolean | true: activate when market price >= activation price, false: <= activation price |
| »»» activation_price | string | Activation price, 0 means trigger immediately |
| »»» price_type | integer(int32) | Activation price type: 0-unknown, 1-latest price, 2-index price, 3-mark price |
| »»» price_offset | string | Callback ratio or price distance, e.g., 0.1 or 0.1% |
| »»» text | string | Custom field |
| »»» reduce_only | boolean | Reduce Position Only |
| »»» position_related | boolean | Whether bound to position |
| »»» created_at | integer(int64) | Created time |
| »»» activated_at | integer(int64) | Activation time |
| »»» finished_at | integer(int64) | End time |
| »»» create_time | integer(int64) | Created time |
| »»» active_time | integer(int64) | Activation time |
| »»» finish_time | integer(int64) | End time |
| »»» reason | string | End reason |
| »»» suborder_text | string | Sub-order text field |
| »»» is_dual_mode | boolean | Whether dual position mode when creating order |
| »»» trigger_price | string | Trigger price |
| »»» suborder_id | integer(int64) | Sub-order ID |
| »»» side_label | string | Order direction label: long/short/open long/open short/close long/close short |
| »»» original_status | integer(int32) | Order status |
| »»» status | string | Simplified order status: open/finished |
| »»» position_side_output | string | Same as side_label, client requires consistency with other order types |
| »»» updated_at | integer(int64) | Update time |
| »»» extremum_price | string | Extremum price |
| »»» status_code | string | Status code value |
| »»» created_at_precise | string | Creation time (high precision, seconds.microseconds format) |
| »»» finished_at_precise | string | End time (high precision, seconds.microseconds format) |
| »»» activated_at_precise | string | Activation time (high precision, seconds.microseconds format) |
| »»» status_label | string | Status internationalization label (translated status text) |
| »»» pos_margin_mode | string | Position margin mode: isolated/cross |
| »»» position_mode | string | Position mode: single, dual, and dual_plus |
| »»» error_label | string | Error label |
| »»» leverage | string | leverage |
| Property | Value |
|---|---|
| price_type | 0 |
| price_type | 1 |
| price_type | 2 |
| price_type | 3 |
| status | open |
| status | finished |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/autoorder/v1/trail/detail'
query_param = 'id=0'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /futures/usdt/autoorder/v1/trail/detail?id=0 \
-H 'Accept: application/json'
GET /futures/{settle}/autoorder/v1/trail/detail
Get trail order details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| id | query | integer(int64) | true | Order ID |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"code": 0,
"message": "ok",
"data": {
"order": {
"id": "63585",
"user_id": "2124438083",
"contract": "BTC_USDT",
"settle": "usdt",
"amount": "10",
"is_gte": false,
"activation_price": "0",
"price_type": 1,
"price_offset": "5%",
"text": "apiv4",
"reduce_only": false,
"position_related": false,
"created_at": "1769569837",
"activated_at": "1769569837",
"finished_at": "1769578529",
"reason": "",
"suborder_text": "apiv4-auto-trail-o-1d29",
"is_dual_mode": false,
"trigger_price": "91047.4",
"suborder_id": "94294117233225616",
"side_label": "买入",
"original_status": 4,
"status": "finished",
"user": "2124438083",
"create_time": "1769569837",
"active_time": "1769569837",
"finish_time": "1769578529",
"position_side_output": "买入",
"updated_at": "1769578529",
"extremum_price": "86711.9",
"status_code": "success",
"created_at_precise": "1769569837778000",
"finished_at_precise": "1769578529853294",
"activated_at_precise": "1769569837976010",
"status_label": "已完成",
"pos_margin_mode": "",
"position_mode": "single",
"error_label": "",
"leverage": ""
}
},
"timestamp": 1769584936814
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | TrailOrderDetailResponse |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/autoorder/v1/trail/update'
query_param = ''
body='{"id":123456789,"amount":"20","activation_price":"51000","price_offset":"0.2%"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /futures/usdt/autoorder/v1/trail/update \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /futures/{settle}/autoorder/v1/trail/update
Update trail order
Body parameter
{
"id": 123456789,
"amount": "20",
"activation_price": "51000",
"price_offset": "0.2%"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | UpdateTrailOrder | true | none |
| » id | body | integer(int64) | true | Order ID |
| » amount | body | string | false | Total trading quantity in contracts, positive for buy, negative for sell, 0 means no modification |
| » activation_price | body | string | false | Activation price, 0 means trigger immediately, empty means no modification |
| » is_gte_str | body | string | false | true: activate when market price >= activation price, false: <= activation price, empty means no modification |
| » price_type | body | integer(int32) | false | Activation price type, not provided or 0 means no modification, 1-latest price, 2-index price, 3-mark price |
| » price_offset | body | string | false | Callback ratio or price distance, e.g., 0.1 or 0.1%; empty means no modification |
| settle | path | string | true | Settle currency |
| Parameter | Value |
|---|---|
| » price_type | 0 |
| » price_type | 1 |
| » price_type | 2 |
| » price_type | 3 |
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"id": "63585",
"user_id": "2124438083",
"contract": "BTC_USDT",
"settle": "usdt",
"amount": "10",
"is_gte": false,
"activation_price": "0",
"price_type": 1,
"price_offset": "5%",
"text": "apiv4",
"reduce_only": false,
"position_related": false,
"created_at": "1769569837",
"activated_at": "1769569837",
"finished_at": "1769578529",
"reason": "",
"suborder_text": "apiv4-auto-trail-o-1d29",
"is_dual_mode": false,
"trigger_price": "91047.4",
"suborder_id": "94294117233225616",
"side_label": "买入",
"original_status": 4,
"status": "finished",
"user": "2124438083",
"create_time": "1769569837",
"active_time": "1769569837",
"finish_time": "1769578529",
"position_side_output": "买入",
"updated_at": "1769578529",
"extremum_price": "86711.9",
"status_code": "success",
"created_at_precise": "1769569837778000",
"finished_at_precise": "1769578529853294",
"activated_at_precise": "1769569837976010",
"status_label": "已完成",
"pos_margin_mode": "",
"position_mode": "single",
"error_label": "",
"leverage": ""
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Updated successfully | Inline |
Status Code 200
TrailOrderResponse
| Name | Type | Description |
|---|---|---|
| » order | object | Trail order details |
| »» id | integer(int64) | Order ID |
| »» user_id | integer(int64) | User ID |
| »» user | integer(int64) | User ID |
| »» contract | string | Contract name |
| »» settle | string | Settle currency |
| »» amount | string | Trading quantity in contracts, positive for buy, negative for sell |
| »» is_gte | boolean | true: activate when market price >= activation price, false: <= activation price |
| »» activation_price | string | Activation price, 0 means trigger immediately |
| »» price_type | integer(int32) | Activation price type: 0-unknown, 1-latest price, 2-index price, 3-mark price |
| »» price_offset | string | Callback ratio or price distance, e.g., 0.1 or 0.1% |
| »» text | string | Custom field |
| »» reduce_only | boolean | Reduce Position Only |
| »» position_related | boolean | Whether bound to position |
| »» created_at | integer(int64) | Created time |
| »» activated_at | integer(int64) | Activation time |
| »» finished_at | integer(int64) | End time |
| »» create_time | integer(int64) | Created time |
| »» active_time | integer(int64) | Activation time |
| »» finish_time | integer(int64) | End time |
| »» reason | string | End reason |
| »» suborder_text | string | Sub-order text field |
| »» is_dual_mode | boolean | Whether dual position mode when creating order |
| »» trigger_price | string | Trigger price |
| »» suborder_id | integer(int64) | Sub-order ID |
| »» side_label | string | Order direction label: long/short/open long/open short/close long/close short |
| »» original_status | integer(int32) | Order status |
| »» status | string | Simplified order status: open/finished |
| »» position_side_output | string | Same as side_label, client requires consistency with other order types |
| »» updated_at | integer(int64) | Update time |
| »» extremum_price | string | Extremum price |
| »» status_code | string | Status code value |
| »» created_at_precise | string | Creation time (high precision, seconds.microseconds format) |
| »» finished_at_precise | string | End time (high precision, seconds.microseconds format) |
| »» activated_at_precise | string | Activation time (high precision, seconds.microseconds format) |
| »» status_label | string | Status internationalization label (translated status text) |
| »» pos_margin_mode | string | Position margin mode: isolated/cross |
| »» position_mode | string | Position mode: single, dual, and dual_plus |
| »» error_label | string | Error label |
| »» leverage | string | leverage |
| Property | Value |
|---|---|
| price_type | 0 |
| price_type | 1 |
| price_type | 2 |
| price_type | 3 |
| status | open |
| status | finished |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/autoorder/v1/trail/change_log'
query_param = 'id=0'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /futures/usdt/autoorder/v1/trail/change_log?id=0 \
-H 'Accept: application/json'
GET /futures/{settle}/autoorder/v1/trail/change_log
Get trail order user modification records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| id | query | integer(int64) | true | Order ID |
| page_num | query | integer(int32) | false | Page number, starting from 1 |
| page_size | query | integer(int32) | false | Number of items per page |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"change_log": [
{
"updated_at": 1546569968,
"amount": "10",
"is_gte": true,
"activation_price": "50000",
"price_type": 1,
"price_offset": "0.1%",
"is_create": true
},
{
"updated_at": 1546570000,
"amount": "20",
"is_gte": true,
"activation_price": "51000",
"price_type": 1,
"price_offset": "0.2%",
"is_create": false
},
{
"updated_at": 1546570100,
"amount": "20",
"is_gte": true,
"activation_price": "51000",
"price_type": 2,
"price_offset": "0.2%",
"is_create": false
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | TrailOrderChangeLogResponse |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/autoorder/v1/chase/create'
query_param = ''
body='{"contract":"string","settle":"string","amount":"string","price_limit":"string","offset_limit":"string","reduce_only":true,"text":"string","is_dual_mode":true,"price_type":0,"price_gap_type":0,"price_gap_value":"string","pos_margin_mode":"string","position_mode":"string"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /futures/usdt/autoorder/v1/chase/create \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /futures/{settle}/autoorder/v1/chase/create
Create a chase order
Body parameter
{
"contract": "string",
"settle": "string",
"amount": "string",
"price_limit": "string",
"offset_limit": "string",
"reduce_only": true,
"text": "string",
"is_dual_mode": true,
"price_type": 0,
"price_gap_type": 0,
"price_gap_value": "string",
"pos_margin_mode": "string",
"position_mode": "string"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| body | body | CreateChaseOrderReq | true | none |
| » contract | body | string | true | Contract name; server-side converted to uppercase |
| » settle | body | string | false | Settle currency, overridden by the path parameter and converted to lowercase |
| » amount | body | string | true | Total order size in contracts, decimal string. Positive for buy, negative for sell. Cannot be 0 |
| » price_limit | body | string | true | 最高追逐价，合法十进制字符串；未设置限价时请传 "0" |
| » offset_limit | body | string | false | Maximum chasing distance from the best price, mutually exclusive with price_limit |
| » reduce_only | body | boolean | false | Whether reduce only |
| » text | body | string | false | Optional custom tag |
| » is_dual_mode | body | boolean | false | Whether dual-position mode is enabled |
| » price_type | body | integer(int64) | false | Price type: 1 best bid/ask, 2 distance from best bid/ask |
| » price_gap_type | body | integer(int64) | false | Used when price_type == 2: 1 absolute price gap, 2 percentage |
| » price_gap_value | body | string | false | Price gap value paired with price_gap_type |
| » pos_margin_mode | body | string | false | Position margin mode, e.g. isolated or cross |
| » position_mode | body | string | false | Position mode (e.g. single, dual, dual_plus) |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"id": "string"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | CreateChaseOrderResp |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/autoorder/v1/chase/stop'
query_param = ''
body='{"id":"string","text":"string","settle":"string"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /futures/usdt/autoorder/v1/chase/stop \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /futures/{settle}/autoorder/v1/chase/stop
Stop a chase order
Body parameter
{
"id": "string",
"text": "string",
"settle": "string"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| body | body | StopChaseOrderReq | true | none |
| » id | body | string | false | Order ID. Either id or text must be provided |
| » text | body | string | false | Custom text. Required only when id is 0 or omitted |
| » settle | body | string | false | Overridden by the path parameter |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"order": {
"id": "string",
"user": "string",
"contract": "string",
"settle": "string",
"amount": "string",
"price_limit": "string",
"reduce_only": true,
"text": "string",
"create_time": 0,
"finish_time": 0,
"original_status": 0,
"status": "string",
"reason": "string",
"fill_amount": "string",
"average_fill_price": "string",
"suborder_id": "string",
"is_dual_mode": true,
"side_label": "string",
"position_side_output": "string",
"chase_price": "string",
"interval_sec": 0,
"updated_at": 0,
"suborder_price": "string",
"suborder_ongoing": true,
"suborder_finish_as": "string",
"price_type": 0,
"price_gap_type": "string",
"price_gap_value": "string",
"status_code": "string",
"create_time_precise": "string",
"finish_time_precise": "string",
"pos_margin_mode": "string",
"position_mode": "string",
"leverage": "string",
"error_label": "string"
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | StopChaseOrderResp |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/autoorder/v1/chase/stop_all'
query_param = ''
body='{"contract":"string","settle":"string","pos_margin_mode":"string"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /futures/usdt/autoorder/v1/chase/stop_all \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /futures/{settle}/autoorder/v1/chase/stop_all
Stop chase orders in batch
Body parameter
{
"contract": "string",
"settle": "string",
"pos_margin_mode": "string"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| body | body | StopAllChaseOrdersReq | true | none |
| » contract | body | string | false | Optional contract name |
| » settle | body | string | false | Overridden by the path parameter |
| » pos_margin_mode | body | string | false | Optional margin mode |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"orders": [
{
"id": "string",
"user": "string",
"contract": "string",
"settle": "string",
"amount": "string",
"price_limit": "string",
"reduce_only": true,
"text": "string",
"create_time": 0,
"finish_time": 0,
"original_status": 0,
"status": "string",
"reason": "string",
"fill_amount": "string",
"average_fill_price": "string",
"suborder_id": "string",
"is_dual_mode": true,
"side_label": "string",
"position_side_output": "string",
"chase_price": "string",
"interval_sec": 0,
"updated_at": 0,
"suborder_price": "string",
"suborder_ongoing": true,
"suborder_finish_as": "string",
"price_type": 0,
"price_gap_type": "string",
"price_gap_value": "string",
"status_code": "string",
"create_time_precise": "string",
"finish_time_precise": "string",
"pos_margin_mode": "string",
"position_mode": "string",
"leverage": "string",
"error_label": "string"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | StopAllChaseOrdersResp |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/autoorder/v1/chase/list'
query_param = 'sort_by=1'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /futures/usdt/autoorder/v1/chase/list?sort_by=1 \
-H 'Accept: application/json'
GET /futures/{settle}/autoorder/v1/chase/list
List chase orders
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| contract | query | string | false | Optional. When non-empty, must be a valid contract (validated against the market cache for the path settle); server-side converted to uppercase |
| is_finished | query | boolean | false | true to query finished orders, false to query in-progress orders |
| start_at | query | integer(int64) | false | Lower time bound for the history list, paired with end_at. Required when is_finished is true |
| end_at | query | integer(int64) | false | Upper time bound for the history list, paired with start_at. Required when is_finished is true |
| page_num | query | integer(uint32) | false | Page number, starting from 1 |
| page_size | query | integer(uint32) | false | Page size; must be between 1 and 100 |
| sort_by | query | integer | true | Sort field: 1 ORDER_SORT_CREATED_AT, 2 ORDER_SORT_FINISHED_AT; cannot be 0 |
| hide_cancel | query | boolean | false | When true, cancelled orders are hidden in the list |
| reduce_only | query | integer | false | OptionalBool: 0 unknown, 1 true, 2 false; used to filter by reduce-only flag |
| side | query | integer | false | Filter by long/short side: 1 long, 2 short |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
| sort_by | 1 |
| sort_by | 2 |
| reduce_only | 0 |
| reduce_only | 1 |
| reduce_only | 2 |
| side | 0 |
| side | 1 |
| side | 2 |
Example responses
200 Response
{
"orders": [
{
"id": "string",
"user": "string",
"contract": "string",
"settle": "string",
"amount": "string",
"price_limit": "string",
"reduce_only": true,
"text": "string",
"create_time": 0,
"finish_time": 0,
"original_status": 0,
"status": "string",
"reason": "string",
"fill_amount": "string",
"average_fill_price": "string",
"suborder_id": "string",
"is_dual_mode": true,
"side_label": "string",
"position_side_output": "string",
"chase_price": "string",
"interval_sec": 0,
"updated_at": 0,
"suborder_price": "string",
"suborder_ongoing": true,
"suborder_finish_as": "string",
"price_type": 0,
"price_gap_type": "string",
"price_gap_value": "string",
"status_code": "string",
"create_time_precise": "string",
"finish_time_precise": "string",
"pos_margin_mode": "string",
"position_mode": "string",
"leverage": "string",
"error_label": "string"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | GetChaseOrdersResp |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/futures/usdt/autoorder/v1/chase/detail'
query_param = 'id=string'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /futures/usdt/autoorder/v1/chase/detail?id=string \
-H 'Accept: application/json'
GET /futures/{settle}/autoorder/v1/chase/detail
Get chase order detail
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| settle | path | string | true | Settle currency |
| id | query | string | true | Order ID, must be a non-zero positive integer |
| Parameter | Value |
|---|---|
| settle | btc |
| settle | usdt |
Example responses
200 Response
{
"order": {
"id": "string",
"user": "string",
"contract": "string",
"settle": "string",
"amount": "string",
"price_limit": "string",
"reduce_only": true,
"text": "string",
"create_time": 0,
"finish_time": 0,
"original_status": 0,
"status": "string",
"reason": "string",
"fill_amount": "string",
"average_fill_price": "string",
"suborder_id": "string",
"is_dual_mode": true,
"side_label": "string",
"position_side_output": "string",
"chase_price": "string",
"interval_sec": 0,
"updated_at": 0,
"suborder_price": "string",
"suborder_ongoing": true,
"suborder_finish_as": "string",
"price_type": 0,
"price_gap_type": "string",
"price_gap_value": "string",
"status_code": "string",
"create_time_precise": "string",
"finish_time_precise": "string",
"pos_margin_mode": "string",
"position_mode": "string",
"leverage": "string",
"error_label": "string"
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | GetChaseOrderDetailResp |
Isolated Margin
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/accounts'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /margin/accounts \
-H 'Accept: application/json'
GET /margin/accounts
Margin account list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Currency pair |
Example responses
200 Response
[
{
"currency_pair": "BTC_USDT",
"account_type": "mmr",
"leverage": "20",
"locked": false,
"risk": "1.3318",
"mmr": "16.5949188975473644",
"base": {
"currency": "BTC",
"available": "0.047060413211",
"locked": "0",
"borrowed": "0.047233",
"interest": "0"
},
"quote": {
"currency": "USDT",
"available": "1234",
"locked": "0",
"borrowed": "0",
"interest": "0"
}
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Margin account information for a trading pair. base corresponds to base currency account information, quote corresponds to quote currency account information] |
| » None | object | Margin account information for a trading pair. base corresponds to base currency account information, quote corresponds to quote currency account information |
| »» currency_pair | string | Currency pair |
| »» account_type | string | Account Type mmr: maintenance margin rate account;inactive: market not activated |
| »» leverage | string | User's current market leverage multiplier |
| »» locked | boolean | Whether the account is locked |
| »» risk | string | Deprecated |
| »» mmr | string | Current Maintenance Margin Rate of the account |
| »» base | object | Currency account information |
| »»» currency | string | Currency name |
| »»» available | string | Amount available for margin trading, available = margin + borrowed |
| »»» locked | string | Frozen funds, such as amounts already placed in margin market for order trading |
| »»» borrowed | string | Borrowed funds |
| »»» interest | string | Unpaid interest |
| »» quote | object | Currency account information |
| »»» currency | string | Currency name |
| »»» available | string | Amount available for margin trading, available = margin + borrowed |
| »»» locked | string | Frozen funds, such as amounts already placed in margin market for order trading |
| »»» borrowed | string | Borrowed funds |
| »»» interest | string | Unpaid interest |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/account_book'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /margin/account_book \
-H 'Accept: application/json'
GET /margin/account_book
Query margin account balance change history
Currently only provides transfer history to and from margin accounts. Query time range cannot exceed 30 days
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query history for specified currency. If currency is specified, currency_pair must also be specified. |
| currency_pair | query | string | false | Specify margin account currency pair. Used in combination with currency. Ignored if currency is not specified |
| type | query | string | false | Query by specified account change type. If not specified, all change types will be included. |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records returned in a single list |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Example responses
200 Response
[
{
"id": "123456",
"time": "1547633726",
"time_ms": 1547633726123,
"currency": "BTC",
"currency_pair": "BTC_USDT",
"change": "1.03",
"balance": "4.59316525194"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | string | Balance change record ID |
| » time | string | Account change timestamp |
| » time_ms | integer(int64) | The timestamp of the change (in milliseconds) |
| » currency | string | Currency changed |
| » currency_pair | string | Account trading pair |
| » change | string | Amount changed. Positive value means transferring in, while negative out |
| » balance | string | Balance after change |
| » type | string | Account book type. Please refer to account book type for more detail |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/funding_accounts'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /margin/funding_accounts \
-H 'Accept: application/json'
GET /margin/funding_accounts
Funding account list
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
Example responses
200 Response
[
{
"currency": "BTC",
"available": "1.238",
"locked": "0",
"lent": "3.32",
"total_lent": "3.32"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency name |
| » available | string | Available assets to lend, which is identical to spot account available |
| » locked | string | Locked amount. i.e. amount in open loans |
| » lent | string | Outstanding loan amount yet to be repaid |
| » total_lent | string | Amount used for lending. total_lent = lent + locked |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/auto_repay'
query_param = 'status=on'
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X POST /margin/auto_repay?status=on \
-H 'Accept: application/json'
POST /margin/auto_repay
Update user auto repayment settings
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| status | query | string | true | Whether to enable auto repayment: on - enabled, off - disabled |
Example responses
200 Response
{
"status": "on"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | User's current auto repayment settings | Inline |
Status Code 200
AutoRepaySetting
| Name | Type | Description |
|---|---|---|
| » status | string | Auto repayment status: on - enabled, off - disabled |
| Property | Value |
|---|---|
| status | on |
| status | off |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/auto_repay'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /margin/auto_repay \
-H 'Accept: application/json'
GET /margin/auto_repay
Query user auto repayment settings
Example responses
200 Response
{
"status": "on"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | User's current auto repayment settings | Inline |
Status Code 200
AutoRepaySetting
| Name | Type | Description |
|---|---|---|
| » status | string | Auto repayment status: on - enabled, off - disabled |
| Property | Value |
|---|---|
| status | on |
| status | off |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/transferable'
query_param = 'currency=BTC'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /margin/transferable?currency=BTC \
-H 'Accept: application/json'
GET /margin/transferable
Get maximum transferable amount for isolated margin
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Query by specified currency name |
| currency_pair | query | string | false | Currency pair |
Example responses
200 Response
{
"currency": "ETH",
"currency_pair": "ETH_USDT",
"amount": "10000"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | MarginTransferable |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /margin/uni/currency_pairs \
-H 'Accept: application/json'
GET /margin/uni/currency_pairs
List lending markets
Example responses
200 Response
[
{
"currency_pair": "AE_USDT",
"base_min_borrow_amount": "100",
"quote_min_borrow_amount": "100",
"leverage": "3"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Currency pair of the loan] |
| » None | object | Currency pair of the loan |
| »» currency_pair | string | Currency pair |
| »» base_min_borrow_amount | string | Minimum borrow amount of base currency |
| »» quote_min_borrow_amount | string | Minimum borrow amount of quote currency |
| »» leverage | string | Position leverage |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /margin/uni/currency_pairs/AE_USDT \
-H 'Accept: application/json'
GET /margin/uni/currency_pairs/{currency_pair}
Get lending market details
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | path | string | true | Currency pair |
Example responses
200 Response
{
"currency_pair": "AE_USDT",
"base_min_borrow_amount": "100",
"quote_min_borrow_amount": "100",
"leverage": "3"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
Currency pair of the loan
| Name | Type | Description |
|---|---|---|
| » currency_pair | string | Currency pair |
| » base_min_borrow_amount | string | Minimum borrow amount of base currency |
| » quote_min_borrow_amount | string | Minimum borrow amount of quote currency |
| » leverage | string | Position leverage |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/uni/estimate_rate'
query_param = 'currencies=BTC,GT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /margin/uni/estimate_rate?currencies=BTC,GT \
-H 'Accept: application/json'
GET /margin/uni/estimate_rate
Estimate interest rate for isolated margin currencies
Interest rates change hourly based on lending depth, so completely accurate rates cannot be provided.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currencies | query | array[string] | true | Array of currency names to query, maximum 10 |
Example responses
200 Response
{
"BTC": "0.000002",
"GT": "0.000001"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
Estimate current hourly lending rates, returned by currency
| Name | Type | Description |
|---|---|---|
| » additionalProperties | string | none |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /margin/uni/loans \
-H 'Content-Type: application/json'
POST /margin/uni/loans
Borrow or repay
Body parameter
{
"currency": "BTC",
"amount": "0.1",
"type": "borrow",
"currency_pair": "BTC_USDT",
"repaid_all": false
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Currency |
| » type | body | string | true | Loan Type margin: margin borrowing |
| » amount | body | string | true | Borrow or repayment amount |
| » repaid_all | body | boolean | false | Full repayment. For repayment operations only. When true, overrides amount and repays the full amount |
| » currency_pair | body | string | true | Currency pair |
| Parameter | Value |
|---|---|
| » type | borrow |
| » type | repay |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Operation successful | None |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/uni/loans'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /margin/uni/loans \
-H 'Accept: application/json'
GET /margin/uni/loans
Query loans
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Currency pair |
| currency | query | string | false | Query by specified currency name |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records returned in a single list |
Example responses
200 Response
[
{
"currency": "USDT",
"currency_pari": "GT_USDT",
"amount": "1",
"type": "margin",
"change_time": 1673247054000,
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Borrowing] |
| » None | object | Borrowing |
| »» currency | string | Currency |
| »» currency_pair | string | Currency pair |
| »» amount | string | Amount to Repay |
| »» type | string | Loan type: platform borrowing - platform, margin borrowing - margin |
| »» create_time | integer(int64) | Created time |
| »» update_time | integer(int64) | Last Update Time |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/uni/loan_records'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /margin/uni/loan_records \
-H 'Accept: application/json'
GET /margin/uni/loan_records
Query loan records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| type | query | string | false | Type: borrow - borrow, repay - repay |
| currency | query | string | false | Query by specified currency name |
| currency_pair | query | string | false | Currency pair |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records returned in a single list |
| Parameter | Value |
|---|---|
| type | borrow |
| type | repay |
Example responses
200 Response
[
{
"type": "borrow",
"currency_pair": "AE_USDT",
"currency": "USDT",
"amount": "1000",
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Borrowing Records |
| »» type | string | Type: borrow - borrow, repay - repay |
| »» currency_pair | string | Currency pair |
| »» currency | string | Currency |
| »» amount | string | Borrow or repayment amount |
| »» create_time | integer(int64) | Created time |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/uni/interest_records'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /margin/uni/interest_records \
-H 'Accept: application/json'
GET /margin/uni/interest_records
Query interest deduction records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Currency pair |
| currency | query | string | false | Query by specified currency name |
| page | query | integer(int32) | false | Page number |
| limit | query | integer | false | Maximum number of records returned in a single list |
| from | query | integer(int64) | false | Start timestamp |
| to | query | integer(int64) | false | Termination Timestamp |
from: Start timestamp
Specify start time, time format is Unix timestamp. If not specified, it defaults to (the data start time of the time range actually returned by to and limit)
to: Termination Timestamp
Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
Example responses
200 Response
[
{
"status": 1,
"currency_pair": "BTC_USDT",
"currency": "USDT",
"actual_rate": "0.00000236",
"interest": "0.00006136",
"type": "platform",
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Interest Deduction Record] |
| » None | object | Interest Deduction Record |
| »» currency | string | Currency name |
| »» currency_pair | string | Currency pair |
| »» actual_rate | string | Actual Rate |
| »» interest | string | Interest |
| »» status | integer | Status: 0 - fail, 1 - success |
| »» type | string | Loan Type margin: margin borrowing |
| »» create_time | integer(int64) | Created time |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/uni/borrowable'
query_param = 'currency=BTC¤cy_pair=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /margin/uni/borrowable?currency=BTC¤cy_pair=BTC_USDT \
-H 'Accept: application/json'
GET /margin/uni/borrowable
Query maximum borrowable amount by currency
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Query by specified currency name |
| currency_pair | query | string | true | Currency pair |
Example responses
200 Response
{
"currency": "AE",
"borrowable": "1123.344",
"currency_pair": "AE_USDT"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | MaxUniBorrowable |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/user/loan_margin_tiers'
query_param = 'currency_pair=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /margin/user/loan_margin_tiers?currency_pair=BTC_USDT \
-H 'Accept: application/json'
GET /margin/user/loan_margin_tiers
Query user's own leverage lending tiers in current market
Query the borrowing tier margin requirements of a specific spot market.For more details about borrowing tier margin requirements, please refer to Underlying Logic of the New Isolated Margin System（https://www.gate.com/en/help/trade/margin-trading/42357）
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | true | Currency pair |
Example responses
200 Response
[
{
"tier_amount": "100",
"mmr": "0.9",
"leverage": "1"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Market gradient information] |
| » None | object | Market gradient information |
| »» upper_limit | string | Maximum borrowing limit. Determined by the leverage you set; the lower the leverage, the larger the borrowing limit. |
| »» mmr | string | Maintenance margin rate.Under tiered margin requirements(https://www.gate.com/en/help/trade/margin-trading/42357), the maintenance margin rate is a composite value. |
| »» leverage | string | the maximum permissible leverage given to the current debt level; the higher the debt level, the lower the maximum leverage. |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/loan_margin_tiers'
query_param = 'currency_pair=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /margin/loan_margin_tiers?currency_pair=BTC_USDT \
-H 'Accept: application/json'
GET /margin/loan_margin_tiers
Query current market leverage lending tiers
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | true | Currency pair |
Example responses
200 Response
[
{
"tier_amount": "100",
"mmr": "0.9",
"leverage": "1"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Market gradient information] |
| » None | object | Market gradient information |
| »» upper_limit | string | Maximum borrowing limit. Determined by the leverage you set; the lower the leverage, the larger the borrowing limit. |
| »» mmr | string | Maintenance margin rate.Under tiered margin requirements(https://www.gate.com/en/help/trade/margin-trading/42357), the maintenance margin rate is a composite value. |
| »» leverage | string | the maximum permissible leverage given to the current debt level; the higher the debt level, the lower the maximum leverage. |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/leverage/user_market_setting'
query_param = ''
body='{"currency_pair":"BTC_USDT","leverage":"10"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /margin/leverage/user_market_setting \
-H 'Content-Type: application/json'
POST /margin/leverage/user_market_setting
Set user market leverage multiplier
Body parameter
{
"currency_pair": "BTC_USDT",
"leverage": "10"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency_pair | body | string | false | Market |
| » leverage | body | string | true | Position leverage |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Set successfully | None |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/margin/user/account'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /margin/user/account \
-H 'Accept: application/json'
GET /margin/user/account
Query user's isolated margin account list
Supports querying risk ratio isolated accounts and margin ratio isolated accounts
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency_pair | query | string | false | Currency pair |
Example responses
200 Response
[
{
"currency_pair": "BTC_USDT",
"account_type": "mmr",
"leverage": "20",
"locked": false,
"risk": "1.3318",
"mmr": "16.5949188975473644",
"base": {
"currency": "BTC",
"available": "0.047060413211",
"locked": "0",
"borrowed": "0.047233",
"interest": "0"
},
"quote": {
"currency": "USDT",
"available": "1234",
"locked": "0",
"borrowed": "0",
"interest": "0"
}
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Margin account information for a trading pair. base corresponds to base currency account information, quote corresponds to quote currency account information] |
| » None | object | Margin account information for a trading pair. base corresponds to base currency account information, quote corresponds to quote currency account information |
| »» currency_pair | string | Currency pair |
| »» account_type | string | Account Type mmr: maintenance margin rate account;inactive: market not activated |
| »» leverage | string | User's current market leverage multiplier |
| »» locked | boolean | Whether the account is locked |
| »» risk | string | Deprecated |
| »» mmr | string | Current Maintenance Margin Rate of the account |
| »» base | object | Currency account information |
| »»» currency | string | Currency name |
| »»» available | string | Amount available for margin trading, available = margin + borrowed |
| »»» locked | string | Frozen funds, such as amounts already placed in margin market for order trading |
| »»» borrowed | string | Borrowed funds |
| »»» interest | string | Unpaid interest |
| »» quote | object | Currency account information |
| »»» currency | string | Currency name |
| »»» available | string | Amount available for margin trading, available = margin + borrowed |
| »»» locked | string | Frozen funds, such as amounts already placed in margin market for order trading |
| »»» borrowed | string | Borrowed funds |
| »»» interest | string | Unpaid interest |
Retrieve user account information
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/detail'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /account/detail \
-H 'Accept: application/json'
GET /account/detail
Retrieve user account information
Example responses
200 Response
{
"user_id": 1667201533,
"ip_whitelist": [
"127.0.0.1"
],
"currency_pairs": [
"USDT_BTC"
],
"key": {
"mode": 1
},
"tier": 2,
"copy_trading_role": 1
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | AccountDetail |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/main_keys'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /account/main_keys \
-H 'Accept: application/json'
GET /account/main_keys
Query All Main Account Key Information
Example responses
200 Response
[
{
"state": 1,
"mode": 1,
"name": "test1",
"user_id": 1,
"perms": [
{
"name": "account",
"read_only": false
},
{
"name": "spot",
"read_only": false
}
],
"ip_whitelist": [],
"currency_pairs": [
"BTC_USD",
"ETH_USD"
],
"key": "c5dcfbf1f3a7*****",
"created_at": 1753030929,
"update_at": 1756300567,
"last_access": 1753030929
},
{
"state": 1,
"mode": 1,
"name": "test2",
"user_id": 1,
"perms": [
{
"name": "spot",
"read_only": false
},
{
"name": "account",
"read_only": false
}
],
"ip_whitelist": [],
"currency_pairs": [
"BTC_USD",
"ETH_USD"
],
"key": "52fd0035f665*****",
"created_at": 1753897991,
"update_at": 1756300567,
"last_access": 1753897991
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | AccountKeyInfo |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/rate_limit'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /account/rate_limit \
-H 'Accept: application/json'
GET /account/rate_limit
Get user transaction rate limit information
This interface is not yet open for use
Example responses
200 Response
[
{
"type": "spot",
"tier": "1",
"ratio": "0",
"main_ratio": "0",
"updated_at": "1728230400"
},
{
"type": "futures",
"tier": "1",
"ratio": "0",
"main_ratio": "0",
"updated_at": "1728230400"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Successfully retrieved | [Inline] |
Status Code 200
AccountRateLimit
| Name | Type | Description |
|---|---|---|
| AccountRateLimit | array | Account rate limit |
| » tier | string | Frequency limit level (For detailed frequency limit rules, see Transaction ratio frequency limit) |
| » ratio | string | Fill rate |
| » main_ratio | string | Total fill ratio of main account |
| » updated_at | string | Update time |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/stp_groups'
query_param = ''
body='{"name":"stp_name"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /account/stp_groups \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /account/stp_groups
Create STP user group
Only the main account is allowed to create a new STP user group
Body parameter
{
"name": "stp_name"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » id | body | integer(int64) | false | STP Group ID |
| » name | body | string | true | STP Group name |
| » creator_id | body | integer(int64) | false | Creator ID |
| » create_time | body | integer(int64) | false | Created time |
Example responses
200 Response
{
"id": 123435,
"name": "group",
"create_time": 1548000000,
"creator_id": 10000
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | User added successfully, returning current users in the STP group | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » id | integer(int64) | STP Group ID |
| » name | string | STP Group name |
| » creator_id | integer(int64) | Creator ID |
| » create_time | integer(int64) | Created time |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/stp_groups'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /account/stp_groups \
-H 'Accept: application/json'
GET /account/stp_groups
Query STP user groups created by the user
Only query STP user groups created by the current main account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| name | query | string | false | Fuzzy search by name |
Example responses
200 Response
[
{
"id": 123435,
"name": "group",
"create_time": 1548000000,
"creator_id": 10000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » id | integer(int64) | STP Group ID |
| » name | string | STP Group name |
| » creator_id | integer(int64) | Creator ID |
| » create_time | integer(int64) | Created time |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/stp_groups/1/users'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /account/stp_groups/1/users \
-H 'Accept: application/json'
GET /account/stp_groups/{stp_id}/users
Query users in the STP user group
Only the main account that created this STP group can query the account ID list of the current STP group
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| stp_id | path | integer(int64) | true | STP Group ID |
Example responses
200 Response
[
{
"user_id": 10000,
"stp_id": 1,
"create_time": 1548000000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » user_id | integer(int64) | User ID |
| » stp_id | integer(int64) | STP Group ID |
| » create_time | integer(int64) | Created time |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/stp_groups/1/users'
query_param = ''
body='[1,2,3]'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /account/stp_groups/1/users \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /account/stp_groups/{stp_id}/users
Add users to the STP user group
Body parameter
[
1,
2,
3
]
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| stp_id | path | integer(int64) | true | STP Group ID |
| body | body | AddSTPGroupUsersRequest | true | User ID |
Example responses
200 Response
[
{
"user_id": 10000,
"stp_id": 1,
"create_time": 1548000000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | User added successfully, returning current users in the STP group | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » user_id | integer(int64) | User ID |
| » stp_id | integer(int64) | STP Group ID |
| » create_time | integer(int64) | Created time |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/stp_groups/1/users'
query_param = 'user_id=1'
r = requests.request('DELETE', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X DELETE /account/stp_groups/1/users?user_id=1 \
-H 'Accept: application/json'
DELETE /account/stp_groups/{stp_id}/users
Delete users from the STP user group
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| stp_id | path | integer(int64) | true | STP Group ID |
| user_id | query | integer(int64) | true | STP user IDs, multiple IDs can be separated by commas |
Example responses
200 Response
[
{
"user_id": 10000,
"stp_id": 1,
"create_time": 1548000000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Users deleted successfully, returns current users in the STP group | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | none |
| » user_id | integer(int64) | User ID |
| » stp_id | integer(int64) | STP Group ID |
| » create_time | integer(int64) | Created time |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/debit_fee'
query_param = ''
body='{"enabled":true}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /account/debit_fee \
-H 'Content-Type: application/json'
POST /account/debit_fee
Configure GT fee deduction
Enable or disable GT fee deduction for the current account
Body parameter
{
"enabled": true
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | DebitFee | true | none |
| » enabled | body | boolean | true | Whether GT fee deduction is enabled |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | None |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/account/debit_fee'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /account/debit_fee \
-H 'Accept: application/json'
GET /account/debit_fee
Query GT fee deduction configuration
Query the GT fee deduction configuration for the current account
Example responses
200 Response
{
"enabled": true
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Success | DebitFee |
Unified account
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/accounts'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /unified/accounts \
-H 'Accept: application/json'
GET /unified/accounts
Get unified account information
The assets of each currency in the account will be adjusted according to their liquidity, defined by corresponding adjustment coefficients, and then uniformly converted to USD to calculate the total asset value and position value of the account.
For specific formulas, please refer to Margin Formula
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
| sub_uid | query | string | false | Sub account user ID |
Example responses
200 Response
{
"user_id": 10001,
"locked": false,
"balances": {
"ETH": {
"available": "0",
"freeze": "0",
"borrowed": "0.075393666654",
"negative_liab": "0",
"futures_pos_liab": "0",
"equity": "1016.1",
"total_freeze": "0",
"total_liab": "0",
"spot_in_use": "1.111"
},
"POINT": {
"available": "9999999999.017023138734",
"freeze": "0",
"borrowed": "0",
"negative_liab": "0",
"futures_pos_liab": "0",
"equity": "12016.1",
"total_freeze": "0",
"total_liab": "0",
"spot_in_use": "12"
},
"USDT": {
"available": "0.00000062023",
"freeze": "0",
"borrowed": "0",
"negative_liab": "0",
"futures_pos_liab": "0",
"equity": "16.1",
"total_freeze": "0",
"total_liab": "0",
"spot_in_use": "12"
}
},
"total": "230.94621713",
"borrowed": "161.66395521",
"total_initial_margin": "1025.0524665088",
"total_margin_balance": "3382495.944473949183",
"total_maintenance_margin": "205.01049330176",
"total_initial_margin_rate": "3299.827135672679",
"total_maintenance_margin_rate": "16499.135678363399",
"total_available_margin": "3381470.892007440383",
"unified_account_total": "3381470.892007440383",
"unified_account_total_liab": "0",
"unified_account_total_equity": "100016.1",
"leverage": "2",
"spot_order_loss": "12",
"spot_hedge": false
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » mode | string | Unified account mode: - classic: Classic account mode - multi_currency: Multi-currency margin mode - portfolio: Portfolio margin mode - single_currency: Single-currency margin mode |
| » user_id | integer(int64) | User ID |
| » refresh_time | integer(int64) | Last refresh time |
| » locked | boolean | Whether the account is locked, valid in cross-currency margin/combined margin mode, false in other modes such as single-currency margin mode |
| » balances | object | none |
| »» UnifiedBalance | object | none |
| »»» available | string | Cross available balance, deducted futures isolated margin occupation and frozen amount (futures isolated occupation, i.e. futures isolated balance), effective in single-currency/multi-currency/portfolio margin mode. |
| »»» freeze | string | Frozen amount, effective in single-currency/multi-currency/portfolio margin mode |
| »»» borrowed | string | Borrowed amount, valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
| »»» negative_liab | string | Negative balance borrowing, valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
| »»» futures_pos_liab | string | Contract opening position borrowing currency (abandoned, to be offline field) |
| »»» equity | string | Currency equity amount (cross), effective in single-currency/multi-currency/portfolio margin mode |
| »»» total_freeze | string | Total frozen (deprecated, to be removed) |
| »»» total_liab | string | Total borrowed amount, valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
| »»» spot_in_use | string | The amount of spot hedging is valid in the combined margin mode, and is 0 in other margin modes such as single currency and cross-currency margin modes |
| »»» funding | string | Uniloan financial management amount, effective when turned on as a unified account margin switch |
| »»» funding_version | string | Funding version |
| »»» cross_balance | string | Full margin balance is valid in single currency margin mode, and is 0 in other modes such as cross currency margin/combined margin mode |
| »»» iso_balance | string | Futures isolated balance, effective in single-currency and multi-currency margin mode, 0 in portfolio margin mode |
| »»» im | string | Cross initial margin, only effective for USDT in single-currency margin mode, 0 in multi-currency/portfolio margin mode |
| »»» mm | string | Cross maintenance margin, only effective for USDT in single-currency margin mode, 0 in multi-currency/portfolio margin mode |
| »»» imr | string | Cross initial margin rate, only effective for USDT in single-currency margin mode, 0 in multi-currency/portfolio margin mode |
| »»» mmr | string | Cross maintenance margin rate, only effective for USDT in single-currency margin mode, 0 in multi-currency/portfolio margin mode |
| »»» margin_balance | string | Cross margin balance, only effective for USDT in single-currency margin mode, 0 in multi-currency/portfolio margin mode |
| »»» available_margin | string | Cross available margin, only effective for USDT in single-currency margin mode, 0 in multi-currency/portfolio margin mode |
| »»» enabled_collateral | boolean | Currency enabled as margin: true - Enabled, false - Disabled |
| »»» balance_version | number(int64) | Balance version number |
| »» total | string | Total account assets converted to USD, i.e. the sum of (available + freeze) * price in all currencies (deprecated, to be removed, replaced by unified_account_total) |
| »» borrowed | string | Total borrowed amount converted to USD, i.e. the sum of borrowed * price of all currencies (excluding point cards), valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
| »» total_initial_margin | string | Total initial margin (cross), effective in multi-currency margin/portfolio margin mode, 0 in single-currency margin mode |
| »» total_margin_balance | string | Total margin balance (cross), effective in multi-currency margin/portfolio margin mode, 0 in single-currency margin mode |
| »» total_maintenance_margin | string | Total maintenance margin (cross), effective in multi-currency margin/portfolio margin mode, 0 in single-currency margin mode |
| »» total_initial_margin_rate | string | Total initial margin rate (cross), effective in multi-currency margin/portfolio margin mode, 0 in single-currency margin mode |
| »» total_maintenance_margin_rate | string | Total maintenance margin rate (cross), effective in multi-currency margin/portfolio margin mode, 0 in single-currency margin mode |
| »» total_available_margin | string | Available margin amount, valid in cross-currency margin/combined margin mode, 0 in other modes such as single-currency margin mode |
| »» unified_account_total | string | Total unified account assets, includes both cross and isolated total assets in single-currency/multi-currency mode, only cross total assets in portfolio margin mode |
| »» unified_account_total_liab | string | Total unified account borrowed, i.e. total cross borrowed, effective in multi-currency margin/portfolio margin mode, 0 in single-currency margin mode |
| »» unified_account_total_equity | string | Total unified account equity, includes both cross and isolated total equity in single-currency/multi-currency mode, only cross total equity in portfolio margin mode |
| »» leverage | string | Account leverage multiplier, effective in multi-currency/portfolio margin mode (deprecated). Currency leverage query API: GET /unified/leverage/user_currency_setting |
| »» spot_order_loss | string | Spot Pending Order Loss, in USDT, effective only in Cross-Currency Margin Mode and Portfolio Margin Mode. |
| »» options_order_loss | string | Option Pending Order Loss, in USDT, effective only in Portfolio Margin Mode. |
| »» spot_hedge | boolean | Spot hedging status: true - enabled, false - disabled |
| »» use_funding | boolean | Whether to use Earn funds as margin |
| »» is_all_collateral | boolean | Whether all currencies are used as margin: true - all currencies as margin, false - no |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/borrowable'
query_param = 'currency=BTC'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /unified/borrowable?currency=BTC \
-H 'Accept: application/json'
GET /unified/borrowable
Query maximum borrowable amount for unified account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Query by specified currency name |
Example responses
200 Response
{
"currency": "ETH",
"amount": "10000"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | UnifiedBorrowable |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/transferable'
query_param = 'currency=BTC'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /unified/transferable?currency=BTC \
-H 'Accept: application/json'
GET /unified/transferable
Query maximum transferable amount for unified account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Query by specified currency name |
Example responses
200 Response
{
"currency": "ETH",
"amount": "10000"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | UnifiedTransferable |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/transferables'
query_param = 'currencies=BTC,ETH'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /unified/transferables?currencies=BTC%2CETH \
-H 'Accept: application/json'
GET /unified/transferables
Batch query maximum transferable amount for unified accounts. Each currency shows the maximum value. After user withdrawal, the transferable amount for all currencies will change
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currencies | query | string | true | Specify the currency name to query in batches, and support up to 100 pass parameters at a time |
Example responses
200 Response
[
{
"currency": "BTC",
"amount": "123456"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » TransferablesResult | object | Batch query unified account maximum transferable results |
| »» currency | string | Currency detail |
| »» amount | string | Maximum transferable amount |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/batch_borrowable'
query_param = 'currencies=BTC,GT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /unified/batch_borrowable?currencies=BTC,GT \
-H 'Accept: application/json'
GET /unified/batch_borrowable
Batch query unified account maximum borrowable amount
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currencies | query | array[string] | true | Specify currency names for querying in an array, separated by commas, maximum 10 currencies |
Example responses
200 Response
[
{
"currency": "BTC",
"amount": "123456"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [UnifiedBorrowable] |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /unified/loans \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /unified/loans
Borrow or repay
When borrowing, ensure the borrowed amount is not below the minimum borrowing threshold for the specific cryptocurrency and does not exceed the maximum borrowing limit set by the platform and user.
Loan interest will be automatically deducted from the account at regular intervals. Users are responsible for managing repayment of borrowed amounts.
For repayment, use repaid_all=true to repay all available amounts
Body parameter
{
"currency": "BTC",
"amount": "0.1",
"type": "borrow",
"repaid_all": false,
"text": "t-test"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Currency |
| » type | body | string | true | Type: borrow - borrow, repay - repay |
| » amount | body | string | true | Borrow or repayment amount |
| » repaid_all | body | boolean | false | Full repayment, only used for repayment operations. When set to true, overrides amount and directly repays the full amount |
| » text | body | string | false | User defined custom ID |
| Parameter | Value |
|---|---|
| » type | borrow |
| » type | repay |
Example responses
200 Response
{
"tran_id": 9527
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Operation successful | Inline |
Status Code 200
Unified account borrowing and repayment response result
| Name | Type | Description |
|---|---|---|
| » tran_id | integer(int64) | Transaction ID |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/loans'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /unified/loans \
-H 'Accept: application/json'
GET /unified/loans
Query loans
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum number of items returned. Default: 100, minimum: 1, maximum: 100 |
| type | query | string | false | Loan type: platform borrowing - platform, margin borrowing - margin |
Example responses
200 Response
[
{
"currency": "USDT",
"currency_pari": "GT_USDT",
"amount": "1",
"type": "margin",
"change_time": 1673247054000,
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Borrowing] |
| » None | object | Borrowing |
| »» currency | string | Currency |
| »» currency_pair | string | Currency pair |
| »» amount | string | Amount to Repay |
| »» type | string | Loan type: platform borrowing - platform, margin borrowing - margin |
| »» create_time | integer(int64) | Created time |
| »» update_time | integer(int64) | Last Update Time |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/loan_records'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /unified/loan_records \
-H 'Accept: application/json'
GET /unified/loan_records
Query loan records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| type | query | string | false | Loan record type: borrow - borrowing, repay - repayment |
| currency | query | string | false | Query by specified currency name |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum number of items returned. Default: 100, minimum: 1, maximum: 100 |
Example responses
200 Response
[
{
"id": 16442,
"type": "borrow",
"margin_mode": "cross",
"currency_pair": "AE_USDT",
"currency": "USDT",
"amount": "1000",
"create_time": 1673247054000,
"repayment_type": "auto_repay"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Borrowing Records |
| »» id | integer(int64) | ID |
| »» type | string | Type: borrow - borrow, repay - repay |
| »» repayment_type | string | Repayment type: none - No repayment type, manual_repay - Manual repayment, auto_repay - Automatic repayment, cancel_auto_repay - Automatic repayment after order cancellation, different_currencies_repayment - Cross-currency repayment |
| »» borrow_type | string | Borrowing type, returned when querying loan records: manual_borrow - Manual borrowing, auto_borrow - Automatic borrowing |
| »» currency_pair | string | Currency pair |
| »» currency | string | Currency |
| »» amount | string | Borrow or repayment amount |
| »» create_time | integer(int64) | Created time |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/interest_records'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /unified/interest_records \
-H 'Accept: application/json'
GET /unified/interest_records
Query interest deduction records
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Query by specified currency name |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum number of items returned. Default: 100, minimum: 1, maximum: 100 |
| from | query | integer(int64) | false | Start timestamp for the query |
| to | query | integer(int64) | false | End timestamp for the query, defaults to current time if not specified |
| type | query | string | false | Loan type: platform borrowing - platform, margin borrowing - margin. Defaults to margin if not specified |
Example responses
200 Response
[
{
"status": 1,
"currency_pair": "BTC_USDT",
"currency": "USDT",
"actual_rate": "0.00000236",
"interest": "0.00006136",
"type": "platform",
"create_time": 1673247054000
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Interest Deduction Record] |
| » None | object | Interest Deduction Record |
| »» currency | string | Currency name |
| »» currency_pair | string | Currency pair |
| »» actual_rate | string | Actual Rate |
| »» interest | string | Interest |
| »» status | integer | Status: 0 - fail, 1 - success |
| »» type | string | Loan Type margin: margin borrowing |
| »» create_time | integer(int64) | Created time |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/risk_units'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /unified/risk_units \
-H 'Accept: application/json'
GET /unified/risk_units
Get user risk unit details
Get user risk unit details, only valid in portfolio margin mode
Example responses
200 Response
{
"user_id": 0,
"spot_hedge": true,
"risk_units": [
{
"symbol": "BTC",
"spot_in_use": "-13500.000001223",
"maintain_margin": "2334.002",
"initial_margin": "2334.002",
"delta": "0.22",
"gamma": "0.42",
"theta": "0.29",
"vega": "0.22"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » user_id | integer(int64) | User ID |
| » spot_hedge | boolean | Spot hedging status: true - enabled, false - disabled |
| » risk_units | array | Risk unit |
| »» RiskUnits | object | none |
| »»» symbol | string | Risk unit flag |
| »»» spot_in_use | string | Spot hedging occupied amount |
| »»» maintain_margin | string | Maintenance margin for risk unit |
| »»» initial_margin | string | Initial margin for risk unit |
| »»» delta | string | Total Delta of risk unit |
| »»» gamma | string | Total Gamma of risk unit |
| »»» theta | string | Total Theta of risk unit |
| »»» vega | string | Total Vega of risk unit |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/unified_mode'
query_param = ''
body='{"mode":"portfolio","settings":{"spot_hedge":true,"usdt_futures":true,"options":true}}'
r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X PUT /unified/unified_mode \
-H 'Content-Type: application/json'
PUT /unified/unified_mode
Set unified account mode
Each account mode switch only requires passing the corresponding account mode parameter, and also supports turning on or off the configuration switches under the corresponding account mode during the switch.
PUT /unified/unified_mode
{
"mode": "classic"
}
- When enabling the portfolio margin mode, mode=portfolio
PUT /unified/unified_mode { "mode": "portfolio", "settings": { "spot_hedge": true } }
- When enabling the single-currency margin mode, mode=single_currency
PUT /unified/unified_mode { "mode": "single_currency" }
<Example>
> Body parameter
```json
{
"mode": "portfolio",
"settings": {
"spot_hedge": true,
"usdt_futures": true,
"options": true
}
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » mode | body | string | true | Unified account mode: |
| » settings | body | object | false | none |
| »» usdt_futures | body | boolean | false | USDT futures switch. In cross-currency margin mode, can only be enabled and cannot be disabled |
| »» spot_hedge | body | boolean | false | Spot hedging switch |
| »» use_funding | body | boolean | false | Earn switch, when mode is cross-currency margin mode, whether to use Earn funds as margin |
| »» options | body | boolean | false | Options switch. In cross-currency margin mode, can only be enabled and cannot be disabled |
» mode: Unified account mode:
classic: Classic account modemulti_currency: Cross-currency margin modeportfolio: Portfolio margin modesingle_currency: Single-currency margin mode| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Set successfully | None |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/unified_mode'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /unified/unified_mode \
-H 'Accept: application/json'
GET /unified/unified_mode
Query mode of the unified account
Unified account mode:
classic: Classic account modemulti_currency: Cross-currency margin modeportfolio: Portfolio margin modesingle_currency: Single-currency margin modeExample responses
200 Response
{
"mode": "portfolio",
"settings": {
"spot_hedge": true,
"usdt_futures": true,
"options": true
}
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » mode | string | Unified account mode: - classic: Classic account mode- multi_currency: Cross-currency margin mode- portfolio: Portfolio margin mode- single_currency: Single-currency margin mode |
| » settings | object | none |
| »» usdt_futures | boolean | USDT futures switch. In cross-currency margin mode, can only be enabled and cannot be disabled |
| »» spot_hedge | boolean | Spot hedging switch |
| »» use_funding | boolean | Earn switch, when mode is cross-currency margin mode, whether to use Earn funds as margin |
| »» options | boolean | Options switch. In cross-currency margin mode, can only be enabled and cannot be disabled |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/estimate_rate'
query_param = 'currencies=BTC,GT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /unified/estimate_rate?currencies=BTC,GT \
-H 'Accept: application/json'
GET /unified/estimate_rate
Query unified account estimated interest rate
Interest rates fluctuate hourly based on lending depth, so exact rates cannot be provided. When a currency is not supported, the interest rate returned will be an empty string
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currencies | query | array[string] | true | Specify currency names for querying in an array, separated by commas, maximum 10 currencies |
Example responses
200 Response
{
"BTC": "0.000002",
"GT": "0.000001",
"ETH": ""
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
Estimate current hourly lending rates, returned by currency
| Name | Type | Description |
|---|---|---|
| » additionalProperties | string | none |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
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 /unified/currency_discount_tiers \
-H 'Accept: application/json'
GET /unified/currency_discount_tiers
Query unified account tiered
Example responses
200 Response
[
[
{
"currency": "USDT",
"discount_tiers": [
{
"tier": "1",
"discount": "1",
"lower_limit": "0",
"leverage": "10",
"upper_limit": "+"
}
]
},
{
"currency": "USDC",
"discount_tiers": [
{
"tier": "1",
"discount": "1",
"lower_limit": "0",
"leverage": "10",
"upper_limit": "10000000"
},
{
"tier": "2",
"discount": "0.98",
"lower_limit": "10000000",
"leverage": "10",
"upper_limit": "15000000"
},
{
"tier": "3",
"discount": "0.95",
"lower_limit": "15000000",
"leverage": "10",
"upper_limit": "20000000"
},
{
"tier": "4",
"discount": "0.925",
"lower_limit": "20000000",
"leverage": "10",
"upper_limit": "50000000"
},
{
"tier": "5",
"discount": "0.9",
"lower_limit": "50000000",
"leverage": "10",
"upper_limit": "100000000"
},
{
"tier": "6",
"discount": "0",
"lower_limit": "100000000",
"leverage": "10",
"upper_limit": "+"
}
]
},
{
"currency": "BTC",
"discount_tiers": [
{
"tier": "1",
"discount": "0.98",
"lower_limit": "0",
"leverage": "10",
"upper_limit": "1000"
},
{
"tier": "2",
"discount": "0.95",
"lower_limit": "1000",
"leverage": "10",
"upper_limit": "10000"
},
{
"tier": "3",
"discount": "0.9",
"lower_limit": "10000",
"leverage": "10",
"upper_limit": "50000"
},
{
"tier": "4",
"discount": "0.85",
"lower_limit": "50000",
"leverage": "10",
"upper_limit": "+"
}
]
},
{
"currency": "ETH",
"discount_tiers": [
{
"tier": "1",
"discount": "0.98",
"lower_limit": "0",
"leverage": "10",
"upper_limit": "1000"
},
{
"tier": "2",
"discount": "0.95",
"lower_limit": "1000",
"leverage": "10",
"upper_limit": "10000"
},
{
"tier": "3",
"discount": "0.9",
"lower_limit": "10000",
"leverage": "10",
"upper_limit": "50000"
},
{
"tier": "4",
"discount": "0.85",
"lower_limit": "50000",
"leverage": "10",
"upper_limit": "+"
}
]
}
]
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Unified account tiered discount |
| »» currency | string | Currency name |
| »» discount_tiers | array | Tiered discount |
| »»» tier | string | Tier |
| »»» discount | string | Discount |
| »»» lower_limit | string | Lower limit |
| »»» upper_limit | string | Upper limit, + indicates positive infinity |
| »»» leverage | string | Position leverage |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/loan_margin_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /unified/loan_margin_tiers \
-H 'Accept: application/json'
GET /unified/loan_margin_tiers
Query unified account tiered loan margin
Example responses
200 Response
[
{
"currency": "USDT",
"margin_tiers": [
{
"tier": "1",
"margin_rate": "0.02",
"lower_limit": "200000",
"upper_limit": "400000",
"leverage": "3"
}
]
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » None | object | Unified account borrowing margin tiers |
| »» currency | string | Currency name |
| »» margin_tiers | array | Tiered margin |
| »»» MarginTiers | object | none |
| »»»» tier | string | Tier |
| »»»» margin_rate | string | Discount |
| »»»» lower_limit | string | Lower limit |
| »»»» upper_limit | string | Upper limit, `` indicates greater than (the last tier) |
| »»»» leverage | string | Position leverage |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/portfolio_calculator'
query_param = ''
body='{"spot_balances":[{"currency":"BTC","equity":"-1","freeze":"10"}],"spot_orders":[{"currency_pairs":"BTC_USDT","order_price":"344","size":"100","left":"100","type":"sell"}],"futures_positions":[{"contract":"BTC_USDT","size":"100"}],"futures_orders":[{"contract":"BTC_USDT","size":"10","left":"8"}],"options_positions":[{"options_name":"BTC_USDT-20240329-32000-C","size":"10"}],"options_orders":[{"options_name":"BTC_USDT-20240329-32000-C","size":"100","left":"80"}],"spot_hedge":false}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /unified/portfolio_calculator \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /unified/portfolio_calculator
Portfolio margin calculator
Portfolio Margin Calculator
This interface calculates maintenance and initial margin requirements under the portfolio margin model for custom simulated position and order portfolios. It currently supports all underlying currencies with active options trading. Each simulated position requires a name and holding quantity; each simulated pending order requires a market identifier, price, and quantity. Market orders are not supported.
Body parameter
{
"spot_balances": [
{
"currency": "BTC",
"equity": "-1",
"freeze": "10"
}
],
"spot_orders": [
{
"currency_pairs": "BTC_USDT",
"order_price": "344",
"size": "100",
"left": "100",
"type": "sell"
}
],
"futures_positions": [
{
"contract": "BTC_USDT",
"size": "100"
}
],
"futures_orders": [
{
"contract": "BTC_USDT",
"size": "10",
"left": "8"
}
],
"options_positions": [
{
"options_name": "BTC_USDT-20240329-32000-C",
"size": "10"
}
],
"options_orders": [
{
"options_name": "BTC_USDT-20240329-32000-C",
"size": "100",
"left": "80"
}
],
"spot_hedge": false
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » spot_balances | body | array | false | Spot |
| »» None | body | object | false | Spot |
| »»» currency | body | string | true | Currency name |
| »»» equity | body | string | true | Currency equity, where equity = balance - borrowed, represents the net delta exposure of your spot positions |
| »» spot_orders | body | array | false | Spot orders |
| »»» None | body | object | false | Spot orders |
| »»»» currency_pairs | body | string | true | Market |
| »»»» order_price | body | string | true | Price |
| »»»» count | body | string | false | Initial order quantity for spot trading pairs, not involved in actual calculation. |
| »»»» left | body | string | true | Unfilled quantity, involved in actual calculation |
| »»»» type | body | string | true | Order type, sell - sell order, buy - buy order |
| »»» futures_positions | body | array | false | Futures positions |
| »»»» None | body | object | false | Futures positions |
| »»»»» contract | body | string | true | Perpetual contract name. Only USDT perpetual contracts for underlying currencies with active options trading are supported. |
| »»»»» size | body | string | true | Position size, measured in contract quantity |
| »»»» futures_orders | body | array | false | Futures order |
| »»»»» None | body | object | false | Futures order |
| »»»»»» contract | body | string | true | Perpetual contract name. Only USDT perpetual contracts for underlying currencies with active options trading are supported. |
| »»»»»» size | body | string | true | Contract quantity, representing the initial order quantity, not involved in actual settlement |
| »»»»»» left | body | string | true | Unfilled contract quantity, involved in actual calculation |
| »»»»» options_positions | body | array | false | Options positions |
| »»»»»» None | body | object | false | Options positions |
| »»»»»»» options_name | body | string | true | Options contract name. Currently supports all options contract markets. |
| »»»»»»» size | body | string | true | Position size, measured in contract quantity |
| »»»»»» options_orders | body | array | false | Option orders |
| »»»»»»» None | body | object | false | Option orders |
| »»»»»»»» options_name | body | string | true | Options contract name. Currently supports all options contract markets. |
| »»»»»»»» size | body | string | true | Initial order quantity, not involved in actual calculation |
| »»»»»»»» left | body | string | true | Unfilled contract quantity, involved in actual calculation |
| »»»»»»» spot_hedge | body | boolean | false | Whether to enable spot hedging |
Example responses
200 Response
{
"maintain_margin_total": "0.000000000000",
"initial_margin_total": "0.000000000000",
"calculate_time": "1709014486",
"risk_unit": [
{
"symbol": "BTC",
"margin_result": [
{
"type": "original_position",
"profit_loss_ranges": [
{
"price_percentage": "-0.200000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "-0.160000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "-0.120000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "-0.080000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "-0.040000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.000000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.040000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.080000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.120000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.160000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
{
"price_percentage": "0.200000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
}
],
"max_loss": {
"price_percentage": "-0.200000000000",
"implied_volatility_percentage": "-0.300000000000",
"profit_loss": "0.000000000000"
},
"mr1": "0.000000000000",
"mr2": "0.000000000000",
"mr3": "0.000000000000",
"mr4": "0.000000000000"
}
],
"maintain_margin": "0.000000000000",
"initial_margin": "0.000000000000"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
Portfolio margin calculator output
| Name | Type | Description |
|---|---|---|
| » maintain_margin_total | string | Total maintenance margin, including only portfolio margin calculation results for positions in risk units, excluding borrowing margin. If borrowing exists, conventional borrowing margin requirements will still apply |
| » initial_margin_total | string | Total initial margin, calculated as the maximum of the following three combinations: position, position + positive delta orders, position + negative delta orders |
| » calculate_time | integer(int64) | Calculation time |
| » risk_unit | array | Risk unit |
| »» None | object | Risk unit |
| »»» symbol | string | Risk unit name |
| »»» spot_in_use | string | Spot hedge usage |
| »»» maintain_margin | string | Maintenance margin |
| »»» initial_margin | string | Initial margin |
| »»» margin_result | array | Margin result |
| »»»» None | object | Margin result |
| »»»»» type | string | Position combination typeoriginal_position - Original positionlong_delta_original_position - Positive delta + Original positionshort_delta_original_position - Negative delta + Original position |
| »»»»» profit_loss_ranges | array | Results of 33 stress scenarios for MR1 |
| »»»»»» None | object | Profit and loss range |
| »»»»»»» price_percentage | string | Percentage change in price |
| »»»»»»» implied_volatility_percentage | string | Percentage change in implied volatility |
| »»»»»»» profit_loss | string | PnL |
| »»»»»» max_loss | object | Profit and loss range |
| »»»»»»» price_percentage | string | Percentage change in price |
| »»»»»»» implied_volatility_percentage | string | Percentage change in implied volatility |
| »»»»»»» profit_loss | string | PnL |
| »»»»»» mr1 | string | Stress testing |
| »»»»»» mr2 | string | Basis spread risk |
| »»»»»» mr3 | string | Volatility spread risk |
| »»»»»» mr4 | string | Option short risk |
| »»»»» delta | string | Total Delta of risk unit |
| »»»»» gamma | string | Total Gamma of risk unit |
| »»»»» theta | string | Total Theta of risk unit |
| »»»»» vega | string | Total Vega of risk unit |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/leverage/user_currency_config'
query_param = 'currency=BTC'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /unified/leverage/user_currency_config?currency=BTC \
-H 'Accept: application/json'
GET /unified/leverage/user_currency_config
Maximum and minimum currency leverage that can be set
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | true | Currency |
Example responses
200 Response
{
"current_leverage": "2",
"min_leverage": "0",
"max_leverage": "0",
"debit": "0",
"available_margin": "0",
"borrowable": "0",
"except_leverage_borrowable": "0"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » current_leverage | string | Current leverage ratio |
| » min_leverage | string | Minimum adjustable leverage ratio |
| » max_leverage | string | Maximum adjustable leverage ratio |
| » debit | string | Current liabilities |
| » available_margin | string | Available Margin |
| » borrowable | string | Maximum borrowable amount at current leverage |
| » except_leverage_borrowable | string | Maximum borrowable from margin and maximum borrowable from Earn, whichever is smaller |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/leverage/user_currency_setting'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /unified/leverage/user_currency_setting \
-H 'Accept: application/json'
GET /unified/leverage/user_currency_setting
Get user currency leverage
Get user currency leverage. If currency is not specified, query all currencies
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Currency |
Example responses
200 Response
[
{
"currency": "BTC",
"leverage": "3"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| None | array | [Leverage multiplier for borrowing currency] |
| » None | object | Leverage multiplier for borrowing currency |
| »» currency | string | Currency name |
| »» leverage | string | Multiplier |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/leverage/user_currency_setting'
query_param = ''
body='{"currency":"BTC","leverage":"3"}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /unified/leverage/user_currency_setting \
-H 'Content-Type: application/json'
POST /unified/leverage/user_currency_setting
Set loan currency leverage
Body parameter
{
"currency": "BTC",
"leverage": "3"
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » currency | body | string | true | Currency name |
| » leverage | body | string | true | Multiplier |
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content (opens new window) | Set successfully | None |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/currencies'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /unified/currencies \
-H 'Accept: application/json'
GET /unified/currencies
List of loan currencies supported by unified account
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | false | Currency |
Example responses
200 Response
[
{
"name": "BTC",
"prec": "0.000001",
"min_borrow_amount": "0.01",
"user_max_borrow_amount": "1000000",
"total_max_borrow_amount": "1000000",
"loan_status": "enable"
}
]
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | List retrieved successfully | [Inline] |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » name | string | Currency name |
| » prec | string | Currency precision |
| » min_borrow_amount | string | Minimum borrowable limit, in currency units |
| » user_max_borrow_amount | string | User's maximum borrowable limit, in USDT |
| » total_max_borrow_amount | string | Platform's maximum borrowable limit, in USDT |
| » loan_status | string | Lending status - disable : Lending prohibited- enable : Lending supported |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/history_loan_rate'
query_param = 'currency=USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())
curl -X GET /unified/history_loan_rate?currency=USDT \
-H 'Accept: application/json'
GET /unified/history_loan_rate
Get historical lending rates
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| tier | query | string | false | VIP level for the floating rate to be queried |
| currency | query | string | true | Currency |
| page | query | integer(int32) | false | Page number |
| limit | query | integer(int32) | false | Maximum number of items returned. Default: 100, minimum: 1, maximum: 100 |
Example responses
200 Response
{
"currency": "USDT",
"tier": "1",
"tier_up_rate": "1.18",
"rates": [
{
"time": 1729047616000,
"rate": "0.00010287"
}
]
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
Status Code 200
| Name | Type | Description |
|---|---|---|
| » currency | string | Currency name |
| » tier | string | VIP level for the floating rate to be retrieved |
| » tier_up_rate | string | Floating rate corresponding to VIP level |
| » rates | array | Historical interest rate information, one data point per hour, array size determined by page and limit parameters from the API request, sorted by time from recent to distant |
| »» time | integer(int64) | Hourly timestamp corresponding to this interest rate, in milliseconds |
| »» rate | string | Historical interest rate for this hour |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/collateral_currencies'
query_param = ''
body='{"collateral_type":1,"enable_list":["BTC","ETH"],"disable_list":["SOL","GT"]}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /unified/collateral_currencies \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /unified/collateral_currencies
Set collateral currency
Body parameter
{
"collateral_type": 1,
"enable_list": [
"BTC",
"ETH"
],
"disable_list": [
"SOL",
"GT"
]
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » collateral_type | body | integer | false | User-set collateral mode: 0(all)-All currencies as collateral, 1(custom)-Custom currencies as collateral. When collateral_type is 0(all), enable_list and disable_list parameters are invalid |
| » enable_list | body | array | false | Currency list, where collateral_type=1(custom) indicates the addition logic |
| » disable_list | body | array | false | Disable list, indicating the disable logic |
| Parameter | Value |
|---|---|
| » collateral_type | 0 |
| » collateral_type | 1 |
Example responses
200 Response
{
"is_success": true
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Updated successfully | Inline |
Status Code 200
Unified account collateral mode settings response
| Name | Type | Description |
|---|---|---|
| » is_success | boolean | Whether the setting was successful |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/estimated_quick_repayment'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())
curl -X GET /unified/estimated_quick_repayment \
-H 'Accept: application/json'
GET /unified/estimated_quick_repayment
Estimated quick repayment details
Available for unified account cross-currency margin mode and portfolio margin mode
Example responses
200 Response
{
"debt_currencies": [
{
"currency": "ETH",
"debt_amount": "1.5",
"estimated_usd": "4500",
"borrowed": "1.5",
"neg_balance": "0"
}
],
"available_currencies": [
{
"currency": "USDT",
"available": "5000",
"estimated_usd": "5000"
}
]
}
400 Response
{
"label": "INVALID_PARAM",
"message": "invalid request"
}
401 Response
{
"label": "INVALID_KEY",
"message": "Invalid API key"
}
403 Response
{
"label": "FORBIDDEN",
"message": "quick repayment is only available in cross-currency margin or portfolio margin mode"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Query successful | Inline |
| 400 | Bad Request (opens new window) | Invalid request parameters | Inline |
| 401 | Unauthorized (opens new window) | Authentication failed | Inline |
| 403 | Forbidden (opens new window) | Access denied (e.g. account mode does not support quick repayment) | Inline |
Status Code 200
QuickEstimatedRepayment
| Name | Type | Description |
|---|---|---|
| » debt_currencies | array | Liability currencies |
| »» UnifiedDebtCurrencies | object | none |
| »»» currency | string | Currency name |
| »»» debt_amount | string | Debt Quantity |
| »»» estimated_usd | string | Estimated USD value |
| »»» borrowed | string | Borrowed amount |
| »»» neg_balance | string | Negative balance |
| »» available_currencies | array | Currencies available for repayment |
| »»» UnifiedAvailableCurrencies | object | none |
| »»»» currency | string | Currency name |
| »»»» available | string | Available Balance |
| »»»» estimated_usd | string | Estimated USD value |
Status Code 400
error response body format when status code is non-2xx
| Name | Type | Description |
|---|---|---|
| » label | string | Error label |
| » message | string | Detailed error message |
Status Code 401
error response body format when status code is non-2xx
| Name | Type | Description |
|---|---|---|
| » label | string | Error label |
| » message | string | Detailed error message |
Status Code 403
error response body format when status code is non-2xx
| Name | Type | Description |
|---|---|---|
| » label | string | Error label |
| » message | string | Detailed error message |
Code samples
# coding: utf-8
import requests
host = "//"
prefix = "//"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
url = '/unified/quick_repayment'
query_param = ''
body='{"debt_currencies":["ETH"],"available_currencies":["USDT","BTC"]}'
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())
curl -X POST /unified/quick_repayment \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST /unified/quick_repayment
Quick repayment
Available for unified account cross-currency margin mode and portfolio margin mode.
Use GET /unified/estimated_quick_repayment to query liabilities and pending repayment information.
Body parameter
{
"debt_currencies": [
"ETH"
],
"available_currencies": [
"USDT",
"BTC"
]
}
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » debt_currencies | body | array | false | Liability currencies |
| » available_currencies | body | array | false | Currencies to repay with |
Example responses
200 Response
{
"order_id": "qr_123456",
"repaid_infos": [
{
"currency": "ETH",
"repaid": "0.5",
"left": "1.0"
}
],
"used_infos": [
{
"currency": "USDT",
"used": "1500"
}
]
}
400 Response
{
"label": "INVALID_PARAM",
"message": "invalid request body"
}
401 Response
{
"label": "INVALID_KEY",
"message": "Invalid API key"
}
403 Response
{
"label": "FORBIDDEN",
"message": "quick repayment is only available in cross-currency margin or portfolio margin mode"
}
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK (opens new window) | Repayment successful | Inline |
| 400 | Bad Request (opens new window) | Invalid request parameters | Inline |
| 401 | Unauthorized (opens new window) | Authentication failed | Inline |
| 403 | Forbidden (opens new window) | Access denied (e.g. account mode does not support quick repayment) | Inline |
Status Code 200
QuickRepaymentResp
| Name | Type | Description |
|---|---|---|
| » order_id | string | Order ID |
| » repaid_infos | array | Repaid currency details |
| »» RepaidInfo | object | Repayment details |
| »»» currency | string | Currency name |
| »»» repaid | string | Repaid amount |
| »»» left | string | Remaining liability amount |
| »» used_infos | array | Currencies used for repayment |
| »»» UsedInfo | object | Repayment details |
| »»»» currency | string | Currency name |
| »»»» used | string | Amount converted |
Status Code 400
error response body format when status code is non-2xx
| Name | Type | Description |
|---|---|---|
| » label | string | Error label |
| » message | string | Detailed error message |
Status Code 401
error response body format when status code is non-2xx
| Name | Type | Description |
|---|---|---|
| » label | string | Error label |
| » message | string | Detailed error message |
Status Code 403
error response body format when status code is non-2xx
| Name | Type | Description |
|---|---|---|
| » label | string | Error label |
| » message | string | Detailed error message |
{
"timeout": 0,
"currency_pair": "string"
}
CountdownCancelAllSpotTask
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| timeout | integer(int32) | true | none | Countdown time in seconds At least 5 seconds, 0 means cancel countdown |
| currency_pair | string | false | none | Currency pair |
{
"tx_id": "string",
"status": "string"
}
TransferOrderStatus
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| tx_id | string | false | none | Order ID |
| status | string | false | none | Transfer status: PENDING - Processing, SUCCESS - Transfer successful, FAIL - Transfer failed, PARTIAL_SUCCESS - Partially successful (this status appears when transferring between sub-accounts) |
{
"user_id": 0,
"mode": 0,
"name": "string",
"perms": [
{
"name": "string",
"read_only": true
}
],
"ip_whitelist": [
"string"
],
"key": "string",
"state": 0,
"created_at": 0,
"updated_at": 0,
"last_access": 0
}
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| user_id | integer(int64) | false | read-only | User ID |
| mode | integer(int32) | false | none | Mode: 1 - classic 2 - portfolio account |
| name | string | false | none | API Key Name |
| perms | array | false | none | none |
| » name | string | false | none | Permission function name (no value will be cleared) - wallet: wallet - spot: spot/margin - futures: perpetual contract - delivery: delivery contract - earn: earn - custody: custody - options: options - account: account information - loan: lending - margin: margin - unified: unified account - copy: copy trading |
| » read_only | boolean | false | none | Read Only |
| ip_whitelist | array | false | none | IP whitelist (list will be cleared if no value is passed) |
| key | string | false | read-only | API Key |
| state | integer(int32) | false | read-only | Status: 1-Normal 2-Frozen 3-Locked |
| created_at | integer(int64) | false | read-only | Created time |
| updated_at | integer(int64) | false | read-only | Last Update Time |
| last_access | integer(int64) | false | read-only | Last Access Time |
{
"mode": "string",
"contract": "BTC_USDT"
}
UpdateDualCompPositionCrossModeRequest
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| mode | string | true | none | Cross/isolated margin mode. ISOLATED - isolated margin, CROSS - cross margin |
| contract | string | true | none | Futures market |
{
"size": "string",
"price": "string",
"amend_text": "string",
"text": "string",
"action_mode": "string"
}
FuturesOrderAmendment
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| size | string | false | none | 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. |
| price | string | false | none | New order price |
| amend_text | string | false | none | Custom info during order amendment |
| text | string | false | none | Internal users can modify information in the text field. |
| action_mode | string | false | none | 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) |
{
"timeout": 0,
"contract": "string"
}
CountdownCancelAllFuturesTask
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| timeout | integer(int32) | true | none | Countdown time in seconds At least 5 seconds, 0 means cancel countdown |
| contract | string | false | none | Futures contract |
{
"contract": "string",
"amount": "string",
"activation_price": "0",
"is_gte": true,
"price_type": 1,
"price_offset": "string",
"reduce_only": false,
"position_related": false,
"text": "apiv4",
"pos_margin_mode": "string",
"position_mode": "string"
}
CreateTrailOrder
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| contract | string | true | none | Contract name |
| amount | string | true | none | Trading quantity in contracts, positive for buy, negative for sell |
| activation_price | string | false | none | Activation price, 0 means trigger immediately |
| is_gte | boolean | false | none | true: activate when market price >= activation price, false: <= activation price |
| price_type | integer(int32) | false | none | Activation price type: 1-latest price, 2-index price, 3-mark price |
| price_offset | string | false | none | Callback ratio or price distance, e.g., 0.1 or 0.1% |
| reduce_only | boolean | false | none | Whether reduce only |
| position_related | boolean | false | none | Whether bound to a position (if position_related = true (position-related), then reduce_only must also be true) |
| text | string | false | none | Order custom information, optional field. Used to identify the order source or set a user-defined ID. If non-empty, it must meet one of the following rules: 1. Internal Reserved Fields (identifying order source): - apiv4: API call2. User-defined Fields (setting custom ID): - Must start with t-- The content after t- must not exceed 28 bytes in length- Can only contain: numbers, letters, underscores (_), hyphens (-), or dots (.) - Examples: t-my-order-001, t-trail_2024.01Note: User-defined fields must not conflict with internal reserved fields. |
| pos_margin_mode | string | false | none | Position margin mode: isolated/cross |
| position_mode | string | false | none | Position mode: single, dual, and dual_plus |
| Property | Value |
|---|---|
| price_type | 1 |
| price_type | 2 |
| price_type | 3 |
{
"contract": "string",
"related_position": 1
}
StopAllTrailOrders
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| contract | string | false | none | Contract name |
| related_position | integer(int32) | false | none | Associated position, if provided, only cancel orders associated with this position, 1-long, 2-short |
| Property | Value |
|---|---|
| related_position | 1 |
| related_position | 2 |
{
"id": 0,
"amount": "string",
"activation_price": "string",
"is_gte_str": "string",
"price_type": 0,
"price_offset": "string"
}
UpdateTrailOrder
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | integer(int64) | true | none | Order ID |
| amount | string | false | none | Total trading quantity in contracts, positive for buy, negative for sell, 0 means no modification |
| activation_price | string | false | none | Activation price, 0 means trigger immediately, empty means no modification |
| is_gte_str | string | false | none | true: activate when market price >= activation price, false: <= activation price, empty means no modification |
| price_type | integer(int32) | false | none | Activation price type, not provided or 0 means no modification, 1-latest price, 2-index price, 3-mark price |
| price_offset | string | false | none | Callback ratio or price distance, e.g., 0.1 or 0.1%; empty means no modification |
| Property | Value |
|---|---|
| price_type | 0 |
| price_type | 1 |
| price_type | 2 |
| price_type | 3 |
{
"name": "string",
"type": "inverse",
"quanto_multiplier": "string",
"leverage_min": "string",
"leverage_max": "string",
"maintenance_rate": "string",
"mark_type": "internal",
"mark_price": "string",
"index_price": "string",
"last_price": "string",
"maker_fee_rate": "string",
"taker_fee_rate": "string",
"order_price_round": "string",
"mark_price_round": "string",
"funding_rate": "string",
"funding_interval": 0,
"funding_next_apply": 0.1,
"risk_limit_base": "string",
"interest_rate": "string",
"risk_limit_step": "string",
"risk_limit_max": "string",
"order_size_min": "string",
"enable_decimal": true,
"order_size_max": "string",
"order_price_deviate": "string",
"ref_discount_rate": "string",
"ref_rebate_rate": "string",
"orderbook_id": 0,
"trade_id": 0,
"trade_size": "string",
"position_size": "string",
"config_change_time": 0.1,
"in_delisting": true,
"orders_limit": 0,
"enable_bonus": true,
"enable_credit": true,
"create_time": 0.1,
"funding_cap_ratio": "string",
"status": "string",
"launch_time": 0,
"delisting_time": 0,
"delisted_time": 0,
"market_order_slip_ratio": "string",
"market_order_size_max": "string",
"funding_rate_limit": "string",
"contract_type": "string",
"funding_impact_value": "string",
"enable_circuit_breaker": true
}
Futures contract details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| name | string | false | none | Futures contract |
| type | string | false | none | Contract type: inverse - inverse contract, direct - direct contract |
| quanto_multiplier | string | false | none | The contract multiplier indicates how many units of the underlying asset the face value of one contract represents. |
| leverage_min | string | false | none | Minimum leverage |
| leverage_max | string | false | none | Maximum leverage |
| maintenance_rate | string | false | none | The maintenance margin rate of the first tier of risk limit sheet |
| mark_type | string | false | none | Deprecated |
| mark_price | string | false | none | Current mark price |
| index_price | string | false | none | Current index price |
| last_price | string | false | none | Last trading price |
| maker_fee_rate | string | false | none | Maker fee rate, negative values indicate rebates |
| taker_fee_rate | string | false | none | Taker fee rate |
| order_price_round | string | false | none | Minimum order price increment |
| mark_price_round | string | false | none | Minimum mark price increment |
| funding_rate | string | false | none | Current funding rate |
| funding_interval | integer | false | none | Funding application interval, unit in seconds |
| funding_next_apply | number(double) | false | none | Next funding time |
| risk_limit_base | string | false | none | Base risk limit (deprecated) |
| interest_rate | string | false | none | Interest rate parameter used in funding rate and premium-related calculations for perpetual contracts. Returned as a string decimal ratio (e.g. 0.0003), same convention as funding_rate (ratio, not percent). |
| risk_limit_step | string | false | none | Risk limit adjustment step (deprecated) |
| risk_limit_max | string | false | none | Maximum risk limit allowed by the contract (deprecated). It is recommended to use /futures/{settle}/risk_limit_tiers to query risk limits |
| order_size_min | string | false | none | Minimum order size allowed by the contract |
| enable_decimal | boolean | false | none | Whether decimal string type is supported for contract lot size. When this field is set to true, it indicates that the contract supports decimal lot sizes (i.e., the size field can use a decimal string type); when set to false, it indicates that the contract does not support decimal lot sizes (i.e., the size field can only use an integer type). |
| order_size_max | string | false | none | Maximum order size allowed by the contract |
| order_price_deviate | string | false | none | Maximum allowed deviation between order price and current mark price. The order price order_price must satisfy the following condition:abs(order_price - mark_price) <= mark_price * order_price_deviate |
| ref_discount_rate | string | false | none | Trading fee discount for referred users |
| ref_rebate_rate | string | false | none | Commission rate for referrers |
| orderbook_id | integer(int64) | false | none | Orderbook update ID |
| trade_id | integer(int64) | false | none | Current trade ID |
| trade_size | string | false | none | Historical cumulative trading volume |
| position_size | string | false | none | Current total long position size |
| config_change_time | number(double) | false | none | Last configuration update time |
| in_delisting | boolean | false | none | in_delisting=true and position_size>0 indicates the contract is in delisting transition periodin_delisting=true and position_size=0 indicates the contract is delisted |
| orders_limit | integer | false | none | Maximum number of pending orders |
| enable_bonus | boolean | false | none | Whether bonus is enabled |
| enable_credit | boolean | false | none | Whether portfolio margin account is enabled |
| create_time | number(double) | false | none | Created time of the contract |
| funding_cap_ratio | string | false | none | Deprecated |
| status | string | false | none | Contract status types include: prelaunch (pre-launch), trading (active), delisting (delisting), delisted (delisted), circuit_breaker (circuit breaker) |
| launch_time | integer(int64) | false | none | Contract expiry timestamp |
| delisting_time | integer(int64) | false | none | Timestamp when contract enters reduce-only state |
| delisted_time | integer(int64) | false | none | Contract delisting time |
| market_order_slip_ratio | string | false | none | The maximum slippage allowed for market orders, with the slippage rate calculated based on the latest market price |
| market_order_size_max | string | false | none | The maximum number of contracts supported for market orders, with a default value of 0. When the default value is used, the maximum number of contracts is limited by the order_size_max field |
| funding_rate_limit | string | false | none | Upper and lower limits of funding rate |
| contract_type | string | false | none | Contract classification type, e.g. stocks, metals, indices, forex, commodities, etc. |
| funding_impact_value | string | false | none | Funding rate depth impact value |
| enable_circuit_breaker | boolean | false | none | Whether the newly launched contract activates mark price circuit breaker (If the platform intends to activate this mechanism for a newly launched contract market to prevent significant price fluctuations and excessive liquidations after launch, an advance announcement will be made). |
| Property | Value |
|---|---|
| type | inverse |
| type | direct |
| mark_type | internal |
| mark_type | index |
{
"user": 0,
"contract": "string",
"size": "string",
"leverage": "string",
"risk_limit": "string",
"leverage_max": "string",
"maintenance_rate": "string",
"value": "string",
"margin": "string",
"entry_price": "string",
"liq_price": "string",
"mark_price": "string",
"initial_margin": "string",
"maintenance_margin": "string",
"unrealised_pnl": "string",
"realised_pnl": "string",
"pnl_pnl": "string",
"pnl_fund": "string",
"pnl_fee": "string",
"history_pnl": "string",
"last_close_pnl": "string",
"realised_point": "string",
"history_point": "string",
"adl_ranking": 0,
"pending_orders": 0,
"close_order": {
"id": 0,
"price": "string",
"is_liq": true
},
"mode": "single",
"cross_leverage_limit": "string",
"update_time": 0,
"update_id": 0,
"open_time": 0,
"risk_limit_table": "string",
"average_maintenance_rate": "string",
"pid": 0,
"pos_margin_mode": "string",
"lever": "string"
}
Futures position details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| user | integer(int64) | false | read-only | User ID |
| contract | string | false | read-only | Futures contract |
| size | string | false | read-only | Position size |
| leverage | string | false | none | leverage for isolated margin. 0 means cross margin. For leverage of cross margin, please refer to cross_leverage_limit. |
| risk_limit | string | false | none | Position risk limit |
| leverage_max | string | false | read-only | the maximum permissible leverage given to the current positon value: the higher positon value, the lower maximum permissible leverage |
| maintenance_rate | string | false | read-only | The maintenance margin requirement for the risk limit at which the current position size is located.Since the maintenance margin for the position has been calculated using a tiered system, the actual maintenance margin rate required for this position is based on average_maintenance_rate. |
| 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 | Estimated liquidation price, for reference only. The actual liquidation trigger is based on the position mmr or the account maintenance margin level. |
| mark_price | string | false | read-only | Current mark price |
| initial_margin | string | false | read-only | Initial margin of postions |
| maintenance_margin | string | false | read-only | Maintencance margin of postions |
| unrealised_pnl | string | false | read-only | Unrealized PNL |
| realised_pnl | string | false | read-only | Realised PnL, the sum of all cash flows generated by this position, including settlement of closing positions, settlement of funding fees, and transaction fee expenses. |
| pnl_pnl | string | false | read-only | settled pnl when closing postion |
| pnl_fund | string | false | read-only | funding fees |
| pnl_fee | string | false | read-only | trading fees |
| history_pnl | string | false | read-only | Total realized PnL from closed positions |
| last_close_pnl | string | false | read-only | PNL of last position close |
| realised_point | string | false | read-only | Realized POINT PNL |
| history_point | string | false | read-only | History realized POINT PNL |
| adl_ranking | integer | false | read-only | Ranking of auto deleveraging, a total of 1-5 grades, 1 is the highest, 5 is the lowest, and 6 is the special case when there is no position held or in liquidation |
| pending_orders | integer | false | read-only | Current pending order quantity |
| close_order | object|null | false | read-only | Current close order information, or null if no close order |
| » id | integer(int64) | false | none | Order ID |
| » price | string | false | none | Order price |
| » is_liq | boolean | false | none | Whether the close order is from liquidation |
| mode | string | false | none | Position mode, including: - single: One-way Mode- dual_long: Long position in Hedge Mode- dual_short: Short position in Hedge Mode |
| cross_leverage_limit | string | false | none | leverage for cross margin |
| update_time | integer(int64) | false | read-only | Last update time |
| update_id | integer(int64) | false | read-only | Update ID. The value increments by 1 each time the position is updated |
| open_time | integer(int64) | false | none | First Open Time |
| risk_limit_table | string | false | read-only | Risk limit table ID |
| average_maintenance_rate | string | false | read-only | Average maintenance margin rate |
| pid | integer(int64) | false | read-only | Sub-account position ID |
| pos_margin_mode | string | false | none | Position Margin Mode isolated - Isolated Margin, cross - Cross Margin |
| lever | string | false | none | Indicates the current leverage of the position, applicable to both isolated and cross margin, gradually replacing the current leverage and cross_leverage_limit |
| Property | Value |
|---|---|
| mode | single |
| mode | dual_long |
| mode | dual_short |
{
"contract": "string",
"size": "string",
"leverage": "string",
"risk_limit": "string",
"leverage_max": "string",
"maintenance_rate": "string",
"margin": "string",
"liq_price": "string",
"realised_pnl": "string",
"history_pnl": "string",
"last_close_pnl": "string",
"realised_point": "string",
"history_point": "string",
"mode": "string",
"cross_leverage_limit": "string",
"entry_price": "string",
"time": 0
}
Contract position details (historical data)
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| contract | string | false | read-only | Futures contract |
| size | string | 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 | the maximum permissible leverage given to the current positon value: the higher positon value, the lower maximum permissible leverage |
| maintenance_rate | string | false | read-only | The maintenance margin rate of the first tier of risk limit sheet |
| margin | string | false | none | Position margin |
| liq_price | string | false | read-only | Liquidation price |
| realised_pnl | string | false | read-only | Realized PnL |
| history_pnl | string | false | read-only | Total realized PnL from closed positions |
| last_close_pnl | string | false | read-only | PNL of last position close |
| realised_point | string | false | read-only | Realized POINT PNL |
| history_point | string | false | read-only | History realized POINT PNL |
| mode | string | false | none | Position mode, including: - single: One-way Mode- dual_long: Long position in Hedge Mode- dual_short: Short position in Hedge Mode |
| cross_leverage_limit | string | false | none | Cross margin leverage (valid only when leverage is 0) |
| entry_price | string | false | read-only | Entry price |
| time | integer(int64) | false | none | Timestamp |
{
"id": 0,
"user": 0,
"create_time": 0.1,
"update_time": 0.1,
"finish_time": 0.1,
"finish_as": "filled",
"status": "open",
"contract": "string",
"size": "string",
"iceberg": "string",
"price": "string",
"close": false,
"is_close": true,
"reduce_only": false,
"is_reduce_only": true,
"is_liq": true,
"tif": "gtc",
"left": "string",
"fill_price": "string",
"text": "string",
"tkfr": "string",
"mkfr": "string",
"refu": 0,
"auto_size": "close_long",
"stp_id": 0,
"stp_act": "co",
"amend_text": "string",
"pid": 0,
"market_order_slip_ratio": "string",
"pos_margin_mode": "string",
"action_mode": "string",
"tpsl_tp_trigger_price": "string",
"tpsl_sl_trigger_price": "string"
}
Futures order details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | integer(int64) | false | read-only | Futures order ID |
| user | integer | false | read-only | User ID |
| create_time | number(double) | false | read-only | Creation time of order |
| update_time | number(double) | false | read-only | OrderUpdateTime |
| finish_time | number(double) | false | read-only | Order finished time. Not returned if order is open |
| finish_as | string | false | read-only | How the order was finished: - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC, finish immediately- auto_deleveraged: finished by ADL - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because the position was closed - reduce_out: only reduce positions by excluding hard-to-fill orders - stp: cancelled because self trade prevention |
| status | string | false | read-only | Order status - open: Pending- finished: Completed |
| contract | string | true | none | Futures contract |
| size | string | true | none | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| iceberg | string | false | none | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| price | string | true | none | Required. Order Price; a price of 0 with tif as ioc represents a market order. |
| close | boolean | false | write-only | Set as true to close the position, with size set to 0 |
| is_close | boolean | false | read-only | Is the order to close position |
| reduce_only | boolean | false | write-only | Set as true to be reduce-only order |
| is_reduce_only | boolean | false | read-only | Is the order reduce-only |
| is_liq | boolean | false | read-only | Is the order for liquidation |
| tif | string | false | none | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none |
| left | string | false | read-only | Unfilled quantity |
| fill_price | string | false | read-only | Fill price |
| text | string | false | none | Custom order information. If not empty, must follow the rules below: 1. Prefixed with t-2. No longer than 28 bytes without t- prefix3. Can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) In addition to user-defined information, the following are internal reserved fields that identify the order source: - web: Web - api: API call - app: Mobile app - auto_deleveraging: Automatic deleveraging - liquidation: Forced liquidation of positions under the old classic mode - liq-xxx: a. Forced liquidation of positions under the new classic mode, including isolated margin, one-way cross margin, and non-hedged positions under two-way cross margin. b. Forced liquidation of isolated positions under the unified account single-currency margin mode - hedge-liq-xxx: Forced liquidation of hedged positions under the new classic mode two-way cross margin, i.e., simultaneously closing long and short positions - pm_liquidate: Forced liquidation under unified account multi-currency margin mode - comb_margin_liquidate: Forced liquidation under unified account portfolio margin mode - scm_liquidate: Forced liquidation of positions under unified account single-currency margin mode - insurance: Insurance - clear: Contract delisting withdrawal |
| tkfr | string | false | read-only | Taker fee |
| mkfr | string | false | read-only | Maker fee |
| refu | integer | false | read-only | Referrer user ID |
| auto_size | string | false | write-only | Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0 |
| stp_id | integer | false | read-only | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
| stp_act | string | false | none | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy.2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter.3. If the user did not use stp_act when placing the order, stp_act will return '-'- cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled |
| amend_text | string | false | read-only | The custom data that the user remarked when amending the order |
| pid | integer(int64) | false | write-only | Position ID |
| market_order_slip_ratio | string | false | none | Custom maximum slippage rate for market orders. If not provided, the default contract settings will be used |
| pos_margin_mode | string | false | none | Position Margin Mode isolated - Isolated Margin, cross - Cross Margin, only passed in simple split position mode |
| action_mode | string | false | none | 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) |
| tpsl_tp_trigger_price | string | false | none | Take profit price |
| tpsl_sl_trigger_price | string | false | none | Stop loss price |
| Property | Value |
|---|---|
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidated |
| finish_as | ioc |
| finish_as | auto_deleveraged |
| finish_as | reduce_only |
| finish_as | position_closed |
| finish_as | reduce_out |
| finish_as | stp |
| status | open |
| status | finished |
| tif | gtc |
| tif | ioc |
| tif | poc |
| tif | fok |
| auto_size | close_long |
| auto_size | close_short |
| stp_act | co |
| stp_act | cn |
| stp_act | cb |
| stp_act | - |
{
"id": 0,
"user": 0,
"create_time": 0.1,
"update_time": "string",
"finish_time": "string",
"finish_as": "filled",
"status": "open",
"contract": "string",
"size": "string",
"iceberg": "string",
"price": "string",
"close": false,
"is_close": true,
"reduce_only": false,
"is_reduce_only": true,
"is_liq": true,
"tif": "gtc",
"left": "string",
"fill_price": "string",
"text": "string",
"tkfr": "string",
"mkfr": "string",
"refu": 0,
"auto_size": "close_long",
"stp_id": 0,
"stp_act": "co",
"amend_text": "string",
"pid": 0,
"market_order_slip_ratio": "string",
"pos_margin_mode": "string",
"tpsl_tp_trigger_price": "string",
"tpsl_sl_trigger_price": "string"
}
Futures order details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | integer(int64) | false | read-only | Futures order ID |
| user | integer | false | read-only | User ID |
| create_time | number(double) | false | read-only | Creation time of order |
| update_time | string | false | read-only | OrderUpdateTime |
| finish_time | string | false | read-only | Order finished time. Not returned if order is open |
| finish_as | string | false | read-only | How the order was finished: - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC, finish immediately- auto_deleveraged: finished by ADL - reduce_only: cancelled because of increasing position while reduce-only set- position_closed: cancelled because the position was closed - reduce_out: only reduce positions by excluding hard-to-fill orders - stp: cancelled because self trade prevention |
| status | string | false | read-only | Order status - open: Pending- finished: Completed |
| contract | string | true | none | Futures contract |
| size | string | true | none | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| iceberg | string | false | none | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| price | string | true | none | Required. Order Price; a price of 0 with tif as ioc represents a market order. |
| close | boolean | false | write-only | Set as true to close the position, with size set to 0 |
| is_close | boolean | false | read-only | Is the order to close position |
| reduce_only | boolean | false | write-only | Set as true to be reduce-only order |
| is_reduce_only | boolean | false | read-only | Is the order reduce-only |
| is_liq | boolean | false | read-only | Is the order for liquidation |
| tif | string | false | none | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none |
| left | string | false | read-only | Unfilled quantity |
| fill_price | string | false | read-only | Fill price |
| text | string | false | none | Custom order information. If not empty, must follow the rules below: 1. Prefixed with t-2. No longer than 28 bytes without t- prefix3. Can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) In addition to user-defined information, the following are internal reserved fields that identify the order source: - web: Web - api: API call - app: Mobile app - auto_deleveraging: Automatic deleveraging - liquidation: Forced liquidation of positions under the old classic mode - liq-xxx: a. Forced liquidation of positions under the new classic mode, including isolated margin, one-way cross margin, and non-hedged positions under two-way cross margin. b. Forced liquidation of isolated positions under the unified account single-currency margin mode - hedge-liq-xxx: Forced liquidation of hedged positions under the new classic mode two-way cross margin, i.e., simultaneously closing long and short positions - pm_liquidate: Forced liquidation under unified account multi-currency margin mode - comb_margin_liquidate: Forced liquidation under unified account portfolio margin mode - scm_liquidate: Forced liquidation of positions under unified account single-currency margin mode - insurance: Insurance - clear: Contract delisting withdrawal |
| tkfr | string | false | read-only | Taker fee |
| mkfr | string | false | read-only | Maker fee |
| refu | integer | false | read-only | Referrer user ID |
| auto_size | string | false | write-only | Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0 |
| stp_id | integer | false | read-only | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
| stp_act | string | false | none | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy.2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter.3. If the user did not use stp_act when placing the order, stp_act will return '-'- cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled |
| amend_text | string | false | read-only | The custom data that the user remarked when amending the order |
| pid | integer(int64) | false | write-only | Position ID |
| market_order_slip_ratio | string | false | none | Custom maximum slippage rate for market orders. If not provided, the default contract settings will be used |
| pos_margin_mode | string | false | none | Position Margin Mode isolated - Isolated Margin, cross - Cross Margin, only passed in simple split position mode |
| tpsl_tp_trigger_price | string | false | none | Take profit price |
| tpsl_sl_trigger_price | string | false | none | Stop loss price |
| Property | Value |
|---|---|
| finish_as | filled |
| finish_as | cancelled |
| finish_as | liquidated |
| finish_as | ioc |
| finish_as | auto_deleveraged |
| finish_as | reduce_only |
| finish_as | position_closed |
| finish_as | reduce_out |
| finish_as | stp |
| status | open |
| status | finished |
| tif | gtc |
| tif | ioc |
| tif | poc |
| tif | fok |
| auto_size | close_long |
| auto_size | close_short |
| stp_act | co |
| stp_act | cn |
| stp_act | cb |
| stp_act | - |
{
"contract": "string",
"size": 0,
"direction": "string",
"iceberg": 0,
"level": 0,
"close": false,
"is_close": true,
"reduce_only": false,
"is_reduce_only": true,
"is_liq": true,
"tif": "gtc",
"left": 0,
"fill_price": "string",
"text": "string",
"tkfr": "string",
"mkfr": "string",
"refu": 0,
"auto_size": "close_long",
"stp_id": 0,
"stp_act": "co",
"amend_text": "string",
"pid": 0
}
contractBBOorderdetails
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| contract | string | true | none | Futures contract |
| size | integer(int64) | true | none | Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders. |
| direction | string | true | none | Direction: 'sell' fetches the bid side, 'buy' fetches the ask side. |
| iceberg | integer(int64) | false | none | Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees. |
| level | integer(int64) | true | write-only | Level: maximum 20 levels |
| close | boolean | false | write-only | Set as true to close the position, with size set to 0 |
| is_close | boolean | false | read-only | Is the order to close position |
| reduce_only | boolean | false | write-only | Set as true to be reduce-only order |
| is_reduce_only | boolean | false | read-only | Is the order reduce-only |
| is_liq | boolean | false | read-only | Is the order for liquidation |
| tif | string | false | none | Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none |
| left | integer(int64) | false | read-only | Unfilled quantity |
| fill_price | string | false | read-only | Fill price |
| text | string | false | none | Order Custom Information: Users can set custom IDs via this field. Custom fields must meet the following conditions: 1. Must start with t-2. Excluding t-, length cannot exceed 28 bytes3. Content can only contain numbers, letters, underscores (_), hyphens (-), or dots (.) In addition to user custom information, the following are internal reserved fields identifying order sources: - web: Web - api: API Call - app: Mobile App - auto_deleveraging: Auto-Deleveraging - liquidation: Forced Liquidation of Legacy Classic Mode Positions - liq-xxx: a. Forced liquidation of New Classic Mode positions, including isolated margin, single-direction cross margin, and non-hedged dual-direction cross margin positions. b. Forced liquidation of isolated margin positions in Unified Account Single-Currency Margin Mode - hedge-liq-xxx: Forced liquidation of hedged portions in New Classic Mode dual-direction cross margin (simultaneous closing of long and short positions) - pm_liquidate: Forced liquidation in Unified Account Cross-Currency Margin Mode - comb_margin_liquidate: Forced liquidation in Unified Account Portfolio Margin Mode - scm_liquidate: Forced liquidation of positions in Unified Account Single-Currency Margin Mode - insurance: Insurance |
| tkfr | string | false | read-only | Taker fee |
| mkfr | string | false | read-only | Maker fee |
| refu | integer | false | read-only | Referrer user ID |
| auto_size | string | false | write-only | Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0 |
| stp_id | integer | false | read-only | Orders between users in the same stp_id group are not allowed to be self-traded1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker.2. stp_id returns 0 by default for orders that have not been set for STP group |
| stp_act | string | false | none | Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy.2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter.3. If the user did not use stp_act when placing the order, stp_act will return '-'- cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled |
| amend_text | string | false | read-only | The custom data that the user remarked when amending the order |
| pid | integer(int64) | false | write-only | Position ID |
| Property | Value |
|---|---|
| tif | gtc |
| tif | ioc |
| tif | poc |
| tif | fok |
| auto_size | close_long |
| auto_size | close_short |
| stp_act | co |
| stp_act | cn |
| stp_act | cb |
| stp_act | - |
{
"order_id": 0,
"text": "string",
"size": "string",
"price": "string",
"amend_text": "string",
"action_mode": "string"
}
Modify contract order parameters
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| order_id | integer(int64) | false | none | Order id, order_id and text must contain at least one |
| text | string | false | none | User-defined order text, at least one of order_id and text must be passed |
| size | string | false | none | New order size, including filled size. - If less than or equal to the filled quantity, the order will be cancelled. - The new order side must be identical to the original one. - Close order size cannot be modified. - For reduce-only orders, increasing the size may cancel other reduce-only orders. - If the price is not modified, decreasing the size will not affect the depth queue, while increasing the size will place it at the end of the current price level. |
| price | string | false | none | New order price |
| amend_text | string | false | none | Custom info during order amendment |
| action_mode | string | false | none | 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) |
{
"contract": "string",
"data": [
{
"t": 0,
"r": "string"
}
]
}
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| contract | string | false | none | Contract name |
| data | array | false | none | Array of Funding Rates |
| » t | integer(int64) | false | none | Unix timestamp in seconds |
| » r | string | false | none | Funding rate |
{
"code": 0,
"message": "string",
"data": {
"id": "string"
},
"timestamp": 0
}
CreateTrailOrderResponse
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| code | integer(int32) | false | none | Status code, 0 means success |
| message | string | false | none | Response message |
| data | object | false | none | none |
| » id | string | false | none | Order ID |
| timestamp | integer(int64) | false | none | Response timestamp (milliseconds) |
{
"code": 0,
"message": "string",
"data": {
"order": {
"id": 0,
"user_id": 0,
"user": 0,
"contract": "string",
"settle": "string",
"amount": "string",
"is_gte": true,
"activation_price": "string",
"price_type": 0,
"price_offset": "string",
"text": "string",
"reduce_only": true,
"position_related": true,
"created_at": 0,
"activated_at": 0,
"finished_at": 0,
"create_time": 0,
"active_time": 0,
"finish_time": 0,
"reason": "string",
"suborder_text": "string",
"is_dual_mode": true,
"trigger_price": "string",
"suborder_id": 0,
"side_label": "string",
"original_status": 0,
"status": "open",
"position_side_output": "string",
"updated_at": 0,
"extremum_price": "string",
"status_code": "string",
"created_at_precise": "string",
"finished_at_precise": "string",
"activated_at_precise": "string",
"status_label": "string",
"pos_margin_mode": "string",
"position_mode": "string",
"error_label": "string",
"leverage": "string"
}
},
"timestamp": 0
}
TrailOrderDetailResponse
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| code | integer(int32) | false | none | Status code, 0 means success |
| message | string | false | none | Response message |
| data | object | false | none | none |
| » order | object | false | none | Trail order details |
| »» id | integer(int64) | false | read-only | Order ID |
| »» user_id | integer(int64) | false | read-only | User ID |
| »» user | integer(int64) | false | read-only | User ID |
| »» contract | string | false | none | Contract name |
| »» settle | string | false | none | Settle currency |
| »» amount | string | false | none | Trading quantity in contracts, positive for buy, negative for sell |
| »» is_gte | boolean | false | none | true: activate when market price >= activation price, false: <= activation price |
| »» activation_price | string | false | none | Activation price, 0 means trigger immediately |
| »» price_type | integer(int32) | false | none | Activation price type: 0-unknown, 1-latest price, 2-index price, 3-mark price |
| »» price_offset | string | false | none | Callback ratio or price distance, e.g., 0.1 or 0.1% |
| »» text | string | false | none | Custom field |
| »» reduce_only | boolean | false | none | Reduce Position Only |
| »» position_related | boolean | false | none | Whether bound to position |
| »» created_at | integer(int64) | false | read-only | Created time |
| »» activated_at | integer(int64) | false | read-only | Activation time |
| »» finished_at | integer(int64) | false | read-only | End time |
| »» create_time | integer(int64) | false | read-only | Created time |
| »» active_time | integer(int64) | false | read-only | Activation time |
| »» finish_time | integer(int64) | false | read-only | End time |
| »» reason | string | false | read-only | End reason |
| »» suborder_text | string | false | read-only | Sub-order text field |
| »» is_dual_mode | boolean | false | read-only | Whether dual position mode when creating order |
| »» trigger_price | string | false | read-only | Trigger price |
| »» suborder_id | integer(int64) | false | read-only | Sub-order ID |
| »» side_label | string | false | read-only | Order direction label: long/short/open long/open short/close long/close short |
| »» original_status | integer(int32) | false | read-only | Order status |
| »» status | string | false | read-only | Simplified order status: open/finished |
| »» position_side_output | string | false | read-only | Same as side_label, client requires consistency with other order types |
| »» updated_at | integer(int64) | false | read-only | Update time |
| »» extremum_price | string | false | read-only | Extremum price |
| »» status_code | string | false | read-only | Status code value |
| »» created_at_precise | string | false | read-only | Creation time (high precision, seconds.microseconds format) |
| »» finished_at_precise | string | false | read-only | End time (high precision, seconds.microseconds format) |
| »» activated_at_precise | string | false | read-only | Activation time (high precision, seconds.microseconds format) |
| »» status_label | string | false | read-only | Status internationalization label (translated status text) |
| »» pos_margin_mode | string | false | read-only | Position margin mode: isolated/cross |
| »» position_mode | string | false | read-only | Position mode: single, dual, and dual_plus |
| »» error_label | string | false | read-only | Error label |
| »» leverage | string | false | read-only | leverage |
| » timestamp | integer(int64) | false | none | Response timestamp (milliseconds) |
| Property | Value |
|---|---|
| price_type | 0 |
| price_type | 1 |
| price_type | 2 |
| price_type | 3 |
| status | open |
| status | finished |
{
"change_log": [
{
"updated_at": 0,
"amount": "string",
"is_gte": true,
"activation_price": "string",
"price_type": 0,
"price_offset": "string",
"is_create": true
}
]
}
TrailOrderChangeLogResponse
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| change_log | [TrailChangeLog] | false | none | [Trail order modification records] |
{
"contract": "string",
"settle": "string",
"amount": "string",
"price_limit": "string",
"offset_limit": "string",
"reduce_only": true,
"text": "string",
"is_dual_mode": true,
"price_type": 0,
"price_gap_type": 0,
"price_gap_value": "string",
"pos_margin_mode": "string",
"position_mode": "string"
}
Request body for creating a chase order
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| contract | string | true | none | Contract name; server-side converted to uppercase |
| settle | string | false | none | Settle currency, overridden by the path parameter and converted to lowercase |
| amount | string | true | none | Total order size in contracts, decimal string. Positive for buy, negative for sell. Cannot be 0 |
| price_limit | string | true | none | 最高追逐价，合法十进制字符串；未设置限价时请传 "0" |
| offset_limit | string | false | none | Maximum chasing distance from the best price, mutually exclusive with price_limit |
| reduce_only | boolean | false | none | Whether reduce only |
| text | string | false | none | Optional custom tag |
| is_dual_mode | boolean | false | none | Whether dual-position mode is enabled |
| price_type | integer(int64) | false | none | Price type: 1 best bid/ask, 2 distance from best bid/ask |
| price_gap_type | integer(int64) | false | none | Used when price_type == 2: 1 absolute price gap, 2 percentage |
| price_gap_value | string | false | none | Price gap value paired with price_gap_type |
| pos_margin_mode | string | false | none | Position margin mode, e.g. isolated or cross |
| position_mode | string | false | none | Position mode (e.g. single, dual, dual_plus) |
{
"id": "string",
"text": "string",
"settle": "string"
}
Request body for stopping a chase order
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | false | none | Order ID. Either id or text must be provided |
| text | string | false | none | Custom text. Required only when id is 0 or omitted |
| settle | string | false | none | Overridden by the path parameter |
{
"order": {
"id": "string",
"user": "string",
"contract": "string",
"settle": "string",
"amount": "string",
"price_limit": "string",
"reduce_only": true,
"text": "string",
"create_time": 0,
"finish_time": 0,
"original_status": 0,
"status": "string",
"reason": "string",
"fill_amount": "string",
"average_fill_price": "string",
"suborder_id": "string",
"is_dual_mode": true,
"side_label": "string",
"position_side_output": "string",
"chase_price": "string",
"interval_sec": 0,
"updated_at": 0,
"suborder_price": "string",
"suborder_ongoing": true,
"suborder_finish_as": "string",
"price_type": 0,
"price_gap_type": "string",
"price_gap_value": "string",
"status_code": "string",
"create_time_precise": "string",
"finish_time_precise": "string",
"pos_margin_mode": "string",
"position_mode": "string",
"leverage": "string",
"error_label": "string"
}
}
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| order | ChaseOrder | false | none | Chase order detail or list item |
{
"contract": "string",
"settle": "string",
"pos_margin_mode": "string"
}
Request body for stopping chase orders in batch
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| contract | string | false | none | Optional contract name |
| settle | string | false | none | Overridden by the path parameter |
| pos_margin_mode | string | false | none | Optional margin mode |
{
"orders": [
{
"id": "string",
"user": "string",
"contract": "string",
"settle": "string",
"amount": "string",
"price_limit": "string",
"reduce_only": true,
"text": "string",
"create_time": 0,
"finish_time": 0,
"original_status": 0,
"status": "string",
"reason": "string",
"fill_amount": "string",
"average_fill_price": "string",
"suborder_id": "string",
"is_dual_mode": true,
"side_label": "string",
"position_side_output": "string",
"chase_price": "string",
"interval_sec": 0,
"updated_at": 0,
"suborder_price": "string",
"suborder_ongoing": true,
"suborder_finish_as": "string",
"price_type": 0,
"price_gap_type": "string",
"price_gap_value": "string",
"status_code": "string",
"create_time_precise": "string",
"finish_time_precise": "string",
"pos_margin_mode": "string",
"position_mode": "string",
"leverage": "string",
"error_label": "string"
}
]
}
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| orders | [ChaseOrder] | false | none | [Chase order detail or list item] |
{
"orders": [
{
"id": "string",
"user": "string",
"contract": "string",
"settle": "string",
"amount": "string",
"price_limit": "string",
"reduce_only": true,
"text": "string",
"create_time": 0,
"finish_time": 0,
"original_status": 0,
"status": "string",
"reason": "string",
"fill_amount": "string",
"average_fill_price": "string",
"suborder_id": "string",
"is_dual_mode": true,
"side_label": "string",
"position_side_output": "string",
"chase_price": "string",
"interval_sec": 0,
"updated_at": 0,
"suborder_price": "string",
"suborder_ongoing": true,
"suborder_finish_as": "string",
"price_type": 0,
"price_gap_type": "string",
"price_gap_value": "string",
"status_code": "string",
"create_time_precise": "string",
"finish_time_precise": "string",
"pos_margin_mode": "string",
"position_mode": "string",
"leverage": "string",
"error_label": "string"
}
]
}
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| orders | [ChaseOrder] | false | none | [Chase order detail or list item] |
{
"order": {
"id": "string",
"user": "string",
"contract": "string",
"settle": "string",
"amount": "string",
"price_limit": "string",
"reduce_only": true,
"text": "string",
"create_time": 0,
"finish_time": 0,
"original_status": 0,
"status": "string",
"reason": "string",
"fill_amount": "string",
"average_fill_price": "string",
"suborder_id": "string",
"is_dual_mode": true,
"side_label": "string",
"position_side_output": "string",
"chase_price": "string",
"interval_sec": 0,
"updated_at": 0,
"suborder_price": "string",
"suborder_ongoing": true,
"suborder_finish_as": "string",
"price_type": 0,
"price_gap_type": "string",
"price_gap_value": "string",
"status_code": "string",
"create_time_precise": "string",
"finish_time_precise": "string",
"pos_margin_mode": "string",
"position_mode": "string",
"leverage": "string",
"error_label": "string"
}
}
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| order | ChaseOrder | false | none | Chase order detail or list item |
{
"updated_at": 0,
"amount": "string",
"is_gte": true,
"activation_price": "string",
"price_type": 0,
"price_offset": "string",
"is_create": true
}
Trail order modification records
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| updated_at | integer(int64) | false | read-only | Update time |
| amount | string | false | read-only | Trading quantity in contracts, positive for buy, negative for sell |
| is_gte | boolean | false | read-only | true: activate when market price >= activation price, false: <= activation price |
| activation_price | string | false | read-only | Activation price, 0 means trigger immediately |
| price_type | integer(int32) | false | read-only | Activation price type: 0-unknown, 1-latest price, 2-index price, 3-mark price |
| price_offset | string | false | read-only | Callback ratio or price distance, e.g., 0.1 or 0.1% |
| is_create | boolean | false | read-only | true - order creation, false - order modification |
| Property | Value |
|---|---|
| price_type | 0 |
| price_type | 1 |
| price_type | 2 |
| price_type | 3 |
{
"id": "string",
"user": "string",
"contract": "string",
"settle": "string",
"amount": "string",
"price_limit": "string",
"reduce_only": true,
"text": "string",
"create_time": 0,
"finish_time": 0,
"original_status": 0,
"status": "string",
"reason": "string",
"fill_amount": "string",
"average_fill_price": "string",
"suborder_id": "string",
"is_dual_mode": true,
"side_label": "string",
"position_side_output": "string",
"chase_price": "string",
"interval_sec": 0,
"updated_at": 0,
"suborder_price": "string",
"suborder_ongoing": true,
"suborder_finish_as": "string",
"price_type": 0,
"price_gap_type": "string",
"price_gap_value": "string",
"status_code": "string",
"create_time_precise": "string",
"finish_time_precise": "string",
"pos_margin_mode": "string",
"position_mode": "string",
"leverage": "string",
"error_label": "string"
}
Chase order detail or list item
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | false | none | none |
| user | string | false | none | none |
| contract | string | false | none | none |
| settle | string | false | none | none |
| amount | string | false | none | Total size in contracts; positive for buy, negative for sell |
| price_limit | string | false | none | none |
| reduce_only | boolean | false | none | none |
| text | string | false | none | none |
| create_time | integer(int64) | false | none | none |
| finish_time | integer(int64) | false | none | none |
| original_status | integer | false | none | Raw status enum |
| status | string | false | none | Simplified status, e.g. open / finished |
| reason | string | false | none | none |
| fill_amount | string | false | none | none |
| average_fill_price | string | false | none | none |
| suborder_id | string | false | none | none |
| is_dual_mode | boolean | false | none | none |
| side_label | string | false | none | none |
| position_side_output | string | false | none | none |
| chase_price | string | false | none | none |
| interval_sec | integer(uint32) | false | none | none |
| updated_at | integer(int64) | false | none | none |
| suborder_price | string | false | none | none |
| suborder_ongoing | boolean | false | none | none |
| suborder_finish_as | string | false | none | none |
| price_type | integer | false | none | PriceType enum: 1 latest, 2 index, 3 mark |
| price_gap_type | string | false | none | none |
| price_gap_value | string | false | none | none |
| status_code | string | false | none | none |
| create_time_precise | string | false | none | Creation time (seconds.microseconds) |
| finish_time_precise | string | false | none | none |
| pos_margin_mode | string | false | none | none |
| position_mode | string | false | none | none |
| leverage | string | false | none | none |
| error_label | string | false | none | none |
{
"currency": "string",
"currency_pair": "string",
"amount": "string"
}
MarginTransferable
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| currency | string | false | none | Currency detail |
| currency_pair | string | false | none | Currency pair |
| amount | string | false | none | Max transferable amount |
{
"currency": "string",
"currency_pair": "string",
"borrowable": "string"
}
MaxUniBorrowable
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| currency | string | true | read-only | Currency |
| currency_pair | string | false | read-only | Currency pair |
| borrowable | string | true | read-only | Maximum borrowable |
{
"ip_whitelist": [
"string"
],
"currency_pairs": [
"string"
],
"user_id": 0,
"tier": 0,
"key": {
"mode": 0
},
"copy_trading_role": 0
}
AccountDetail
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| ip_whitelist | array | false | none | IP Whitelist |
| currency_pairs | array | false | none | Trading pair whitelist |
| user_id | integer(int64) | false | none | User ID |
| tier | integer(int64) | false | none | User VIP level |
| key | object | false | none | API Key details |
| » mode | integer(int32) | false | none | Mode: 1 - Classic mode, 2 - Legacy unified mode |
| copy_trading_role | integer(int32) | false | none | User role: 0 - Normal user 1 - Copy trading leader 2 - Copy trading follower 3 - Both leader and follower |
{
"state": 0,
"mode": 0,
"name": "string",
"currency_pairs": [
"string"
],
"user_id": 0,
"ip_whitelist": [
"string"
],
"perms": [
{
"name": "string",
"read_only": true
}
],
"key": {
"mode": 0
},
"created_at": "string",
"updated_at": "string",
"last_access": "string"
}
AccountKeyInfo
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| state | integer(int32) | false | none | API key status: 1 - Normal, 2 - Locked, 3 - Frozen (can only be modified, default is 1 when creating)API Key Status: 1 - Normal, 2 - Locked, 3 - Frozen (can only be modified; default is 1 upon creation) |
| mode | integer(int32) | false | none | User mode: 1 - Classic mode, 2 - Legacy unified mode (can only be specified when creating, cannot be modified) |
| name | string | false | none | API Key Remark |
| currency_pairs | array | false | none | Trading Pair Whitelist, Maximum 30 Pairs |
| user_id | integer(int64) | false | none | User ID |
| ip_whitelist | array | false | none | IP Whitelist |
| perms | array | false | none | none |
| » name | string | false | none | Permission function name (no value will be cleared) - wallet: wallet- spot: spot/margin- futures: perpetual contract- delivery: delivery contract- earn: earn- custody: custody- options: options- account: account information- loan: lending- margin: margin- unified: unified account- copy: copy trading- pilot: pilot- otc: otc- alpha: alpha- crossx: cross-exchange |
| » read_only | boolean | false | none | Read Only |
| key | object | false | none | API Key details |
| » mode | integer(int32) | false | none | Mode: 1 - Classic mode, 2 - Legacy unified mode |
| created_at | string | false | read-only | Created time |
| updated_at | string | false | read-only | Last Update Time |
| last_access | string | false | read-only | Last Access Time |