NAV Navbar
Shell Python

Gate API v4 v4.6.3

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 spot, margin and futures trading operations. There are public APIs to retrieve the real-time market statistics, and private APIs which needs authentication to trade on user's behalf.

Base URLs:

Terms of service

Email: API support

Web: API support

License: Apache License 2.0

Available SDK:

Changelog

v4.6.3

2019-06-11

v4.6.2

2019-04-24

v4.6.1

2019-04-02

v4.6.0

2019-03-21

SDK related only

v4.5.2

2019-03-14

v4.5.1

2019-03-11

v4.5.0

2019-03-05

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

v1.3.0

2019-02-13

Important update

v1.2.1

2019-02-13

v1.2.0

2019-01-17

v1.1.0

2019-01-08

v1.0.0

2018-12-30

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 "")
    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, s, hashlib.sha512).hexdigest()
    return {'KEY': key, 'Timestamp': str(t), 'SIGN': sign}

if __name__ == "__main__":
    host = 'https://fx-api.gateio.io'
    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/contracts \
  -H 'Accept: application/json'

import requests

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

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

GET /futures/contracts

List all futures contracts

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/contracts/BTC_USD \
  -H 'Accept: application/json'

import requests

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

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

GET /futures/contracts/{contract}

Get a single contract

Parameters

Name In Type Required Description
contract path string true Futures contract

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/order_book?contract=BTC_USD \
  -H 'Accept: application/json'

import requests

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

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

GET /futures/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
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
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/trades?contract=BTC_USD \
  -H 'Accept: application/json'

import requests

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

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

GET /futures/trades

Futures trading history

Parameters

Name In Type Required Description
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 last record of id in previous list-query results

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/candlesticks?contract=BTC_USD \
  -H 'Accept: application/json'

import requests

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

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

GET /futures/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
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
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/tickers \
  -H 'Accept: application/json'

import requests

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

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

GET /futures/tickers

List futures tickers

Parameters

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

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",
    "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 volume in recent 24h in BTC
» volume_24h_usd string Trade volume in recent 24h in USD
» 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/funding_rate?contract=BTC_USD \
  -H 'Accept: application/json'

import requests

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

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

GET /futures/funding_rate

Funding rate history

Parameters

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

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/insurance \
  -H 'Accept: application/json'

import requests

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

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

GET /futures/insurance

Futures insurance balance history

Parameters

Name In Type Required Description
limit query integer false Maximum number of record returned in one list

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

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

Query futures account

Example responses

200 Response

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

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

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

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

Query account book

Parameters

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

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

List all positions of a user

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

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/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/positions/{contract}

Get single position

Parameters

Name In Type Required Description
contract path string true Futures contract

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

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/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/positions/{contract}/margin

Update position margin

Parameters

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

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

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/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/positions/{contract}/leverage

Update position leverage

Parameters

Name In Type Required Description
contract path string true Futures contract
leverage query string true New position leverage

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

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/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/positions/{contract}/risk_limit

Update position risk limit

Parameters

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

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/orders"
query_param=""
body_param='{"contract":"BTC_USD","size":6024,"iceberg":0,"price":"3765","tif":"gtc"}'
timestamp=$(date +%s)
body_hash=$(printf $body_param | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\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"

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/orders'
query_param = ''
body='{"contract":"BTC_USD","size":6024,"iceberg":0,"price":"3765","tif":"gtc"}'
# 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/orders

Create a futures order

Body parameter

{
  "contract": "BTC_USD",
  "size": 6024,
  "iceberg": 0,
  "price": "3765",
  "tif": "gtc"
}

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 post-only order
» tif body string false Time in force

Detailed descriptions

» tif: Time in force

Enumerated Values

Parameter Value
» tif gtc
» tif ioc
» tif poc

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": "api",
  "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/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"

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

List futures orders

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 last record of id in previous list-query results

Enumerated Values

Parameter Value
status open
status finished

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": "api",
    "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/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"

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

Cancel all open orders matched

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

Enumerated Values

Parameter Value
side ask
side bid

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": "api",
    "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/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"

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/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/orders/{order_id}

Get a single order

Parameters

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

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": "api",
  "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/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"

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/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/orders/{order_id}

Cancel a single order

Parameters

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

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": "api",
  "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/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"

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

List personal trading history

Parameters

Name In Type Required Description
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 last record of id in previous list-query results

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

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

List position close history

Parameters

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

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

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

List liquidation history

Parameters

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

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

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

Detailed descriptions

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

»» strategy_type: How the order will be triggered

»» rule: Trigger condition type

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

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

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

Enumerated Values

Parameter Value
status open
status finished

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

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

Cancel all open orders

Parameters

Name In Type Required Description
contract query string true Futures contract

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

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/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/price_orders/{order_id}

Get a single order

Parameters

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

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

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/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/price_orders/{order_id}

Cancel a single order

Parameters

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

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
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 post-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, post-only
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 read-only How 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

FuturesErrorResponse

{
  "label": "INVALID_PARAM_VALUE",
  "detail": "string"
}

error response body format when status code is non-2xx

Properties

Name Type Required Restrictions Description
label string false none error identifier. Possible values are:

Invalid request format or content:

- INVALID_PARAM_VALUE: invalid argument
- INVALID_PROTOCOL: invalid argument
- INVALID_ARGUMENT: invalid argument
- INVALID_REQUEST_BODY: invalid request body
- MISSING_REQUIRED_PARAM: missing required parameter

Authentication related:

- INVALID_CREDENTIALS: missing authentication credentials
- USER_NOT_FOUND: user no futures account

Business related:

- CONTRACT_NO_COUNTER: no matching order
- CONTRACT_NOT_FOUND: no such contract
- NOT_FOUND: request resource not found
- RISK_LIMIT_EXCEEDED: risk limit exceeded
- INSUFFICIENT_AVAILABLE: insufficient available
- LIQUIDATE_IMMEDIATELY: liquidate immediately if traded
- LEVERAGE_TOO_HIGH: leverage too high
- LEVERAGE_TOO_LOW: Leverage too low
- ORDER_NOT_FOUND: no such order
- ORDER_NOT_OWNED: no such order
- ORDER_FINISHED: order has been finished
- TOO_MANY_ORDERS: too many open orders
- POSITION_CROSS_MARGIN: margin not allowd to be updated in cross margin
- POSITION_IN_LIQUIDATION: position is in liquidation
- POSITION_IN_CLOSE: position is in close
- POSITION_EMPTY: position is empty
- REMOVE_TOO_MUCH: remove too much margin
- RISK_LIMIT_NOT_MULTIPLE: risk limit not multiple of step
- RISK_LIMIT_TOO_HIGH: risk limit too high
- RISK_LIMIT_TOO_lOW: risk limit too low
- PRICE_TOO_DEVIATED: order price deviated too much from mark price
- SIZE_TOO_LARGE: order size too large
- SIZE_TOO_SMALL: order size too small
- PRICE_OVER_LIQUIDATION: order price exceeds liquidation price while increasing position
- PRICE_OVER_BANKRUPT: order price exceeds backrupt price while reducing position
- ORDER_POC_IMMEDIATE: would trade immediately for POC order
- INCREASE_POSITION: would increase position for reduce-only order

Server error:
- INTERNAL: internal error
- SERVER_ERROR: internal error
- TOO_BUSY: server is too busy
detail string false none detail information, only for some error codes

Enumerated Values

Property Value
label INVALID_PARAM_VALUE
label INVALID_PROTOCOL
label INVALID_ARGUMENT
label INVALID_REQUEST_BODY
label MISSING_REQUIRED_PARAM
label INVALID_CREDENTIALS
label USER_NOT_FOUND
label CONTRACT_NO_COUNTER
label CONTRACT_NOT_FOUND
label NOT_FOUND
label RISK_LIMIT_EXCEEDED
label INSUFFICIENT_AVAILABLE
label LIQUIDATE_IMMEDIATELY
label LEVERAGE_TOO_HIGH
label LEVERAGE_TOO_LOW
label ORDER_NOT_FOUND
label ORDER_NOT_OWNED
label ORDER_FINISHED
label TOO_MANY_ORDERS
label POSITION_CROSS_MARGIN
label POSITION_IN_LIQUIDATION
label POSITION_IN_CLOSE
label POSITION_EMPTY
label REMOVE_TOO_MUCH
label RISK_LIMIT_NOT_MULTIPLE
label RISK_LIMIT_TOO_HIGH
label RISK_LIMIT_TOO_lOW
label PRICE_TOO_DEVIATED
label SIZE_TOO_LARGE
label SIZE_TOO_SMALL
label PRICE_OVER_LIQUIDATION
label PRICE_OVER_BANKRUPT
label ORDER_POC_IMMEDIATE
label INCREASE_POSITION
label INTERNAL
label SERVER_ERROR
label TOO_BUSY