# Futures

Perpetual futures

# Query all futures contracts

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/contracts'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())


curl -X GET https://api.gateio.ws/api/v4/futures/usdt/contracts \
  -H 'Accept: application/json'

GET /futures/{settle}/contracts

Query all futures contracts

Parameters

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

# Enumerated Values

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"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	[Futures contract details]
» None	Contract	Futures contract details
»» name	string	Futures contract
»» type	string	Contract type: inverse - inverse contract, direct - direct contract
»» quanto_multiplier	string	The contract multiplier indicates how many units of the underlying asset the face value of one contract represents.
»» leverage_min	string	Minimum leverage
»» leverage_max	string	Maximum leverage
»» maintenance_rate	string	The maintenance margin rate of the first tier of risk limit sheet
»» mark_type	string	Deprecated
»» mark_price	string	Current mark price
»» index_price	string	Current index price
»» last_price	string	Last trading price
»» maker_fee_rate	string	Maker fee rate, negative values indicate rebates
»» taker_fee_rate	string	Taker fee rate
»» order_price_round	string	Minimum order price increment
»» mark_price_round	string	Minimum mark price increment
»» funding_rate	string	Current funding rate
»» funding_interval	integer	Funding application interval, unit in seconds
»» funding_next_apply	number(double)	Next funding time
»» risk_limit_base	string	Base risk limit (deprecated)
»» interest_rate	string	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	Risk limit adjustment step (deprecated)
»» risk_limit_max	string	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	Minimum order size allowed by the contract
»» enable_decimal	boolean	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	Maximum order size allowed by the contract
»» order_price_deviate	string	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	Trading fee discount for referred users
»» ref_rebate_rate	string	Commission rate for referrers
»» orderbook_id	integer(int64)	Orderbook update ID
»» trade_id	integer(int64)	Current trade ID
»» trade_size	string	Historical cumulative trading volume
»» position_size	string	Current total long position size
»» config_change_time	number(double)	Last configuration update time
»» in_delisting	boolean	`in_delisting=true` and position_size>0 indicates the contract is in delisting transition period `in_delisting=true` and position_size=0 indicates the contract is delisted
»» orders_limit	integer	Maximum number of pending orders
»» enable_bonus	boolean	Whether bonus is enabled
»» enable_credit	boolean	Whether portfolio margin account is enabled
»» create_time	number(double)	Created time of the contract
»» funding_cap_ratio	string	Deprecated
»» status	string	Contract status types include: prelaunch (pre-launch), trading (active), delisting (delisting), delisted (delisted), circuit_breaker (circuit breaker)
»» launch_time	integer(int64)	Contract expiry timestamp
»» delisting_time	integer(int64)	Timestamp when contract enters reduce-only state
»» delisted_time	integer(int64)	Contract delisting time
»» market_order_slip_ratio	string	The maximum slippage allowed for market orders, with the slippage rate calculated based on the latest market price
»» market_order_size_max	string	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	Upper and lower limits of funding rate
»» contract_type	string	Contract classification type, e.g. stocks, metals, indices, forex, commodities, etc.
»» funding_impact_value	string	Funding rate depth impact value

# Enumerated Values

Property	Value
type	inverse
type	direct
mark_type	internal
mark_type	index

# Query single contract information

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/contracts/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())


curl -X GET https://api.gateio.ws/api/v4/futures/usdt/contracts/BTC_USDT \
  -H 'Accept: application/json'

GET /futures/{settle}/contracts/{contract}

Query single contract information

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	path	string	true	Futures contract

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

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"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Contract information	Contract

Response Schema

Status Code 200

Futures contract details

Name	Type	Description
» name	string	Futures contract
» type	string	Contract type: inverse - inverse contract, direct - direct contract
» quanto_multiplier	string	The contract multiplier indicates how many units of the underlying asset the face value of one contract represents.
» leverage_min	string	Minimum leverage
» leverage_max	string	Maximum leverage
» maintenance_rate	string	The maintenance margin rate of the first tier of risk limit sheet
» mark_type	string	Deprecated
» mark_price	string	Current mark price
» index_price	string	Current index price
» last_price	string	Last trading price
» maker_fee_rate	string	Maker fee rate, negative values indicate rebates
» taker_fee_rate	string	Taker fee rate
» order_price_round	string	Minimum order price increment
» mark_price_round	string	Minimum mark price increment
» funding_rate	string	Current funding rate
» funding_interval	integer	Funding application interval, unit in seconds
» funding_next_apply	number(double)	Next funding time
» risk_limit_base	string	Base risk limit (deprecated)
» interest_rate	string	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	Risk limit adjustment step (deprecated)
» risk_limit_max	string	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	Minimum order size allowed by the contract
» enable_decimal	boolean	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	Maximum order size allowed by the contract
» order_price_deviate	string	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	Trading fee discount for referred users
» ref_rebate_rate	string	Commission rate for referrers
» orderbook_id	integer(int64)	Orderbook update ID
» trade_id	integer(int64)	Current trade ID
» trade_size	string	Historical cumulative trading volume
» position_size	string	Current total long position size
» config_change_time	number(double)	Last configuration update time
» in_delisting	boolean	`in_delisting=true` and position_size>0 indicates the contract is in delisting transition period `in_delisting=true` and position_size=0 indicates the contract is delisted
» orders_limit	integer	Maximum number of pending orders
» enable_bonus	boolean	Whether bonus is enabled
» enable_credit	boolean	Whether portfolio margin account is enabled
» create_time	number(double)	Created time of the contract
» funding_cap_ratio	string	Deprecated
» status	string	Contract status types include: prelaunch (pre-launch), trading (active), delisting (delisting), delisted (delisted), circuit_breaker (circuit breaker)
» launch_time	integer(int64)	Contract expiry timestamp
» delisting_time	integer(int64)	Timestamp when contract enters reduce-only state
» delisted_time	integer(int64)	Contract delisting time
» market_order_slip_ratio	string	The maximum slippage allowed for market orders, with the slippage rate calculated based on the latest market price
» market_order_size_max	string	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	Upper and lower limits of funding rate
» contract_type	string	Contract classification type, e.g. stocks, metals, indices, forex, commodities, etc.
» funding_impact_value	string	Funding rate depth impact value

# Enumerated Values

Property	Value
type	inverse
type	direct
mark_type	internal
mark_type	index

# Query futures market depth information

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/order_book'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())


curl -X GET https://api.gateio.ws/api/v4/futures/usdt/order_book?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /futures/{settle}/order_book

Query futures market depth information

Bids will be sorted by price from high to low, while asks sorted reversely

Parameters

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

# Enumerated Values

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"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Depth query successful	FuturesOrderBook

Response Schema

Status Code 200

Name	Type	Description
» id	integer(int64)	Order Book ID. Increases by 1 on every order book change. Set `with_id=true` to include this field in response
» current	number(double)	Response data generation timestamp
» update	number(double)	Order book changed timestamp
» asks	array	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

# Futures market transaction records

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/trades'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())


curl -X GET https://api.gateio.ws/api/v4/futures/usdt/trades?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /futures/{settle}/trades

Futures market transaction records

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	true	Futures contract
limit	query	integer	false	Maximum number of records 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 This parameter is deprecated. Use `from` and `to` instead to limit time range
from	query	integer(int64)	false	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.
to	query	integer(int64)	false	Specify end time in Unix seconds, default to current time.

# Detailed descriptions

last_id: Specify the starting point for this list based on a previously retrieved id

This parameter is deprecated. Use from and to instead to limit time range

from: Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items.
If items between from and to are more than limit, only limit number will be returned.

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

[
  {
    "id": 121234231,
    "create_time": 1514764800,
    "contract": "BTC_USDT",
    "size": "-100",
    "price": "100.123"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» id	integer(int64)	Fill ID
» create_time	number(double)	Fill Time
» create_time_ms	number(double)	Trade time, with millisecond precision to 3 decimal places
» contract	string	Futures contract
» size	string	Trading size
» price	string	Trade price (quote currency)
» is_internal	boolean	Deprecated

# Futures market K-line chart

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/candlesticks'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())


curl -X GET https://api.gateio.ws/api/v4/futures/usdt/candlesticks?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /futures/{settle}/candlesticks

Futures market K-line chart

Return specified contract candlesticks. If prefix contract with mark_, the contract's mark price candlesticks are returned; if prefix with index_, index price candlesticks will be returned.

Maximum of 2000 points are returned in one query. Be sure not to exceed the limit when specifying from, to and interval

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	true	Futures contract
from	query	integer(int64)	false	Start time of candlesticks, formatted in Unix timestamp in seconds. Default to`to - 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

# Enumerated Values

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"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Query successful	[FuturesCandlestick]

Response Schema

Status Code 200

Name	Type	Description
None	array	[data point in every timestamp]
» None	FuturesCandlestick	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)

# Premium Index K-line chart

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/premium_index'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())


curl -X GET https://api.gateio.ws/api/v4/futures/usdt/premium_index?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /futures/{settle}/premium_index

Premium Index K-line chart

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

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	true	Futures contract
from	query	integer(int64)	false	Start time of candlesticks, formatted in Unix timestamp in seconds. Default to`to - 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

# Enumerated Values

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"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Query successful	[FuturesPremiumIndex]

Response Schema

Status Code 200

Name	Type	Description
None	array	[data point in every timestamp]
» None	FuturesPremiumIndex	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

# Get all futures trading statistics

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/tickers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())


curl -X GET https://api.gateio.ws/api/v4/futures/usdt/tickers \
  -H 'Accept: application/json'

GET /futures/{settle}/tickers

Get all futures trading statistics

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	false	Futures contract, return related data only if specified

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

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"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Query successful	[FuturesTicker]

Response Schema

Status Code 200

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

# Futures market historical funding rate

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/funding_rate'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())


curl -X GET https://api.gateio.ws/api/v4/futures/usdt/funding_rate?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /futures/{settle}/funding_rate

Futures market historical funding rate

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	true	Futures contract
limit	query	integer	false	Maximum number of records returned in a single list
from	query	integer(int64)	false	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	query	integer(int64)	false	Termination Timestamp Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp

# Detailed descriptions

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

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

[
  {
    "t": 1543968000,
    "r": "0.000157"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	History query successful	[FundingRateRecord]

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» t	integer(int64)	Unix timestamp in seconds
» r	string	Funding rate

# Batch Query Historical Funding Rate Data for Perpetual Contracts

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/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 https://api.gateio.ws/api/v4/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"
  ]
}

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
body	body	BatchFundingRatesRequest	true	none
» contracts	body	array	true	Array of Contract Names

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

[
  [
    {
      "contract": "BTC_USDT",
      "data": [
        {
          "t": 1543968000,
          "r": "0.000157"
        },
        {
          "t": 1544054400,
          "r": "0.000145"
        }
      ]
    }
  ]
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Batch Query Successful	[BatchFundingRatesResponse]

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» contract	string	Contract name
» data	array	Array of Funding Rates
»» t	integer(int64)	Unix timestamp in seconds
»» r	string	Funding rate

# Futures market insurance fund history

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/insurance'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())


curl -X GET https://api.gateio.ws/api/v4/futures/usdt/insurance \
  -H 'Accept: application/json'

GET /futures/{settle}/insurance

Futures market insurance fund history

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
limit	query	integer	false	Maximum number of records returned in a single list

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

[
  {
    "t": 1543968000,
    "b": "83.0031"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Query successful	[InsuranceRecord]

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» t	integer(int64)	Unix timestamp in seconds
» b	string	Insurance balance

# Futures statistics

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/contract_stats'
query_param = 'contract=BTC_USDT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())


curl -X GET https://api.gateio.ws/api/v4/futures/usdt/contract_stats?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /futures/{settle}/contract_stats

Futures statistics

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	true	Futures contract
from	query	integer(int64)	false	Start timestamp
interval	query	string	false	none
limit	query	integer	false	none

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

[
  {
    "time": 1603865400,
    "lsr_taker": 100,
    "lsr_account": 0.5,
    "long_liq_size": "0",
    "short_liq_size": "0",
    "open_interest": "124724",
    "short_liq_usd": 0,
    "mark_price": "8865",
    "top_lsr_size": "1.02",
    "short_liq_amount": 0,
    "long_liq_amount": 0,
    "open_interest_usd": 1511,
    "top_lsr_account": 1.5,
    "long_liq_usd": 0
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» 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)
» 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)
» 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

# Query index constituents

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/index_constituents/BTC_USDT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())


curl -X GET https://api.gateio.ws/api/v4/futures/usdt/index_constituents/BTC_USDT \
  -H 'Accept: application/json'

GET /futures/{settle}/index_constituents/{index}

Query index constituents

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
index	path	string	true	Index name

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

{
  "index": "BTC_USDT",
  "constituents": [
    {
      "exchange": "Binance",
      "symbols": [
        "BTC_USDT"
      ]
    },
    {
      "exchange": "Gate.com",
      "symbols": [
        "BTC_USDT"
      ]
    },
    {
      "exchange": "Huobi",
      "symbols": [
        "BTC_USDT"
      ]
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Query successful	FuturesIndexConstituents

Response Schema

Status Code 200

Name	Type	Description
» index	string	Index name
» constituents	array	Constituents
»» IndexConstituent	object	none
»»» exchange	string	Exchange
»»» symbols	array	Symbol list

# Query liquidation order history

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/liq_orders'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())


curl -X GET https://api.gateio.ws/api/v4/futures/usdt/liq_orders \
  -H 'Accept: application/json'

GET /futures/{settle}/liq_orders

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

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	false	Futures contract, return related data only if specified
from	query	integer(int64)	false	Start timestamp 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	query	integer(int64)	false	Termination Timestamp Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
limit	query	integer	false	Maximum number of records returned in a single list

# Detailed descriptions

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

# Enumerated Values

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"
  }
]

Responses

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

Response Schema

Status Code 200

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

# Query risk limit tiers

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/risk_limit_tiers'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())


curl -X GET https://api.gateio.ws/api/v4/futures/usdt/risk_limit_tiers \
  -H 'Accept: application/json'

GET /futures/{settle}/risk_limit_tiers

Query risk limit tiers

When the 'contract' parameter is not passed, the default is to query the risk limits for the top 100 markets. 'Limit' and 'offset' correspond to pagination queries at the market level, not to the length of the returned array. This only takes effect when the contract parameter is empty.

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	false	Futures contract, return related data only if specified
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0

# Enumerated Values

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"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Query successful	[FuturesLimitRiskTiers]

Response Schema

Status Code 200

Name	Type	Description
None	array	[Retrieve risk limit configurations for different tiers under a specified contract]
» None	FuturesLimitRiskTiers	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

# Get futures account

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/accounts'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/accounts"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/accounts

Get futures account

Query account information for classic future account and unified account

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency

# Enumerated Values

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
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Query successful	FuturesAccount

Response Schema

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.

WARNING

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

# Query futures account change history

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/account_book'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/account_book"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/account_book

Query futures account change history

If the contract field is passed, only records containing this field after 2023-10-30 can be filtered。

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	false	Futures contract, return related data only if specified
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0
from	query	integer(int64)	false	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	query	integer(int64)	false	Termination Timestamp Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
type	query	string	false	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

# Detailed descriptions

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:

- 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

# Enumerated Values

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"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» time	number(double)	Change time
» change	string	Change amount
» balance	string	Balance after change
» type	string	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

# Enumerated Values

Property	Value
type	dnw
type	pnl
type	fee
type	refr
type	fund
type	point_dnw
type	point_fee
type	point_refr
type	bonus_offset

WARNING

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

# Get user position list

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/positions'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/positions"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/positions

Get user position list

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
holding	query	boolean	false	Return only real positions - true, return all - false
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0

# Enumerated Values

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"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	[Futures position details]
» None	Position	Futures position details
»» user	integer(int64)	User ID
»» contract	string	Futures contract
»» size	string	Position size
»» leverage	string	leverage for isolated margin. 0 means cross margin. For leverage of cross margin, please refer to `cross_leverage_limit`.
»» risk_limit	string	Position risk limit
»» leverage_max	string	the maximum permissible leverage given to the current positon value: the higher positon value, the lower maximum permissible leverage
»» maintenance_rate	string	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	Position value calculated in settlement currency
»» margin	string	Position margin
»» entry_price	string	Entry price
»» liq_price	string	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	Current mark price
»» initial_margin	string	Initial margin of postions
»» maintenance_margin	string	Maintencance margin of postions
»» unrealised_pnl	string	Unrealized PNL
»» realised_pnl	string	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	settled pnl when closing postion
»» pnl_fund	string	funding fees
»» pnl_fee	string	trading fees
»» history_pnl	string	Total realized PnL from closed positions
»» last_close_pnl	string	PNL of last position close
»» realised_point	string	Realized POINT PNL
»» history_point	string	History realized POINT PNL
»» adl_ranking	integer	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	Current pending order quantity
»» close_order	object\|null	Current close order information, or `null` if no close order
»»» id	integer(int64)	Order ID
»»» price	string	Order price
»»» is_liq	boolean	Whether the close order is from liquidation
»» mode	string	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	leverage for cross margin
»» update_time	integer(int64)	Last update time
»» update_id	integer(int64)	Update ID. The value increments by 1 each time the position is updated
»» open_time	integer(int64)	First Open Time
»» risk_limit_table	string	Risk limit table ID
»» average_maintenance_rate	string	Average maintenance margin rate
»» pid	integer(int64)	Sub-account position ID
»» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin
»» lever	string	Indicates the current leverage of the position, applicable to both isolated and cross margin, gradually replacing the current leverage and cross_leverage_limit

# Enumerated Values

Property	Value
mode	single
mode	dual_long
mode	dual_short

WARNING

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

# Get user's historical position information list by time

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/positions_timerange'
query_param = 'contract=BTC_USDT'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/positions_timerange"
query_param="contract=BTC_USDT"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/positions_timerange

Get user's historical position information list by time

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	true	Futures contract
from	query	integer(int64)	false	Start timestamp 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	query	integer(int64)	false	Termination Timestamp Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0

# Detailed descriptions

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

# Enumerated Values

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"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	[Contract position details (historical data)]
» None	PositionTimerange	Contract position details (historical data)
»» contract	string	Futures contract
»» size	string	Position size
»» leverage	string	Position leverage. 0 means cross margin; positive number means isolated margin
»» risk_limit	string	Position risk limit
»» leverage_max	string	the maximum permissible leverage given to the current positon value: the higher positon value, the lower maximum permissible leverage
»» maintenance_rate	string	The maintenance margin rate of the first tier of risk limit sheet
»» margin	string	Position margin
»» liq_price	string	Liquidation price
»» realised_pnl	string	Realized PnL
»» history_pnl	string	Total realized PnL from closed positions
»» last_close_pnl	string	PNL of last position close
»» realised_point	string	Realized POINT PNL
»» history_point	string	History realized POINT PNL
»» mode	string	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	Cross margin leverage (valid only when `leverage` is 0)
»» entry_price	string	Entry price
»» time	integer(int64)	Timestamp

WARNING

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

# Get single position information

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/positions/BTC_USDT'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/positions/BTC_USDT"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/positions/{contract}

Get single position information

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}

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	path	string	true	Futures contract

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

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"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Position information	Position

Response Schema

Status Code 200

Futures position details

Name	Type	Description
» user	integer(int64)	User ID
» contract	string	Futures contract
» size	string	Position size
» leverage	string	leverage for isolated margin. 0 means cross margin. For leverage of cross margin, please refer to `cross_leverage_limit`.
» risk_limit	string	Position risk limit
» leverage_max	string	the maximum permissible leverage given to the current positon value: the higher positon value, the lower maximum permissible leverage
» maintenance_rate	string	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	Position value calculated in settlement currency
» margin	string	Position margin
» entry_price	string	Entry price
» liq_price	string	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	Current mark price
» initial_margin	string	Initial margin of postions
» maintenance_margin	string	Maintencance margin of postions
» unrealised_pnl	string	Unrealized PNL
» realised_pnl	string	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	settled pnl when closing postion
» pnl_fund	string	funding fees
» pnl_fee	string	trading fees
» history_pnl	string	Total realized PnL from closed positions
» last_close_pnl	string	PNL of last position close
» realised_point	string	Realized POINT PNL
» history_point	string	History realized POINT PNL
» adl_ranking	integer	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	Current pending order quantity
» close_order	object\|null	Current close order information, or `null` if no close order
»» id	integer(int64)	Order ID
»» price	string	Order price
»» is_liq	boolean	Whether the close order is from liquidation
» mode	string	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	leverage for cross margin
» update_time	integer(int64)	Last update time
» update_id	integer(int64)	Update ID. The value increments by 1 each time the position is updated
» open_time	integer(int64)	First Open Time
» risk_limit_table	string	Risk limit table ID
» average_maintenance_rate	string	Average maintenance margin rate
» pid	integer(int64)	Sub-account position ID
» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin
» lever	string	Indicates the current leverage of the position, applicable to both isolated and cross margin, gradually replacing the current leverage and cross_leverage_limit

# Enumerated Values

Property	Value
mode	single
mode	dual_long
mode	dual_short

WARNING

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

# Get Leverage Information for Specified Mode

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/get_leverage/BTC_USDT'
query_param = 'pos_margin_mode=isolated&dual_side=dual_long'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/get_leverage/BTC_USDT"
query_param="pos_margin_mode=isolated&dual_side=dual_long"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/get_leverage/{contract}

Get Leverage Information for Specified Mode

Get Leverage Information for Specified Mode

Parameters

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

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

{
  "Lever": "10"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	query leverage success	FuturesLeverage

Response Schema

Status Code 200

Return result includes Lever field

Name	Type	Description
» Lever	string	leverage

WARNING

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

# Update position margin

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/positions/BTC_USDT/margin'
query_param = 'change=0.01'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/positions/BTC_USDT/margin"
query_param="change=0.01"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/positions/{contract}/margin

Update position margin

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.

Parameters

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

# Enumerated Values

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"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Position information	Position

Response Schema

Status Code 200

Futures position details

Name	Type	Description
» user	integer(int64)	User ID
» contract	string	Futures contract
» size	string	Position size
» leverage	string	leverage for isolated margin. 0 means cross margin. For leverage of cross margin, please refer to `cross_leverage_limit`.
» risk_limit	string	Position risk limit
» leverage_max	string	the maximum permissible leverage given to the current positon value: the higher positon value, the lower maximum permissible leverage
» maintenance_rate	string	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	Position value calculated in settlement currency
» margin	string	Position margin
» entry_price	string	Entry price
» liq_price	string	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	Current mark price
» initial_margin	string	Initial margin of postions
» maintenance_margin	string	Maintencance margin of postions
» unrealised_pnl	string	Unrealized PNL
» realised_pnl	string	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	settled pnl when closing postion
» pnl_fund	string	funding fees
» pnl_fee	string	trading fees
» history_pnl	string	Total realized PnL from closed positions
» last_close_pnl	string	PNL of last position close
» realised_point	string	Realized POINT PNL
» history_point	string	History realized POINT PNL
» adl_ranking	integer	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	Current pending order quantity
» close_order	object\|null	Current close order information, or `null` if no close order
»» id	integer(int64)	Order ID
»» price	string	Order price
»» is_liq	boolean	Whether the close order is from liquidation
» mode	string	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	leverage for cross margin
» update_time	integer(int64)	Last update time
» update_id	integer(int64)	Update ID. The value increments by 1 each time the position is updated
» open_time	integer(int64)	First Open Time
» risk_limit_table	string	Risk limit table ID
» average_maintenance_rate	string	Average maintenance margin rate
» pid	integer(int64)	Sub-account position ID
» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin
» lever	string	Indicates the current leverage of the position, applicable to both isolated and cross margin, gradually replacing the current leverage and cross_leverage_limit

# Enumerated Values

Property	Value
mode	single
mode	dual_long
mode	dual_short

WARNING

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

# Update position leverage

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/positions/BTC_USDT/leverage'
query_param = 'leverage=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/positions/BTC_USDT/leverage"
query_param="leverage=10"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/positions/{contract}/leverage

Update position leverage

⚠️ Position Mode Switching Rules:

leverage ≠ 0: Isolated Margin Mode (Regardless of whether cross_leverage_limit is filled, this parameter will be ignored)
leverage = 0: Cross Margin Mode (Use cross_leverage_limit to set the leverage multiple)

Examples:

Set isolated margin with 10x leverage: leverage=10
Set cross margin with 10x leverage: leverage=0&cross_leverage_limit=10
leverage=5&cross_leverage_limit=10 → Result: Isolated margin with 5x leverage (cross_leverage_limit is ignored)

⚠️ Warning: Incorrect settings may cause unexpected position mode switching, affecting risk management.

Parameters

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

# Enumerated Values

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"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Position information	Position

Response Schema

Status Code 200

Futures position details

Name	Type	Description
» user	integer(int64)	User ID
» contract	string	Futures contract
» size	string	Position size
» leverage	string	leverage for isolated margin. 0 means cross margin. For leverage of cross margin, please refer to `cross_leverage_limit`.
» risk_limit	string	Position risk limit
» leverage_max	string	the maximum permissible leverage given to the current positon value: the higher positon value, the lower maximum permissible leverage
» maintenance_rate	string	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	Position value calculated in settlement currency
» margin	string	Position margin
» entry_price	string	Entry price
» liq_price	string	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	Current mark price
» initial_margin	string	Initial margin of postions
» maintenance_margin	string	Maintencance margin of postions
» unrealised_pnl	string	Unrealized PNL
» realised_pnl	string	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	settled pnl when closing postion
» pnl_fund	string	funding fees
» pnl_fee	string	trading fees
» history_pnl	string	Total realized PnL from closed positions
» last_close_pnl	string	PNL of last position close
» realised_point	string	Realized POINT PNL
» history_point	string	History realized POINT PNL
» adl_ranking	integer	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	Current pending order quantity
» close_order	object\|null	Current close order information, or `null` if no close order
»» id	integer(int64)	Order ID
»» price	string	Order price
»» is_liq	boolean	Whether the close order is from liquidation
» mode	string	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	leverage for cross margin
» update_time	integer(int64)	Last update time
» update_id	integer(int64)	Update ID. The value increments by 1 each time the position is updated
» open_time	integer(int64)	First Open Time
» risk_limit_table	string	Risk limit table ID
» average_maintenance_rate	string	Average maintenance margin rate
» pid	integer(int64)	Sub-account position ID
» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin
» lever	string	Indicates the current leverage of the position, applicable to both isolated and cross margin, gradually replacing the current leverage and cross_leverage_limit

# Enumerated Values

Property	Value
mode	single
mode	dual_long
mode	dual_short

WARNING

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

# Update Leverage for Specified Mode

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/positions/BTC_USDT/set_leverage'
query_param = 'leverage=10&margin_mode=cross'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/positions/BTC_USDT/set_leverage"
query_param="leverage=10&margin_mode=cross"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/positions/{contract}/set_leverage

Update Leverage for Specified Mode

To simplify the complex logic of the leverage interface, added a new interface for modifying leverage

Parameters

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

# Enumerated Values

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"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Position information	Position

Response Schema

Status Code 200

Futures position details

Name	Type	Description
» user	integer(int64)	User ID
» contract	string	Futures contract
» size	string	Position size
» leverage	string	leverage for isolated margin. 0 means cross margin. For leverage of cross margin, please refer to `cross_leverage_limit`.
» risk_limit	string	Position risk limit
» leverage_max	string	the maximum permissible leverage given to the current positon value: the higher positon value, the lower maximum permissible leverage
» maintenance_rate	string	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	Position value calculated in settlement currency
» margin	string	Position margin
» entry_price	string	Entry price
» liq_price	string	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	Current mark price
» initial_margin	string	Initial margin of postions
» maintenance_margin	string	Maintencance margin of postions
» unrealised_pnl	string	Unrealized PNL
» realised_pnl	string	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	settled pnl when closing postion
» pnl_fund	string	funding fees
» pnl_fee	string	trading fees
» history_pnl	string	Total realized PnL from closed positions
» last_close_pnl	string	PNL of last position close
» realised_point	string	Realized POINT PNL
» history_point	string	History realized POINT PNL
» adl_ranking	integer	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	Current pending order quantity
» close_order	object\|null	Current close order information, or `null` if no close order
»» id	integer(int64)	Order ID
»» price	string	Order price
»» is_liq	boolean	Whether the close order is from liquidation
» mode	string	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	leverage for cross margin
» update_time	integer(int64)	Last update time
» update_id	integer(int64)	Update ID. The value increments by 1 each time the position is updated
» open_time	integer(int64)	First Open Time
» risk_limit_table	string	Risk limit table ID
» average_maintenance_rate	string	Average maintenance margin rate
» pid	integer(int64)	Sub-account position ID
» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin
» lever	string	Indicates the current leverage of the position, applicable to both isolated and cross margin, gradually replacing the current leverage and cross_leverage_limit

# Enumerated Values

Property	Value
mode	single
mode	dual_long
mode	dual_short

WARNING

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

# Switch Position Margin Mode

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/positions/cross_mode'
query_param = ''
body='{"mode":"ISOLATED","contract":"BTC_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/positions/cross_mode"
query_param=""
body_param='{"mode":"ISOLATED","contract":"BTC_USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/positions/cross_mode

Switch Position Margin Mode

Body parameter

{
  "mode": "ISOLATED",
  "contract": "BTC_USDT"
}

Parameters

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

# Enumerated Values

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"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Position information	Position

Response Schema

Status Code 200

Futures position details

Name	Type	Description
» user	integer(int64)	User ID
» contract	string	Futures contract
» size	string	Position size
» leverage	string	leverage for isolated margin. 0 means cross margin. For leverage of cross margin, please refer to `cross_leverage_limit`.
» risk_limit	string	Position risk limit
» leverage_max	string	the maximum permissible leverage given to the current positon value: the higher positon value, the lower maximum permissible leverage
» maintenance_rate	string	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	Position value calculated in settlement currency
» margin	string	Position margin
» entry_price	string	Entry price
» liq_price	string	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	Current mark price
» initial_margin	string	Initial margin of postions
» maintenance_margin	string	Maintencance margin of postions
» unrealised_pnl	string	Unrealized PNL
» realised_pnl	string	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	settled pnl when closing postion
» pnl_fund	string	funding fees
» pnl_fee	string	trading fees
» history_pnl	string	Total realized PnL from closed positions
» last_close_pnl	string	PNL of last position close
» realised_point	string	Realized POINT PNL
» history_point	string	History realized POINT PNL
» adl_ranking	integer	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	Current pending order quantity
» close_order	object\|null	Current close order information, or `null` if no close order
»» id	integer(int64)	Order ID
»» price	string	Order price
»» is_liq	boolean	Whether the close order is from liquidation
» mode	string	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	leverage for cross margin
» update_time	integer(int64)	Last update time
» update_id	integer(int64)	Update ID. The value increments by 1 each time the position is updated
» open_time	integer(int64)	First Open Time
» risk_limit_table	string	Risk limit table ID
» average_maintenance_rate	string	Average maintenance margin rate
» pid	integer(int64)	Sub-account position ID
» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin
» lever	string	Indicates the current leverage of the position, applicable to both isolated and cross margin, gradually replacing the current leverage and cross_leverage_limit

# Enumerated Values

Property	Value
mode	single
mode	dual_long
mode	dual_short

WARNING

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

# Switch Between Cross and Isolated Margin Modes Under Hedge Mode

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/dual_comp/positions/cross_mode'
query_param = ''
body='{"mode":"ISOLATED","contract":"BTC_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_comp/positions/cross_mode"
query_param=""
body_param='{"mode":"ISOLATED","contract":"BTC_USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/dual_comp/positions/cross_mode

Switch Between Cross and Isolated Margin Modes Under Hedge Mode

Body parameter

{
  "mode": "ISOLATED",
  "contract": "BTC_USDT"
}

Parameters

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

# Enumerated Values

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"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Query successful	[Position]

Response Schema

Status Code 200

Name	Type	Description
None	array	[Futures position details]
» None	Position	Futures position details
»» user	integer(int64)	User ID
»» contract	string	Futures contract
»» size	string	Position size
»» leverage	string	leverage for isolated margin. 0 means cross margin. For leverage of cross margin, please refer to `cross_leverage_limit`.
»» risk_limit	string	Position risk limit
»» leverage_max	string	the maximum permissible leverage given to the current positon value: the higher positon value, the lower maximum permissible leverage
»» maintenance_rate	string	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	Position value calculated in settlement currency
»» margin	string	Position margin
»» entry_price	string	Entry price
»» liq_price	string	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	Current mark price
»» initial_margin	string	Initial margin of postions
»» maintenance_margin	string	Maintencance margin of postions
»» unrealised_pnl	string	Unrealized PNL
»» realised_pnl	string	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	settled pnl when closing postion
»» pnl_fund	string	funding fees
»» pnl_fee	string	trading fees
»» history_pnl	string	Total realized PnL from closed positions
»» last_close_pnl	string	PNL of last position close
»» realised_point	string	Realized POINT PNL
»» history_point	string	History realized POINT PNL
»» adl_ranking	integer	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	Current pending order quantity
»» close_order	object\|null	Current close order information, or `null` if no close order
»»» id	integer(int64)	Order ID
»»» price	string	Order price
»»» is_liq	boolean	Whether the close order is from liquidation
»» mode	string	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	leverage for cross margin
»» update_time	integer(int64)	Last update time
»» update_id	integer(int64)	Update ID. The value increments by 1 each time the position is updated
»» open_time	integer(int64)	First Open Time
»» risk_limit_table	string	Risk limit table ID
»» average_maintenance_rate	string	Average maintenance margin rate
»» pid	integer(int64)	Sub-account position ID
»» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin
»» lever	string	Indicates the current leverage of the position, applicable to both isolated and cross margin, gradually replacing the current leverage and cross_leverage_limit

# Enumerated Values

Property	Value
mode	single
mode	dual_long
mode	dual_short

WARNING

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

# Update position risk limit

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/positions/BTC_USDT/risk_limit'
query_param = 'risk_limit=1000000'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/positions/BTC_USDT/risk_limit"
query_param="risk_limit=1000000"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/positions/{contract}/risk_limit

Update position risk limit

Parameters

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

# Enumerated Values

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"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Position information	Position

Response Schema

Status Code 200

Futures position details

Name	Type	Description
» user	integer(int64)	User ID
» contract	string	Futures contract
» size	string	Position size
» leverage	string	leverage for isolated margin. 0 means cross margin. For leverage of cross margin, please refer to `cross_leverage_limit`.
» risk_limit	string	Position risk limit
» leverage_max	string	the maximum permissible leverage given to the current positon value: the higher positon value, the lower maximum permissible leverage
» maintenance_rate	string	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	Position value calculated in settlement currency
» margin	string	Position margin
» entry_price	string	Entry price
» liq_price	string	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	Current mark price
» initial_margin	string	Initial margin of postions
» maintenance_margin	string	Maintencance margin of postions
» unrealised_pnl	string	Unrealized PNL
» realised_pnl	string	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	settled pnl when closing postion
» pnl_fund	string	funding fees
» pnl_fee	string	trading fees
» history_pnl	string	Total realized PnL from closed positions
» last_close_pnl	string	PNL of last position close
» realised_point	string	Realized POINT PNL
» history_point	string	History realized POINT PNL
» adl_ranking	integer	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	Current pending order quantity
» close_order	object\|null	Current close order information, or `null` if no close order
»» id	integer(int64)	Order ID
»» price	string	Order price
»» is_liq	boolean	Whether the close order is from liquidation
» mode	string	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	leverage for cross margin
» update_time	integer(int64)	Last update time
» update_id	integer(int64)	Update ID. The value increments by 1 each time the position is updated
» open_time	integer(int64)	First Open Time
» risk_limit_table	string	Risk limit table ID
» average_maintenance_rate	string	Average maintenance margin rate
» pid	integer(int64)	Sub-account position ID
» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin
» lever	string	Indicates the current leverage of the position, applicable to both isolated and cross margin, gradually replacing the current leverage and cross_leverage_limit

# Enumerated Values

Property	Value
mode	single
mode	dual_long
mode	dual_short

WARNING

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

# Set position mode

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/dual_mode'
query_param = 'dual_mode=true'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_mode"
query_param="dual_mode=true"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/dual_mode

Set position mode

The prerequisite for changing mode is that all positions have no holdings and no pending orders

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
dual_mode	query	boolean	true	Whether to enable Hedge Mode

# Enumerated Values

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
}

Responses

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

Response Schema

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.

WARNING

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

# Set Position Holding Mode, replacing the dual_mode interface

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/set_position_mode'
query_param = 'position_mode=dual_plus'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/set_position_mode"
query_param="position_mode=dual_plus"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/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

Parameters

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

# Enumerated Values

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
}

Responses

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

Response Schema

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.

WARNING

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

# Get position information in Hedge Mode

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/dual_comp/positions/BTC_USDT'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/dual_comp/positions/BTC_USDT"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/dual_comp/positions/{contract}

Get position information in Hedge Mode

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	path	string	true	Futures contract

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

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"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Query successful	[Position]

Response Schema

Status Code 200

Name	Type	Description
None	array	[Futures position details]
» None	Position	Futures position details
»» user	integer(int64)	User ID
»» contract	string	Futures contract
»» size	string	Position size
»» leverage	string	leverage for isolated margin. 0 means cross margin. For leverage of cross margin, please refer to `cross_leverage_limit`.
»» risk_limit	string	Position risk limit
»» leverage_max	string	the maximum permissible leverage given to the current positon value: the higher positon value, the lower maximum permissible leverage
»» maintenance_rate	string	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	Position value calculated in settlement currency
»» margin	string	Position margin
»» entry_price	string	Entry price
»» liq_price	string	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	Current mark price
»» initial_margin	string	Initial margin of postions
»» maintenance_margin	string	Maintencance margin of postions
»» unrealised_pnl	string	Unrealized PNL
»» realised_pnl	string	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	settled pnl when closing postion
»» pnl_fund	string	funding fees
»» pnl_fee	string	trading fees
»» history_pnl	string	Total realized PnL from closed positions
»» last_close_pnl	string	PNL of last position close
»» realised_point	string	Realized POINT PNL
»» history_point	string	History realized POINT PNL
»» adl_ranking	integer	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	Current pending order quantity
»» close_order	object\|null	Current close order information, or `null` if no close order
»»» id	integer(int64)	Order ID
»»» price	string	Order price
»»» is_liq	boolean	Whether the close order is from liquidation
»» mode	string	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	leverage for cross margin
»» update_time	integer(int64)	Last update time
»» update_id	integer(int64)	Update ID. The value increments by 1 each time the position is updated
»» open_time	integer(int64)	First Open Time
»» risk_limit_table	string	Risk limit table ID
»» average_maintenance_rate	string	Average maintenance margin rate
»» pid	integer(int64)	Sub-account position ID
»» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin
»» lever	string	Indicates the current leverage of the position, applicable to both isolated and cross margin, gradually replacing the current leverage and cross_leverage_limit

# Enumerated Values

Property	Value
mode	single
mode	dual_long
mode	dual_short

WARNING

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

# Update position margin in Hedge Mode

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/dual_comp/positions/BTC_USDT/margin'
query_param = 'change=0.01&dual_side=dual_long'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_comp/positions/BTC_USDT/margin"
query_param="change=0.01&dual_side=dual_long"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/dual_comp/positions/{contract}/margin

Update position margin in Hedge Mode

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	path	string	true	Futures contract
change	query	string	true	Margin change amount, positive number increases, negative number decreases
dual_side	query	string	true	Long or short position

# Enumerated Values

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"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Query successful	[Position]

Response Schema

Status Code 200

Name	Type	Description
None	array	[Futures position details]
» None	Position	Futures position details
»» user	integer(int64)	User ID
»» contract	string	Futures contract
»» size	string	Position size
»» leverage	string	leverage for isolated margin. 0 means cross margin. For leverage of cross margin, please refer to `cross_leverage_limit`.
»» risk_limit	string	Position risk limit
»» leverage_max	string	the maximum permissible leverage given to the current positon value: the higher positon value, the lower maximum permissible leverage
»» maintenance_rate	string	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	Position value calculated in settlement currency
»» margin	string	Position margin
»» entry_price	string	Entry price
»» liq_price	string	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	Current mark price
»» initial_margin	string	Initial margin of postions
»» maintenance_margin	string	Maintencance margin of postions
»» unrealised_pnl	string	Unrealized PNL
»» realised_pnl	string	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	settled pnl when closing postion
»» pnl_fund	string	funding fees
»» pnl_fee	string	trading fees
»» history_pnl	string	Total realized PnL from closed positions
»» last_close_pnl	string	PNL of last position close
»» realised_point	string	Realized POINT PNL
»» history_point	string	History realized POINT PNL
»» adl_ranking	integer	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	Current pending order quantity
»» close_order	object\|null	Current close order information, or `null` if no close order
»»» id	integer(int64)	Order ID
»»» price	string	Order price
»»» is_liq	boolean	Whether the close order is from liquidation
»» mode	string	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	leverage for cross margin
»» update_time	integer(int64)	Last update time
»» update_id	integer(int64)	Update ID. The value increments by 1 each time the position is updated
»» open_time	integer(int64)	First Open Time
»» risk_limit_table	string	Risk limit table ID
»» average_maintenance_rate	string	Average maintenance margin rate
»» pid	integer(int64)	Sub-account position ID
»» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin
»» lever	string	Indicates the current leverage of the position, applicable to both isolated and cross margin, gradually replacing the current leverage and cross_leverage_limit

# Enumerated Values

Property	Value
mode	single
mode	dual_long
mode	dual_short

WARNING

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

# Update position leverage in Hedge Mode

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/dual_comp/positions/BTC_USDT/leverage'
query_param = 'leverage=10'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_comp/positions/BTC_USDT/leverage"
query_param="leverage=10"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/dual_comp/positions/{contract}/leverage

Update position leverage in Hedge Mode

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	path	string	true	Futures contract
leverage	query	string	true	New position leverage
cross_leverage_limit	query	string	false	Cross margin leverage (valid only when `leverage` is 0)

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

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"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Query successful	[Position]

Response Schema

Status Code 200

Name	Type	Description
None	array	[Futures position details]
» None	Position	Futures position details
»» user	integer(int64)	User ID
»» contract	string	Futures contract
»» size	string	Position size
»» leverage	string	leverage for isolated margin. 0 means cross margin. For leverage of cross margin, please refer to `cross_leverage_limit`.
»» risk_limit	string	Position risk limit
»» leverage_max	string	the maximum permissible leverage given to the current positon value: the higher positon value, the lower maximum permissible leverage
»» maintenance_rate	string	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	Position value calculated in settlement currency
»» margin	string	Position margin
»» entry_price	string	Entry price
»» liq_price	string	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	Current mark price
»» initial_margin	string	Initial margin of postions
»» maintenance_margin	string	Maintencance margin of postions
»» unrealised_pnl	string	Unrealized PNL
»» realised_pnl	string	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	settled pnl when closing postion
»» pnl_fund	string	funding fees
»» pnl_fee	string	trading fees
»» history_pnl	string	Total realized PnL from closed positions
»» last_close_pnl	string	PNL of last position close
»» realised_point	string	Realized POINT PNL
»» history_point	string	History realized POINT PNL
»» adl_ranking	integer	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	Current pending order quantity
»» close_order	object\|null	Current close order information, or `null` if no close order
»»» id	integer(int64)	Order ID
»»» price	string	Order price
»»» is_liq	boolean	Whether the close order is from liquidation
»» mode	string	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	leverage for cross margin
»» update_time	integer(int64)	Last update time
»» update_id	integer(int64)	Update ID. The value increments by 1 each time the position is updated
»» open_time	integer(int64)	First Open Time
»» risk_limit_table	string	Risk limit table ID
»» average_maintenance_rate	string	Average maintenance margin rate
»» pid	integer(int64)	Sub-account position ID
»» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin
»» lever	string	Indicates the current leverage of the position, applicable to both isolated and cross margin, gradually replacing the current leverage and cross_leverage_limit

# Enumerated Values

Property	Value
mode	single
mode	dual_long
mode	dual_short

WARNING

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

# Update position risk limit in Hedge Mode

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/dual_comp/positions/BTC_USDT/risk_limit'
query_param = 'risk_limit=1000000'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/dual_comp/positions/BTC_USDT/risk_limit"
query_param="risk_limit=1000000"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/dual_comp/positions/{contract}/risk_limit

Update position risk limit in Hedge Mode

Parameters

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

# Enumerated Values

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"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Query successful	[Position]

Response Schema

Status Code 200

Name	Type	Description
None	array	[Futures position details]
» None	Position	Futures position details
»» user	integer(int64)	User ID
»» contract	string	Futures contract
»» size	string	Position size
»» leverage	string	leverage for isolated margin. 0 means cross margin. For leverage of cross margin, please refer to `cross_leverage_limit`.
»» risk_limit	string	Position risk limit
»» leverage_max	string	the maximum permissible leverage given to the current positon value: the higher positon value, the lower maximum permissible leverage
»» maintenance_rate	string	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	Position value calculated in settlement currency
»» margin	string	Position margin
»» entry_price	string	Entry price
»» liq_price	string	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	Current mark price
»» initial_margin	string	Initial margin of postions
»» maintenance_margin	string	Maintencance margin of postions
»» unrealised_pnl	string	Unrealized PNL
»» realised_pnl	string	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	settled pnl when closing postion
»» pnl_fund	string	funding fees
»» pnl_fee	string	trading fees
»» history_pnl	string	Total realized PnL from closed positions
»» last_close_pnl	string	PNL of last position close
»» realised_point	string	Realized POINT PNL
»» history_point	string	History realized POINT PNL
»» adl_ranking	integer	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	Current pending order quantity
»» close_order	object\|null	Current close order information, or `null` if no close order
»»» id	integer(int64)	Order ID
»»» price	string	Order price
»»» is_liq	boolean	Whether the close order is from liquidation
»» mode	string	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	leverage for cross margin
»» update_time	integer(int64)	Last update time
»» update_id	integer(int64)	Update ID. The value increments by 1 each time the position is updated
»» open_time	integer(int64)	First Open Time
»» risk_limit_table	string	Risk limit table ID
»» average_maintenance_rate	string	Average maintenance margin rate
»» pid	integer(int64)	Sub-account position ID
»» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin
»» lever	string	Indicates the current leverage of the position, applicable to both isolated and cross margin, gradually replacing the current leverage and cross_leverage_limit

# Enumerated Values

Property	Value
mode	single
mode	dual_long
mode	dual_short

WARNING

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

# Query futures order list

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/orders

Query futures order list

Zero-fill order cannot be retrieved for 10 minutes after cancellation
Historical orders, by default, only data within the past 6 months is supported. If you need to query data for a longer period, please use GET /futures/{settle}/orders_timerange.

Parameters

Name	In	Type	Required	Description
contract	query	string	false	Futures contract, return related data only if specified
status	query	string	true	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 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
settle	path	string	true	Settle currency

# Detailed descriptions

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

# Enumerated Values

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"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	[Futures order details]
» None	FuturesOrder	Futures order details
»» id	integer(int64)	Futures order ID
»» user	integer	User ID
»» create_time	number(double)	Creation time of order
»» update_time	number(double)	OrderUpdateTime
»» 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	Required. Order Price; a price of 0 with `tif` as `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	Custom order information. If not empty, must follow the rules below: 1. Prefixed with `t-` 2. No longer than 28 bytes without `t-` prefix 3. Can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) 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	Taker fee
»» mkfr	string	Maker fee
»» refu	integer	Referrer user ID
»» stp_id	integer	Orders between users in the same `stp_id` group are not allowed to be self-traded 1. If the `stp_id` of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the `stp_act` of the taker. 2. `stp_id` returns `0` by default for orders that have not been set for `STP group`
»» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade 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	The custom data that the user remarked when amending the order
»» market_order_slip_ratio	string	Custom maximum slippage rate for market orders. If not provided, the default contract settings will be used
»» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin, only passed in simple split position mode

# Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
finish_as	stp
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok
stp_act	co
stp_act	cn
stp_act	cb
stp_act	-

# Response Headers

Status	Header	Type	Format	Description
200	X-Pagination-Limit	integer		Limit specified for pagination
200	X-Pagination-Offset	integer		Offset specified for pagination

WARNING

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

# Place futures order

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/orders'
query_param = ''
body='{"contract":"BTC_USDT","size":"6024","iceberg":"0","price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-","order_value":"64112.2099000000005","trade_value":"64112.2099000000005","market_order_slip_ratio":"0.03","pos_margin_mode":"isolated"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/orders"
query_param=""
body_param='{"contract":"BTC_USDT","size":"6024","iceberg":"0","price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-","order_value":"64112.2099000000005","trade_value":"64112.2099000000005","market_order_slip_ratio":"0.03","pos_margin_mode":"isolated"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/orders

Place futures order

When placing an order, the number of contracts is specified size, not the number of coins. The number of coins corresponding to each contract is returned in the contract details interface quanto_multiplier
0 The order that was completed cannot be obtained after 10 minutes of withdrawal, and the order will be mentioned that the order does not exist
Setting reduce_only to true can prevent the position from being penetrated when reducing the position
In single-position mode, if you need to close the position, you need to set size to 0 and close to true
In dual warehouse mode,
Reduce position: reduce_only=true, size is a positive number that indicates short position, negative number that indicates long position
Add number that indicates adding long positions, and negative numbers indicate adding short positions
Close position: size=0, set the direction of closing position according to auto_size, and set reduce_only to true at the same time - reduce_only: Make sure to only perform position reduction operations to prevent increased positions
Set stp_act to determine the use of a strategy that restricts user transactions. For detailed usage, refer to the body parameter stp_act

Body 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"
}

Parameters

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 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none
» text	body	string	false	Custom order information. If not empty, must follow the rules below: 1. Prefixed with `t-` 2. No longer than 28 bytes without `t-` prefix 3. Can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) 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
» 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 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
» 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
settle	path	string	true	Settle currency

# Detailed descriptions

» tif: Time in force

- gtc: GoodTillCancelled
- ioc: ImmediateOrCancelled, taker only
- poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee
- fok: FillOrKill, fill either completely or none

» text: Custom order information. If not empty, must follow the rules below:

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

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

» stp_act: 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

# Enumerated Values

Parameter	Value
» tif	gtc
» tif	ioc
» tif	poc
» tif	fok
» auto_size	close_long
» auto_size	close_short
» stp_act	co
» stp_act	cn
» stp_act	cb
» stp_act	-
settle	btc
settle	usdt

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"
}

Responses

Status	Meaning	Description	Schema
201	Created (opens new window)	Order details	FuturesOrder

Response Schema

Status Code 201

Futures order details

Name	Type	Description
» id	integer(int64)	Futures order ID
» user	integer	User ID
» create_time	number(double)	Creation time of order
» update_time	number(double)	OrderUpdateTime
» 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	Required. Order Price; a price of 0 with `tif` as `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	Custom order information. If not empty, must follow the rules below: 1. Prefixed with `t-` 2. No longer than 28 bytes without `t-` prefix 3. Can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) 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	Taker fee
» mkfr	string	Maker fee
» refu	integer	Referrer user ID
» stp_id	integer	Orders between users in the same `stp_id` group are not allowed to be self-traded 1. If the `stp_id` of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the `stp_act` of the taker. 2. `stp_id` returns `0` by default for orders that have not been set for `STP group`
» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade 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	The custom data that the user remarked when amending the order
» market_order_slip_ratio	string	Custom maximum slippage rate for market orders. If not provided, the default contract settings will be used
» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin, only passed in simple split position mode

# Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
finish_as	stp
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok
stp_act	co
stp_act	cn
stp_act	cb
stp_act	-

WARNING

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

# Cancel all orders with 'open' status

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/usdt/orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /futures/{settle}/orders

Cancel all orders with 'open' status

Zero-fill orders cannot be retrieved 10 minutes after order cancellation

Parameters

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

# Enumerated Values

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"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Batch cancellation successful	[FuturesOrder]

Response Schema

Status Code 200

Name	Type	Description
None	array	[Futures order details]
» None	FuturesOrder	Futures order details
»» id	integer(int64)	Futures order ID
»» user	integer	User ID
»» create_time	number(double)	Creation time of order
»» update_time	number(double)	OrderUpdateTime
»» 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	Required. Order Price; a price of 0 with `tif` as `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	Custom order information. If not empty, must follow the rules below: 1. Prefixed with `t-` 2. No longer than 28 bytes without `t-` prefix 3. Can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) 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	Taker fee
»» mkfr	string	Maker fee
»» refu	integer	Referrer user ID
»» stp_id	integer	Orders between users in the same `stp_id` group are not allowed to be self-traded 1. If the `stp_id` of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the `stp_act` of the taker. 2. `stp_id` returns `0` by default for orders that have not been set for `STP group`
»» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade 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	The custom data that the user remarked when amending the order
»» market_order_slip_ratio	string	Custom maximum slippage rate for market orders. If not provided, the default contract settings will be used
»» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin, only passed in simple split position mode

# Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
finish_as	stp
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok
stp_act	co
stp_act	cn
stp_act	cb
stp_act	-

WARNING

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

# Query futures order list by time range

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/orders_timerange'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/orders_timerange"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/orders_timerange

Query futures order list by time range

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	false	Futures contract, return related data only if specified
from	query	integer(int64)	false	Start timestamp 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	query	integer(int64)	false	Termination Timestamp Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0

# Detailed descriptions

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

# Enumerated Values

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"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	[Futures order details]
» None	FuturesOrderTimerange	Futures order details
»» id	integer(int64)	Futures order ID
»» user	integer	User ID
»» create_time	number(double)	Creation time of order
»» update_time	string	OrderUpdateTime
»» finish_time	string	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	Required. Order Price; a price of 0 with `tif` as `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	Custom order information. If not empty, must follow the rules below: 1. Prefixed with `t-` 2. No longer than 28 bytes without `t-` prefix 3. Can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) 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	Taker fee
»» mkfr	string	Maker fee
»» refu	integer	Referrer user ID
»» stp_id	integer	Orders between users in the same `stp_id` group are not allowed to be self-traded 1. If the `stp_id` of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the `stp_act` of the taker. 2. `stp_id` returns `0` by default for orders that have not been set for `STP group`
»» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade 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	The custom data that the user remarked when amending the order
»» market_order_slip_ratio	string	Custom maximum slippage rate for market orders. If not provided, the default contract settings will be used
»» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin, only passed in simple split position mode

# Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
finish_as	stp
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok
stp_act	co
stp_act	cn
stp_act	cb
stp_act	-

# Response Headers

Status	Header	Type	Format	Description
200	X-Pagination-Limit	integer		Limit specified for pagination
200	X-Pagination-Offset	integer		Offset specified for pagination

WARNING

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

# Place batch futures orders

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/batch_orders'
query_param = ''
body='[{"contract":"BTC_USDT","size":"6024","iceberg":"0","price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-","order_value":"64112.2099000000005","trade_value":"64112.2099000000005","market_order_slip_ratio":"0.03","pos_margin_mode":"isolated"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/batch_orders"
query_param=""
body_param='[{"contract":"BTC_USDT","size":"6024","iceberg":"0","price":"3765","tif":"gtc","text":"t-my-custom-id","stp_act":"-","order_value":"64112.2099000000005","trade_value":"64112.2099000000005","market_order_slip_ratio":"0.03","pos_margin_mode":"isolated"}]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/batch_orders

Place batch futures orders

Up to 10 orders per request
If any of the order's parameters are missing or in the wrong format, all of them will not be executed, and a http status 400 error will be returned directly
If the parameters are checked and passed, all are executed. Even if there is a business logic error in the middle (such as insufficient funds), it will not affect other execution orders
The returned result is in array format, and the order corresponds to the orders in the request body
In the returned result, the succeeded field of type bool indicates whether the execution was successful or not
If the execution is successful, the normal order content is included; if the execution fails, the label field is included to indicate the cause of the error
In the rate limiting, each order is counted individually

Body parameter

[
  {
    "contract": "BTC_USDT",
    "size": "6024",
    "iceberg": "0",
    "price": "3765",
    "tif": "gtc",
    "text": "t-my-custom-id",
    "stp_act": "-",
    "order_value": "64112.2099000000005",
    "trade_value": "64112.2099000000005",
    "market_order_slip_ratio": "0.03",
    "pos_margin_mode": "isolated"
  }
]

Parameters

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

# Enumerated Values

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"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Request execution completed	[BatchFuturesOrder]

Response Schema

Status Code 200

Name	Type	Description
None	array	[Futures order details]
» None	BatchFuturesOrder	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-` prefix 3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance
»» tkfr	string	Taker fee
»» mkfr	string	Maker fee
»» refu	integer	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-traded 1. If the `stp_id` of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the `stp_act` of the taker. 2. `stp_id` returns `0` by default for orders that have not been set for `STP group`
»» market_order_slip_ratio	string	The maximum slippage ratio

# Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
finish_as	stp
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok
stp_act	co
stp_act	cn
stp_act	cb
stp_act	-

WARNING

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

# Query single order details

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/orders/{order_id}

Query single order details

Zero-fill order cannot be retrieved for 10 minutes after cancellation
Historical orders, by default, only data within the past 6 months is supported.

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
order_id	path	string	true	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: 1. If the order was not filled and has been cancelled, after 60 seconds you cannot query the order by `text`; continuing to use `text` returns error ORDER_NOT_FOUND. 2. If the order was fully or partially filled, you can query the order by `text` indefinitely.

# Detailed descriptions

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:
1. If the order was not filled and has been cancelled, after 60 seconds you cannot query the order by text; continuing to use text returns error ORDER_NOT_FOUND.
2. If the order was fully or partially filled, you can query the order by text indefinitely.

# Enumerated Values

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"
}

Responses

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

Response Schema

Status Code 200

Futures order details

Name	Type	Description
» id	integer(int64)	Futures order ID
» user	integer	User ID
» create_time	number(double)	Creation time of order
» update_time	number(double)	OrderUpdateTime
» 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	Required. Order Price; a price of 0 with `tif` as `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	Custom order information. If not empty, must follow the rules below: 1. Prefixed with `t-` 2. No longer than 28 bytes without `t-` prefix 3. Can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) 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	Taker fee
» mkfr	string	Maker fee
» refu	integer	Referrer user ID
» stp_id	integer	Orders between users in the same `stp_id` group are not allowed to be self-traded 1. If the `stp_id` of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the `stp_act` of the taker. 2. `stp_id` returns `0` by default for orders that have not been set for `STP group`
» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade 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	The custom data that the user remarked when amending the order
» market_order_slip_ratio	string	Custom maximum slippage rate for market orders. If not provided, the default contract settings will be used
» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin, only passed in simple split position mode

# Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
finish_as	stp
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok
stp_act	co
stp_act	cn
stp_act	cb
stp_act	-

WARNING

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

# Amend single order

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/orders/12345'
query_param = ''
body='{"size":"100","price":"54321","contract":"BTC_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PUT', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="PUT"
url="/futures/usdt/orders/12345"
query_param=""
body_param='{"size":"100","price":"54321","contract":"BTC_USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

PUT /futures/{settle}/orders/{order_id}

Amend single order

Body parameter

{
  "size": "100",
  "price": "54321",
  "contract": "BTC_USDT"
}

Parameters

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. - 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	body	string	false	New order price
» amend_text	body	string	false	Custom info during order amendment
» text	body	string	false	Internal users can modify information in the text field.
settle	path	string	true	Settle currency
order_id	path	string	true	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: 1. If the order was not filled and has been cancelled, after 60 seconds you cannot query the order by `text`; continuing to use `text` returns error ORDER_NOT_FOUND. 2. If the order was fully or partially filled, you can query the order by `text` indefinitely.

# Detailed descriptions

» size: New order size, including filled part.

- If new size is less than or equal to filled size, the order will be cancelled.
- Order side must be identical to the original one.
- Close order size cannot be changed.
- For reduce only orders, increasing size may leads to other reduce only orders being cancelled.
- If price is not changed, decreasing size will not change its precedence in order book, while increasing will move it to the last at current price.

# Enumerated Values

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"
}

Responses

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

Response Schema

Status Code 200

Futures order details

Name	Type	Description
» id	integer(int64)	Futures order ID
» user	integer	User ID
» create_time	number(double)	Creation time of order
» update_time	number(double)	OrderUpdateTime
» 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	Required. Order Price; a price of 0 with `tif` as `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	Custom order information. If not empty, must follow the rules below: 1. Prefixed with `t-` 2. No longer than 28 bytes without `t-` prefix 3. Can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) 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	Taker fee
» mkfr	string	Maker fee
» refu	integer	Referrer user ID
» stp_id	integer	Orders between users in the same `stp_id` group are not allowed to be self-traded 1. If the `stp_id` of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the `stp_act` of the taker. 2. `stp_id` returns `0` by default for orders that have not been set for `STP group`
» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade 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	The custom data that the user remarked when amending the order
» market_order_slip_ratio	string	Custom maximum slippage rate for market orders. If not provided, the default contract settings will be used
» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin, only passed in simple split position mode

# Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
finish_as	stp
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok
stp_act	co
stp_act	cn
stp_act	cb
stp_act	-

WARNING

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

# Cancel single order

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/orders/12345'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/usdt/orders/12345"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /futures/{settle}/orders/{order_id}

Cancel single order

Parameters

Name	In	Type	Required	Description
x-gate-exptime	header	string	false	Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected
settle	path	string	true	Settle currency
order_id	path	string	true	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: 1. If the order was not filled and has been cancelled, after 60 seconds you cannot query the order by `text`; continuing to use `text` returns error ORDER_NOT_FOUND. 2. If the order was fully or partially filled, you can query the order by `text` indefinitely.

# Detailed descriptions

# Enumerated Values

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"
}

Responses

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

Response Schema

Status Code 200

Futures order details

Name	Type	Description
» id	integer(int64)	Futures order ID
» user	integer	User ID
» create_time	number(double)	Creation time of order
» update_time	number(double)	OrderUpdateTime
» 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	Required. Order Price; a price of 0 with `tif` as `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	Custom order information. If not empty, must follow the rules below: 1. Prefixed with `t-` 2. No longer than 28 bytes without `t-` prefix 3. Can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) 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	Taker fee
» mkfr	string	Maker fee
» refu	integer	Referrer user ID
» stp_id	integer	Orders between users in the same `stp_id` group are not allowed to be self-traded 1. If the `stp_id` of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the `stp_act` of the taker. 2. `stp_id` returns `0` by default for orders that have not been set for `STP group`
» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade 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	The custom data that the user remarked when amending the order
» market_order_slip_ratio	string	Custom maximum slippage rate for market orders. If not provided, the default contract settings will be used
» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin, only passed in simple split position mode

# Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
finish_as	stp
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok
stp_act	co
stp_act	cn
stp_act	cb
stp_act	-

WARNING

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

# Query personal trading records

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/my_trades'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/my_trades"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/my_trades

Query personal trading records

By default, only supports querying data within 6 months. For older data, use GET /futures/{settle}/my_trades_timerange

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	false	Futures contract, return related data only if specified
order	query	integer(int64)	false	Futures order ID, return related data only if specified
limit	query	integer	false	Maximum number of records 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 This parameter is deprecated. If you need to iterate through and retrieve more records, we recommend using 'GET /futures/{settle}/my_trades_timerange'.

# Detailed descriptions

last_id: Specify the starting point for this list based on a previously retrieved id

This parameter is deprecated. If you need to iterate through and retrieve more records, we recommend using 'GET /futures/{settle}/my_trades_timerange'.

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

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"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» id	integer(int64)	Fill ID
» create_time	number(double)	Fill Time
» contract	string	Futures contract
» order_id	string	Related order ID
» size	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

# Enumerated Values

Property	Value
role	taker
role	maker

# Response Headers

Status	Header	Type	Format	Description
200	X-Pagination-Limit	integer		Limit specified for pagination
200	X-Pagination-Offset	integer		Offset specified for pagination

WARNING

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

# Query personal trading records by time range

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/my_trades_timerange'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/my_trades_timerange"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/my_trades_timerange

Query personal trading records by time range

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	false	Futures contract, return related data only if specified
from	query	integer(int64)	false	Start timestamp 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	query	integer(int64)	false	Termination Timestamp Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix 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

# Detailed descriptions

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

# Enumerated Values

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"
  }
]

Responses

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

Response Schema

Status Code 200

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

# Enumerated Values

Property	Value
role	taker
role	maker

# Response Headers

Status	Header	Type	Format	Description
200	X-Pagination-Limit	integer		Limit specified for pagination
200	X-Pagination-Offset	integer		Offset specified for pagination

WARNING

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

# Query position close history

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/position_close'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/position_close"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/position_close

Query position close history

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	false	Futures contract, return related data only if specified
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0
from	query	integer(int64)	false	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	query	integer(int64)	false	Termination Timestamp Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
side	query	string	false	Query side. long or shot
pnl	query	string	false	Query profit or loss

# Detailed descriptions

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

# Enumerated Values

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"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» time	number(double)	Position close time
» contract	string	Futures contract
» side	string	Position side - `long`: 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

# Enumerated Values

Property	Value
side	long
side	short

WARNING

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

# Query liquidation history

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/liquidates'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/liquidates"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/liquidates

Query liquidation history

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	false	Futures contract, return related data only if specified
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0
from	query	integer(int64)	false	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	query	integer(int64)	false	Termination Timestamp Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
at	query	integer	false	Specify liquidation timestamp

# Detailed descriptions

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

# Enumerated Values

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"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» time	integer(int64)	Liquidation time
» contract	string	Futures contract
» leverage	string	Position leverage. Not returned in public endpoints
» size	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

WARNING

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

# Query ADL auto-deleveraging order information

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/auto_deleverages'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/auto_deleverages"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/auto_deleverages

Query ADL auto-deleveraging order information

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	false	Futures contract, return related data only if specified
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0
from	query	integer(int64)	false	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	query	integer(int64)	false	Termination Timestamp Specify the end time. If not specified, it defaults to the current time, and the time format is a Unix timestamp
at	query	integer	false	Specify auto-deleveraging timestamp

# Detailed descriptions

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

# Enumerated Values

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"
  }
]

Responses

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

Response Schema

Status Code 200

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

WARNING

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

# Countdown cancel orders

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/countdown_cancel_all'
query_param = ''
body='{"timeout":30,"contract":"BTC_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/countdown_cancel_all"
query_param=""
body_param='{"timeout":30,"contract":"BTC_USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/countdown_cancel_all

Countdown cancel orders

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"
}

Parameters

Name	In	Type	Required	Description
body	body	CountdownCancelAllFuturesTask	true	none
» timeout	body	integer(int32)	true	Countdown time in seconds At least 5 seconds, 0 means cancel countdown
» contract	body	string	false	Futures contract
settle	path	string	true	Settle currency

# Detailed descriptions

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

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

{
  "triggerTime": "1660039145000"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Countdown set successfully	TriggerTime

Response Schema

Status Code 200

triggerTime

Name	Type	Description
» triggerTime	integer(int64)	Timestamp when countdown ends, in milliseconds

WARNING

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

# Query futures market trading fee rates

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/fee'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/fee"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/fee

Query futures market trading fee rates

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
contract	query	string	false	Futures contract, return related data only if specified

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

{
  "1INCH_USDT": {
    "taker_fee": "0.00025",
    "maker_fee": "-0.00010"
  },
  "AAVE_USDT": {
    "taker_fee": "0.00025",
    "maker_fee": "-0.00010"
  }
}

Responses

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

Response Schema

Status Code 200

FuturesFee

Name	Type	Description
» additionalProperties	FuturesFee	The returned result is a map type, where the key represents the market and taker and maker fee rates
»» taker_fee	string	Taker fee
»» maker_fee	string	maker fee

WARNING

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

# Cancel batch orders by specified ID list

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/batch_cancel_orders'
query_param = ''
body='["1","2","3"]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/batch_cancel_orders"
query_param=""
body_param='["1","2","3"]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/batch_cancel_orders

Cancel 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"
]

Parameters

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

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

[
  {
    "user_id": 111,
    "id": "123456",
    "succeeded": true,
    "message": ""
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» FutureCancelOrderResult	object	Order cancellation result
»» id	string	Order ID
»» user_id	integer(int64)	User ID
»» succeeded	boolean	Whether cancellation succeeded
»» message	string	Error description when cancellation fails, empty if successful

WARNING

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

# Batch modify orders by specified IDs

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/batch_amend_orders'
query_param = ''
body='[{"order_id":121212,"amend_text":"batch amend text","size":"100","price":"54321"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/batch_amend_orders"
query_param=""
body_param='[{"order_id":121212,"amend_text":"batch amend text","size":"100","price":"54321"}]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/batch_amend_orders

Batch modify orders by specified IDs

Multiple different order IDs can be specified. A maximum of 10 orders can be modified in one request

Body parameter

[
  {
    "order_id": 121212,
    "amend_text": "batch amend text",
    "size": "100",
    "price": "54321"
  }
]

Parameters

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

# Enumerated Values

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"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Request execution completed	[BatchFuturesOrder]

Response Schema

Status Code 200

Name	Type	Description
None	array	[Futures order details]
» None	BatchFuturesOrder	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-` prefix 3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance
»» tkfr	string	Taker fee
»» mkfr	string	Maker fee
»» refu	integer	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-traded 1. If the `stp_id` of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the `stp_act` of the taker. 2. `stp_id` returns `0` by default for orders that have not been set for `STP group`
»» market_order_slip_ratio	string	The maximum slippage ratio

# Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
finish_as	stp
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok
stp_act	co
stp_act	cn
stp_act	cb
stp_act	-

WARNING

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

# Query risk limit table by table_id

Code samples

# coding: utf-8
import requests

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/risk_limit_table'
query_param = 'table_id=CYBER_USDT_20241122'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())


curl -X GET https://api.gateio.ws/api/v4/futures/usdt/risk_limit_table?table_id=CYBER_USDT_20241122 \
  -H 'Accept: application/json'

GET /futures/{settle}/risk_limit_table

Query risk limit table by table_id

Just pass table_id

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
table_id	query	string	true	Risk limit table ID

# Enumerated Values

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"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Query successful	[FuturesRiskLimitTier]

Response Schema

Status Code 200

Name	Type	Description
None	array	[Information for each tier of the gradient risk limit table]
» None	FuturesRiskLimitTier	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

# Level-based BBO Contract Order Placement

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/bbo_orders'
query_param = ''
body='{"contract":"PI_USDT","level":8,"direction":"sell","size":1}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/bbo_orders"
query_param=""
body_param='{"contract":"PI_USDT","level":8,"direction":"sell","size":1}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/bbo_orders

Level-based BBO Contract Order Placement

Compared to the futures trading order placement interface (futures/{settle}/orders), it adds the level and direction parameters.

Body parameter

{
  "contract": "PI_USDT",
  "level": 8,
  "direction": "sell",
  "size": 1
}

Parameters

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 - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none
» text	body	string	false	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 bytes 3. 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
» 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 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
» pid	body	integer(int64)	false	Position ID
settle	path	string	true	Settle currency

# Detailed descriptions

» text: 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 bytes
3. 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

# Enumerated Values

Parameter	Value
» tif	gtc
» tif	ioc
» tif	poc
» tif	fok
» auto_size	close_long
» auto_size	close_short
» stp_act	co
» stp_act	cn
» stp_act	cb
» stp_act	-
settle	btc
settle	usdt

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"
}

Responses

Status	Meaning	Description	Schema
201	Created (opens new window)	Order details	FuturesOrder

Response Schema

Status Code 201

Futures order details

Name	Type	Description
» id	integer(int64)	Futures order ID
» user	integer	User ID
» create_time	number(double)	Creation time of order
» update_time	number(double)	OrderUpdateTime
» 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	Required. Order Price; a price of 0 with `tif` as `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	Custom order information. If not empty, must follow the rules below: 1. Prefixed with `t-` 2. No longer than 28 bytes without `t-` prefix 3. Can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) 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	Taker fee
» mkfr	string	Maker fee
» refu	integer	Referrer user ID
» stp_id	integer	Orders between users in the same `stp_id` group are not allowed to be self-traded 1. If the `stp_id` of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the `stp_act` of the taker. 2. `stp_id` returns `0` by default for orders that have not been set for `STP group`
» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade 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	The custom data that the user remarked when amending the order
» market_order_slip_ratio	string	Custom maximum slippage rate for market orders. If not provided, the default contract settings will be used
» pos_margin_mode	string	Position Margin Mode isolated - Isolated Margin, cross - Cross Margin, only passed in simple split position mode

# Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
finish_as	stp
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok
stp_act	co
stp_act	cn
stp_act	cb
stp_act	-

WARNING

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

# Create trail order

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/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"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/autoorder/v1/trail/create"
query_param=""
body_param='{"contract":"BTC_USDT","amount":"10","activation_price":"50000","is_gte":true,"price_type":1,"price_offset":"0.1%","reduce_only":false,"text":"apiv4"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/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"
}

Parameters

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. If non-empty, it must meet one of the following rules: 1. Internal Reserved Fields (identifying order source): - `apiv4`: API call 2. 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.01` Note: User-defined fields must not conflict with internal reserved fields.
» 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

# Detailed descriptions

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

1. Internal Reserved Fields (identifying order source):
- apiv4: API call
2. 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.01

Note: User-defined fields must not conflict with internal reserved fields.

# Enumerated Values

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
}

Responses

Status	Meaning	Description	Schema
201	Created (opens new window)	Created successfully	CreateTrailOrderResponse

Response Schema

Status Code 201

CreateTrailOrderResponse

Name	Type	Description
» code	integer(int32)	Status code, 0 means success
» message	string	Response message
» data	object	none
»» id	string	Order ID
» timestamp	integer(int64)	Response timestamp (milliseconds)

WARNING

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

# Terminate trail order

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/autoorder/v1/trail/stop'
query_param = ''
body='{"id":123456789}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/autoorder/v1/trail/stop"
query_param=""
body_param='{"id":123456789}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/autoorder/v1/trail/stop

Terminate trail order

Body parameter

{
  "id": 123456789
}

Parameters

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

# Enumerated Values

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

Responses

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

Response Schema

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

# Enumerated Values

Property	Value
price_type	0
price_type	1
price_type	2
price_type	3
status	open
status	finished

WARNING

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

# Batch terminate trail orders

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/autoorder/v1/trail/stop_all'
query_param = ''
body='{"contract":"BTC_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/autoorder/v1/trail/stop_all"
query_param=""
body_param='{"contract":"BTC_USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/autoorder/v1/trail/stop_all

Batch terminate trail orders

Body parameter

{
  "contract": "BTC_USDT"
}

Parameters

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

# Enumerated Values

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"
    }
  ]
}

Responses

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

Response Schema

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

# Enumerated Values

Property	Value
price_type	0
price_type	1
price_type	2
price_type	3
status	open
status	finished

WARNING

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

# Get trail order list

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/autoorder/v1/trail/list'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/autoorder/v1/trail/list"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/autoorder/v1/trail/list

Get trail order list

Parameters

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

# Enumerated Values

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"
    }
  ]
}

Responses

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

Response Schema

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

# Enumerated Values

Property	Value
price_type	0
price_type	1
price_type	2
price_type	3
status	open
status	finished

WARNING

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

# Get trail order details

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/autoorder/v1/trail/detail'
query_param = 'id=0'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/autoorder/v1/trail/detail"
query_param="id=0"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/autoorder/v1/trail/detail

Get trail order details

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
id	query	integer(int64)	true	Order ID

# Enumerated Values

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
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Query successful	TrailOrderDetailResponse

Response Schema

Status Code 200

TrailOrderDetailResponse

Name	Type	Description
» code	integer(int32)	Status code, 0 means success
» message	string	Response message
» data	object	none
»» 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
»» timestamp	integer(int64)	Response timestamp (milliseconds)

# Enumerated Values

Property	Value
price_type	0
price_type	1
price_type	2
price_type	3
status	open
status	finished

WARNING

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

# Update trail order

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/autoorder/v1/trail/update'
query_param = ''
body='{"id":123456789,"amount":"20","activation_price":"51000","price_offset":"0.2%"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/autoorder/v1/trail/update"
query_param=""
body_param='{"id":123456789,"amount":"20","activation_price":"51000","price_offset":"0.2%"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/autoorder/v1/trail/update

Update trail order

Body parameter

{
  "id": 123456789,
  "amount": "20",
  "activation_price": "51000",
  "price_offset": "0.2%"
}

Parameters

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

# Enumerated Values

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

Responses

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

Response Schema

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

# Enumerated Values

Property	Value
price_type	0
price_type	1
price_type	2
price_type	3
status	open
status	finished

WARNING

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

# Get trail order user modification records

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/autoorder/v1/trail/change_log'
query_param = 'id=0'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/autoorder/v1/trail/change_log"
query_param="id=0"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/autoorder/v1/trail/change_log

Get trail order user modification records

Parameters

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

# Enumerated Values

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
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Query successful	TrailOrderChangeLogResponse

Response Schema

Status Code 200

TrailOrderChangeLogResponse

Name	Type	Description
» change_log	array	[Trail order modification records]
»» None	TrailChangeLog	Trail order modification records
»»» updated_at	integer(int64)	Update time
»»» 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%`
»»» is_create	boolean	true - order creation, false - order modification

# Enumerated Values

Property	Value
price_type	0
price_type	1
price_type	2
price_type	3

WARNING

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

# Query auto order list

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/price_orders'
query_param = 'status=open'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/price_orders"
query_param="status=open"
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url?$query_param"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/price_orders

Query auto order list

Parameters

Name	In	Type	Required	Description
status	query	string	true	Query order list based on status
contract	query	string	false	Futures contract, return related data only if specified
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0
settle	path	string	true	Settle currency

# Enumerated Values

Parameter	Value
status	open
status	finished
settle	btc
settle	usdt

Example responses

200 Response

[
  {
    "initial": {
      "contract": "BTC_USDT",
      "size": 100,
      "price": "5.03"
    },
    "trigger": {
      "strategy_type": 0,
      "price_type": 0,
      "price": "3000",
      "rule": 1,
      "expiration": 86400
    },
    "id": 1283293,
    "id_string": "1283293",
    "user": 1234,
    "create_time": 1514764800,
    "finish_time": 1514764900,
    "trade_id": 13566,
    "status": "finished",
    "finish_as": "cancelled",
    "reason": "",
    "order_type": "close-long-order"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	[Futures price-triggered order details]
» None	FuturesPriceTriggeredOrder	Futures price-triggered order details
»» initial	object	none
»»» contract	string	Futures contract
»»» size	integer(int64)	Represents the number of contracts that need to be closed, full closing: size=0 Partial closing: plan-close-short-position size>0 Partial closing: plan-close-long-position size<0
»»» amount	string	Same as `size`; used for decimal contract size. When both `size` and `amount` are provided, `amount` takes precedence.
»»» price	string	Order price. Set to 0 to use market price
»»» tif	string	Time in force strategy, default is gtc, market orders currently only support ioc mode - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled
»»» text	string	The source of the order, including: - web: Web - api: API call - app: Mobile app
»»» reduce_only	boolean	When set to true, perform automatic position reduction operation. Set to true to ensure that the order will not open a new position, and is only used to close or reduce positions
»»» is_reduce_only	boolean	Is the order reduce-only
»»» is_close	boolean	Is the order to close position
»» trigger	object	none
»»» strategy_type	integer(int32)	Trigger Strategy - 0: Price trigger, triggered when price meets conditions - 1: Price spread trigger, i.e. the difference between the latest price specified in `price_type` and the second-last price Currently only supports 0 (latest transaction price)
»»» price_type	integer(int32)	Reference price type. 0 - Latest trade price, 1 - Mark price, 2 - Index price
»»» price	string	Price value for price trigger, or spread value for spread trigger
»»» rule	integer(int32)	Price Condition Type - 1: Trigger when the price calculated based on `strategy_type` and `price_type` is greater than or equal to `Trigger.Price`, while Trigger.Price must > last_price - 2: Trigger when the price calculated based on `strategy_type` and `price_type` is less than or equal to `Trigger.Price`, and Trigger.Price must < last_price
»»» expiration	integer	Maximum wait time for trigger condition (in seconds). Order will be cancelled if timeout
»» id	integer(int64)	Auto order ID
»» id_string	string	String form of the auto order ID; the same order as numeric `id`, as the decimal string of `id` to avoid int64 precision loss in JavaScript and similar environments. Prefer this field to display the order ID or when a string unique identifier is needed; one-to-one with `id`. Same meaning as the field of the same name in futures price-trigger REST APIs and in `futures.orders` / `futures.autoorders` WebSocket pushes.
»» user	integer	User ID
»» create_time	number(double)	Created time
»» finish_time	number(double)	End time
»» trade_id	integer(int64)	ID of the order created after trigger
»» status	string	Order status - `open`: Active - `finished`: Finished - `inactive`: Inactive, only applies to order take-profit/stop-loss - `invalid`: Invalid, only applies to order take-profit/stop-loss
»» finish_as	string	Finish status: cancelled - Cancelled; succeeded - Succeeded; failed - Failed; expired - Expired
»» reason	string	Additional description of how the order was completed
»» order_type	string	Types of take-profit and stop-loss orders, including: - `close-long-order`: Order take-profit/stop-loss, close long position - `close-short-order`: Order take-profit/stop-loss, close short position - `close-long-position`: Position take-profit/stop-loss, used to close all long positions - `close-short-position`: Position take-profit/stop-loss, used to close all short positions - `plan-close-long-position`: Position plan take-profit/stop-loss, used to close all or partial long positions - `plan-close-short-position`: Position plan take-profit/stop-loss, used to close all or partial short positions The two types of order take-profit/stop-loss are read-only and cannot be passed in requests
»» me_order_id	integer(int64)	Corresponding order ID for order take-profit/stop-loss orders

# Enumerated Values

Property	Value
tif	gtc
tif	ioc
strategy_type	0
strategy_type	1
price_type	0
price_type	1
price_type	2
rule	1
rule	2
status	open
status	finished
status	inactive
status	invalid
finish_as	cancelled
finish_as	succeeded
finish_as	failed
finish_as	expired

WARNING

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

# Create price-triggered order

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/price_orders'
query_param = ''
body='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/usdt/price_orders"
query_param=""
body_param='{"initial":{"contract":"BTC_USDT","size":100,"price":"5.03"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400},"order_type":"close-long-order"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /futures/{settle}/price_orders

Create price-triggered order

Body parameter

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  },
  "order_type": "close-long-order"
}

Parameters

Name	In	Type	Required	Description
body	body	FuturesPriceTriggeredOrder	true	none
» initial	body	object	true	none
»» contract	body	string	true	Futures contract
»» size	body	integer(int64)	false	Represents the number of contracts that need to be closed, full closing: size=0 Partial closing: plan-close-short-position size>0 Partial closing: plan-close-long-position size<0
»» amount	body	string	false	Same as `size`; used for decimal contract size. When both `size` and `amount` are provided, `amount` takes precedence.
»» price	body	string	true	Order price. Set to 0 to use market price
»» close	body	boolean	false	When fully closing a position in single-position mode, close must be set to true to execute the close operation. When partially closing a position in single-position mode or in dual-position mode, close can be left unset or set to false.
»» tif	body	string	false	Time in force strategy, default is gtc, market orders currently only support ioc mode - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled
»» text	body	string	false	The source of the order, including: - web: Web - api: API call - app: Mobile app
»» reduce_only	body	boolean	false	When set to true, perform automatic position reduction operation. Set to true to ensure that the order will not open a new position, and is only used to close or reduce positions
»» auto_size	body	string	false	One-way Mode: auto_size is not required Hedge Mode full closing (size=0): auto_size must be set, close_long for closing long positions, close_short for closing short positions Hedge Mode partial closing (size≠0): auto_size is not required
» trigger	body	object	true	none
»» strategy_type	body	integer(int32)	false	Trigger Strategy - 0: Price trigger, triggered when price meets conditions - 1: Price spread trigger, i.e. the difference between the latest price specified in `price_type` and the second-last price Currently only supports 0 (latest transaction price)
»» price_type	body	integer(int32)	false	Reference price type. 0 - Latest trade price, 1 - Mark price, 2 - Index price
»» price	body	string	true	Price value for price trigger, or spread value for spread trigger
»» rule	body	integer(int32)	true	Price Condition Type - 1: Trigger when the price calculated based on `strategy_type` and `price_type` is greater than or equal to `Trigger.Price`, while Trigger.Price must > last_price - 2: Trigger when the price calculated based on `strategy_type` and `price_type` is less than or equal to `Trigger.Price`, and Trigger.Price must < last_price
»» expiration	body	integer	false	Maximum wait time for trigger condition (in seconds). Order will be cancelled if timeout
» order_type	body	string	false	Types of take-profit and stop-loss orders, including: - `close-long-order`: Order take-profit/stop-loss, close long position - `close-short-order`: Order take-profit/stop-loss, close short position - `close-long-position`: Position take-profit/stop-loss, used to close all long positions - `close-short-position`: Position take-profit/stop-loss, used to close all short positions - `plan-close-long-position`: Position plan take-profit/stop-loss, used to close all or partial long positions - `plan-close-short-position`: Position plan take-profit/stop-loss, used to close all or partial short positions The two types of order take-profit/stop-loss are read-only and cannot be passed in requests
settle	path	string	true	Settle currency

# Detailed descriptions

»» size: Represents the number of contracts that need to be closed, full closing: size=0
Partial closing: plan-close-short-position size>0
Partial closing: plan-close-long-position size<0

»» close: When fully closing a position in single-position mode, close must be set to true to execute the close operation.
When partially closing a position in single-position mode or in dual-position mode, close can be left unset or set to false.

»» tif: Time in force strategy, default is gtc, market orders currently only support ioc mode

- gtc: GoodTillCancelled
- ioc: ImmediateOrCancelled

»» text: The source of the order, including:
- web: Web
- api: API call
- app: Mobile app

»» auto_size: One-way Mode: auto_size is not required
Hedge Mode full closing (size=0): auto_size must be set, close_long for closing long positions, close_short for closing short positions
Hedge Mode partial closing (size≠0): auto_size is not required

»» strategy_type: Trigger Strategy

- 0: Price trigger, triggered when price meets conditions
- 1: Price spread trigger, i.e. the difference between the latest price specified in price_type and the second-last price
Currently only supports 0 (latest transaction price)

»» rule: Price Condition Type

- 1: Trigger when the price calculated based on strategy_type and price_type is greater than or equal to Trigger.Price, while Trigger.Price must > last_price
- 2: Trigger when the price calculated based on strategy_type and price_type is less than or equal to Trigger.Price, and Trigger.Price must < last_price

» order_type: Types of take-profit and stop-loss orders, including:

- close-long-order: Order take-profit/stop-loss, close long position
- close-short-order: Order take-profit/stop-loss, close short position
- close-long-position: Position take-profit/stop-loss, used to close all long positions
- close-short-position: Position take-profit/stop-loss, used to close all short positions
- plan-close-long-position: Position plan take-profit/stop-loss, used to close all or partial long positions
- plan-close-short-position: Position plan take-profit/stop-loss, used to close all or partial short positions

The two types of order take-profit/stop-loss are read-only and cannot be passed in requests

# Enumerated Values

Parameter	Value
»» tif	gtc
»» tif	ioc
»» strategy_type	0
»» strategy_type	1
»» price_type	0
»» price_type	1
»» price_type	2
»» rule	1
»» rule	2
settle	btc
settle	usdt

Example responses

201 Response

{
  "id": 1432329,
  "id_string": "1432329"
}

Responses

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

Response Schema

Status Code 201

TriggerOrderResponse

Name	Type	Description
» id	integer(int64)	Auto order ID
» id_string	string	String form of the auto order ID; the same order as numeric `id`, as the decimal string of `id` to avoid int64 precision loss in JavaScript and similar environments. Prefer this field to display the order ID or when a string unique identifier is needed; one-to-one with `id`. Same meaning as the field of the same name in futures price-trigger REST APIs and in `futures.orders` / `futures.autoorders` WebSocket pushes.

WARNING

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

# Cancel all auto orders

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/price_orders'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/usdt/price_orders"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /futures/{settle}/price_orders

Cancel all auto orders

Parameters

Name	In	Type	Required	Description
contract	query	string	false	Futures contract, return related data only if specified
settle	path	string	true	Settle currency

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

[
  {
    "initial": {
      "contract": "BTC_USDT",
      "size": 100,
      "price": "5.03"
    },
    "trigger": {
      "strategy_type": 0,
      "price_type": 0,
      "price": "3000",
      "rule": 1,
      "expiration": 86400
    },
    "id": 1283293,
    "id_string": "1283293",
    "user": 1234,
    "create_time": 1514764800,
    "finish_time": 1514764900,
    "trade_id": 13566,
    "status": "finished",
    "finish_as": "cancelled",
    "reason": "",
    "order_type": "close-long-order"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Batch cancel request is received and processed. Success is determined based on the order list	[FuturesPriceTriggeredOrder]

Response Schema

Status Code 200

Name	Type	Description
None	array	[Futures price-triggered order details]
» None	FuturesPriceTriggeredOrder	Futures price-triggered order details
»» initial	object	none
»»» contract	string	Futures contract
»»» size	integer(int64)	Represents the number of contracts that need to be closed, full closing: size=0 Partial closing: plan-close-short-position size>0 Partial closing: plan-close-long-position size<0
»»» amount	string	Same as `size`; used for decimal contract size. When both `size` and `amount` are provided, `amount` takes precedence.
»»» price	string	Order price. Set to 0 to use market price
»»» tif	string	Time in force strategy, default is gtc, market orders currently only support ioc mode - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled
»»» text	string	The source of the order, including: - web: Web - api: API call - app: Mobile app
»»» reduce_only	boolean	When set to true, perform automatic position reduction operation. Set to true to ensure that the order will not open a new position, and is only used to close or reduce positions
»»» is_reduce_only	boolean	Is the order reduce-only
»»» is_close	boolean	Is the order to close position
»» trigger	object	none
»»» strategy_type	integer(int32)	Trigger Strategy - 0: Price trigger, triggered when price meets conditions - 1: Price spread trigger, i.e. the difference between the latest price specified in `price_type` and the second-last price Currently only supports 0 (latest transaction price)
»»» price_type	integer(int32)	Reference price type. 0 - Latest trade price, 1 - Mark price, 2 - Index price
»»» price	string	Price value for price trigger, or spread value for spread trigger
»»» rule	integer(int32)	Price Condition Type - 1: Trigger when the price calculated based on `strategy_type` and `price_type` is greater than or equal to `Trigger.Price`, while Trigger.Price must > last_price - 2: Trigger when the price calculated based on `strategy_type` and `price_type` is less than or equal to `Trigger.Price`, and Trigger.Price must < last_price
»»» expiration	integer	Maximum wait time for trigger condition (in seconds). Order will be cancelled if timeout
»» id	integer(int64)	Auto order ID
»» id_string	string	String form of the auto order ID; the same order as numeric `id`, as the decimal string of `id` to avoid int64 precision loss in JavaScript and similar environments. Prefer this field to display the order ID or when a string unique identifier is needed; one-to-one with `id`. Same meaning as the field of the same name in futures price-trigger REST APIs and in `futures.orders` / `futures.autoorders` WebSocket pushes.
»» user	integer	User ID
»» create_time	number(double)	Created time
»» finish_time	number(double)	End time
»» trade_id	integer(int64)	ID of the order created after trigger
»» status	string	Order status - `open`: Active - `finished`: Finished - `inactive`: Inactive, only applies to order take-profit/stop-loss - `invalid`: Invalid, only applies to order take-profit/stop-loss
»» finish_as	string	Finish status: cancelled - Cancelled; succeeded - Succeeded; failed - Failed; expired - Expired
»» reason	string	Additional description of how the order was completed
»» order_type	string	Types of take-profit and stop-loss orders, including: - `close-long-order`: Order take-profit/stop-loss, close long position - `close-short-order`: Order take-profit/stop-loss, close short position - `close-long-position`: Position take-profit/stop-loss, used to close all long positions - `close-short-position`: Position take-profit/stop-loss, used to close all short positions - `plan-close-long-position`: Position plan take-profit/stop-loss, used to close all or partial long positions - `plan-close-short-position`: Position plan take-profit/stop-loss, used to close all or partial short positions The two types of order take-profit/stop-loss are read-only and cannot be passed in requests
»» me_order_id	integer(int64)	Corresponding order ID for order take-profit/stop-loss orders

# Enumerated Values

Property	Value
tif	gtc
tif	ioc
strategy_type	0
strategy_type	1
price_type	0
price_type	1
price_type	2
rule	1
rule	2
status	open
status	finished
status	inactive
status	invalid
finish_as	cancelled
finish_as	succeeded
finish_as	failed
finish_as	expired

WARNING

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

# Query single auto order details

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/price_orders/0'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/usdt/price_orders/0"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

GET /futures/{settle}/price_orders/{order_id}

Query single auto order details

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
order_id	path	integer(int64)	true	ID returned when order is successfully created

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  },
  "id": 1283293,
  "id_string": "1283293",
  "user": 1234,
  "create_time": 1514764800,
  "finish_time": 1514764900,
  "trade_id": 13566,
  "status": "finished",
  "finish_as": "cancelled",
  "reason": "",
  "order_type": "close-long-order"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Auto order details	FuturesPriceTriggeredOrder

Response Schema

Status Code 200

Futures price-triggered order details

Name	Type	Description
» initial	object	none
»» contract	string	Futures contract
»» size	integer(int64)	Represents the number of contracts that need to be closed, full closing: size=0 Partial closing: plan-close-short-position size>0 Partial closing: plan-close-long-position size<0
»» amount	string	Same as `size`; used for decimal contract size. When both `size` and `amount` are provided, `amount` takes precedence.
»» price	string	Order price. Set to 0 to use market price
»» tif	string	Time in force strategy, default is gtc, market orders currently only support ioc mode - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled
»» text	string	The source of the order, including: - web: Web - api: API call - app: Mobile app
»» reduce_only	boolean	When set to true, perform automatic position reduction operation. Set to true to ensure that the order will not open a new position, and is only used to close or reduce positions
»» is_reduce_only	boolean	Is the order reduce-only
»» is_close	boolean	Is the order to close position
» trigger	object	none
»» strategy_type	integer(int32)	Trigger Strategy - 0: Price trigger, triggered when price meets conditions - 1: Price spread trigger, i.e. the difference between the latest price specified in `price_type` and the second-last price Currently only supports 0 (latest transaction price)
»» price_type	integer(int32)	Reference price type. 0 - Latest trade price, 1 - Mark price, 2 - Index price
»» price	string	Price value for price trigger, or spread value for spread trigger
»» rule	integer(int32)	Price Condition Type - 1: Trigger when the price calculated based on `strategy_type` and `price_type` is greater than or equal to `Trigger.Price`, while Trigger.Price must > last_price - 2: Trigger when the price calculated based on `strategy_type` and `price_type` is less than or equal to `Trigger.Price`, and Trigger.Price must < last_price
»» expiration	integer	Maximum wait time for trigger condition (in seconds). Order will be cancelled if timeout
» id	integer(int64)	Auto order ID
» id_string	string	String form of the auto order ID; the same order as numeric `id`, as the decimal string of `id` to avoid int64 precision loss in JavaScript and similar environments. Prefer this field to display the order ID or when a string unique identifier is needed; one-to-one with `id`. Same meaning as the field of the same name in futures price-trigger REST APIs and in `futures.orders` / `futures.autoorders` WebSocket pushes.
» user	integer	User ID
» create_time	number(double)	Created time
» finish_time	number(double)	End time
» trade_id	integer(int64)	ID of the order created after trigger
» status	string	Order status - `open`: Active - `finished`: Finished - `inactive`: Inactive, only applies to order take-profit/stop-loss - `invalid`: Invalid, only applies to order take-profit/stop-loss
» finish_as	string	Finish status: cancelled - Cancelled; succeeded - Succeeded; failed - Failed; expired - Expired
» reason	string	Additional description of how the order was completed
» order_type	string	Types of take-profit and stop-loss orders, including: - `close-long-order`: Order take-profit/stop-loss, close long position - `close-short-order`: Order take-profit/stop-loss, close short position - `close-long-position`: Position take-profit/stop-loss, used to close all long positions - `close-short-position`: Position take-profit/stop-loss, used to close all short positions - `plan-close-long-position`: Position plan take-profit/stop-loss, used to close all or partial long positions - `plan-close-short-position`: Position plan take-profit/stop-loss, used to close all or partial short positions The two types of order take-profit/stop-loss are read-only and cannot be passed in requests
» me_order_id	integer(int64)	Corresponding order ID for order take-profit/stop-loss orders

# Enumerated Values

Property	Value
tif	gtc
tif	ioc
strategy_type	0
strategy_type	1
price_type	0
price_type	1
price_type	2
rule	1
rule	2
status	open
status	finished
status	inactive
status	invalid
finish_as	cancelled
finish_as	succeeded
finish_as	failed
finish_as	expired

WARNING

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

# Cancel single auto order

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/price_orders/0'
query_param = ''
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('DELETE', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('DELETE', host + prefix + url, headers=headers)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/usdt/price_orders/0"
query_param=""
body_param=''
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

DELETE /futures/{settle}/price_orders/{order_id}

Cancel single auto order

Parameters

Name	In	Type	Required	Description
settle	path	string	true	Settle currency
order_id	path	integer(int64)	true	ID returned when order is successfully created

# Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

{
  "initial": {
    "contract": "BTC_USDT",
    "size": 100,
    "price": "5.03"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  },
  "id": 1283293,
  "id_string": "1283293",
  "user": 1234,
  "create_time": 1514764800,
  "finish_time": 1514764900,
  "trade_id": 13566,
  "status": "finished",
  "finish_as": "cancelled",
  "reason": "",
  "order_type": "close-long-order"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Auto order details	FuturesPriceTriggeredOrder

Response Schema

Status Code 200

Futures price-triggered order details

Name	Type	Description
» initial	object	none
»» contract	string	Futures contract
»» size	integer(int64)	Represents the number of contracts that need to be closed, full closing: size=0 Partial closing: plan-close-short-position size>0 Partial closing: plan-close-long-position size<0
»» amount	string	Same as `size`; used for decimal contract size. When both `size` and `amount` are provided, `amount` takes precedence.
»» price	string	Order price. Set to 0 to use market price
»» tif	string	Time in force strategy, default is gtc, market orders currently only support ioc mode - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled
»» text	string	The source of the order, including: - web: Web - api: API call - app: Mobile app
»» reduce_only	boolean	When set to true, perform automatic position reduction operation. Set to true to ensure that the order will not open a new position, and is only used to close or reduce positions
»» is_reduce_only	boolean	Is the order reduce-only
»» is_close	boolean	Is the order to close position
» trigger	object	none
»» strategy_type	integer(int32)	Trigger Strategy - 0: Price trigger, triggered when price meets conditions - 1: Price spread trigger, i.e. the difference between the latest price specified in `price_type` and the second-last price Currently only supports 0 (latest transaction price)
»» price_type	integer(int32)	Reference price type. 0 - Latest trade price, 1 - Mark price, 2 - Index price
»» price	string	Price value for price trigger, or spread value for spread trigger
»» rule	integer(int32)	Price Condition Type - 1: Trigger when the price calculated based on `strategy_type` and `price_type` is greater than or equal to `Trigger.Price`, while Trigger.Price must > last_price - 2: Trigger when the price calculated based on `strategy_type` and `price_type` is less than or equal to `Trigger.Price`, and Trigger.Price must < last_price
»» expiration	integer	Maximum wait time for trigger condition (in seconds). Order will be cancelled if timeout
» id	integer(int64)	Auto order ID
» id_string	string	String form of the auto order ID; the same order as numeric `id`, as the decimal string of `id` to avoid int64 precision loss in JavaScript and similar environments. Prefer this field to display the order ID or when a string unique identifier is needed; one-to-one with `id`. Same meaning as the field of the same name in futures price-trigger REST APIs and in `futures.orders` / `futures.autoorders` WebSocket pushes.
» user	integer	User ID
» create_time	number(double)	Created time
» finish_time	number(double)	End time
» trade_id	integer(int64)	ID of the order created after trigger
» status	string	Order status - `open`: Active - `finished`: Finished - `inactive`: Inactive, only applies to order take-profit/stop-loss - `invalid`: Invalid, only applies to order take-profit/stop-loss
» finish_as	string	Finish status: cancelled - Cancelled; succeeded - Succeeded; failed - Failed; expired - Expired
» reason	string	Additional description of how the order was completed
» order_type	string	Types of take-profit and stop-loss orders, including: - `close-long-order`: Order take-profit/stop-loss, close long position - `close-short-order`: Order take-profit/stop-loss, close short position - `close-long-position`: Position take-profit/stop-loss, used to close all long positions - `close-short-position`: Position take-profit/stop-loss, used to close all short positions - `plan-close-long-position`: Position plan take-profit/stop-loss, used to close all or partial long positions - `plan-close-short-position`: Position plan take-profit/stop-loss, used to close all or partial short positions The two types of order take-profit/stop-loss are read-only and cannot be passed in requests
» me_order_id	integer(int64)	Corresponding order ID for order take-profit/stop-loss orders

# Enumerated Values

Property	Value
tif	gtc
tif	ioc
strategy_type	0
strategy_type	1
price_type	0
price_type	1
price_type	2
rule	1
rule	2
status	open
status	finished
status	inactive
status	invalid
finish_as	cancelled
finish_as	succeeded
finish_as	failed
finish_as	expired

WARNING

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

# Modify a Single Auto Order

Code samples

# coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://api.gateio.ws"
prefix = "/api/v4"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/futures/usdt/price_orders/amend/0'
query_param = ''
body='{"order_id":123456789,"size":0,"price":"0","trigger_price":"988888","price_type":0,"auto_size":"close_long"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PUT', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PUT', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="PUT"
url="/futures/usdt/price_orders/amend/0"
query_param=""
body_param='{"order_id":123456789,"size":0,"price":"0","trigger_price":"988888","price_type":0,"auto_size":"close_long"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

full_url="$host$prefix$url"
curl -X $method $full_url -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

PUT /futures/{settle}/price_orders/amend/{order_id}

Modify a Single Auto Order

Body parameter

{
  "order_id": 123456789,
  "size": 0,
  "price": "0",
  "trigger_price": "988888",
  "price_type": 0,
  "auto_size": "close_long"
}

Parameters

Name	In	Type	Required	Description
body	body	FuturesUpdatePriceTriggeredOrder	true	none
» settle	body	string	false	Settlement Currency (e.g., USDT, BTC)
» order_id	body	integer(int64)	true	ID of the Pending Take-Profit/Stop-Loss Trigger Order
» size	body	integer(int64)	false	Modified Contract Quantity. Full Close: 0; Partial Close: Positive/Negative values indicate direction (consistent with the creation interface logic).
» amount	body	string	false	Same as `size`; used for decimal contract size. When both `size` and `amount` are provided, `amount` takes precedence.
» price	body	string	false	Represents the modified trading price. A value of 0 indicates a market order.
» trigger_price	body	string	false	Modified Trigger Price
» price_type	body	integer(int32)	false	Reference price type. 0 - Latest trade price, 1 - Mark price, 2 - Index price
» auto_size	body	string	false	One-way Mode: auto_size is not required Hedge Mode partial closing (size≠0): auto_size is not required Hedge Mode full closing (size=0): auto_size must be set, close_long for closing long positions, close_short for closing short positions
» close	body	boolean	false	When fully closing a position in single-position mode, close must be set to true to execute the close operation. When partially closing a position in single-position mode or in dual-position mode, close can be left unset or set to false.
settle	path	string	true	Settle currency
order_id	path	integer(int64)	true	ID returned when order is successfully created

# Detailed descriptions

» auto_size: One-way Mode: auto_size is not required
Hedge Mode partial closing (size≠0): auto_size is not required
Hedge Mode full closing (size=0): auto_size must be set, close_long for closing long positions, close_short for closing short positions

» close: When fully closing a position in single-position mode, close must be set to true to execute the close operation.
When partially closing a position in single-position mode or in dual-position mode, close can be left unset or set to false.

# Enumerated Values

Parameter	Value
» price_type	0
» price_type	1
» price_type	2
settle	btc
settle	usdt

Example responses

200 Response

{
  "id": 1432329,
  "id_string": "1432329"
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Order created successfully	TriggerOrderResponse

Response Schema

Status Code 200

TriggerOrderResponse

Name	Type	Description
» id	integer(int64)	Auto order ID
» id_string	string	String form of the auto order ID; the same order as numeric `id`, as the decimal string of `id` to avoid int64 precision loss in JavaScript and similar environments. Prefer this field to display the order ID or when a string unique identifier is needed; one-to-one with `id`. Same meaning as the field of the same name in futures price-trigger REST APIs and in `futures.orders` / `futures.autoorders` WebSocket pushes.

WARNING

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

# Schemas

# MyFuturesTradeTimeRange

{
  "trade_id": "string",
  "create_time": 0,
  "contract": "string",
  "order_id": "string",
  "size": "string",
  "close_size": "string",
  "price": "string",
  "role": "taker",
  "text": "string",
  "fee": "string",
  "point_fee": "string"
}

# Properties

Name	Type	Required	Restrictions	Description
trade_id	string	false	none	Fill ID
create_time	number(double)	false	none	Fill Time
contract	string	false	none	Futures contract
order_id	string	false	none	Related order ID
size	string	false	none	Trading size
close_size	string	false	none	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	false	none	Fill Price
role	string	false	none	Trade role. taker - taker, maker - maker
text	string	false	none	Order custom information
fee	string	false	none	Trade fee
point_fee	string	false	none	Points used to deduct trade fee

# Enumerated Values

Property	Value
role	taker
role	maker

# FuturesPriceTriggeredOrder

{
  "initial": {
    "contract": "string",
    "size": 0,
    "amount": "string",
    "price": "string",
    "close": false,
    "tif": "gtc",
    "text": "string",
    "reduce_only": false,
    "auto_size": "string",
    "is_reduce_only": true,
    "is_close": true
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "string",
    "rule": 1,
    "expiration": 0
  },
  "id": 0,
  "id_string": "string",
  "user": 0,
  "create_time": 0,
  "finish_time": 0,
  "trade_id": 0,
  "status": "open",
  "finish_as": "cancelled",
  "reason": "string",
  "order_type": "string",
  "me_order_id": 0
}

Futures price-triggered order details

# Properties

Name	Type	Required	Restrictions	Description
initial	object	true	none	none
» contract	string	true	none	Futures contract
» size	integer(int64)	false	none	Represents the number of contracts that need to be closed, full closing: size=0 Partial closing: plan-close-short-position size>0 Partial closing: plan-close-long-position size<0
» amount	string	false	none	Same as `size`; used for decimal contract size. When both `size` and `amount` are provided, `amount` takes precedence.
» price	string	true	none	Order price. Set to 0 to use market price
» close	boolean	false	write-only	When fully closing a position in single-position mode, close must be set to true to execute the close operation. When partially closing a position in single-position mode or in dual-position mode, close can be left unset or set to false.
» tif	string	false	none	Time in force strategy, default is gtc, market orders currently only support ioc mode - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled
» text	string	false	none	The source of the order, including: - web: Web - api: API call - app: Mobile app
» reduce_only	boolean	false	none	When set to true, perform automatic position reduction operation. Set to true to ensure that the order will not open a new position, and is only used to close or reduce positions
» auto_size	string	false	write-only	One-way Mode: auto_size is not required Hedge Mode full closing (size=0): auto_size must be set, close_long for closing long positions, close_short for closing short positions Hedge Mode partial closing (size≠0): auto_size is not required
» is_reduce_only	boolean	false	read-only	Is the order reduce-only
» is_close	boolean	false	read-only	Is the order to close position
trigger	object	true	none	none
» strategy_type	integer(int32)	false	none	Trigger Strategy - 0: Price trigger, triggered when price meets conditions - 1: Price spread trigger, i.e. the difference between the latest price specified in `price_type` and the second-last price Currently only supports 0 (latest transaction price)
» price_type	integer(int32)	false	none	Reference price type. 0 - Latest trade price, 1 - Mark price, 2 - Index price
» price	string	true	none	Price value for price trigger, or spread value for spread trigger
» rule	integer(int32)	true	none	Price Condition Type - 1: Trigger when the price calculated based on `strategy_type` and `price_type` is greater than or equal to `Trigger.Price`, while Trigger.Price must > last_price - 2: Trigger when the price calculated based on `strategy_type` and `price_type` is less than or equal to `Trigger.Price`, and Trigger.Price must < last_price
» expiration	integer	false	none	Maximum wait time for trigger condition (in seconds). Order will be cancelled if timeout
id	integer(int64)	false	read-only	Auto order ID
id_string	string	false	read-only	String form of the auto order ID; the same order as numeric `id`, as the decimal string of `id` to avoid int64 precision loss in JavaScript and similar environments. Prefer this field to display the order ID or when a string unique identifier is needed; one-to-one with `id`. Same meaning as the field of the same name in futures price-trigger REST APIs and in `futures.orders` / `futures.autoorders` WebSocket pushes.
user	integer	false	read-only	User ID
create_time	number(double)	false	read-only	Created time
finish_time	number(double)	false	read-only	End time
trade_id	integer(int64)	false	read-only	ID of the order created after trigger
status	string	false	read-only	Order status - `open`: Active - `finished`: Finished - `inactive`: Inactive, only applies to order take-profit/stop-loss - `invalid`: Invalid, only applies to order take-profit/stop-loss
finish_as	string	false	read-only	Finish status: cancelled - Cancelled; succeeded - Succeeded; failed - Failed; expired - Expired
reason	string	false	read-only	Additional description of how the order was completed
order_type	string	false	none	Types of take-profit and stop-loss orders, including: - `close-long-order`: Order take-profit/stop-loss, close long position - `close-short-order`: Order take-profit/stop-loss, close short position - `close-long-position`: Position take-profit/stop-loss, used to close all long positions - `close-short-position`: Position take-profit/stop-loss, used to close all short positions - `plan-close-long-position`: Position plan take-profit/stop-loss, used to close all or partial long positions - `plan-close-short-position`: Position plan take-profit/stop-loss, used to close all or partial short positions The two types of order take-profit/stop-loss are read-only and cannot be passed in requests
me_order_id	integer(int64)	false	read-only	Corresponding order ID for order take-profit/stop-loss orders

# Enumerated Values

Property	Value
tif	gtc
tif	ioc
strategy_type	0
strategy_type	1
price_type	0
price_type	1
price_type	2
rule	1
rule	2
status	open
status	finished
status	inactive
status	invalid
finish_as	cancelled
finish_as	succeeded
finish_as	failed
finish_as	expired

# BatchAmendOrderReq

{
  "order_id": 0,
  "text": "string",
  "size": "string",
  "price": "string",
  "amend_text": "string"
}

Modify contract order parameters

# Properties

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

# UpdateDualCompPositionCrossModeRequest

{
  "mode": "string",
  "contract": "BTC_USDT"
}

UpdateDualCompPositionCrossModeRequest

# Properties

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

# Contract

{
  "name": "string",
  "type": "inverse",
  "quanto_multiplier": "string",
  "leverage_min": "string",
  "leverage_max": "string",
  "maintenance_rate": "string",
  "mark_type": "internal",
  "mark_price": "string",
  "index_price": "string",
  "last_price": "string",
  "maker_fee_rate": "string",
  "taker_fee_rate": "string",
  "order_price_round": "string",
  "mark_price_round": "string",
  "funding_rate": "string",
  "funding_interval": 0,
  "funding_next_apply": 0,
  "risk_limit_base": "string",
  "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,
  "in_delisting": true,
  "orders_limit": 0,
  "enable_bonus": true,
  "enable_credit": true,
  "create_time": 0,
  "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"
}

Futures contract details

# Properties

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 period `in_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

# Enumerated Values

Property	Value
type	inverse
type	direct
mark_type	internal
mark_type	index

# CancelBatchFutureOrdersRequest

[
  "string"
]

Order ID array

# Properties

None

# FundingRateRecord

{
  "t": 0,
  "r": "string"
}

# Properties

Name	Type	Required	Restrictions	Description
t	integer(int64)	false	none	Unix timestamp in seconds
r	string	false	none	Funding rate

# CreateTrailOrderResponse

{
  "code": 0,
  "message": "string",
  "data": {
    "id": "string"
  },
  "timestamp": 0
}

CreateTrailOrderResponse

# Properties

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)

# BatchFundingRatesResponse

{
  "contract": "string",
  "data": [
    {
      "t": 0,
      "r": "string"
    }
  ]
}

# Properties

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

# CreateTrailOrder

{
  "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

# Properties

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 call 2. 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.01` Note: 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

# Enumerated Values

Property	Value
price_type	1
price_type	2
price_type	3

# StopTrailOrder

{
  "id": 0,
  "text": "string"
}

StopTrailOrder

# Properties

Name	Type	Required	Restrictions	Description
id	integer(int64)	false	none	Order ID, if ID is specified, text is not needed
text	string	false	none	Custom text, if ID is not specified, terminate based on user_id and text

# TriggerTime

{
  "triggerTime": "1660039145000"
}

triggerTime

# Properties

Name	Type	Required	Restrictions	Description
triggerTime	integer(int64)	false	none	Timestamp when countdown ends, in milliseconds

# BatchFuturesOrder

{
  "succeeded": true,
  "label": "string",
  "detail": "string",
  "id": 0,
  "user": 0,
  "create_time": 0,
  "finish_time": 0,
  "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_act": "co",
  "stp_id": 0,
  "market_order_slip_ratio": "string"
}

Futures order details

# Properties

Name	Type	Required	Restrictions	Description
succeeded	boolean	false	none	Request execution result
label	string	false	none	Error label, only exists if execution fails
detail	string	false	none	Error detail, only present if execution failed and details need to be given
id	integer(int64)	false	read-only	Futures order ID
user	integer	false	read-only	User ID
create_time	number(double)	false	read-only	Creation time of order
finish_time	number(double)	false	read-only	Order finished time. Not returned if order is open
finish_as	string	false	read-only	How the order was finished: - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is `IOC`, finish immediately - auto_deleveraged: finished by ADL - reduce_only: cancelled because of increasing position while `reduce-only` set - position_closed: cancelled because the position was closed - reduce_out: only reduce positions by excluding hard-to-fill orders - stp: cancelled because self trade prevention
status	string	false	read-only	Order status - `open`: Pending - `finished`: Completed
contract	string	false	none	Futures contract
size	string	false	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	false	none	Order price. Price of 0 with `tif` set to `ioc` represents a market order.
close	boolean	false	write-only	Set as `true` to close the position, with `size` set to 0
is_close	boolean	false	read-only	Is the order to close position
reduce_only	boolean	false	write-only	Set as `true` to be reduce-only order
is_reduce_only	boolean	false	read-only	Is the order reduce-only
is_liq	boolean	false	read-only	Is the order for liquidation
tif	string	false	none	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none
left	string	false	read-only	Unfilled quantity
fill_price	string	false	read-only	Fill price
text	string	false	none	User defined information. If not empty, must follow the rules below: 1. prefixed with `t-` 2. no longer than 28 bytes without `t-` prefix 3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance
tkfr	string	false	read-only	Taker fee
mkfr	string	false	read-only	Maker fee
refu	integer	false	read-only	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_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
stp_id	integer	false	read-only	Orders between users in the same `stp_id` group are not allowed to be self-traded 1. If the `stp_id` of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the `stp_act` of the taker. 2. `stp_id` returns `0` by default for orders that have not been set for `STP group`
market_order_slip_ratio	string	false	none	The maximum slippage ratio

# Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
finish_as	stp
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok
auto_size	close_long
auto_size	close_short
stp_act	co
stp_act	cn
stp_act	cb
stp_act	-

# FuturesPremiumIndex

{
  "t": 0,
  "c": "string",
  "h": "string",
  "l": "string",
  "o": "string"
}

data point in every timestamp

# Properties

Name	Type	Required	Restrictions	Description
t	number(double)	false	none	Unix timestamp in seconds
c	string	false	none	Close price
h	string	false	none	Highest price
l	string	false	none	Lowest price
o	string	false	none	Open price

# TrailOrderDetailResponse

{
  "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

# Properties

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)

# Enumerated Values

Property	Value
price_type	0
price_type	1
price_type	2
price_type	3
status	open
status	finished

# FuturesBBOOrder

{
  "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

# Properties

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 bytes 3. 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-traded 1. If the `stp_id` of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the `stp_act` of the taker. 2. `stp_id` returns `0` by default for orders that have not been set for `STP group`
stp_act	string	false	none	Self-Trading Prevention Action. Users can use this field to set self-trade 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

# Enumerated Values

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	-

# FuturesRiskLimitTier

{
  "tier": 0,
  "risk_limit": "string",
  "initial_rate": "string",
  "maintenance_rate": "string",
  "leverage_max": "string",
  "deduction": "string"
}

Information for each tier of the gradient risk limit table

# Properties

Name	Type	Required	Restrictions	Description
tier	integer(int)	false	none	Tier
risk_limit	string	false	none	Position risk limit
initial_rate	string	false	none	Initial margin rate
maintenance_rate	string	false	none	The maintenance margin rate of the first tier of risk limit sheet
leverage_max	string	false	none	Maximum leverage
deduction	string	false	none	Maintenance margin quick calculation deduction amount

# FuturesPositionCrossMode

{
  "mode": "string",
  "contract": "BTC_USDT"
}

FuturesPositionCrossMode

# Properties

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

# FuturesCandlestick

{
  "t": 0,
  "v": "string",
  "c": "string",
  "h": "string",
  "l": "string",
  "o": "string",
  "sum": "string"
}

data point in every timestamp

# Properties

Name	Type	Required	Restrictions	Description
t	number(double)	false	none	Unix timestamp in seconds
v	string	false	none	size volume (contract size). Only returned if `contract` is not prefixed
c	string	false	none	Close price (quote currency)
h	string	false	none	Highest price (quote currency)
l	string	false	none	Lowest price (quote currency)
o	string	false	none	Open price (quote currency)
sum	string	false	none	Trading volume (unit: Quote currency)

# FuturesAccountBook

{
  "time": 0,
  "change": "string",
  "balance": "string",
  "type": "dnw",
  "text": "string",
  "contract": "string",
  "trade_id": "string",
  "id": "string"
}

# Properties

Name	Type	Required	Restrictions	Description
time	number(double)	false	none	Change time
change	string	false	none	Change amount
balance	string	false	none	Balance after change
type	string	false	none	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	false	none	Comment
contract	string	false	none	Futures contract, the field is only available for data after 2023-10-30
trade_id	string	false	none	trade id
id	string	false	none	Account change record ID

# Enumerated Values

Property	Value
type	dnw
type	pnl
type	fee
type	refr
type	fund
type	point_dnw
type	point_fee
type	point_refr
type	bonus_offset

# FuturesLeverage

{
  "Lever": "string"
}

Return result includes Lever field

# Properties

Name	Type	Required	Restrictions	Description
Lever	string	false	none	leverage

# MyFuturesTrade

{
  "id": 0,
  "create_time": 0,
  "contract": "string",
  "order_id": "string",
  "size": "string",
  "close_size": "string",
  "price": "string",
  "role": "taker",
  "text": "string",
  "fee": "string",
  "point_fee": "string",
  "trade_value": "string"
}

# Properties

Name	Type	Required	Restrictions	Description
id	integer(int64)	false	none	Fill ID
create_time	number(double)	false	none	Fill Time
contract	string	false	none	Futures contract
order_id	string	false	none	Related order ID
size	string	false	none	Trading size
close_size	string	false	none	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	false	none	Fill Price
role	string	false	none	Trade role. taker - taker, maker - maker
text	string	false	none	Order custom information
fee	string	false	none	Trade fee
point_fee	string	false	none	Points used to deduct trade fee
trade_value	string	false	none	trade value

# Enumerated Values

Property	Value
role	taker
role	maker

# FuturesTrade

{
  "id": 0,
  "create_time": 0,
  "create_time_ms": 0,
  "contract": "string",
  "size": "string",
  "price": "string",
  "is_internal": true
}

# Properties

Name	Type	Required	Restrictions	Description
id	integer(int64)	false	none	Fill ID
create_time	number(double)	false	none	Fill Time
create_time_ms	number(double)	false	none	Trade time, with millisecond precision to 3 decimal places
contract	string	false	none	Futures contract
size	string	false	none	Trading size
price	string	false	none	Trade price (quote currency)
is_internal	boolean	false	none	Deprecated

# FuturesOrder

{
  "id": 0,
  "user": 0,
  "create_time": 0,
  "update_time": 0,
  "finish_time": 0,
  "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"
}

Futures order details

# Properties

Name	Type	Required	Restrictions	Description
id	integer(int64)	false	read-only	Futures order ID
user	integer	false	read-only	User ID
create_time	number(double)	false	read-only	Creation time of order
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-` prefix 3. 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-traded 1. If the `stp_id` of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the `stp_act` of the taker. 2. `stp_id` returns `0` by default for orders that have not been set for `STP group`
stp_act	string	false	none	Self-Trading Prevention Action. Users can use this field to set self-trade 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

# Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
finish_as	stp
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok
auto_size	close_long
auto_size	close_short
stp_act	co
stp_act	cn
stp_act	cb
stp_act	-

# StopAllTrailOrders

{
  "contract": "string",
  "related_position": 1
}

StopAllTrailOrders

# Properties

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

# Enumerated Values

Property	Value
related_position	1
related_position	2

# FuturesLiqOrder

{
  "time": 0,
  "contract": "string",
  "size": "string",
  "order_size": "string",
  "order_price": "string",
  "fill_price": "string",
  "left": "string"
}

# Properties

Name	Type	Required	Restrictions	Description
time	integer(int64)	false	read-only	Liquidation time
contract	string	false	read-only	Futures contract
size	string	false	read-only	User position size
order_size	string	false	read-only	Number of forced liquidation orders
order_price	string	false	read-only	Liquidation order price
fill_price	string	false	read-only	Liquidation order average taker price
left	string	false	read-only	System liquidation order maker size

# TriggerOrderResponse

{
  "id": 0,
  "id_string": "string"
}

TriggerOrderResponse

# Properties

Name	Type	Required	Restrictions	Description
id	integer(int64)	false	none	Auto order ID
id_string	string	false	read-only	String form of the auto order ID; the same order as numeric `id`, as the decimal string of `id` to avoid int64 precision loss in JavaScript and similar environments. Prefer this field to display the order ID or when a string unique identifier is needed; one-to-one with `id`. Same meaning as the field of the same name in futures price-trigger REST APIs and in `futures.orders` / `futures.autoorders` WebSocket pushes.

# FuturesOrderTimerange

{
  "id": 0,
  "user": 0,
  "create_time": 0,
  "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"
}

Futures order details

# Properties

Name	Type	Required	Restrictions	Description
id	integer(int64)	false	read-only	Futures order ID
user	integer	false	read-only	User ID
create_time	number(double)	false	read-only	Creation time of order
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-` prefix 3. 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-traded 1. If the `stp_id` of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the `stp_act` of the taker. 2. `stp_id` returns `0` by default for orders that have not been set for `STP group`
stp_act	string	false	none	Self-Trading Prevention Action. Users can use this field to set self-trade 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

# Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
finish_as	position_closed
finish_as	reduce_out
finish_as	stp
status	open
status	finished
tif	gtc
tif	ioc
tif	poc
tif	fok
auto_size	close_long
auto_size	close_short
stp_act	co
stp_act	cn
stp_act	cb
stp_act	-

# FuturesOrderAmendment

{
  "size": "string",
  "price": "string",
  "amend_text": "string",
  "text": "string"
}

FuturesOrderAmendment

# Properties

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.

# CountdownCancelAllFuturesTask

{
  "timeout": 0,
  "contract": "string"
}

CountdownCancelAllFuturesTask

# Properties

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

# PositionTimerange

{
  "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)

# Properties

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

# FuturesLiquidate

{
  "time": 0,
  "contract": "string",
  "leverage": "string",
  "size": "string",
  "margin": "string",
  "entry_price": "string",
  "liq_price": "string",
  "mark_price": "string",
  "order_id": 0,
  "order_price": "string",
  "fill_price": "string",
  "left": "string"
}

# Properties

Name	Type	Required	Restrictions	Description
time	integer(int64)	false	read-only	Liquidation time
contract	string	false	read-only	Futures contract
leverage	string	false	read-only	Position leverage. Not returned in public endpoints
size	string	false	read-only	Position size
margin	string	false	read-only	Position margin. Not returned in public endpoints
entry_price	string	false	read-only	Average entry price. Not returned in public endpoints
liq_price	string	false	read-only	Liquidation price. Not returned in public endpoints
mark_price	string	false	read-only	Mark price. Not returned in public endpoints
order_id	integer(int64)	false	read-only	Liquidation order ID. Not returned in public endpoints
order_price	string	false	read-only	Liquidation order price
fill_price	string	false	read-only	Liquidation order average taker price
left	string	false	read-only	Liquidation order maker size

# FuturesAutoDeleverage

{
  "time": 0,
  "user": 0,
  "order_id": 0,
  "contract": "string",
  "leverage": "string",
  "cross_leverage_limit": "string",
  "entry_price": "string",
  "fill_price": "string",
  "trade_size": "string",
  "position_size": "string"
}

# Properties

Name	Type	Required	Restrictions	Description
time	integer(int64)	false	read-only	Automatic deleveraging time
user	integer(int64)	false	read-only	User ID
order_id	integer(int64)	false	read-only	Order ID. Order IDs before 2023-02-20 are null
contract	string	false	read-only	Futures contract
leverage	string	false	read-only	leverage for isolated margin. 0 means cross margin. For leverage of cross margin, please refer to `cross_leverage_limit`.
cross_leverage_limit	string	false	read-only	leverage for cross margin
entry_price	string	false	read-only	Average entry price
fill_price	string	false	read-only	Average fill price
trade_size	string	false	read-only	Trading size
position_size	string	false	read-only	Positions after auto-deleveraging

# FuturesUpdatePriceTriggeredOrder

{
  "settle": "string",
  "order_id": 0,
  "size": 0,
  "amount": "string",
  "price": "string",
  "trigger_price": "string",
  "price_type": 0,
  "auto_size": "string",
  "close": true
}

Modify Price Order Details

# Properties

Name	Type	Required	Restrictions	Description
settle	string	false	none	Settlement Currency (e.g., USDT, BTC)
order_id	integer(int64)	true	none	ID of the Pending Take-Profit/Stop-Loss Trigger Order
size	integer(int64)	false	none	Modified Contract Quantity. Full Close: 0; Partial Close: Positive/Negative values indicate direction (consistent with the creation interface logic).
amount	string	false	none	Same as `size`; used for decimal contract size. When both `size` and `amount` are provided, `amount` takes precedence.
price	string	false	none	Represents the modified trading price. A value of 0 indicates a market order.
trigger_price	string	false	none	Modified Trigger Price
price_type	integer(int32)	false	none	Reference price type. 0 - Latest trade price, 1 - Mark price, 2 - Index price
auto_size	string	false	none	One-way Mode: auto_size is not required Hedge Mode partial closing (size≠0): auto_size is not required Hedge Mode full closing (size=0): auto_size must be set, close_long for closing long positions, close_short for closing short positions
close	boolean	false	none	When fully closing a position in single-position mode, close must be set to true to execute the close operation. When partially closing a position in single-position mode or in dual-position mode, close can be left unset or set to false.

# Enumerated Values

Property	Value
price_type	0
price_type	1
price_type	2

# PositionClose

{
  "time": 0,
  "contract": "string",
  "side": "long",
  "pnl": "string",
  "pnl_pnl": "string",
  "pnl_fund": "string",
  "pnl_fee": "string",
  "text": "string",
  "max_size": "string",
  "accum_size": "string",
  "first_open_time": 0,
  "long_price": "string",
  "short_price": "string"
}

# Properties

Name	Type	Required	Restrictions	Description
time	number(double)	false	read-only	Position close time
contract	string	false	read-only	Futures contract
side	string	false	read-only	Position side - `long`: Long position - `short`: Short position
pnl	string	false	read-only	PnL
pnl_pnl	string	false	read-only	PNL - Position P/L
pnl_fund	string	false	read-only	PNL - Funding Fees
pnl_fee	string	false	read-only	PNL - Transaction Fees
text	string	false	read-only	Source of close order. See `order.text` field for specific values
max_size	string	false	read-only	Max Trade Size
accum_size	string	false	read-only	Cumulative closed position volume
first_open_time	integer(int64)	false	read-only	First Open Time
long_price	string	false	read-only	When side is 'long', it indicates the opening average price; when side is 'short', it indicates the closing average price
short_price	string	false	read-only	When side is 'long', it indicates the closing average price; when side is 'short', it indicates the opening average price

# Enumerated Values

Property	Value
side	long
side	short

# TrailOrderChangeLogResponse

{
  "change_log": [
    {
      "updated_at": 0,
      "amount": "string",
      "is_gte": true,
      "activation_price": "string",
      "price_type": 0,
      "price_offset": "string",
      "is_create": true
    }
  ]
}

TrailOrderChangeLogResponse

# Properties

Name	Type	Required	Restrictions	Description
change_log	[TrailChangeLog]	false	none	[Trail order modification records]

# FuturesFee

{
  "taker_fee": "string",
  "maker_fee": "string"
}

The returned result is a map type, where the key represents the market and taker and maker fee rates

# Properties

Name	Type	Required	Restrictions	Description
taker_fee	string	false	read-only	Taker fee
maker_fee	string	false	read-only	maker fee

# FuturesOrderBook

{
  "id": 0,
  "current": 0,
  "update": 0,
  "asks": [
    {
      "p": "string",
      "s": "string"
    }
  ],
  "bids": [
    {
      "p": "string",
      "s": "string"
    }
  ]
}

# Properties

Name	Type	Required	Restrictions	Description
id	integer(int64)	false	none	Order Book ID. Increases by 1 on every order book change. Set `with_id=true` to include this field in response
current	number(double)	false	none	Response data generation timestamp
update	number(double)	false	none	Order book changed timestamp
asks	array	true	none	Ask Depth
» FuturesOrderBookItem	object	false	none	none
»» p	string	false	none	Price (quote currency)
»» s	string	false	none	Size
» bids	array	true	none	Bid Depth
»» FuturesOrderBookItem	object	false	none	none
»»» p	string	false	none	Price (quote currency)
»»» s	string	false	none	Size

# FuturesAccount

{
  "total": "string",
  "unrealised_pnl": "string",
  "position_margin": "string",
  "order_margin": "string",
  "available": "string",
  "point": "string",
  "currency": "string",
  "in_dual_mode": true,
  "enable_credit": true,
  "position_initial_margin": "string",
  "maintenance_margin": "string",
  "bonus": "string",
  "enable_evolved_classic": true,
  "cross_order_margin": "string",
  "cross_initial_margin": "string",
  "cross_maintenance_margin": "string",
  "cross_unrealised_pnl": "string",
  "cross_available": "string",
  "cross_margin_balance": "string",
  "cross_mmr": "string",
  "cross_imr": "string",
  "isolated_position_margin": "string",
  "enable_new_dual_mode": true,
  "margin_mode": 0,
  "enable_tiered_mm": true,
  "enable_dual_plus": true,
  "position_mode": "string",
  "history": {
    "dnw": "string",
    "pnl": "string",
    "fee": "string",
    "refr": "string",
    "fund": "string",
    "point_dnw": "string",
    "point_fee": "string",
    "point_refr": "string",
    "bonus_dnw": "string",
    "bonus_offset": "string",
    "cross_settle": "string"
  }
}

# Properties

Name	Type	Required	Restrictions	Description
total	string	false	none	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	false	none	Unrealized PNL
position_margin	string	false	none	Deprecated
order_margin	string	false	none	initial margin of all open orders
available	string	false	none	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	false	none	Point card amount
currency	string	false	none	Settlement currency
in_dual_mode	boolean	false	none	Whether Hedge Mode is enabled
enable_credit	boolean	false	none	Whether portfolio margin account mode is enabled
position_initial_margin	string	false	none	Initial margin occupied by positions, applicable to unified account mode
maintenance_margin	string	false	none	Maintenance margin occupied by positions, applicable to new classic account margin mode and unified account mode
bonus	string	false	none	Bonus
enable_evolved_classic	boolean	false	none	Deprecated
cross_order_margin	string	false	none	Cross margin order margin, applicable to new classic account margin mode
cross_initial_margin	string	false	none	Cross margin initial margin, applicable to new classic account margin mode
cross_maintenance_margin	string	false	none	Cross margin maintenance margin, applicable to new classic account margin mode
cross_unrealised_pnl	string	false	none	Cross margin unrealized P&L, applicable to new classic account margin mode
cross_available	string	false	none	Cross margin available balance, applicable to new classic account margin mode
cross_margin_balance	string	false	none	Cross margin balance, applicable to new classic account margin mode
cross_mmr	string	false	none	Cross margin maintenance margin rate, applicable to new classic account margin mode
cross_imr	string	false	none	Cross margin initial margin rate, applicable to new classic account margin mode
isolated_position_margin	string	false	none	Isolated position margin, applicable to new classic account margin mode
enable_new_dual_mode	boolean	false	none	Deprecated
margin_mode	integer	false	none	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	false	none	Whether to enable tiered maintenance margin calculation
enable_dual_plus	boolean	false	none	Whether to Support Split Position Mode
position_mode	string	false	none	Position Holding Mode single - Single Direction Position, dual - Dual Direction Position, dual_plus - Split Position
history	object	false	none	Statistical data
» dnw	string	false	none	total amount of deposit and withdraw
» pnl	string	false	none	total amount of trading profit and loss
» fee	string	false	none	total amount of fee
» refr	string	false	none	total amount of referrer rebates
» fund	string	false	none	total amount of funding costs
» point_dnw	string	false	none	total amount of point deposit and withdraw
» point_fee	string	false	none	total amount of point fee
» point_refr	string	false	none	total amount of referrer rebates of point fee
» bonus_dnw	string	false	none	total amount of perpetual contract bonus transfer
» bonus_offset	string	false	none	total amount of perpetual contract bonus deduction
» cross_settle	string	false	none	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.

# FuturesTicker

{
  "contract": "string",
  "last": "string",
  "change_percentage": "string",
  "total_size": "string",
  "low_24h": "string",
  "high_24h": "string",
  "volume_24h": "string",
  "volume_24h_btc": "string",
  "volume_24h_usd": "string",
  "volume_24h_base": "string",
  "volume_24h_quote": "string",
  "volume_24h_settle": "string",
  "mark_price": "string",
  "funding_rate": "string",
  "funding_rate_indicative": "string",
  "index_price": "string",
  "quanto_base_rate": "string",
  "lowest_ask": "string",
  "lowest_size": "string",
  "highest_bid": "string",
  "highest_size": "string",
  "change_utc0": "string",
  "change_utc8": "string",
  "change_price": "string",
  "change_utc0_price": "string",
  "change_utc8_price": "string"
}

# Properties

Name	Type	Required	Restrictions	Description
contract	string	false	none	Futures contract
last	string	false	none	Last trading price
change_percentage	string	false	none	Price change percentage. Negative values indicate price decrease, e.g. -7.45
total_size	string	false	none	Contract total size
low_24h	string	false	none	24-hour lowest price
high_24h	string	false	none	24-hour highest price
volume_24h	string	false	none	24-hour trading volume
volume_24h_btc	string	false	none	24-hour trading volume in BTC (deprecated, use `volume_24h_base`, `volume_24h_quote`, `volume_24h_settle` instead)
volume_24h_usd	string	false	none	24-hour trading volume in USD (deprecated, use `volume_24h_base`, `volume_24h_quote`, `volume_24h_settle` instead)
volume_24h_base	string	false	none	24-hour trading volume in base currency
volume_24h_quote	string	false	none	24-hour trading volume in quote currency
volume_24h_settle	string	false	none	24-hour trading volume in settle currency
mark_price	string	false	none	Recent mark price
funding_rate	string	false	none	Funding rate
funding_rate_indicative	string	false	none	Indicative Funding rate in next period. (deprecated. use `funding_rate`)
index_price	string	false	none	Index price
quanto_base_rate	string	false	none	Deprecated
lowest_ask	string	false	none	Recent lowest ask
lowest_size	string	false	none	The latest seller's lowest price order quantity
highest_bid	string	false	none	Recent highest bid
highest_size	string	false	none	The latest buyer's highest price order volume
change_utc0	string	false	none	Percentage change at utc0. Negative values indicate a drop, e.g., -7.45%
change_utc8	string	false	none	Percentage change at utc8. Negative values indicate a drop, e.g., -7.45%
change_price	string	false	none	24h change amount. Negative values indicate a drop, e.g., -7.45
change_utc0_price	string	false	none	Change amount at utc0. Negative values indicate a drop, e.g., -7.45
change_utc8_price	string	false	none	Change amount at utc8. Negative values indicate a drop, e.g., -7.45

# ContractStat

{
  "time": 0,
  "lsr_taker": 0,
  "lsr_account": 0,
  "long_liq_size": "string",
  "long_liq_amount": 0,
  "long_liq_usd": 0,
  "short_liq_size": "string",
  "short_liq_amount": 0,
  "short_liq_usd": 0,
  "open_interest": "string",
  "open_interest_usd": 0,
  "top_lsr_account": 0,
  "top_lsr_size": "string",
  "mark_price": 0
}

# Properties

Name	Type	Required	Restrictions	Description
time	integer(int64)	false	none	Stat timestamp
lsr_taker	number(double)	false	none	Long/short taker ratio
lsr_account	number(double)	false	none	Long/short position user ratio
long_liq_size	string	false	none	Long liquidation size (contracts)
long_liq_amount	number(double)	false	none	Long liquidation amount (base currency)
long_liq_usd	number(double)	false	none	Long liquidation volume (quote currency)
short_liq_size	string	false	none	Short liquidation size (contracts)
short_liq_amount	number(double)	false	none	Short liquidation amount (base currency)
short_liq_usd	number(double)	false	none	Short liquidation volume (quote currency)
open_interest	string	false	none	Total open interest size (contracts)
open_interest_usd	number(double)	false	none	Total open interest volume (quote currency)
top_lsr_account	number(double)	false	none	Top trader long/short account ratio
top_lsr_size	string	false	none	Top trader long/short position ratio
mark_price	number(double)	false	none	Mark price

# InsuranceRecord

{
  "t": 0,
  "b": "string"
}

# Properties

Name	Type	Required	Restrictions	Description
t	integer(int64)	false	none	Unix timestamp in seconds
b	string	false	none	Insurance balance

# FuturesIndexConstituents

{
  "index": "string",
  "constituents": [
    {
      "exchange": "string",
      "symbols": []
    }
  ]
}

# Properties

Name	Type	Required	Restrictions	Description
index	string	false	read-only	Index name
constituents	array	false	read-only	Constituents
» IndexConstituent	object	false	none	none
»» exchange	string	false	none	Exchange
»» symbols	array	false	none	Symbol list

# FuturesLimitRiskTiers

{
  "tier": 0,
  "risk_limit": "string",
  "initial_rate": "string",
  "maintenance_rate": "string",
  "leverage_max": "string",
  "contract": "string",
  "deduction": "string"
}

Retrieve risk limit configurations for different tiers under a specified contract

# Properties

Name	Type	Required	Restrictions	Description
tier	integer(int)	false	none	Tier
risk_limit	string	false	none	Position risk limit
initial_rate	string	false	none	Initial margin rate
maintenance_rate	string	false	none	The maintenance margin rate of the first tier of risk limit sheet
leverage_max	string	false	none	Maximum leverage
contract	string	false	none	Market, only visible when market pagination is requested
deduction	string	false	none	Maintenance margin quick calculation deduction amount

# UpdateTrailOrder

{
  "id": 0,
  "amount": "string",
  "activation_price": "string",
  "is_gte_str": "string",
  "price_type": 0,
  "price_offset": "string"
}

UpdateTrailOrder

# Properties

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

# Enumerated Values

Property	Value
price_type	0
price_type	1
price_type	2
price_type	3

# BatchFundingRatesRequest

{
  "contracts": [
    "BTC_USDT",
    "ETH_USDT"
  ]
}

# Properties

Name	Type	Required	Restrictions	Description
contracts	array	true	none	Array of Contract Names

# Position

{
  "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

# Properties

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

# Enumerated Values

Property	Value
mode	single
mode	dual_long
mode	dual_short

# TrailChangeLog

{
  "updated_at": 0,
  "amount": "string",
  "is_gte": true,
  "activation_price": "string",
  "price_type": 0,
  "price_offset": "string",
  "is_create": true
}

Trail order modification records

# Properties

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

# Enumerated Values

Property	Value
price_type	0
price_type	1
price_type	2
price_type	3