Gate API v4 v4.9.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.

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

Base URLs:

• Real Trading: https://fx-api.gateio.ws/api/v4
• TestNet Trading: https://fx-api-testnet.gateio.ws/api/v4

Terms of service

Email: API support

Web: API support

License: Apache License 2.0

Available SDK:

• Python
• Java
• PHP
• Javascript
• Go

Changelog

v4.9.0

2019-12-17

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

v4.8.1

2019-11-27

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

v4.8.0

2019-11-07

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

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

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

v4.7.3

2019-07-18

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

v4.6.3

2019-06-11

• Add point information in Futures account and position

v4.6.2

2019-04-24

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

v4.6.1

2019-04-02

• Add high_24h, low_24h and funding_rate_indicative in futures ticker

v4.6.0

2019-03-21

SDK related only

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

v4.5.1

2019-03-11

• Fix missing URL parameter description

v4.5.0

2019-03-05

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

• Add Futures price triggered auto order API support. Refer to /futures/price_orders for details

v1.3.0

2019-02-13

Important update

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

v1.2.1

2019-02-13

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

v1.2.0

2019-01-17

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

v1.1.0

2019-01-08

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

v1.0.0

2018-12-30

• Initial release

Authentication

APIv4 uses standalone API keys management from APIv2. So before using APIv4, you need to log into the console to generate new API keys for APIv4.

Besides, APIv4 uses 2 API key pairs. One for Spot and margin trading, the other one for futures trading. Make sure you use the right API keys for different operations.

Comparing with APIv2

What is kept?

1. KEY, SIGN signature headers. KEY means API key, SIGN means signature calculated based on API key and secret.
2. How content of SIGN is calculated, i.e. HexEncode(HMAC_SHA512(secret, signature_string))

What is changed?

1. Improved signature_string generation method(see next section for details)
2. Added Timestamp headers to include time in signature

API Signature string generation

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

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

Request Method

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

Request URL

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

Query String

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

HexEncode(SHA512(Request Payload))

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

Timestamp

Request timestamp in Unix seconds, like 1541992193.

Request time should deviate no longer than 15 minutes from the server time, and must be the same with the Timestamp header content.

Examples

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

1. List all orders

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

Signature string：

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

Explanation：

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

1. Create an order

    POST /api/v4/futures/orders HTTP/1.1

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

Signature string：

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

Explanation：

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

# example authentication implementation in Python

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

import time
import hashlib
import hmac
import requests
import json

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

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

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

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

Futures

Futures trade

List all futures contracts

Code samples

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

# coding: utf-8
import requests

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

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

GET /futures/{settle}/contracts

List all futures contracts

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

[
  {
    "name": "BTC_USD",
    "type": "inverse",
    "quanto_multiplier": "0",
    "mark_type": "index",
    "last_price": "4123",
    "mark_price": "4121.41",
    "index_price": "4121.5",
    "funding_next_apply": 1546588800,
    "funding_rate": "0.000333",
    "funding_interval": 28800,
    "funding_offset": 0,
    "interest_rate": "0.001",
    "order_price_round": "0.5",
    "mark_price_round": "0.01",
    "leverage_min": "1",
    "leverage_max": "100",
    "maintenance_rate": "0.005",
    "risk_limit_base": "10",
    "risk_limit_step": "10",
    "risk_limit_max": "50",
    "maker_fee_rate": "-0.00025",
    "taker_fee_rate": "0.00075",
    "order_price_deviate": "1",
    "order_size_min": 1,
    "order_size_max": 1000000,
    "orders_limit": 50,
    "orderbook_id": 39635902,
    "trade_id": 6935987,
    "trade_size": 1992012909,
    "position_size": 4323221,
    "config_change_time": 1547540148
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	List retrieved	[Contract]

Get a single contract

Code samples

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

# coding: utf-8
import requests

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

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

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

Get a single contract

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

{
  "name": "BTC_USD",
  "type": "inverse",
  "quanto_multiplier": "0",
  "mark_type": "index",
  "last_price": "4123",
  "mark_price": "4121.41",
  "index_price": "4121.5",
  "funding_next_apply": 1546588800,
  "funding_rate": "0.000333",
  "funding_interval": 28800,
  "funding_offset": 0,
  "interest_rate": "0.001",
  "order_price_round": "0.5",
  "mark_price_round": "0.01",
  "leverage_min": "1",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "risk_limit_base": "10",
  "risk_limit_step": "10",
  "risk_limit_max": "50",
  "maker_fee_rate": "-0.00025",
  "taker_fee_rate": "0.00075",
  "order_price_deviate": "1",
  "order_size_min": 1,
  "order_size_max": 1000000,
  "orders_limit": 50,
  "orderbook_id": 39635902,
  "trade_id": 6935987,
  "trade_size": 1992012909,
  "position_size": 4323221,
  "config_change_time": 1547540148
}

Responses

Status	Meaning	Description	Schema
200	OK	Contract information	Contract

Futures order book

Code samples

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

# coding: utf-8
import requests

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

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

GET /futures/{settle}/order_book

Futures order book

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

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency
contract	query	string	true	Futures contract
interval	query	string	false	Order depth. 0 means no aggregation is applied. default to 0
limit	query	integer	false	Maximum number of order depth data in asks or bids

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
interval	0
interval	0.1
interval	0.01

Example responses

200 Response

{
  "asks": [
    {
      "p": "1.52",
      "s": 100
    },
    {
      "p": "1.53",
      "s": 40
    }
  ],
  "bids": [
    {
      "p": "1.17",
      "s": 150
    },
    {
      "p": "1.16",
      "s": 203
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Order book retrieved	Inline

Response Schema

Status Code 200

Name	Type	Description
» asks	array	Asks order depth
»» futures_order_book_item	object	none
»»» p	string	Price
»»» s	integer(int64)	Size
»» bids	array	Bids order depth
»»» futures_order_book_item	object	none
»»»» p	string	Price
»»»» s	integer(int64)	Size

Futures trading history

Code samples

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

# coding: utf-8
import requests

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

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

GET /futures/{settle}/trades

Futures trading history

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency
contract	query	string	true	Futures contract
limit	query	integer	false	Maximum number of record returned in one list
last_id	query	string	false	Specify list staring point using the id of last record in previous list-query results
from	query	number	false	Specify starting time in Unix seconds. If not specified, to and limit will be used to limit response items.
to	query	number	false	Specify end time in Unix seconds, default to current time

Detailed descriptions

last_id: Specify list staring point using the id of last record in previous list-query results

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

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
» id	integer(int64)	Trade ID
» create_time	number	Trading time
» contract	string	Futures contract
» size	integer(int64)	Trading size
» price	string	Trading price

Get futures candlesticks

Code samples

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

# coding: utf-8
import requests

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

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

GET /futures/{settle}/candlesticks

Get futures candlesticks

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

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

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency
contract	query	string	true	Futures contract
from	query	number	false	Start time of candlesticks, formatted in Unix timestamp in seconds.
to	query	number	false	End time of candlesticks, formatted in Unix timestamp in seconds. Default to current time
limit	query	integer	false	Maximum recent data points returned. limit is conflicted with from and to. If either from or to is specified, request will be rejected.
interval	query	string	false	Interval time between data points

Detailed descriptions

from: Start time of candlesticks, formatted in Unix timestamp in seconds. Default toto - 100 * interval if not specified

Enumerated Values

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

Example responses

200 Response

[
  {
    "t": 1539852480,
    "v": 97151,
    "c": "1.032",
    "h": "1.032",
    "l": "1.032",
    "o": "1.032"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	Successfully retrieved	[Inline]

Response Schema

Status Code 200

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

List futures tickers

Code samples

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

# coding: utf-8
import requests

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

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

GET /futures/{settle}/tickers

List futures tickers

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

[
  {
    "contract": "BTC_USD",
    "last": "6432",
    "low_24h": "6278",
    "high_24h": "6790",
    "change_percentage": "4.43",
    "total_size": "32323904",
    "volume_24h": "184040233284",
    "volume_24h_btc": "28613220",
    "volume_24h_usd": "184040233284",
    "volume_24h_base": "28613220",
    "volume_24h_quote": "184040233284",
    "volume_24h_settle": "28613220",
    "mark_price": "6534",
    "funding_rate": "0.0001",
    "funding_rate_indicative": "0.0001",
    "index_price": "6531"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	Successfully retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
» contract	string	Futures contract
» last	string	Last trading price
» change_percentage	string	Change percentage.
» total_size	string	Contract total size
» low_24h	string	Lowest trading price in recent 24h
» high_24h	string	Highest trading price in recent 24h
» volume_24h	string	Trade size in recent 24h
» volume_24h_btc	string	Trade volumes in recent 24h in BTC(deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead)
» volume_24h_usd	string	Trade volumes in recent 24h in USD(deprecated, use volume_24h_base, volume_24h_quote, volume_24h_settle instead)
» volume_24h_base	string	Trade volume in recent 24h, in base currency
» volume_24h_quote	string	Trade volume in recent 24h, in quote currency
» volume_24h_settle	string	Trade volume in recent 24h, in settle currency
» mark_price	string	Recent mark price
» funding_rate	string	Funding rate
» funding_rate_indicative	string	Indicative Funding rate in next period
» index_price	string	Index price
» quanto_base_rate	string	Exchange rate of base currency and settlement currency in Quanto contract. Not existed in contract of other types

Funding rate history

Code samples

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

# coding: utf-8
import requests

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

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

GET /futures/{settle}/funding_rate

Funding rate history

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency
contract	query	string	true	Futures contract
limit	query	integer	false	Maximum number of record returned in one list

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK	History retrieved	[Inline]

Response Schema

Status Code 200

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

Futures insurance balance history

Code samples

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

# coding: utf-8
import requests

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

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

GET /futures/{settle}/insurance

Futures insurance balance history

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency
limit	query	integer	false	Maximum number of record returned in one list

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

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

Responses

Status	Meaning	Description	Schema
200	OK	Successfully retrieved	[Inline]

Response Schema

Status Code 200

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

Query futures account

Code samples

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://fx-api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/btc/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"

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

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

url = '/futures/btc/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())

GET /futures/{settle}/accounts

Query futures account

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

{
  "total": "4.4516",
  "unrealised_pnl": "0",
  "available": "4.98",
  "order_margin": "0.1",
  "position_margin": "5.1",
  "point": "10000",
  "currency": "BTC"
}

Responses

Status	Meaning	Description	Schema
200	OK	List retrieved	Inline

Response Schema

Status Code 200

Name	Type	Description
» total	string	Total assets, total = position_margin + order_margin + available
» unrealised_pnl	string	Unrealized PNL
» position_margin	string	Position margin
» order_margin	string	Order margin of unfinished orders
» available	string	Available balance to transfer out or trade
» point	string	POINT amount
» currency	string	Settle currency

Query account book

Code samples

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://fx-api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/btc/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"

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

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

url = '/futures/btc/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())

GET /futures/{settle}/account_book

Query account book

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency
limit	query	integer	false	Maximum number of record returned in one list
from	query	integer	false	Start timestamp
to	query	integer	false	End timestamp
type	query	string	false	Changing Type:

Detailed descriptions

type: Changing Type: - dnw: Deposit & Withdraw - pnl: Profit & Loss by reducing position - fee: Trading fee - refr: Referrer rebate - fund: Funding - point_dnw: POINT Deposit & Withdraw - point_fee: POINT Trading fee - point_refr: POINT Referrer rebate

Enumerated Values

Parameter	Value
settle	btc
settle	usdt
type	dnw
type	pnl
type	fee
type	refr
type	fund
type	point_dnw
type	point_fee
type	point_refr

Example responses

200 Response

[
  {
    "time": 1547633726,
    "change": "0.000010152188",
    "balance": "4.59316525194",
    "text": "ETH_USD:6086261",
    "type": "fee"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
» time	number	Change time
» change	string	Change amount
» balance	string	Balance after change
» type	string	Changing Type: - dnw: Deposit & Withdraw - pnl: Profit & Loss by reducing position - fee: Trading fee - refr: Referrer rebate - fund: Funding - point_dnw: POINT Deposit & Withdraw - point_fee: POINT Trading fee - point_refr: POINT Referrer rebate
» text	string	Comment

Enumerated Values

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

List all positions of a user

Code samples

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://fx-api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/btc/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"

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

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

url = '/futures/btc/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())

GET /futures/{settle}/positions

List all positions of a user

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

[
  {
    "user": 10000,
    "contract": "BTC_USD",
    "size": -9440,
    "leverage": "0",
    "risk_limit": "100",
    "leverage_max": "100",
    "maintenance_rate": "0.005",
    "value": "2.497143098997",
    "margin": "4.431548146258",
    "entry_price": "3779.55",
    "liq_price": "99999999",
    "mark_price": "3780.32",
    "unrealised_pnl": "-0.000507486844",
    "realised_pnl": "0.045543982432",
    "history_pnl": "0",
    "last_close_pnl": "0",
    "realised_point": "0",
    "history_point": "0",
    "adl_ranking": 5,
    "pending_orders": 16,
    "close_order": {
      "id": 232323,
      "price": "3779",
      "is_liq": false
    }
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	List retrieved	[Position]

Get single position

Code samples

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://fx-api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/btc/positions/BTC_USD"
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"

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

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

url = '/futures/btc/positions/BTC_USD'
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())

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

Get single position

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

{
  "user": 10000,
  "contract": "BTC_USD",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Position information	Position

Update position margin

Code samples

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://fx-api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/btc/positions/BTC_USD/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"

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

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

url = '/futures/btc/positions/BTC_USD/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())

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

Update position margin

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency
contract	path	string	true	Futures contract
change	query	string	true	Margin change. Use positive number to increase margin, negative number otherwise.

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

{
  "user": 10000,
  "contract": "BTC_USD",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Position information	Position

Update position leverage

Code samples

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://fx-api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/btc/positions/BTC_USD/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"

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

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

url = '/futures/btc/positions/BTC_USD/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())

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

Update position leverage

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency
contract	path	string	true	Futures contract
leverage	query	string	true	New position leverage

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

{
  "user": 10000,
  "contract": "BTC_USD",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Position information	Position

Update position risk limit

Code samples

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

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

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

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

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

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

Update position risk limit

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency
contract	path	string	true	Futures contract
risk_limit	query	string	true	New position risk limit

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

{
  "user": 10000,
  "contract": "BTC_USD",
  "size": -9440,
  "leverage": "0",
  "risk_limit": "100",
  "leverage_max": "100",
  "maintenance_rate": "0.005",
  "value": "2.497143098997",
  "margin": "4.431548146258",
  "entry_price": "3779.55",
  "liq_price": "99999999",
  "mark_price": "3780.32",
  "unrealised_pnl": "-0.000507486844",
  "realised_pnl": "0.045543982432",
  "history_pnl": "0",
  "last_close_pnl": "0",
  "realised_point": "0",
  "history_point": "0",
  "adl_ranking": 5,
  "pending_orders": 16,
  "close_order": {
    "id": 232323,
    "price": "3779",
    "is_liq": false
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Position information	Position

Create a futures order

Code samples

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://fx-api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/btc/orders"
query_param=""
body_param='{"contract":"BTC_USD","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}'
timestamp=$(date +%s)
body_hash=$(printf $body_param | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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"

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

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

url = '/futures/btc/orders'
query_param = ''
body='{"contract":"BTC_USD","size":6024,"iceberg":0,"price":"3765","tif":"gtc","text":"t-my-custom-id"}'
# 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())

POST /futures/{settle}/orders

Create a futures order

Zero-fill order cannot be retrieved 60 seconds after cancellation

Body parameter

{
  "contract": "BTC_USD",
  "size": 6024,
  "iceberg": 0,
  "price": "3765",
  "tif": "gtc",
  "text": "t-my-custom-id"
}

Parameters

Name	In	Type	Required	Description
body	body	FuturesOrder	true	none
» contract	body	string	true	Futures contract
» size	body	integer(int64)	false	Order size. Specify positive number to make a bid, and negative number to ask
» iceberg	body	integer(int64)	false	Display size for iceberg order. 0 for non-iceberg. Note that you would pay the taker fee for the hidden size
» price	body	string	false	Order price. 0 for market order with tif set as ioc
» close	body	boolean	false	Set as true to close the position, with size set to 0
» reduce_only	body	boolean	false	Set as true to be reduce-only order
» tif	body	string	false	Time in force
» text	body	string	false	User defined information. If not empty, must follow the rules below:
settle	path	string	false	Settle currency

Detailed descriptions

» tif: Time in force

• gtc: GoodTillCancelled
• ioc: ImmediateOrCancelled, taker only
• poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee

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

1. prefixed with t-
2. no longer than 16 bytes without t- prefix
3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created:

• web: from web
• api: from API
• app: from mobile phones
• auto_deleveraging: from ADL
• liquidation: from liquidation
• insurance: from insurance

Enumerated Values

Parameter	Value
» tif	gtc
» tif	ioc
» tif	poc
settle	btc
settle	usdt

Example responses

201 Response

{
  "id": 15675394,
  "user": 100000,
  "contract": "BTC_USD",
  "create_time": 1546569968,
  "size": 6024,
  "iceberg": 0,
  "left": 6024,
  "price": "3765",
  "fill_price": "0",
  "mkfr": "-0.00025",
  "tkfr": "0.00075",
  "tif": "gtc",
  "refu": 0,
  "is_reduce_only": false,
  "is_close": false,
  "is_liq": false,
  "text": "t-my-custom-id",
  "status": "finished",
  "finish_time": 1514764900,
  "finish_as": "cancelled"
}

Responses

Status	Meaning	Description	Schema
201	Created	Order details	FuturesOrder

List futures orders

Code samples

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://fx-api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/btc/orders"
query_param="contract=BTC_USD&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"

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

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

url = '/futures/btc/orders'
query_param = 'contract=BTC_USD&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())

GET /futures/{settle}/orders

List futures orders

Zero-fill order cannot be retrieved 60 seconds after cancellation

Parameters

Name	In	Type	Required	Description
contract	query	string	true	Futures contract
status	query	string	true	List orders based on status
limit	query	integer	false	Maximum number of record returned in one list
last_id	query	string	false	Specify list staring point using the id of last record in previous list-query results
settle	path	string	false	Settle currency

Enumerated Values

Parameter	Value
status	open
status	finished
settle	btc
settle	usdt

Example responses

200 Response

[
  {
    "id": 15675394,
    "user": 100000,
    "contract": "BTC_USD",
    "create_time": 1546569968,
    "size": 6024,
    "iceberg": 0,
    "left": 6024,
    "price": "3765",
    "fill_price": "0",
    "mkfr": "-0.00025",
    "tkfr": "0.00075",
    "tif": "gtc",
    "refu": 0,
    "is_reduce_only": false,
    "is_close": false,
    "is_liq": false,
    "text": "t-my-custom-id",
    "status": "finished",
    "finish_time": 1514764900,
    "finish_as": "cancelled"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	List retrieved	[FuturesOrder]

Cancel all open orders matched

Code samples

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://fx-api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/btc/orders"
query_param="contract=BTC_USD"
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"

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

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

url = '/futures/btc/orders'
query_param = 'contract=BTC_USD'
# 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())

DELETE /futures/{settle}/orders

Cancel all open orders matched

Zero-fill order cannot be retrieved 60 seconds after cancellation

Parameters

Name	In	Type	Required	Description
contract	query	string	true	Futures contract
side	query	string	false	All bids or asks. Both included in not specified
settle	path	string	false	Settle currency

Enumerated Values

Parameter	Value
side	ask
side	bid
settle	btc
settle	usdt

Example responses

200 Response

[
  {
    "id": 15675394,
    "user": 100000,
    "contract": "BTC_USD",
    "create_time": 1546569968,
    "size": 6024,
    "iceberg": 0,
    "left": 6024,
    "price": "3765",
    "fill_price": "0",
    "mkfr": "-0.00025",
    "tkfr": "0.00075",
    "tif": "gtc",
    "refu": 0,
    "is_reduce_only": false,
    "is_close": false,
    "is_liq": false,
    "text": "t-my-custom-id",
    "status": "finished",
    "finish_time": 1514764900,
    "finish_as": "cancelled"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	All orders matched cancelled	[FuturesOrder]

Get a single order

Code samples

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://fx-api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/btc/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"

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

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

url = '/futures/btc/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())

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

Get a single order

Zero-fill order cannot be retrieved 60 seconds after cancellation

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency
order_id	path	string	true	ID returned on order successfully being created

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

{
  "id": 15675394,
  "user": 100000,
  "contract": "BTC_USD",
  "create_time": 1546569968,
  "size": 6024,
  "iceberg": 0,
  "left": 6024,
  "price": "3765",
  "fill_price": "0",
  "mkfr": "-0.00025",
  "tkfr": "0.00075",
  "tif": "gtc",
  "refu": 0,
  "is_reduce_only": false,
  "is_close": false,
  "is_liq": false,
  "text": "t-my-custom-id",
  "status": "finished",
  "finish_time": 1514764900,
  "finish_as": "cancelled"
}

Responses

Status	Meaning	Description	Schema
200	OK	Order details	FuturesOrder

Cancel a single order

Code samples

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://fx-api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/btc/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"

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

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

url = '/futures/btc/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())

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

Cancel a single order

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency
order_id	path	string	true	ID returned on order successfully being created

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

{
  "id": 15675394,
  "user": 100000,
  "contract": "BTC_USD",
  "create_time": 1546569968,
  "size": 6024,
  "iceberg": 0,
  "left": 6024,
  "price": "3765",
  "fill_price": "0",
  "mkfr": "-0.00025",
  "tkfr": "0.00075",
  "tif": "gtc",
  "refu": 0,
  "is_reduce_only": false,
  "is_close": false,
  "is_liq": false,
  "text": "t-my-custom-id",
  "status": "finished",
  "finish_time": 1514764900,
  "finish_as": "cancelled"
}

Responses

Status	Meaning	Description	Schema
200	OK	Order details	FuturesOrder

List personal trading history

Code samples

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://fx-api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/btc/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"

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

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

url = '/futures/btc/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())

GET /futures/{settle}/my_trades

List personal trading history

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency
contract	query	string	false	Futures contract, return related data only if specified
order	query	integer	false	Futures order ID, return related data only if specified
limit	query	integer	false	Maximum number of record returned in one list
last_id	query	string	false	Specify list staring point using the id of last record in previous list-query results

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

[
  {
    "id": 121234231,
    "create_time": 1514764800,
    "contract": "BTC_USD",
    "order_id": "21893289839",
    "size": 100,
    "price": "100.123",
    "role": "taker"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
» id	integer(int64)	Trade ID
» create_time	number	Trading time
» contract	string	Futures contract
» order_id	string	Order ID related
» size	integer(int64)	Trading size
» price	string	Trading price
» role	string	Trade role. Available values are taker and maker

Enumerated Values

Property	Value
role	taker
role	maker

List position close history

Code samples

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://fx-api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/btc/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"

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

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

url = '/futures/btc/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())

GET /futures/{settle}/position_close

List position close history

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency
contract	query	string	false	Futures contract, return related data only if specified
limit	query	integer	false	Maximum number of record returned in one list

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

[
  {
    "time": 1546487347,
    "pnl": "0.00013",
    "side": "long",
    "contract": "BTC_USD",
    "text": "web"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	List retrieved	[Inline]

Response Schema

Status Code 200

Name	Type	Description
» time	number	Position close time
» contract	string	Futures contract
» side	string	Position side, long or short
» pnl	string	PNL
» text	string	Text of close order

Enumerated Values

Property	Value
side	long
side	short

List liquidation history

Code samples

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://fx-api.gateio.ws"
prefix="/api/v4"
method="GET"
url="/futures/btc/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"

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

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

url = '/futures/btc/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())

GET /futures/{settle}/liquidates

List liquidation history

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency
contract	query	string	false	Futures contract, return related data only if specified
limit	query	integer	false	Maximum number of record returned in one list
at	query	integer	false	Specify a liquidation timestamp

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

[
  {
    "time": 1548654951,
    "contract": "BTC_USD",
    "size": 600,
    "leverage": "25",
    "margin": "0.006705256878",
    "entry_price": "3536.123",
    "liq_price": "3421.54",
    "mark_price": "3420.27",
    "order_id": 317393847,
    "order_price": "3405",
    "fill_price": "3424",
    "left": 0
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	List retrieved	[Inline]

Response Schema

Status Code 200

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

Create a price-triggered order

Code samples

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://fx-api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/futures/btc/price_orders"
query_param=""
body_param='{"initial":{"contract":"BTC_USD","size":100,"price":"5.03","close":false,"tif":"gtc","text":"web"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400}}'
timestamp=$(date +%s)
body_hash=$(printf $body_param | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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"

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

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

url = '/futures/btc/price_orders'
query_param = ''
body='{"initial":{"contract":"BTC_USD","size":100,"price":"5.03","close":false,"tif":"gtc","text":"web"},"trigger":{"strategy_type":0,"price_type":0,"price":"3000","rule":1,"expiration":86400}}'
# 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())

POST /futures/{settle}/price_orders

Create a price-triggered order

Body parameter

{
  "initial": {
    "contract": "BTC_USD",
    "size": 100,
    "price": "5.03",
    "close": false,
    "tif": "gtc",
    "text": "web"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  }
}

Parameters

Name	In	Type	Required	Description
body	body	FuturesPriceTriggeredOrder	true	none
» initial	body	object	true	none
»» contract	body	string	true	Futures contract
»» size	body	integer(int64)	false	Order size. Positive size means to buy, while negative one means to sell. Set to 0 to close the position
»» price	body	string	true	Order price. Set to 0 to use market price
»» close	body	boolean	false	Set to true if trying to close the position
»» tif	body	string	false	Time in force. If using market price, only ioc is supported.
»» text	body	string	false	How the order is created. Possible values are: web, api and app
»» reduce_only	body	boolean	false	Set to true to create an reduce-only order
» trigger	body	object	true	none
»» strategy_type	body	integer	false	How the order will be triggered
»» price_type	body	integer	false	Price type. 0 - latest deal price, 1 - mark price, 2 - index price
»» price	body	string	false	Value of price on price triggered, or price gap on price gap triggered
»» rule	body	integer	false	Trigger condition type
»» expiration	body	integer	false	How many seconds will the order wait for the condition being triggered. Order will be cancelled on timed out
settle	path	string	false	Settle currency

Detailed descriptions

»» tif: Time in force. If using market price, only ioc is supported.

• gtc: GoodTillCancelled
• ioc: ImmediateOrCancelled

»» strategy_type: How the order will be triggered

• 0: by price, which means order will be triggered on price condition satisfied
• 1: by price gap, which means order will be triggered on gap of recent two prices of specified price_type satisfied. Only 0 is supported currently

»» rule: Trigger condition type

• 1: calculated price based on strategy_type and price_type >= price
• 2: calculated price based on strategy_type and price_type <= price

Enumerated Values

Parameter	Value
»» tif	gtc
»» tif	ioc
»» text	web
»» text	api
»» text	app
»» strategy_type	0
»» strategy_type	1
»» price_type	0
»» price_type	1
»» price_type	2
»» rule	1
»» rule	2
settle	btc
settle	usdt

Example responses

201 Response

{
  "id": 1432329
}

Responses

Status	Meaning	Description	Schema
201	Created	Order created	Inline

Response Schema

Status Code 201

TriggerOrderResponse

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

List all auto orders

Code samples

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

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

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

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

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

GET /futures/{settle}/price_orders

List all auto orders

Parameters

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

Enumerated Values

Parameter	Value
status	open
status	finished
settle	btc
settle	usdt

Example responses

200 Response

[
  {
    "initial": {
      "contract": "BTC_USD",
      "size": 100,
      "price": "5.03",
      "tif": "gtc",
      "text": "web"
    },
    "trigger": {
      "strategy_type": 0,
      "price_type": 0,
      "price": "3000",
      "rule": 1,
      "expiration": 86400
    },
    "id": 1283293,
    "user": 1234,
    "create_time": 1514764800,
    "finish_time": 1514764900,
    "trade_id": 13566,
    "status": "finished",
    "finish_as": "cancelled",
    "reason": ""
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	List retrieved	[FuturesPriceTriggeredOrder]

Cancel all open orders

Code samples

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://fx-api.gateio.ws"
prefix="/api/v4"
method="DELETE"
url="/futures/btc/price_orders"
query_param="contract=BTC_USD"
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"

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

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

url = '/futures/btc/price_orders'
query_param = 'contract=BTC_USD'
# 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())

DELETE /futures/{settle}/price_orders

Cancel all open orders

Parameters

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

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

[
  {
    "initial": {
      "contract": "BTC_USD",
      "size": 100,
      "price": "5.03",
      "tif": "gtc",
      "text": "web"
    },
    "trigger": {
      "strategy_type": 0,
      "price_type": 0,
      "price": "3000",
      "rule": 1,
      "expiration": 86400
    },
    "id": 1283293,
    "user": 1234,
    "create_time": 1514764800,
    "finish_time": 1514764900,
    "trade_id": 13566,
    "status": "finished",
    "finish_as": "cancelled",
    "reason": ""
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	Batch cancellation request accepted. Query order status by listing orders	[FuturesPriceTriggeredOrder]

Get a single order

Code samples

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

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

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

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

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

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

Get a single order

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency
order_id	path	string	true	ID returned on order successfully being created

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

{
  "initial": {
    "contract": "BTC_USD",
    "size": 100,
    "price": "5.03",
    "tif": "gtc",
    "text": "web"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  },
  "id": 1283293,
  "user": 1234,
  "create_time": 1514764800,
  "finish_time": 1514764900,
  "trade_id": 13566,
  "status": "finished",
  "finish_as": "cancelled",
  "reason": ""
}

Responses

Status	Meaning	Description	Schema
200	OK	Auto order detail	FuturesPriceTriggeredOrder

Cancel a single order

Code samples

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

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

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

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

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

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

Cancel a single order

Parameters

Name	In	Type	Required	Description
settle	path	string	false	Settle currency
order_id	path	string	true	ID returned on order successfully being created

Enumerated Values

Parameter	Value
settle	btc
settle	usdt

Example responses

200 Response

{
  "initial": {
    "contract": "BTC_USD",
    "size": 100,
    "price": "5.03",
    "tif": "gtc",
    "text": "web"
  },
  "trigger": {
    "strategy_type": 0,
    "price_type": 0,
    "price": "3000",
    "rule": 1,
    "expiration": 86400
  },
  "id": 1283293,
  "user": 1234,
  "create_time": 1514764800,
  "finish_time": 1514764900,
  "trade_id": 13566,
  "status": "finished",
  "finish_as": "cancelled",
  "reason": ""
}

Responses

Status	Meaning	Description	Schema
200	OK	Auto order detail	FuturesPriceTriggeredOrder

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",
  "orderbook_id": 0,
  "trade_id": 0,
  "trade_size": 0,
  "position_size": 0,
  "config_change_time": 0
}

Futures contract details

Properties

Name	Type	Required	Restrictions	Description
name	string	false	none	Futures contract name
type	string	false	none	Futures contract type
quanto_multiplier	string	false	none	Multiplier used in converting from invoicing to settlement currency in quanto futures
leverage_min	string	false	none	Minimum leverage
leverage_max	string	false	none	Maximum leverage
maintenance_rate	string	false	none	Maintenance rate of margin
mark_type	string	false	none	Mark price type, internal - based on internal trading, index - based on external index price
mark_price	string	false	none	Current mark price
index_price	string	false	none	Current index price
last_price	string	false	none	Last trading price
maker_fee_rate	string	false	none	Maker fee rate, where negative means rebate
taker_fee_rate	string	false	none	Taker fee rate
order_price_round	string	false	none	Minimum order price increment
mark_price_round	string	false	none	Minimum mark price increment
funding_rate	string	false	none	Current funding rate
funding_interval	integer	false	none	Funding application interval, unit in seconds
funding_next_apply	number	false	none	Next funding time
risk_limit_base	string	false	none	Risk limit base
risk_limit_step	string	false	none	Step of adjusting risk limit
risk_limit_max	string	false	none	Maximum risk limit the contract allowed
order_size_min	integer(int64)	false	none	Minimum order size the contract allowed
order_size_max	integer(int64)	false	none	Maximum order size the contract allowed
order_price_deviate	string	false	none	deviation between order price and current index price. If price of an order is denoted as order_price, it must meet the following condition: abs(order_price - mark_price) <= mark_price * order_price_deviate
orderbook_id	integer(int64)	false	none	Current orderbook ID
trade_id	integer(int64)	false	none	Current trade ID
trade_size	integer(int64)	false	none	Historical accumulation trade size
position_size	integer(int64)	false	none	Current total long position size
config_change_time	number	false	none	Configuration's last changed time

Enumerated Values

Property	Value
type	inverse
type	direct
mark_type	internal
mark_type	index

Position

{
  "user": 0,
  "contract": "string",
  "size": 0,
  "leverage": "string",
  "risk_limit": "string",
  "leverage_max": "string",
  "maintenance_rate": "string",
  "value": "string",
  "margin": "string",
  "entry_price": "string",
  "liq_price": "string",
  "mark_price": "string",
  "unrealised_pnl": "string",
  "realised_pnl": "string",
  "history_pnl": "string",
  "last_close_pnl": "string",
  "realised_point": "string",
  "history_point": "string",
  "adl_ranking": 0,
  "pending_orders": 0,
  "close_order": {
    "id": 0,
    "price": "string",
    "is_liq": true
  }
}

Futures position details

Properties

Name	Type	Required	Restrictions	Description
user	integer(int64)	false	read-only	User ID
contract	string	false	read-only	Futures contract
size	integer(int64)	false	read-only	Position size
leverage	string	false	none	Position leverage. 0 means cross margin; positive number means isolated margin
risk_limit	string	false	none	Position risk limit
leverage_max	string	false	read-only	Maximum leverage under current risk limit
maintenance_rate	string	false	read-only	Maintenance rate under current risk limit
value	string	false	read-only	Position value calculated in settlement currency
margin	string	false	none	Position margin
entry_price	string	false	read-only	Entry price
liq_price	string	false	read-only	Liquidation price
mark_price	string	false	read-only	Current mark price
unrealised_pnl	string	false	read-only	Unrealized PNL
realised_pnl	string	false	read-only	Realized PNL
history_pnl	string	false	read-only	History realized PNL
last_close_pnl	string	false	read-only	PNL of last position close
realised_point	string	false	read-only	Realized POINT PNL
history_point	string	false	read-only	History realized POINT PNL
adl_ranking	integer	false	read-only	ADL ranking, range from 1 to 5
pending_orders	integer	false	read-only	Current open orders
close_order	object	false	read-only	Current close order if any, or null
» id	integer(int64)	false	none	Close order ID
» price	string	false	none	Close order price
» is_liq	boolean	false	none	Is the close order from liquidation

FuturesOrder

{
  "id": 0,
  "user": 0,
  "create_time": 0,
  "finish_time": 0,
  "finish_as": "filled",
  "status": "open",
  "contract": "string",
  "size": 0,
  "iceberg": 0,
  "price": "string",
  "close": false,
  "is_close": true,
  "reduce_only": false,
  "is_reduce_only": true,
  "is_liq": true,
  "tif": "gtc",
  "left": 0,
  "fill_price": "string",
  "text": "string",
  "tkfr": "string",
  "mkfr": "string",
  "refu": 0
}

Futures order details

Properties

Name	Type	Required	Restrictions	Description
id	integer(int64)	false	read-only	Futures order ID
user	integer	false	read-only	User ID
create_time	number	false	read-only	Order creation time
finish_time	number	false	read-only	Order finished time. Not returned if order is open
finish_as	string	false	read-only	How the order is 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
status	string	false	read-only	Order status - open: waiting to be traded - finished: finished
contract	string	true	none	Futures contract
size	integer(int64)	false	none	Order size. Specify positive number to make a bid, and negative number to ask
iceberg	integer(int64)	false	none	Display size for iceberg order. 0 for non-iceberg. Note that you would pay the taker fee for the hidden size
price	string	false	none	Order price. 0 for market order with tif set as ioc
close	boolean	false	write-only	Set as true to close the position, with size set to 0
is_close	boolean	false	read-only	Is the order to close position
reduce_only	boolean	false	write-only	Set as true to be reduce-only order
is_reduce_only	boolean	false	read-only	Is the order reduce-only
is_liq	boolean	false	read-only	Is the order for liquidation
tif	string	false	none	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee
left	integer(int64)	false	read-only	Size left to be traded
fill_price	string	false	read-only	Fill price of the order
text	string	false	none	User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 16 bytes without t- prefix 3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - web: from web - api: from API - app: from mobile phones - auto_deleveraging: from ADL - liquidation: from liquidation - insurance: from insurance
tkfr	string	false	read-only	Taker fee
mkfr	string	false	read-only	Maker fee
refu	integer	false	read-only	Reference user ID

Enumerated Values

Property	Value
finish_as	filled
finish_as	cancelled
finish_as	liquidated
finish_as	ioc
finish_as	auto_deleveraged
finish_as	reduce_only
status	open
status	finished
tif	gtc
tif	ioc
tif	poc

FuturesPriceTriggeredOrder

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

Futures order details

Properties

Name	Type	Required	Restrictions	Description
initial	object	true	none	none
» contract	string	true	none	Futures contract
» size	integer(int64)	false	none	Order size. Positive size means to buy, while negative one means to sell. Set to 0 to close the position
» price	string	true	none	Order price. Set to 0 to use market price
» close	boolean	false	write-only	Set to true if trying to close the position
» tif	string	false	none	Time in force. If using market price, only ioc is supported. - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled
» text	string	false	none	How the order is created. Possible values are: web, api and app
» reduce_only	boolean	false	none	Set to true to create an reduce-only order
» is_reduce_only	boolean	false	read-only	Is the order reduce-only
» is_close	boolean	false	read-only	Is the order to close position
trigger	object	true	none	none
» strategy_type	integer	false	none	How the order will be triggered - 0: by price, which means order will be triggered on price condition satisfied - 1: by price gap, which means order will be triggered on gap of recent two prices of specified price_type satisfied. Only 0 is supported currently
» price_type	integer	false	none	Price type. 0 - latest deal price, 1 - mark price, 2 - index price
» price	string	false	none	Value of price on price triggered, or price gap on price gap triggered
» rule	integer	false	none	Trigger condition type - 1: calculated price based on strategy_type and price_type >= price - 2: calculated price based on strategy_type and price_type <= price
» expiration	integer	false	none	How many seconds will the order wait for the condition being triggered. Order will be cancelled on timed out
id	integer(int64)	false	read-only	Auto order ID
user	integer	false	read-only	User ID
create_time	number	false	read-only	Creation time
finish_time	number	false	read-only	Finished time
trade_id	integer(int64)	false	read-only	ID of the newly created order on condition triggered
status	string	false	read-only	Order status.
finish_as	string	false	read-only	How order is finished
reason	string	false	read-only	Extra messages of how order is finished

Enumerated Values

Property	Value
tif	gtc
tif	ioc
text	web
text	api
text	app
strategy_type	0
strategy_type	1
price_type	0
price_type	1
price_type	2
rule	1
rule	2
status	open
status	finished
finish_as	cancelled
finish_as	succeeded
finish_as	failed
finish_as	expired