Gate Perp DEX API v1.0.0

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

Gate Perp DEX API v1.0.0 provides comprehensive on-chain perpetual contract trading capabilities, including market detail queries, on-chain perpetual contract trading interfaces, and more. All transactions are executed on-chain through wallet signatures, providing a truly transparent, verifiable, and non-custodial contract trading experience.

• Public APIs: Query real-time market data such as contract information, order books, and market statistics
• Private APIs: Authenticated APIs supporting order management, position management, account queries, trading history, and more
• Price Triggered Orders: Support for creating price-triggered orders that automatically place orders when market prices meet specified conditions
• Risk Control: Provides risk limit tier queries, liquidation history queries, and other risk management features

With Gate Perp DEX API, you can implement automated trading strategies and programmatic trading based on APIs.

Access URL

REST API BaseURL:

• Live trading: https://api.gateperps.com/api/v1/

Technical Support

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

• Submit Work Order Feedback
• Online Work Order Feedback
• Send your contact information and questions to mm@gate.com We will assign technical specialists to serve you.

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

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

DANGER

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

Changelog

v1.0.0

• Added Gate Perp DEX API with complete REST and WebSocket endpoints
• On-chain perpetual contract trading operations
• Position management and risk control
• Market data query interfaces
• Account management and trading history

API

HTTP convention

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

Time

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

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

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

API Gateway in/out time

In every API request, the response header will always include the following fields:

• X-In-Time: The timestamp when the API gateway receives a request, in Unix timestamp format, measured in microseconds.

• X-Out-Time: The timestamp when the API gateway returns a response, in Unix timestamp format, measured in microseconds.

For example:

X-In-Time: 1695715091540163
X-Out-Time: 1695715091551905

Pagination

Pagination is achieved using one of the following method

• page-limit
• limit-offset

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

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

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

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

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

Using limit-offset method, send request parameters like:

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

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

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

Frequency limit rule

Rate Limit

Each request to the API response header will contain the following fields:：

• X-Gate-RateLimit-Requests-Remain - your remaining requests for current endpoint
• X-Gate-RateLimit-Limit - your current limit for current endpoint
• X-Gate-RateLimit-Reset-Timestamp - the timestamp indicating when your request limit resets if you have exceeded your rate_limit. Otherwise, this is just the current timestamp (it may not exactly match timeNow).

REST API Rate Limits:

Different endpoints have different rate limit rules. Specific rate limit information will be returned in response headers. It is recommended to control request frequency reasonably based on the rate limit information in response headers to avoid triggering rate limits.

WebSocket Rate Limits:

• Perp DEX: Bulk order/single order/single order modification/single order cancellation/bulk cancellation, a total of 100 requests per second (100r/s).
• Others: No limit.
• Number of connections per IP: ≤ 300

Trace ID

The API response will carry the header: X-Gate-Trace-ID . This header is used for tracking.

Self-Trade Prevention (STP)

WARNING

Important Notice: Self-Trade Prevention (STP) mechanism is not applicable in DEX scenarios. If the current on-chain perpetual system has not implemented STP functionality, it is recommended to remove all STP-related content from the documentation and API responses (including related fields such as stp_act, stp_id, finish_as=stp).

Concepts

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

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

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

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

STP Strategies

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

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

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

API Parameter Adjustment

Take placing Perp order as an example:

POST /dex_futures/usdt/orders

New request body parameter:

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

New response fields:

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

User case

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

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

T1: The STP strategy version released.

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

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

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

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

• If stp_act is co , the order placed by taker will be retained, the order status will be open, and the system will cancel the order of maker.

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

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

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

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

Error Handling

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

The error response body follows a format like:

{
  "label": "INVALID_PARAM_VALUE",
  "message": "Invalid parameter `text` with value: abc"
}

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

or with Python requests:

import json
import requests

try:
    response = requests.get('https://api.gateperps.com/api/v1/dex_futures/usdt/contracts/BTC_USDT')
    response.raise_for_status()
except requests.exceptions.HTTPError as e:
    detail = json.loads(e.response.text)
    if detail.get('label') == 'INVALID_PARAM_VALUE':
        print(f"Parameter error: {detail.get('message')}")

label list

• Request parameter or format related

label	Meaning
INVALID_PARAM_VALUE	Invalid parameter value
INVALID_PROTOCOL	Invalid parameter value
INVALID_ARGUMENT	Invalid argument
INVALID_REQUEST_BODY	Invalid request body
MISSING_REQUIRED_PARAM	Missing required parameter
BAD_REQUEST	Invalid request
INVALID_CONTENT_TYPE	Invalid Content-Type header
NOT_ACCEPTABLE	Invalid Accept- Header
METHOD_NOT_ALLOWED	Request method is not allowed
NOT_FOUND	Request URL not exists

• Authentication related

label	Meaning
INVALID_CREDENTIALS	Invalid credentials provided
INVALID_KEY	Invalid API Key
IP_FORBIDDEN	Request IP not in whitelist
READ_ONLY	API key is read-only
INVALID_SIGNATURE	Invalid signature
MISSING_REQUIRED_HEADER	Missing required authentication header
REQUEST_EXPIRED	Request Timestamp is far from the server time
ACCOUNT_LOCKED	Account is locked
FORBIDDEN	Account has no permission to request operation

• Perp related

label	Meaning
USER_NOT_FOUND	User has no Perp account
CONTRACT_NO_COUNTER	No counter order found
CONTRACT_NOT_FOUND	Contract not found
RISK_LIMIT_EXCEEDED	Risk limit exceeded
INSUFFICIENT_AVAILABLE	Balance is not enough
LIQUIDATE_IMMEDIATELY	Operation may cause liquidation
LEVERAGE_TOO_HIGH	leverage too high
LEVERAGE_TOO_LOW	leverage too low
ORDER_NOT_FOUND	Order not found
ORDER_NOT_OWNED	Order not owned
ORDER_FINISHED	Order already finished
TOO_MANY_ORDERS	Too many open orders
POSITION_CROSS_MARGIN	margin updating is not allowed in cross margin
POSITION_IN_LIQUIDATION	Position is being liquidated
POSITION_IN_CLOSE	Position is closing
POSITION_EMPTY	Position is empty
REMOVE_TOO_MUCH	Changed margin exceeds allowed
RISK_LIMIT_NOT_MULTIPLE	Risk limit is not a multiple of step
RISK_LIMIT_TOO_HIGH	Risk limit too high
RISK_LIMIT_TOO_lOW	Risk limit too low
PRICE_TOO_DEVIATED	Order price deviates too much from mark price
SIZE_TOO_LARGE	Order size exceeds maximum
SIZE_TOO_SMALL	Order size does not reach minimum
PRICE_OVER_LIQUIDATION	Price to increase position can not exceeds liquidation price
PRICE_OVER_BANKRUPT	Price to decrease position cannot exceeds bankrupting price
ORDER_POC_IMMEDIATE	POC order will be finished immediately
INCREASE_POSITION	POC order will increase position
CONTRACT_IN_DELISTING	Contract is delisting, only reduce-only order or close order is allowed
POSITION_NOT_FOUND	Position not found
POSITION_DUAL_MODE	Operation forbidden in dual-mode
ORDER_PENDING	Operation forbidden with pending orders
POSITION_HOLDING	Operation forbidden with holding position
REDUCE_EXCEEDED	Reduce order would exceed position in dual-mode
NO_CHANGE	No change is made
AMEND_WITH_STOP	Amend forbidden with stop order
ORDER_FOK	Killed for FOK

• Server errors

label	Meaning
INTERNAL	Internal server error
SERVER_ERROR	Internal server error
TOO_BUSY	Server is too busy at the moment

Authentication

Gate Perp DEX API Permissions

When creating a Gate Perp DEX API Key, you can configure whether to enable on-chain perpetual contract trading permissions for the Key. You can set the permissions to read-write or read-only.

Products	Permissions
Perp DEX Perpetual Contract	Read-only query orders, positions, account info, etc. Read-write query orders & place orders, manage positions, etc.

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

Important Notes:

• Gate Perp DEX API is an independent API system that requires a separate Gate Perp DEX API Key
• Gate Perp DEX API Key is independent from Gate.io spot, margin, delivery contract, and other product API Keys
• When using Gate Perp DEX API for trading, ensure the API Key has the corresponding read-write permissions
• Perp DEX API Key is used for server-side calls and authentication. All transactions require wallet signatures to complete on-chain execution
• To ensure the security of on-chain transaction calls, it is recommended to configure IP whitelist for the API Key
• Since on-chain operations depend on wallet signatures, please keep private keys and signature services secure

Gate Perp DEX API signed request requirements

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

API Signature string generation

In Gate Perp DEX API, signature string is concatenated as the following way:

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

Request Method

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

Request URL

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

Query String

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

HexEncode(SHA512(Request Payload))

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

Timestamp

Timestamp request header value.

Examples

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

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

1. List all orders

	GET /api/v1/dex_futures/orders?contract=BTC_USD&status=finished&limit=50 HTTP/1.1

Signature string：

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

Explanation：

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

Signature generated

55f84ea195d6fe57ce62464daaa7c3c02fa9d1dde954e4c898289c9a2407a3d6fb3faf24deff16790d726b66ac9f74526668b13bd01029199cc4fcc522418b8a

2. Create an order

	POST /api/v1/dex_futures/orders HTTP/1.1

	{"contract":"BTC_USD","type":"limit","size":100,"price":6800,"time_in_force":"gtc"}

Signature string：

	POST\n
	/api/v1/dex_futures/orders\n
	\n
	ad3c169203dc3026558f01b4df307641fa1fa361f086b2306658886d5708767b1854797c68d9e62fef2f991645aa82673622ebf417e091d0bd22bafe5d956cca\n
	1541993715

Explanation：

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

Signature generated

eae42da914a590ddf727473aff25fc87d50b64783941061f47a3fdb92742541fc4c2c14017581b4199a1418d54471c269c03a38d788d802e2c306c37636389f0

# example authentication implementation in Python

"""
Python SDK is recommended as it has already implemented the authentication process for every API:
"""

import time
import hashlib
import hmac
import requests
import json

def gen_sign(method, url, query_string=None, payload_string=None):
    key = ''        # api_key
    secret = ''     # api_secret

    t = time.time()
    m = hashlib.sha512()
    m.update((payload_string or "").encode('utf-8'))
    hashed_payload = m.hexdigest()
    s = '%s\n%s\n%s\n%s\n%s' % (method, url, query_string or "", hashed_payload, t)
    sign = hmac.new(secret.encode('utf-8'), s.encode('utf-8'), hashlib.sha512).hexdigest()
    return {'KEY': key, 'Timestamp': str(t), 'SIGN': sign}

if __name__ == "__main__":
    host = "https://api.gateperps.com"
    prefix = "/api/v1"
    common_headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

    url = '/dex_futures/orders'
    body = {"contract": "BTC_USD", "size": 100, "price": "30", "tif": "gtc"}
    request_content = json.dumps(body)
    sign_headers = gen_sign('POST', prefix + url, "", request_content)
    sign_headers.update(common_headers)
    print('signature headers: %s' % sign_headers)
    res = requests.post(host + prefix + url, headers=sign_headers, data=request_content)
    print(res.status_code)
    print(res.content)

Perp

Perpetual contracts

Query all Perp contracts

Code samples

# coding: utf-8
import requests

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

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

curl -X GET https://api.gateperps.com/api/v1/dex_futures/usdt/contracts \
  -H 'Accept: application/json'

GET /dex_futures/usdt/contracts

Query all Perp contracts

Parameters

Name	In	Type	Required	Description
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0

Example responses

200 Response

[
  {}
]

Responses

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

This operation does not require authentication

Query single contract information

Code samples

# coding: utf-8
import requests

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

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

curl -X GET https://api.gateperps.com/api/v1/dex_futures/usdt/contracts/BTC_USDT \
  -H 'Accept: application/json'

GET /dex_futures/usdt/contracts/{contract}

Query single contract information

Parameters

Name	In	Type	Required	Description
contract	path	string	true	Perp contract

Example responses

200 Response

{}

Responses

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

This operation does not require authentication

Query Perp market depth information

Code samples

# coding: utf-8
import requests

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com/api/v1/dex_futures/usdt/order_book?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /dex_futures/usdt/order_book

Query Perp market depth information

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

Parameters

Name	In	Type	Required	Description
contract	query	string	true	Perp contract
interval	query	string	false	Price precision for depth aggregation, 0 means no aggregation, defaults to 0 if not specified
limit	query	integer	false	Number of depth levels
with_id	query	boolean	false	Whether to return depth update ID. This ID increments by 1 each time depth changes

Example responses

200 Response

{}

Responses

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

Response Schema

Status Code 200

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

This operation does not require authentication

Perp market transaction records

Code samples

# coding: utf-8
import requests

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com/api/v1/dex_futures/usdt/trades?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /dex_futures/usdt/trades

Perp market transaction records

Parameters

Name	In	Type	Required	Description
contract	query	string	true	Perp contract
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0
last_id	query	string	false	Specify the starting point for this list based on a previously retrieved id
from	query	integer(int64)	false	Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items.
to	query	integer(int64)	false	Specify end time in Unix seconds, default to current time.

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.

Example responses

200 Response

[
  {}
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» id	integer(int64)	Fill ID
» create_time	number(double)	Fill Time
» create_time_ms	number(double)	Trade time, with millisecond precision to 3 decimal places
» contract	string	Perp contract
» size	integer(int64)	Trading size
» price	string	Trade price (quote currency)
» is_internal	boolean	Whether it is an internal trade. Internal trade refers to the takeover of liquidation orders by the insurance fund and ADL users. Since it is not a normal matching on the market depth, the trade price may deviate from the market, and it will not be recorded in the K-line. If it is not an internal trade, this field will not be returned

This operation does not require authentication

Perp market K-line chart

Code samples

# coding: utf-8
import requests

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com/api/v1/dex_futures/usdt/candlesticks?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /dex_futures/usdt/candlesticks

Perp 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
contract	query	string	true	Perp contract
from	query	integer(int64)	false	Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified
to	query	integer(int64)	false	Specify the end time of the K-line chart, defaults to current time if not specified, note that the time format is Unix timestamp with second precision
limit	query	integer	false	Maximum number of recent data points to return. limit conflicts with from and to. If either from or to is specified, request will be rejected.
interval	query	string	false	Interval time between data points. Note that 1w means natural week(Mon-Sun), while 7d means every 7d since unix 0. 30d represents a natural month, not 30 days
timezone	query	string	false	Time zone: all/utc0/utc8, default utc0

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

Example responses

200 Response

[
  {}
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» None	object	data point in every timestamp
»» t	number(double)	Unix timestamp in seconds
»» v	integer(int64)	size volume (contract size). Only returned if contract is not prefixed
»» c	string	Close price (quote currency)
»» h	string	Highest price (quote currency)
»» l	string	Lowest price (quote currency)
»» o	string	Open price (quote currency)
»» sum	string	Trading volume (unit: Quote currency)

This operation does not require authentication

Premium Index K-line chart

Code samples

# coding: utf-8
import requests

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com/api/v1/dex_futures/usdt/premium_index?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /dex_futures/usdt/premium_index

Premium Index K-line chart

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

Parameters

Name	In	Type	Required	Description
contract	query	string	true	Perp contract
from	query	integer(int64)	false	Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified
to	query	integer(int64)	false	Specify the end time of the K-line chart, defaults to current time if not specified, note that the time format is Unix timestamp with second precision
limit	query	integer	false	Maximum number of recent data points to return. limit conflicts with from and to. If either from or to is specified, request will be rejected.
interval	query	string	false	Time interval between data points

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

Example responses

200 Response

[
  {}
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» None	object	data point in every timestamp
»» t	number(double)	Unix timestamp in seconds
»» c	string	Close price
»» h	string	Highest price
»» l	string	Lowest price
»» o	string	Open price

This operation does not require authentication

Get all Perp trading statistics

Code samples

# coding: utf-8
import requests

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

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

curl -X GET https://api.gateperps.com/api/v1/dex_futures/usdt/tickers \
  -H 'Accept: application/json'

GET /dex_futures/usdt/tickers

Get all Perp trading statistics

Parameters

Name	In	Type	Required	Description
contract	query	string	false	Perp contract, return related data only if specified

Example responses

200 Response

[
  {}
]

Responses

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

Response Schema

Status Code 200

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

This operation does not require authentication

Perp market historical funding rate

Code samples

# coding: utf-8
import requests

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com/api/v1/dex_futures/usdt/funding_rate?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /dex_futures/usdt/funding_rate

Perp market historical funding rate

Parameters

Name	In	Type	Required	Description
contract	query	string	true	Perp contract
limit	query	integer	false	Maximum number of records returned in a single list
from	query	integer(int64)	false	Start timestamp
to	query	integer(int64)	false	Termination Timestamp

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

Example responses

200 Response

[
  {}
]

Responses

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

Response Schema

Status Code 200

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

This operation does not require authentication

Perp market insurance fund history

Code samples

# coding: utf-8
import requests

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

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

curl -X GET https://api.gateperps.com/api/v1/dex_futures/usdt/insurance \
  -H 'Accept: application/json'

GET /dex_futures/usdt/insurance

Perp market insurance fund history

Parameters

Name	In	Type	Required	Description
limit	query	integer	false	Maximum number of records returned in a single list

Example responses

200 Response

[
  {}
]

Responses

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

Response Schema

Status Code 200

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

This operation does not require authentication

Perp statistics

Code samples

# coding: utf-8
import requests

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com/api/v1/dex_futures/usdt/contract_stats?contract=BTC_USDT \
  -H 'Accept: application/json'

GET /dex_futures/usdt/contract_stats

Perp statistics

Parameters

Name	In	Type	Required	Description
contract	query	string	true	Perp contract
from	query	integer(int64)	false	Start timestamp
interval	query	string	false	none
limit	query	integer	false	none

Example responses

200 Response

[
  {}
]

Responses

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

Response Schema

Status Code 200

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

This operation does not require authentication

Query index constituents

Code samples

# coding: utf-8
import requests

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com/api/v1/dex_futures/usdt/index_constituents/BTC_USDT \
  -H 'Accept: application/json'

GET /dex_futures/usdt/index_constituents/{index}

Query index constituents

Parameters

Name	In	Type	Required	Description
index	path	string	true	Index name

Example responses

200 Response

{}

Responses

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

Response Schema

Status Code 200

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

This operation does not require authentication

Query liquidation order history

Code samples

# coding: utf-8
import requests

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

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

curl -X GET https://api.gateperps.com/api/v1/dex_futures/usdt/liq_orders \
  -H 'Accept: application/json'

GET /dex_futures/usdt/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
contract	query	string	false	Perp contract, return related data only if specified
from	query	integer(int64)	false	Start timestamp
to	query	integer(int64)	false	Termination Timestamp
limit	query	integer	false	Maximum number of records returned in a single list

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

Example responses

200 Response

[
  {}
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» time	integer(int64)	Liquidation time
» contract	string	Perp contract
» size	integer(int64)	User position size
» order_size	integer(int64)	Number of forced liquidation orders
» order_price	string	Liquidation order price
» fill_price	string	Liquidation order average taker price
» left	integer(int64)	System liquidation order maker size

This operation does not require authentication

Query risk limit tiers

Code samples

# coding: utf-8
import requests

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

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

curl -X GET https://api.gateperps.com/api/v1/dex_futures/usdt/risk_limit_tiers \
  -H 'Accept: application/json'

GET /dex_futures/usdt/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
contract	query	string	false	Perp 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

Example responses

200 Response

{}

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» None	object	Retrieve risk limit configurations for different tiers under a specified contract
»» tier	integer(int)	Tier
»» risk_limit	string	Position risk limit
»» initial_rate	string	Initial margin rate
»» maintenance_rate	string	Maintenance margin rate
»» leverage_max	string	Maximum leverage
»» contract	string	Market, only visible when market pagination is requested
»» deduction	string	Maintenance margin quick calculation deduction amount

This operation does not require authentication

Get Perp account

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="GET"
url="/dex_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 /dex_futures/usdt/accounts

Get Perp account

Parameters

Name	In	Type	Required	Description

Example responses

200 Response

{}

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» total	string	total is the balance after the user's accumulated on-chain asset changes and profit and loss (including realized profit and loss, fund, fee and referral rebate), excluding unrealized profit and loss. total = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund)
» unrealised_pnl	string	Unrealized PNL
» position_margin	string	Position margin
» order_margin	string	Order margin of unfinished orders
» available	string	Refers to the available on-chain transfer or trading amount
» currency	string	Settlement currency
» in_dual_mode	boolean	Whether dual mode is enabled
» position_mode	string	Position mode: single - one-way, dual - dual-side, split - sub-positions (in_dual_mode is deprecated)
» position_initial_margin	string	Initial margin occupied by positions
» maintenance_margin	string	Maintenance margin occupied by positions
» history	object	Statistical data
»» dnw	string	total amount of on-chain asset changes
»» 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

WARNING

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

Query Perp account change history

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="GET"
url="/dex_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 /dex_futures/usdt/account_book

Query Perp 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
contract	query	string	false	Perp contract, return related data only if specified
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0
from	query	integer(int64)	false	Start timestamp
to	query	integer(int64)	false	Termination Timestamp
type	query	string	false	Change types:

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: On-chain asset changes
• pnl: Profit and loss from position reduction
• fee: Trading fees
• refr: Referrer rebates
• fund: Funding fees

Example responses

200 Response

[
  {}
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» time	number(double)	Change time
» change	string	Change amount
» balance	string	Balance after change
» type	string	Change types: - dnw: On-chain asset changes - pnl: Profit and loss from position reduction - fee: Trading fees - refr: Referrer rebates - fund: Funding fees
» text	string	Comment
» contract	string	Perp 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

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.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="GET"
url="/dex_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 /dex_futures/usdt/positions

Get user position list

Parameters

Name	In	Type	Required	Description
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

Example responses

200 Response

[
  {}
]

Responses

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

WARNING

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

Get single position information

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="GET"
url="/dex_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 /dex_futures/usdt/positions/{contract}

Get single position information

Parameters

Name	In	Type	Required	Description
contract	path	string	true	Perp contract

Example responses

200 Response

{}

Responses

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

WARNING

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

Update position margin

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="POST"
url="/dex_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 /dex_futures/usdt/positions/{contract}/margin

Update position margin

Parameters

Name	In	Type	Required	Description
contract	path	string	true	Perp contract
change	query	string	true	Margin change amount, positive number increases, negative number decreases

Example responses

200 Response

{}

Responses

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

WARNING

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

Update position leverage

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="POST"
url="/dex_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 /dex_futures/usdt/positions/{contract}/leverage

Update position leverage

Parameters

Name	In	Type	Required	Description
contract	path	string	true	Perp contract
leverage	query	string	true	New position leverage
cross_leverage_limit	query	string	false	Cross margin leverage (valid only when leverage is 0)
pid	query	integer(int32)	false	Product ID

Example responses

200 Response

{}

Responses

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

WARNING

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

Switch Position Margin Mode

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="POST"
url="/dex_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 /dex_futures/usdt/positions/cross_mode

Switch Position Margin Mode

Body parameter

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

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» mode	body	string	true	Cross margin or isolated margin mode. ISOLATED - isolated margin mode, CROSS - cross margin mode
» contract	body	string	true	Perp market

Example responses

200 Response

{}

Responses

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

WARNING

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

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.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="POST"
url="/dex_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 /dex_futures/usdt/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
body	body	object	true	none
» mode	body	string	true	Cross margin or isolated margin mode. ISOLATED - isolated margin mode, CROSS - cross margin mode
» contract	body	string	true	Perp market

Example responses

200 Response

[
  {}
]

Responses

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

WARNING

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

Update position risk limit

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="POST"
url="/dex_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 /dex_futures/usdt/positions/{contract}/risk_limit

Update position risk limit

Parameters

Name	In	Type	Required	Description
contract	path	string	true	Perp contract
risk_limit	query	string	true	New risk limit value

Example responses

200 Response

{}

Responses

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

WARNING

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

Set position mode

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="POST"
url="/dex_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 /dex_futures/usdt/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
dual_mode	query	boolean	true	Whether to enable dual mode

Example responses

200 Response

{}

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» total	string	total is the balance after the user's accumulated on-chain asset changes and profit and loss (including realized profit and loss, fund, fee and referral rebate), excluding unrealized profit and loss. total = SUM(history_dnw, history_pnl, history_fee, history_refr, history_fund)
» unrealised_pnl	string	Unrealized PNL
» position_margin	string	Position margin
» order_margin	string	Order margin of unfinished orders
» available	string	Refers to the available on-chain transfer or trading amount
» currency	string	Settlement currency
» in_dual_mode	boolean	Whether dual mode is enabled
» position_mode	string	Position mode: single - one-way, dual - dual-side, split - sub-positions (in_dual_mode is deprecated)
» position_initial_margin	string	Initial margin occupied by positions
» maintenance_margin	string	Maintenance margin occupied by positions
» history	object	Statistical data
»» dnw	string	total amount of on-chain asset changes
»» 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

WARNING

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

Get position information in dual mode

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="GET"
url="/dex_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 /dex_futures/usdt/dual_comp/positions/{contract}

Get position information in dual mode

Parameters

Name	In	Type	Required	Description
contract	path	string	true	Perp contract

Example responses

200 Response

[
  {}
]

Responses

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

WARNING

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

Update position margin in dual mode

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="POST"
url="/dex_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 /dex_futures/usdt/dual_comp/positions/{contract}/margin

Update position margin in dual mode

Parameters

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

Example responses

200 Response

[
  {}
]

Responses

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

WARNING

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

Update position leverage in dual mode

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="POST"
url="/dex_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 /dex_futures/usdt/dual_comp/positions/{contract}/leverage

Update position leverage in dual mode

Parameters

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

Example responses

200 Response

[
  {}
]

Responses

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

WARNING

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

Update position risk limit in dual mode

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="POST"
url="/dex_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 /dex_futures/usdt/dual_comp/positions/{contract}/risk_limit

Update position risk limit in dual mode

Parameters

Name	In	Type	Required	Description
contract	path	string	true	Perp contract
risk_limit	query	string	true	New risk limit value

Example responses

200 Response

[
  {}
]

Responses

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

WARNING

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

Place Perp order

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_futures/usdt/orders'
query_param = ''
body='{}'
# 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.gateperps.com"
prefix="/api/v1/dex_futures"
method="POST"
url="/dex_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 -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /dex_futures/usdt/orders

Place Perp 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 cancellation, 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

{}

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	Perp contract
» size	body	integer(int64)	true	Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders.
» iceberg	body	integer(int64)	false	Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees.
» price	body	string	false	Order price. Price of 0 with tif set to ioc represents a market order.
» close	body	boolean	false	Set as true to close the position, with size set to 0
» reduce_only	body	boolean	false	Set as true to be reduce-only order
» tif	body	string	false	Time in force
» text	body	string	false	Custom order information. If not empty, must follow the rules below:
» auto_size	body	string	false	Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0
» stp_act	body	string	false	Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies
» limit_vip	body	integer(int64)	false	Counterparty user's VIP level for limit order fills. Current order will only match with orders whose VIP level is less than or equal to the specified level. Only 11~16 are supported; default is 0
» pid	body	integer(int64)	false	Position ID

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
• liq-xxx: Forced liquidation of positions
• hedge-liq-xxx: Forced liquidation of hedged positions, i.e., simultaneously closing long and short positions
• insurance: Insurance

» 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

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

Example responses

201 Response

{}

Responses

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

WARNING

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

Query futures order list

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="GET"
url="/dex_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 /dex_futures/usdt/orders

Query Perp 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 /dex_futures/usdt/orders_timerange.

Parameters

Name	In	Type	Required	Description
contract	query	string	false	Perp 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

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

Example responses

200 Response

[
  {}
]

Responses

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

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

Cancel all orders with 'open' status

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

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

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

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

DELETE /dex_futures/usdt/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	true	Perp 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

Example responses

200 Response

[
  {}
]

Responses

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

WARNING

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

Query Perp order list by time range

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="GET"
url="/dex_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 /dex_futures/usdt/orders_timerange

Query Perp order list by time range

Parameters

Name	In	Type	Required	Description
contract	query	string	false	Perp contract, return related data only if specified
from	query	integer(int64)	false	Start timestamp
to	query	integer(int64)	false	Termination Timestamp
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0

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

Example responses

200 Response

[
  {}
]

Responses

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

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

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_futures/usdt/batch_orders'
query_param = ''
body='[{}]'
# 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.gateperps.com"
prefix="/api/v1/dex_futures"
method="POST"
url="/dex_futures/usdt/batch_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 -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /dex_futures/usdt/batch_orders

Place batch Perp 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

[
  {}
]

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

Example responses

200 Response

[
  {}
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	[Perp order details]
» None	object	Perp 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)	Perp order 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	Perp contract
»» size	integer(int64)	Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders.
»» iceberg	integer(int64)	Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees.
»» price	string	Order price. Price of 0 with tif set to ioc represents a market order.
»» is_close	boolean	Is the order to close position
»» is_reduce_only	boolean	Is the order reduce-only
»» is_liq	boolean	Is the order for liquidation
»» tif	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none
»» left	integer(int64)	Unfilled quantity
»» fill_price	string	Fill price
»» text	string	User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- 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
»» 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

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.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="GET"
url="/dex_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 /dex_futures/usdt/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
order_id	path	string	true	Order ID returned, or user custom ID(i.e., text field).

Detailed descriptions

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

Example responses

200 Response

{}

Responses

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

WARNING

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

Cancel single order

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="DELETE"
url="/dex_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 /dex_futures/usdt/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
order_id	path	string	true	Order ID returned, or user custom ID(i.e., text field).

Detailed descriptions

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

Example responses

200 Response

{}

Responses

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

WARNING

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

Amend single order

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

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

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

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

PUT /dex_futures/usdt/orders/{order_id}

Amend single order

Body parameter

{
  "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	object	true	none
» size	body	integer(int64)	false	New order size, including filled part.
» price	body	string	false	New order price
» amend_text	body	string	false	Custom info during order amendment
» text	body	string	false	Internal users can modify information in the text field.
order_id	path	string	true	Order ID returned, or user custom ID(i.e., text field).

Detailed descriptions

» size: New order size, including filled part.

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

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

Example responses

200 Response

{}

Responses

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

WARNING

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

Query personal trading records

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="GET"
url="/dex_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 /dex_futures/usdt/my_trades

Query personal trading records

By default, only data within the past 6 months is supported. If you need to query data for a longer period, please use GET /dex_futures/usdt/my_trades_timerange.

Parameters

Name	In	Type	Required	Description
contract	query	string	false	Perp contract, return related data only if specified
order	query	integer(int64)	false	Perp 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

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 /dex_futures/usdt/my_trades_timerange'.

Example responses

200 Response

[
  {}
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» id	integer(int64)	Fill ID
» create_time	number(double)	Fill Time
» contract	string	Perp contract
» order_id	string	Related order ID
» size	integer(int64)	Trading size
» close_size	integer(int64)	Number of closed positions: close_size=0 && size＞0 Open long position close_size=0 && size＜0 Open short position close_size>0 && size>0 && size <= close_size Close short position close_size>0 && size>0 && size > close_size Close short position and open long position close_size<0 && size<0 && size >= close_size Close long position close_size<0 && size<0 && size < close_size Close long position and open short position
» price	string	Fill Price
» role	string	Trade role. taker - taker, maker - maker
» text	string	Order custom information
» fee	string	Trade fee

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.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="GET"
url="/dex_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 /dex_futures/usdt/my_trades_timerange

Query personal trading records by time range

Parameters

Name	In	Type	Required	Description
contract	query	string	false	Perp contract, return related data only if specified
from	query	integer(int64)	false	Start timestamp
to	query	integer(int64)	false	Termination Timestamp
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0
role	query	string	false	Query role, maker or taker

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

Example responses

200 Response

[
  {}
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» trade_id	string	Fill ID
» create_time	number(double)	Fill Time
» contract	string	Perp contract
» order_id	string	Related order ID
» size	integer(int64)	Trading size
» close_size	integer(int64)	Number of closed positions: close_size=0 && size＞0 Open long position close_size=0 && size＜0 Open short position close_size>0 && size>0 && size <= close_size Close short position close_size>0 && size>0 && size > close_size Close short position and open long position close_size<0 && size<0 && size >= close_size Close long position close_size<0 && size<0 && size < close_size Close long position and open short position
» price	string	Fill Price
» role	string	Trade role. taker - taker, maker - maker
» text	string	Order custom information
» fee	string	Trade fee

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.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="GET"
url="/dex_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 /dex_futures/usdt/position_close

Query position close history

Parameters

Name	In	Type	Required	Description
contract	query	string	false	Perp contract, return related data only if specified
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0
from	query	integer(int64)	false	Start timestamp
to	query	integer(int64)	false	Termination Timestamp
side	query	string	false	Query side. long or shot
pnl	query	string	false	Query profit or loss

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

Example responses

200 Response

[
  {}
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» time	number(double)	Position close time
» contract	string	Perp 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.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="GET"
url="/dex_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 /dex_futures/usdt/liquidates

Query liquidation history

Parameters

Name	In	Type	Required	Description
contract	query	string	false	Perp contract, return related data only if specified
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0
from	query	integer(int64)	false	Start timestamp
to	query	integer(int64)	false	Termination Timestamp
at	query	integer	false	Specify liquidation timestamp

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

Example responses

200 Response

[
  {}
]

Responses

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

Response Schema

Status Code 200

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

WARNING

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

Query ADL auto-deleveraging order information

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="GET"
url="/dex_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 /dex_futures/usdt/auto_deleverages

Query ADL auto-deleveraging order information

Parameters

Name	In	Type	Required	Description
contract	query	string	false	Perp contract, return related data only if specified
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0
from	query	integer(int64)	false	Start timestamp
to	query	integer(int64)	false	Termination Timestamp
at	query	integer	false	Specify auto-deleveraging timestamp

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

Example responses

200 Response

[
  {}
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» time	integer(int64)	Automatic deleveraging time
» order_id	integer(int64)	Order ID. Order IDs before 2023-02-20 are null
» contract	string	Perp contract
» leverage	string	Position leverage
» cross_leverage_limit	string	Cross margin leverage (valid only when leverage is 0)
» entry_price	string	Average entry price
» fill_price	string	Average fill price
» trade_size	integer(int64)	Trading size
» position_size	integer(int64)	Positions after auto-deleveraging

WARNING

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

Countdown cancel orders

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="POST"
url="/dex_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 /dex_futures/usdt/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	object	true	none
» timeout	body	integer(int32)	true	Countdown time in seconds
» contract	body	string	false	Perp contract

Detailed descriptions

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

Example responses

200 Response

{
  "triggerTime": "1660039145000"
}

Responses

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

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.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="GET"
url="/dex_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 /dex_futures/usdt/fee

Query futures market trading fee rates

Parameters

Name	In	Type	Required	Description
contract	query	string	false	Perp contract, return related data only if specified

Example responses

200 Response

{}

Responses

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

Response Schema

Status Code 200

FuturesFee

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

WARNING

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

Cancel batch orders by specified ID list

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com"
prefix="/api/v1/dex_futures"
method="POST"
url="/dex_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 /dex_futures/usdt/batch_cancel_orders

Cancel batch orders by specified ID list

Multiple different order IDs can be specified, maximum 20 records per 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	array[string]	true	none

Example responses

200 Response

[
  {
    "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
»» 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.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_futures/usdt/batch_amend_orders'
query_param = ''
body='[{}]'
# 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.gateperps.com"
prefix="/api/v1/dex_futures"
method="POST"
url="/dex_futures/usdt/batch_amend_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 -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /dex_futures/usdt/batch_amend_orders

Batch modify orders by specified IDs

Multiple different order IDs can be specified, maximum 10 orders per request

Body parameter

[
  {}
]

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

Example responses

200 Response

[
  {}
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	[Perp order details]
» None	object	Perp 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)	Perp order 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	Perp contract
»» size	integer(int64)	Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders.
»» iceberg	integer(int64)	Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees.
»» price	string	Order price. Price of 0 with tif set to ioc represents a market order.
»» is_close	boolean	Is the order to close position
»» is_reduce_only	boolean	Is the order reduce-only
»» is_liq	boolean	Is the order for liquidation
»» tif	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none
»» left	integer(int64)	Unfilled quantity
»» fill_price	string	Fill price
»» text	string	User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- 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
»» 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

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.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_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.gateperps.com/api/v1/dex_futures/usdt/risk_limit_table?table_id=CYBER_USDT_20241122 \
  -H 'Accept: application/json'

GET /dex_futures/usdt/risk_limit_table

Query risk limit table by table_id

Just pass table_id

Parameters

Name	In	Type	Required	Description
table_id	query	string	true	Risk limit table ID

Example responses

200 Response

{}

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» None	object	Information for each tier of the gradient risk limit table
»» tier	integer(int)	Tier
»» risk_limit	string	Position risk limit
»» initial_rate	string	Initial margin rate
»» maintenance_rate	string	Maintenance margin rate
»» leverage_max	string	Maximum leverage
»» deduction	string	Maintenance margin quick calculation deduction amount

This operation does not require authentication

Level-based BBO Contract Order Placement

Code samples

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

host = "https://api.gateperps.com"
prefix = "/api/v1/dex_futures"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/dex_futures/usdt/bbo_orders'
query_param = ''
body='{}'
# 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.gateperps.com"
prefix="/api/v1/dex_futures"
method="POST"
url="/dex_futures/usdt/bbo_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 -d "$body_param" -H "Content-Type: application/json" \
    -H "Timestamp: $timestamp" -H "KEY: $key" -H "SIGN: $sign"

POST /dex_futures/usdt/bbo_orders

Level-based BBO Contract Order Placement

Compared to the Perp trading order placement interface (dex_futures/usdt/orders), it adds the level and direction parameters.

Body parameter

{}

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	Perp contract
» size	body	integer(int64)	true	Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders.
» direction	body	string	true	Direction: 'sell' fetches the bid side, 'buy' fetches the ask side.
» iceberg	body	integer(int64)	false	Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees.
» level	body	integer(int64)	true	Level: maximum 20 levels
» close	body	boolean	false	Set as true to close the position, with size set to 0
» reduce_only	body	boolean	false	Set as true to be reduce-only order
» tif	body	string	false	Time in force
» text	body	string	false	Custom order information. If not empty, must follow the rules below:
» auto_size	body	string	false	Set side to close dual-mode position. close_long closes the long side; while close_short the short one. Note size also needs to be set to 0
» stp_act	body	string	false	Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies
» limit_vip	body	integer(int64)	false	Counterparty user's VIP level for limit order fills. Current order will only match with orders whose VIP level is less than or equal to the specified level. Only 11~16 are supported; default is 0
» pid	body	integer(int64)	false	Position ID

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
• liq-xxx: Forced liquidation of positions
• hedge-liq-xxx: Forced liquidation of hedged positions, i.e., simultaneously closing long and short positions
• insurance: Insurance

» 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

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

Example responses

201 Response

{}

Responses

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

WARNING

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

Schemas

Contract

{
  "name": "string",
  "type": "inverse",
  "quanto_multiplier": "string",
  "leverage_min": "string",
  "leverage_max": "string",
  "maintenance_rate": "string",
  "mark_type": "internal",
  "mark_price": "string",
  "index_price": "string",
  "last_price": "string",
  "maker_fee_rate": "string",
  "taker_fee_rate": "string",
  "order_price_round": "string",
  "mark_price_round": "string",
  "funding_rate": "string",
  "funding_interval": 0,
  "funding_next_apply": 0,
  "risk_limit_base": "string",
  "risk_limit_step": "string",
  "risk_limit_max": "string",
  "order_size_min": 0,
  "order_size_max": 0,
  "order_price_deviate": "string",
  "ref_discount_rate": "string",
  "ref_rebate_rate": "string",
  "orderbook_id": 0,
  "trade_id": 0,
  "trade_size": 0,
  "position_size": 0,
  "config_change_time": 0,
  "in_delisting": true,
  "orders_limit": 0,
  "create_time": 0,
  "funding_cap_ratio": "string",
  "status": "string",
  "launch_time": 0,
  "delisting_time": 0,
  "delisted_time": 0
}

Perp contract details

Properties

Name	Type	Required	Restrictions	Description
name	string	false	none	Perp contract
type	string	false	none	Contract type: inverse - inverse contract, direct - direct contract
quanto_multiplier	string	false	none	Multiplier used in converting from invoicing to settlement currency
leverage_min	string	false	none	Minimum leverage
leverage_max	string	false	none	Maximum leverage
maintenance_rate	string	false	none	Maintenance rate of margin
mark_type	string	false	none	Mark price type: internal - internal trading price, index - external index price
mark_price	string	false	none	Current mark price
index_price	string	false	none	Current index price
last_price	string	false	none	Last trading price
maker_fee_rate	string	false	none	Maker fee rate, negative values indicate rebates
taker_fee_rate	string	false	none	Taker fee rate
order_price_round	string	false	none	Minimum order price increment
mark_price_round	string	false	none	Minimum mark price increment
funding_rate	string	false	none	Current funding rate
funding_interval	integer	false	none	Funding application interval, unit in seconds
funding_next_apply	number(double)	false	none	Next funding time
risk_limit_base	string	false	none	Base risk limit (deprecated)
risk_limit_step	string	false	none	Risk limit adjustment step (deprecated)
risk_limit_max	string	false	none	Maximum risk limit allowed by the contract (deprecated). It is recommended to use /dex_futures/usdt/risk_limit_tiers to query risk limits
order_size_min	integer(int64)	false	none	Minimum order size allowed by the contract
order_size_max	integer(int64)	false	none	Maximum order size allowed by the contract
order_price_deviate	string	false	none	Maximum allowed deviation between order price and current mark price. The order price order_price must satisfy the following condition: abs(order_price - mark_price) <= mark_price * order_price_deviate
ref_discount_rate	string	false	none	Trading fee discount for referred users
ref_rebate_rate	string	false	none	Commission rate for referrers
orderbook_id	integer(int64)	false	none	Orderbook update ID
trade_id	integer(int64)	false	none	Current trade ID
trade_size	integer(int64)	false	none	Historical cumulative trading volume
position_size	integer(int64)	false	none	Current total long position size
config_change_time	number(double)	false	none	Last configuration update time
in_delisting	boolean	false	none	in_delisting=true and position_size>0 indicates the contract is in delisting transition period in_delisting=true and position_size=0 indicates the contract is delisted
orders_limit	integer	false	none	Maximum number of pending orders
create_time	number(double)	false	none	Created time of the contract
funding_cap_ratio	string	false	none	The factor for the maximum of the funding rate. Maximum of funding rate = (1/market maximum leverage - maintenance margin rate) * funding_cap_ratio
status	string	false	none	Contract status types include: prelaunch (pre-launch), trading (active), delisting (delisting), delisted (delisted), circuit_breaker (circuit breaker)
launch_time	integer(int64)	false	none	Contract expiry timestamp
delisting_time	integer(int64)	false	none	Timestamp when contract enters reduce-only state
delisted_time	integer(int64)	false	none	Contract delisting time

Enumerated Values

Property	Value
type	inverse
type	direct
mark_type	internal
mark_type	index

Position

{
  "contract": "string",
  "size": 0,
  "leverage": "string",
  "risk_limit": "string",
  "leverage_max": "string",
  "maintenance_rate": "string",
  "value": "string",
  "margin": "string",
  "entry_price": "string",
  "liq_price": "string",
  "mark_price": "string",
  "initial_margin": "string",
  "maintenance_margin": "string",
  "unrealised_pnl": "string",
  "realised_pnl": "string",
  "pnl_pnl": "string",
  "pnl_fund": "string",
  "pnl_fee": "string",
  "history_pnl": "string",
  "last_close_pnl": "string",
  "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
}

Perp position details

Properties

Name	Type	Required	Restrictions	Description
contract	string	false	read-only	Perp contract
size	integer(int64)	false	read-only	Position size
leverage	string	false	none	Position leverage. 0 means cross margin; positive number means isolated margin
risk_limit	string	false	none	Position risk limit
leverage_max	string	false	read-only	Maximum leverage under current risk limit
maintenance_rate	string	false	read-only	Maintenance rate under current risk limit
value	string	false	read-only	Position value calculated in settlement currency
margin	string	false	none	Position margin
entry_price	string	false	read-only	Entry price
liq_price	string	false	read-only	Liquidation price
mark_price	string	false	read-only	Current mark price
initial_margin	string	false	read-only	The initial margin occupied by the position
maintenance_margin	string	false	read-only	Maintenance margin required for the position
unrealised_pnl	string	false	read-only	Unrealized PNL
realised_pnl	string	false	read-only	Realized PnL
pnl_pnl	string	false	read-only	Realized PNL - Position P/L
pnl_fund	string	false	read-only	Realized PNL - Funding Fees
pnl_fee	string	false	read-only	Realized PNL - Transaction Fees
history_pnl	string	false	read-only	Total realized PnL from closed positions
last_close_pnl	string	false	read-only	PNL of last position close
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: Single position mode - dual_long: Long position in dual position mode - dual_short: Short position in dual position mode
cross_leverage_limit	string	false	none	Cross margin leverage (valid only when leverage is 0)
update_time	integer(int64)	false	read-only	Last update time
update_id	integer(int64)	false	read-only	Update ID. The value increments by 1 each time the position is updated
open_time	integer(int64)	false	none	First Open Time
risk_limit_table	string	false	read-only	Risk limit table ID
average_maintenance_rate	string	false	read-only	Average maintenance margin rate
pid	integer(int64)	false	read-only	Sub-account position ID

Enumerated Values

Property	Value
mode	single
mode	dual_long
mode	dual_short

FuturesOrder

{
  "id": 0,
  "create_time": 0,
  "update_time": 0,
  "finish_time": 0,
  "finish_as": "filled",
  "status": "open",
  "contract": "string",
  "size": 0,
  "iceberg": 0,
  "price": "string",
  "close": false,
  "is_close": true,
  "reduce_only": false,
  "is_reduce_only": true,
  "is_liq": true,
  "tif": "gtc",
  "left": 0,
  "fill_price": "string",
  "text": "string",
  "tkfr": "string",
  "mkfr": "string",
  "auto_size": "close_long",
  "stp_id": 0,
  "stp_act": "co",
  "amend_text": "string",
  "limit_vip": 0,
  "pid": 0
}

Futures order details

Properties

Name	Type	Required	Restrictions	Description
id	integer(int64)	false	read-only	Futures order ID
create_time	number(double)	false	read-only	Creation time of order
update_time	number(double)	false	read-only	OrderUpdateTime
finish_time	number(double)	false	read-only	Order finished time. Not returned if order is open
finish_as	string	false	read-only	How the order was finished: - filled: all filled - cancelled: manually cancelled - liquidated: cancelled because of liquidation - ioc: time in force is IOC, finish immediately - auto_deleveraged: finished by ADL - reduce_only: cancelled because of increasing position while reduce-only set - position_closed: cancelled because the position was closed - reduce_out: only reduce positions by excluding hard-to-fill orders - stp: cancelled because self trade prevention
status	string	false	read-only	Order status - open: Pending - finished: Completed
contract	string	true	none	Futures contract
size	integer(int64)	true	none	Required. Trading quantity. Positive for buy, negative for sell. Set to 0 for close position orders.
iceberg	integer(int64)	false	none	Display size for iceberg orders. 0 for non-iceberg orders. Note that hidden portions are charged taker fees.
price	string	false	none	Order price. Price of 0 with tif set to ioc represents a market order.
close	boolean	false	write-only	Set as true to close the position, with size set to 0
is_close	boolean	false	read-only	Is the order to close position
reduce_only	boolean	false	write-only	Set as true to be reduce-only order
is_reduce_only	boolean	false	read-only	Is the order reduce-only
is_liq	boolean	false	read-only	Is the order for liquidation
tif	string	false	none	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none
left	integer(int64)	false	read-only	Unfilled quantity
fill_price	string	false	read-only	Fill price
text	string	false	none	Custom order information. If not empty, must follow the rules below: 1. Prefixed with t- 2. No longer than 28 bytes without t- 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 - liq-xxx: Forced liquidation of positions - hedge-liq-xxx: Forced liquidation of hedged positions, i.e., simultaneously closing long and short positions - insurance: Insurance
tkfr	string	false	read-only	Taker fee
mkfr	string	false	read-only	Maker fee
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
limit_vip	integer(int64)	false	write-only	Counterparty user's VIP level for limit order fills. Current order will only match with orders whose VIP level is less than or equal to the specified level. Only 11~16 are supported; default is 0
pid	integer(int64)	false	write-only	Position ID

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	-

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",
  "auto_size": "close_long",
  "stp_id": 0,
  "stp_act": "co",
  "amend_text": "string",
  "limit_vip": 0,
  "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	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 - liq-xxx: Forced liquidation of positions - hedge-liq-xxx: Forced liquidation of hedged positions, i.e., simultaneously closing long and short positions - insurance: Insurance
tkfr	string	false	read-only	Taker fee
mkfr	string	false	read-only	Maker fee
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
limit_vip	integer(int64)	false	write-only	Counterparty user's VIP level for limit order fills. Current order will only match with orders whose VIP level is less than or equal to the specified level. Only 11~16 are supported; default is 0
pid	integer(int64)	false	write-only	Position ID

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	-

BatchAmendOrderReq

{
  "order_id": 0,
  "text": "string",
  "size": 0,
  "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	integer(int64)	false	none	New order size, including filled size. - If less than or equal to the filled quantity, the order will be cancelled. - The new order side must be identical to the original one. - Close order size cannot be modified. - For reduce-only orders, increasing the size may cancel other reduce-only orders. - If the price is not modified, decreasing the size will not affect the depth queue, while increasing the size will place it at the end of the current price level.
price	string	false	none	New order price
amend_text	string	false	none	Custom info during order amendment