Spot

Spot trading

Query all currency information

Code samples

# coding: utf-8
import requests

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

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

curl -X GET https://api.gateio.ws/api/v4/spot/currencies \
  -H 'Accept: application/json'

GET /spot/currencies

Query all currency information

When a currency corresponds to multiple chains, you can query the information of multiple chains through the chains field, such as the charging and recharge status, identification, etc. of the chain

Example responses

200 Response

[
  {
    "currency": "GT",
    "name": "GateToken",
    "delisted": false,
    "withdraw_disabled": false,
    "withdraw_delayed": false,
    "deposit_disabled": false,
    "trade_disabled": false,
    "chain": "GT",
    "chains": [
      {
        "name": "GT",
        "addr": "",
        "withdraw_disabled": false,
        "withdraw_delayed": false,
        "deposit_disabled": false
      },
      {
        "name": "ETH",
        "withdraw_disabled": false,
        "withdraw_delayed": false,
        "deposit_disabled": false,
        "addr": "0xE66747a101bFF2dBA3697199DCcE5b743b454759"
      },
      {
        "name": "GTEVM",
        "withdraw_disabled": false,
        "withdraw_delayed": false,
        "deposit_disabled": false,
        "addr": ""
      }
    ],
    "total_supply": "2100000",
    "market_cap": "18880000",
    "category": []
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» currency	string	Currency symbol
» name	string	Currency name
» delisted	boolean	Whether currency is de-listed
» withdraw_disabled	boolean	Whether currency's withdrawal is disabled (deprecated)
» withdraw_delayed	boolean	Whether currency's withdrawal is delayed (deprecated)
» deposit_disabled	boolean	Whether currency's deposit is disabled (deprecated)
» trade_disabled	boolean	Whether currency's trading is disabled
» fixed_rate	string	Fixed fee rate. Only for fixed rate currencies, not valid for normal currencies
» chain	string	The main chain corresponding to the coin
» chains	array	All links corresponding to coins
»» SpotCurrencyChain	object	none
»»» name	string	Blockchain name
»»» addr	string	token address
»»» withdraw_disabled	boolean	Whether currency's withdrawal is disabled
»»» withdraw_delayed	boolean	Whether currency's withdrawal is delayed
»»» deposit_disabled	boolean	Whether currency's deposit is disabled
»» total_supply	string	Total supply
»» market_cap	string	Market cap
»» category	array	Currency categories - stocks: Stocks - metals: Metals - indices: Indices - forex: Forex - commodities: Commodities

This operation does not require authentication

Query single currency information

Code samples

# coding: utf-8
import requests

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

url = '/spot/currencies/GT'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/spot/currencies/GT \
  -H 'Accept: application/json'

GET /spot/currencies/{currency}

Query single currency information

Parameters

Name	In	Type	Required	Description
currency	path	any	true	Currency name

Example responses

200 Response

{
  "currency": "GT",
  "name": "GateToken",
  "delisted": false,
  "withdraw_disabled": false,
  "withdraw_delayed": false,
  "deposit_disabled": false,
  "trade_disabled": false,
  "chain": "GT",
  "chains": [
    {
      "name": "GT",
      "addr": "",
      "withdraw_disabled": false,
      "withdraw_delayed": false,
      "deposit_disabled": false
    },
    {
      "name": "ETH",
      "withdraw_disabled": false,
      "withdraw_delayed": false,
      "deposit_disabled": false,
      "addr": "0xE66747a101bFF2dBA3697199DCcE5b743b454759"
    },
    {
      "name": "GTEVM",
      "withdraw_disabled": false,
      "withdraw_delayed": false,
      "deposit_disabled": false,
      "addr": ""
    }
  ],
  "total_supply": "2100000",
  "market_cap": "18880000",
  "category": []
}

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» currency	string	Currency symbol
» name	string	Currency name
» delisted	boolean	Whether currency is de-listed
» withdraw_disabled	boolean	Whether currency's withdrawal is disabled (deprecated)
» withdraw_delayed	boolean	Whether currency's withdrawal is delayed (deprecated)
» deposit_disabled	boolean	Whether currency's deposit is disabled (deprecated)
» trade_disabled	boolean	Whether currency's trading is disabled
» fixed_rate	string	Fixed fee rate. Only for fixed rate currencies, not valid for normal currencies
» chain	string	The main chain corresponding to the coin
» chains	array	All links corresponding to coins
»» SpotCurrencyChain	object	none
»»» name	string	Blockchain name
»»» addr	string	token address
»»» withdraw_disabled	boolean	Whether currency's withdrawal is disabled
»»» withdraw_delayed	boolean	Whether currency's withdrawal is delayed
»»» deposit_disabled	boolean	Whether currency's deposit is disabled
»» total_supply	string	Total supply
»» market_cap	string	Market cap
»» category	array	Currency categories - stocks: Stocks - metals: Metals - indices: Indices - forex: Forex - commodities: Commodities

This operation does not require authentication

Query all supported currency pairs

Code samples

# coding: utf-8
import requests

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

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

curl -X GET https://api.gateio.ws/api/v4/spot/currency_pairs \
  -H 'Accept: application/json'

GET /spot/currency_pairs

Query all supported currency pairs

Example responses

200 Response

[
  {
    "id": "ETH_USDT",
    "base": "ETH",
    "base_name": "Ethereum",
    "quote": "USDT",
    "quote_name": "Tether",
    "trade_quotes": [
      "USDC",
      "RLUSD"
    ],
    "fee": "0.2",
    "min_base_amount": "0.001",
    "min_quote_amount": "1.0",
    "max_base_amount": "10000",
    "max_quote_amount": "10000000",
    "amount_precision": 3,
    "precision": 6,
    "trade_status": "tradable",
    "sell_start": 1516378650,
    "buy_start": 1516378650,
    "delisting_time": 0,
    "type": "normal",
    "trade_url": "https://www.gate.io/trade/ETH_USDT",
    "st_tag": false,
    "up_rate": "0.05",
    "down_rate": "0.02",
    "slippage": "0.05",
    "market_order_max_stock": "100000",
    "market_order_max_money": "1000000"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	All currency pairs retrieved	[CurrencyPair]

Response Schema

Status Code 200

Name	Type	Description
None	array	[Spot currency pair]
» None	CurrencyPair	Spot currency pair
»» id	string	Currency pair
»» base	string	Base currency
»» base_name	string	Base currency name
»» quote	string	Quote currency
»» quote_name	string	Quote currency name
»» trade_quotes	array|null	Quote currencies supported by the unified market; null means that the market does not support unified quote currencies
»» fee	string	Trading fee rate(deprecated)
»» min_base_amount	string	Minimum amount of base currency to trade, null means no limit
»» min_quote_amount	string	Minimum amount of quote currency to trade, null means no limit
»» max_base_amount	string	Maximum amount of base currency to trade, null means no limit
»» max_quote_amount	string	Maximum amount of quote currency to trade, null means no limit
»» amount_precision	integer	Quantity precision
»» precision	integer	Price precision
»» trade_status	string	Trading status - untradable: cannot be traded - buyable: can be bought - sellable: can be sold - tradable: can be bought and sold
»» sell_start	integer(int64)	Sell start unix timestamp in seconds
»» buy_start	integer(int64)	Buy start unix timestamp in seconds
»» delisting_time	integer(int64)	Expected time to remove the shelves, Unix timestamp in seconds
»» type	string	Trading pair type, normal: normal, premarket: pre-market
»» trade_url	string	Transaction link
»» st_tag	boolean	Whether the trading pair is in ST risk assessment, false - No, true - Yes
»» up_rate	string	Maximum Quote Rise Percentage
»» down_rate	string	Maximum Quote Decline Percentage
»» slippage	string	Maximum supported slippage ratio for Spot Market Order Placement, calculated based on the latest market price at the time of order placement as the benchmark (Example: 0.03 means 3%)
»» market_order_max_stock	string	Maximum market order quantity. null or 0 means no limit
»» market_order_max_money	string	Maximum market order amount. null or 0 means no limit

Enumerated Values

Property	Value
trade_status	untradable
trade_status	buyable
trade_status	sellable
trade_status	tradable

This operation does not require authentication

Query single currency pair details

Code samples

# coding: utf-8
import requests

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

url = '/spot/currency_pairs/ETH_BTC'
query_param = ''
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/spot/currency_pairs/ETH_BTC \
  -H 'Accept: application/json'

GET /spot/currency_pairs/{currency_pair}

Query single currency pair details

Parameters

Name	In	Type	Required	Description
currency_pair	path	string	true	Currency pair

Example responses

200 Response

{
  "id": "ETH_USDT",
  "base": "ETH",
  "base_name": "Ethereum",
  "quote": "USDT",
  "quote_name": "Tether",
  "trade_quotes": [
    "USDC",
    "RLUSD"
  ],
  "fee": "0.2",
  "min_base_amount": "0.001",
  "min_quote_amount": "1.0",
  "max_base_amount": "10000",
  "max_quote_amount": "10000000",
  "amount_precision": 3,
  "precision": 6,
  "trade_status": "tradable",
  "sell_start": 1516378650,
  "buy_start": 1516378650,
  "delisting_time": 0,
  "type": "normal",
  "trade_url": "https://www.gate.io/trade/ETH_USDT",
  "st_tag": false,
  "up_rate": "0.05",
  "down_rate": "0.02",
  "slippage": "0.05",
  "market_order_max_stock": "100000",
  "market_order_max_money": "1000000"
}

Responses

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

Response Schema

Status Code 200

Spot currency pair

Name	Type	Description
» id	string	Currency pair
» base	string	Base currency
» base_name	string	Base currency name
» quote	string	Quote currency
» quote_name	string	Quote currency name
» trade_quotes	array|null	Quote currencies supported by the unified market; null means that the market does not support unified quote currencies
» fee	string	Trading fee rate(deprecated)
» min_base_amount	string	Minimum amount of base currency to trade, null means no limit
» min_quote_amount	string	Minimum amount of quote currency to trade, null means no limit
» max_base_amount	string	Maximum amount of base currency to trade, null means no limit
» max_quote_amount	string	Maximum amount of quote currency to trade, null means no limit
» amount_precision	integer	Quantity precision
» precision	integer	Price precision
» trade_status	string	Trading status - untradable: cannot be traded - buyable: can be bought - sellable: can be sold - tradable: can be bought and sold
» sell_start	integer(int64)	Sell start unix timestamp in seconds
» buy_start	integer(int64)	Buy start unix timestamp in seconds
» delisting_time	integer(int64)	Expected time to remove the shelves, Unix timestamp in seconds
» type	string	Trading pair type, normal: normal, premarket: pre-market
» trade_url	string	Transaction link
» st_tag	boolean	Whether the trading pair is in ST risk assessment, false - No, true - Yes
» up_rate	string	Maximum Quote Rise Percentage
» down_rate	string	Maximum Quote Decline Percentage
» slippage	string	Maximum supported slippage ratio for Spot Market Order Placement, calculated based on the latest market price at the time of order placement as the benchmark (Example: 0.03 means 3%)
» market_order_max_stock	string	Maximum market order quantity. null or 0 means no limit
» market_order_max_money	string	Maximum market order amount. null or 0 means no limit

Enumerated Values

Property	Value
trade_status	untradable
trade_status	buyable
trade_status	sellable
trade_status	tradable

This operation does not require authentication

Get currency pair ticker information

Code samples

# coding: utf-8
import requests

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

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

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

GET /spot/tickers

Get currency pair ticker information

If currency_pair is specified, only query that currency pair; otherwise return all information

Parameters

Name	In	Type	Required	Description
currency_pair	query	string	false	Currency pair
timezone	query	string	false	Timezone

Enumerated Values

Parameter	Value
timezone	utc0
timezone	utc8
timezone	all

Example responses

200 Response

[
  {
    "currency_pair": "BTC3L_USDT",
    "last": "2.46140352",
    "lowest_ask": "2.477",
    "highest_bid": "2.4606821",
    "change_percentage": "-8.91",
    "change_utc0": "-8.91",
    "change_utc8": "-8.91",
    "base_volume": "656614.0845820589",
    "quote_volume": "1602221.66468375534639404191",
    "high_24h": "2.7431",
    "low_24h": "1.9863",
    "etf_net_value": "2.46316141",
    "etf_pre_net_value": "2.43201848",
    "etf_pre_timestamp": 1611244800,
    "etf_leverage": "2.2803019447281203"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» currency_pair	string	Currency pair
» last	string	Last trading price
» lowest_ask	string	Recent lowest ask
» lowest_size	string	Latest seller's lowest price quantity; not available for batch queries; available for single queries, empty if no data
» highest_bid	string	Recent highest bid
» highest_size	string	Latest buyer's highest price quantity; not available for batch queries; available for single queries, empty if no data
» change_percentage	string	24h price change percentage (negative for decrease, e.g., -7.45)
» change_utc0	string	UTC+0 timezone, 24h price change percentage, negative for decline (e.g., -7.45)
» change_utc8	string	UTC+8 timezone, 24h price change percentage, negative for decline (e.g., -7.45)
» base_volume	string	Base currency trading volume in the last 24h
» quote_volume	string	Quote currency trading volume in the last 24h
» high_24h	string	24h High
» low_24h	string	24h Low
» etf_net_value	string	ETF net value
» etf_pre_net_value	string|null	ETF net value at previous rebalancing point
» etf_pre_timestamp	integer(int64)|null	ETF previous rebalancing time
» etf_leverage	string|null	ETF current leverage

This operation does not require authentication

Get market depth information

Code samples

# coding: utf-8
import requests

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

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

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

GET /spot/order_book

Get market depth information

Market depth buy orders are sorted by price from high to low, sell orders are reversed

Parameters

Name	In	Type	Required	Description
currency_pair	query	string	true	Currency pair
interval	query	string	false	Price precision for merged depth. 0 means no merging. If not specified, defaults to 0
limit	query	integer	false	Number of depth levels
with_id	query	boolean	false	Return order book update ID

Example responses

200 Response

{
  "id": 123456,
  "current": 1623898993123,
  "update": 1623898993121,
  "asks": [
    [
      "1.52",
      "1.151"
    ],
    [
      "1.53",
      "1.218"
    ]
  ],
  "bids": [
    [
      "1.17",
      "201.863"
    ],
    [
      "1.16",
      "725.464"
    ]
  ]
}

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» id	integer(int64)	Order book ID, which is updated whenever the order book is changed. Valid only when with_id is set to true
» current	integer(int64)	The timestamp of the response data being generated (in milliseconds)
» update	integer(int64)	The timestamp of when the orderbook last changed (in milliseconds)
» asks	array	Ask Depth
»» None	array	Price and Quantity Pair
» bids	array	Bid Depth
»» None	array	Price and Quantity Pair

This operation does not require authentication

Query market transaction records

Code samples

# coding: utf-8
import requests

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

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

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

GET /spot/trades

Query market transaction records

Supports querying by time range using from and to parameters or pagination based on last_id. By default, queries the last 30 days.

Pagination based on last_id is no longer recommended. If last_id is specified, the time range query parameters will be ignored.

When using limit&page pagination to retrieve data, the maximum number of pages is 100,000, that is, limit * (page - 1) <= 100,000.

Parameters

Name	In	Type	Required	Description
currency_pair	query	string	true	Currency pair
limit	query	integer(int32)	false	Maximum number of items returned in list. Default: 100, minimum: 1, maximum: 1000
last_id	query	string	false	Use the ID of the last record in the previous list as the starting point for the next list Operations based on custom IDs can only be checked when orders are pending. After orders are completed (filled/cancelled), they can be checked within 1 hour after completion. After expiration, only order IDs can be used
reverse	query	boolean	false	Whether to retrieve data less than last_id. Default returns records greater than last_id. Set to true to trace back market trade records, false to get latest trades. No effect when last_id is not set.
from	query	integer(int64)	false	Start timestamp for the query
to	query	integer(int64)	false	End timestamp for the query, defaults to current time if not specified
page	query	integer(int32)	false	Page number

Detailed descriptions

last_id: Use the ID of the last record in the previous list as the starting point for the next list

Operations based on custom IDs can only be checked when orders are pending. After orders are completed (filled/cancelled), they can be checked within 1 hour after completion. After expiration, only order IDs can be used

reverse: Whether to retrieve data less than last_id. Default returns records greater than last_id.

Set to true to trace back market trade records, false to get latest trades.

No effect when last_id is not set.

Example responses

200 Response

[
  {
    "id": "1232893232",
    "create_time": "1548000000",
    "create_time_ms": "1548000000123.456",
    "currency_pair": "BTC_USDT",
    "order_id": "4128442423",
    "side": "buy",
    "role": "maker",
    "amount": "0.15",
    "price": "0.03",
    "fee": "0.0005",
    "fee_currency": "ETH",
    "point_fee": "0",
    "gt_fee": "0",
    "sequence_id": "588018",
    "text": "t-test",
    "deal": "0.0045",
    "trade_quote": "USDC"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» id	string	Fill ID
» create_time	string	Fill Time
» create_time_ms	string	Trading time, with millisecond precision
» currency_pair	string	Currency pair
» side	string	Buy or sell order
» role	string	Trade role, not returned in public endpoints
» amount	string	Trade amount
» price	string	Order price
» order_id	string	Related order ID, not returned in public endpoints
» fee	string	Fee deducted, not returned in public endpoints
» fee_currency	string	Fee currency unit, not returned in public endpoints
» point_fee	string	Points used to deduct fee, not returned in public endpoints
» gt_fee	string	GT used to deduct fee, not returned in public endpoints
» amend_text	string	The custom data that the user remarked when amending the order
» sequence_id	string	Consecutive trade ID within a single market. Used to track and identify trades in the specific market
» text	string	Order's Custom Information. This field is not returned by public interfaces. The scenarios pm_liquidate, comb_margin_liquidate, and scm_liquidate represent full-account forced liquidation orders. liquidate represents isolated-account forced liquidation orders.
» deal	string	Total Executed Value
» trade_quote	string	Actual quote currency used for the trade

Enumerated Values

Property	Value
side	buy
side	sell
role	taker
role	maker

This operation does not require authentication

Market K-line chart

Code samples

# coding: utf-8
import requests

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

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

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

GET /spot/candlesticks

Market K-line chart

K-line chart data returns a maximum of 1000 points per request. When specifying from, to, and interval, ensure the number of points is not excessive

Parameters

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

Enumerated Values

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

Example responses

200 Response

[
  [
    "1539852480",
    "971519.677",
    "0.0021724",
    "0.0021922",
    "0.0021724",
    "0.0021737",
    "true"
  ]
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» None	array	Candlestick data for each time granularity, from left to right: - Unix timestamp with second precision - Trading volume in quote currency - Closing price - Highest price - Lowest price - Opening price - Trading volume in base currency - Whether window is closed; true means this candlestick data segment is complete, false means not yet complete

This operation does not require authentication

Query account fee rates

Code samples

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

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

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

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

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

GET /spot/fee

Query account fee rates

This API is deprecated. The new fee query API is /wallet/fee

Parameters

Name	In	Type	Required	Description
currency_pair	query	string	false	Specify currency pair to get more accurate fee settings. This field is optional. Usually fee settings are the same for all currency pairs.

Detailed descriptions

currency_pair: Specify currency pair to get more accurate fee settings.

This field is optional. Usually fee settings are the same for all currency pairs.

Example responses

200 Response

{
  "user_id": 10001,
  "taker_fee": "0.002",
  "maker_fee": "0.002",
  "gt_discount": false,
  "gt_taker_fee": "0",
  "gt_maker_fee": "0",
  "loan_fee": "0.18",
  "point_type": "1",
  "currency_pair": "BTC_USDT",
  "debit_fee": 3
}

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» user_id	integer(int64)	User ID
» taker_fee	string	taker fee rate
» maker_fee	string	maker fee rate
» rpi_maker_fee	string	RPI MM maker fee rate
» gt_discount	boolean	Whether GT deduction discount is enabled
» gt_taker_fee	string	Taker fee rate if using GT deduction. It will be 0 if GT deduction is disabled
» gt_maker_fee	string	Maker fee rate with GT deduction. Returns 0 if GT deduction is disabled
» loan_fee	string	Loan fee rate of margin lending
» point_type	string	Point card type: 0 - Original version, 1 - New version since 202009
» currency_pair	string	Currency pair
» debit_fee	integer	Deduction types for rates, 1 - GT deduction, 2 - Point card deduction, 3 - VIP rates
» rpi_mm	integer	RPI MM Level

WARNING

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

Batch query account fee rates

Code samples

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

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

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

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

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

GET /spot/batch_fee

Batch query account fee rates

Parameters

Name	In	Type	Required	Description
currency_pairs	query	string	true	Maximum 50 currency pairs per request

Example responses

200 Response

{
  "BTC_USDT": {
    "user_id": 10001,
    "taker_fee": "0.002",
    "maker_fee": "0.002",
    "rpi_maker_fee": "-0.00175",
    "gt_discount": false,
    "gt_taker_fee": "0",
    "gt_maker_fee": "0",
    "loan_fee": "0.18",
    "point_type": "1",
    "currency_pair": "BTC_USDT",
    "debit_fee": 3,
    "rpi_mm": 2
  },
  "GT_USDT": {
    "user_id": 10001,
    "taker_fee": "0.002",
    "maker_fee": "0.002",
    "rpi_maker_fee": "-0.00175",
    "gt_discount": false,
    "gt_taker_fee": "0",
    "gt_maker_fee": "0",
    "loan_fee": "0.18",
    "point_type": "1",
    "currency_pair": "GT_USDT",
    "debit_fee": 3,
    "rpi_mm": 2
  },
  "ETH_USDT": {
    "user_id": 10001,
    "taker_fee": "0.002",
    "maker_fee": "0.002",
    "rpi_maker_fee": "-0.00175",
    "gt_discount": false,
    "gt_taker_fee": "0",
    "gt_maker_fee": "0",
    "loan_fee": "0.18",
    "point_type": "1",
    "currency_pair": "ETH_USDT",
    "debit_fee": 3,
    "rpi_mm": 2
  }
}

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» additionalProperties	SpotFee	none
»» user_id	integer(int64)	User ID
»» taker_fee	string	taker fee rate
»» maker_fee	string	maker fee rate
»» rpi_maker_fee	string	RPI MM maker fee rate
»» gt_discount	boolean	Whether GT deduction discount is enabled
»» gt_taker_fee	string	Taker fee rate if using GT deduction. It will be 0 if GT deduction is disabled
»» gt_maker_fee	string	Maker fee rate with GT deduction. Returns 0 if GT deduction is disabled
»» loan_fee	string	Loan fee rate of margin lending
»» point_type	string	Point card type: 0 - Original version, 1 - New version since 202009
»» currency_pair	string	Currency pair
»» debit_fee	integer	Deduction types for rates, 1 - GT deduction, 2 - Point card deduction, 3 - VIP rates
»» rpi_mm	integer	RPI MM Level

WARNING

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

List spot trading accounts

Code samples

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

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

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

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

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

GET /spot/accounts

List spot trading accounts

Parameters

Name	In	Type	Required	Description
currency	query	string	false	Query by specified currency name

Example responses

200 Response

[
  {
    "currency": "ETH",
    "available": "968.8",
    "locked": "0",
    "update_id": 98
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» currency	string	Currency detail
» available	string	Available amount
» locked	string	Locked amount, used in trading
» update_id	integer(int64)	Version number

WARNING

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

Query spot account transaction history

Code samples

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

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

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

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

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

GET /spot/account_book

Query spot account transaction history

Record query time range cannot exceed 30 days.

When using limit&page pagination to retrieve data, the maximum number of pages is 100,000, that is, limit * (page - 1) <= 100,000.

Parameters

Name	In	Type	Required	Description
currency	query	string	false	Query by specified currency name
from	query	integer(int64)	false	Start timestamp for the query
to	query	integer(int64)	false	End timestamp for the query, defaults to current time if not specified
page	query	integer(int32)	false	Page number
limit	query	integer	false	Maximum number of records returned in a single list
type	query	string	false	Query by specified account change type. If not specified, all change types will be included.
code	query	string	false	Specify account change code for query. If not specified, all change types are included. This parameter has higher priority than type

Example responses

200 Response

[
  {
    "id": "123456",
    "time": 1547633726123,
    "currency": "BTC",
    "change": "1.03",
    "balance": "4.59316525194",
    "type": "margin_in",
    "text": "3815099"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» id	string	Balance change record ID
» time	integer(int64)	The timestamp of the change (in milliseconds)
» currency	string	Currency changed
» change	string	Amount changed. Positive value means transferring in, while negative out
» balance	string	Balance after change
» type	string	Account change type; deprecated (see code for account change type encoding)
» code	string	Account change code, see [Asset Record Code] (Asset Record Code)
» text	string	Additional information

WARNING

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

Batch place orders

Code samples

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

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

url = '/spot/batch_orders'
query_param = ''
body='[{"text":"t-abc123","currency_pair":"BTC_USDT","trade_quote":"USDC","type":"limit","account":"unified","side":"buy","amount":"0.001","price":"65000","time_in_force":"gtc","iceberg":"0","slippage":"0.05","stop_profit":{"trigger_price":"67000","order_price":"67000"},"stop_loss":{"trigger_price":"63000","order_price":"63000"}}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/batch_orders"
query_param=""
body_param='[{"text":"t-abc123","currency_pair":"BTC_USDT","trade_quote":"USDC","type":"limit","account":"unified","side":"buy","amount":"0.001","price":"65000","time_in_force":"gtc","iceberg":"0","slippage":"0.05","stop_profit":{"trigger_price":"67000","order_price":"67000"},"stop_loss":{"trigger_price":"63000","order_price":"63000"}}]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /spot/batch_orders

Batch place orders

Batch order requirements:

1. Custom order field text must be specified
2. Up to 4 currency pairs per request, with up to 10 orders per currency pair
3. Spot orders and margin orders cannot be mixed; all account fields in the same request must be identical

Body parameter

[
  {
    "text": "t-abc123",
    "currency_pair": "BTC_USDT",
    "trade_quote": "USDC",
    "type": "limit",
    "account": "unified",
    "side": "buy",
    "amount": "0.001",
    "price": "65000",
    "time_in_force": "gtc",
    "iceberg": "0",
    "slippage": "0.05",
    "stop_profit": {
      "trigger_price": "67000",
      "order_price": "67000"
    },
    "stop_loss": {
      "trigger_price": "63000",
      "order_price": "63000"
    }
  }
]

Parameters

Name	In	Type	Required	Description
x-gate-exptime	header	string	false	Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected
body	body	array[Order]	true	none

Example responses

200 Response

[
  {
    "order_id": "12332324",
    "amend_text": "t-123456",
    "text": "t-123456",
    "succeeded": true,
    "label": "",
    "message": "",
    "id": "12332324",
    "create_time": "1548000000",
    "update_time": "1548000100",
    "create_time_ms": 1548000000123,
    "update_time_ms": 1548000100123,
    "currency_pair": "ETC_BTC",
    "status": "cancelled",
    "type": "limit",
    "account": "spot",
    "side": "buy",
    "amount": "1",
    "price": "5.00032",
    "time_in_force": "gtc",
    "iceberg": "0",
    "left": "0.5",
    "filled_amount": "1.242",
    "filled_total": "2.50016",
    "avg_deal_price": "5.00032",
    "fee": "0.005",
    "fee_currency": "ETH",
    "point_fee": "0",
    "gt_fee": "0",
    "gt_discount": false,
    "rebated_fee": "0",
    "rebated_fee_currency": "BTC",
    "stp_act": "cn",
    "finish_as": "stp",
    "stp_id": 10240
  }
]

Responses

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

Response Schema

Status Code 200

Contains multiple order objects; for the specific structure of the order object, refer to the structure of the /spot/orders order placement interface

Name	Type	Description
None	array	Contains multiple order objects; for the specific structure of the order object, refer to the structure of the /spot/orders order placement interface
» None	BatchOrder	Batch order details
»» order_id	string	Order ID
»» amend_text	string	The custom data that the user remarked when amending the order
»» text	string	Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: 1. Must start with t- 2. Excluding t-, length cannot exceed 28 bytes 3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.)
»» succeeded	boolean	Request execution result
»» label	string	Error label, if any, otherwise an empty string
»» message	string	Detailed error message, if any, otherwise an empty string
»» id	string	Order ID
»» create_time	string	Creation time of order
»» update_time	string	Last modification time of order
»» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
»» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
»» status	string	Order status - open: to be filled - closed: closed order - cancelled: cancelled
»» currency_pair	string	Currency pair
»» type	string	Order Type - limit : Limit Order - market : Market Order
»» account	string	Account type, spot - spot account, margin - leveraged account, unified - unified account
»» side	string	Buy or sell order
»» amount	string	Trade amount
»» price	string	Order price
»» time_in_force	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none
»» iceberg	string	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported
»» auto_repay	boolean	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order
»» left	string	Amount left to fill
»» filled_amount	string	Amount filled
»» fill_price	string	Total filled in quote currency. Deprecated in favor of filled_total
»» filled_total	string	Total filled in quote currency
»» avg_deal_price	string	Average fill price
»» fee	string	Fee deducted
»» fee_currency	string	Fee currency unit
»» point_fee	string	Points used to deduct fee
»» gt_fee	string	GT used to deduct fee
»» gt_discount	boolean	Whether GT fee deduction is enabled
»» rebated_fee	string	Rebated fee
»» rebated_fee_currency	string	Rebated fee currency unit
»» stp_id	integer	Orders between users in the same stp_id group are not allowed to be self-traded 1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker. 2. stp_id returns 0 by default for orders that have not been set for STP group
»» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group, he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy。 2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter。 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled
»» finish_as	string	How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only requirement not met because time-in-force is set to poc (maker-only); rejected after being detected as taker - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown
»» stop_profit	object	Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged.
»»» trigger_price	string	Take profit trigger price When side == "buy", trigger_price must be greater than price When side == "sell", trigger_price must be less than price
»»» order_price	string	Take profit order price
»» stop_loss	object	Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged.
»»» trigger_price	string	Stop loss trigger price When side == "buy", trigger_price must be less than price When side == "sell", trigger_price must be greater than price
»»» order_price	string	Stop-loss order price

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
account	spot
account	margin
account	cross_margin
account	unified
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	liquidate_cancelled
finish_as	depth_not_enough
finish_as	trader_not_enough
finish_as	small
finish_as	ioc
finish_as	poc
finish_as	fok
finish_as	stp
finish_as	price_protect_cancelled
finish_as	unknown

WARNING

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

List all open orders

Code samples

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

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

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

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

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

GET /spot/open_orders

List all open orders

Query the current order list of all trading pairs. Please note that the paging parameter controls the number of pending orders in each trading pair. There is no paging control trading pairs. All trading pairs with pending orders will be returned.

Parameters

Name	In	Type	Required	Description
page	query	integer(int32)	false	Page number
limit	query	integer	false	Maximum number of records returned in one page in each currency pair
account	query	string	false	Specify query account

Example responses

200 Response

[
  {
    "currency_pair": "ETH_BTC",
    "total": 1,
    "orders": [
      {
        "id": "12332324",
        "text": "t-123456",
        "create_time": "1548000000",
        "update_time": "1548000100",
        "currency_pair": "ETH_BTC",
        "status": "open",
        "type": "limit",
        "account": "spot",
        "side": "buy",
        "amount": "1",
        "price": "5.00032",
        "time_in_force": "gtc",
        "left": "0.5",
        "filled_total": "2.50016",
        "fee": "0.005",
        "fee_currency": "ETH",
        "point_fee": "0",
        "gt_fee": "0",
        "gt_discount": false,
        "rebated_fee": "0",
        "rebated_fee_currency": "BTC"
      }
    ]
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» currency_pair	string	Currency pair
» total	integer	Total number of open orders for this trading pair on the current page
» orders	array	none
»» None	object	Spot order details
»»» id	string	Order ID
»»» text	string	User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- 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: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders liquidate represents isolated-margin liquidation orders
»»» amend_text	string	The custom data that the user remarked when amending the order
»»» create_time	string	Creation time of order
»»» update_time	string	Last modification time of order
»»» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
»»» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
»»» status	string	Order status - open: to be filled - closed: closed order - cancelled: cancelled
»»» currency_pair	string	Currency pair
»»» trade_quote	string	Actual quote currency used for the trade; can be specified only in a unified market
»»» type	string	Order Type - limit : Limit Order - market : Market Order
»»» account	string	Account type, spot - spot account, margin - leveraged account, unified - unified account
»»» side	string	Buy or sell order
»»» amount	string	Trade amount When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT. When type is market, the meaning depends on the side: - side: buy refers to the quote currency, e.g. USDT in BTC_USDT - side: sell refers to the base currency, e.g. BTC in BTC_USDT
»»» price	string	Trading price, required when type=limit
»»» time_in_force	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market
»»» iceberg	string	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported
»»» auto_repay	boolean	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order
»»» left	string	Amount left to fill
»»» filled_amount	string	Amount filled
»»» fill_price	string	Total filled in quote currency. Deprecated in favor of filled_total
»»» filled_total	string	Total filled in quote currency
»»» avg_deal_price	string	Average fill price
»»» fee	string	Fee deducted
»»» fee_currency	string	Fee currency unit
»»» point_fee	string	Points used to deduct fee
»»» gt_fee	string	GT used to deduct fee
»»» gt_maker_fee	string	GT amount used to deduct maker fee
»»» gt_taker_fee	string	GT amount used to deduct taker fee
»»» gt_discount	boolean	Whether GT fee deduction is enabled
»»» rebated_fee	string	Rebated fee
»»» rebated_fee_currency	string	Rebated fee currency unit
»»» stp_id	integer	Orders between users in the same stp_id group are not allowed to be self-traded 1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker. 2. stp_id returns 0 by default for orders that have not been set for STP group
»»» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter. 3. If the user did not use stp_act when placing the order, stp_act will return '-' - cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled
»»» finish_as	string	How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only requirement not met because time-in-force is set to poc (maker-only); rejected after being detected as taker - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown
»»» stop_profit	object	Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged.
»»»» trigger_price	string	Take profit trigger price When side == "buy", trigger_price must be greater than price When side == "sell", trigger_price must be less than price
»»»» order_price	string	Take profit order price
»»» stop_loss	object	Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged.
»»»» trigger_price	string	Stop loss trigger price When side == "buy", trigger_price must be less than price When side == "sell", trigger_price must be greater than price
»»»» order_price	string	Stop-loss order price

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	liquidate_cancelled
finish_as	depth_not_enough
finish_as	trader_not_enough
finish_as	small
finish_as	ioc
finish_as	poc
finish_as	fok
finish_as	stp
finish_as	price_protect_cancelled
finish_as	unknown

WARNING

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

Close position when cross-currency is disabled

Code samples

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

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

url = '/spot/cross_liquidate_orders'
query_param = ''
body='{"currency_pair":"GT_USDT","amount":"12","price":"10.15","text":"t-34535"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/cross_liquidate_orders"
query_param=""
body_param='{"currency_pair":"GT_USDT","amount":"12","price":"10.15","text":"t-34535"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /spot/cross_liquidate_orders

Close position when cross-currency is disabled

Currently, only cross-margin accounts are supported to place buy orders for disabled currencies. Maximum buy quantity = (unpaid principal and interest - currency balance - the amount of the currency in pending orders) / 0.998

Body parameter

{
  "currency_pair": "GT_USDT",
  "amount": "12",
  "price": "10.15",
  "text": "t-34535"
}

Parameters

Name	In	Type	Required	Description
body	body	LiquidateOrder	true	none
» text	body	string	false	Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: 1. Must start with t- 2. Excluding t-, length cannot exceed 28 bytes 3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.)
» currency_pair	body	string	true	Currency pair
» amount	body	string	true	Trade amount
» price	body	string	true	Order price
» action_mode	body	string	false	Processing mode: Different fields are returned when placing an order based on action_mode. This field is only valid during the request and is not included in the response ACK: Asynchronous mode, only returns key order fields RESULT: No liquidation information FULL: Full mode (default)

Detailed descriptions

» text: Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions:

1. Must start with t-
2. Excluding t-, length cannot exceed 28 bytes
3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.)

» action_mode: Processing mode:

Different fields are returned when placing an order based on action_mode. This field is only valid during the request and is not included in the response
ACK: Asynchronous mode, only returns key order fields
RESULT: No liquidation information
FULL: Full mode (default)

Example responses

201 Response

{
  "id": "1852454420",
  "text": "t-abc123",
  "amend_text": "-",
  "create_time": "1710488334",
  "update_time": "1710488334",
  "create_time_ms": 1710488334073,
  "update_time_ms": 1710488334074,
  "status": "closed",
  "currency_pair": "BTC_USDT",
  "trade_quote": "USDC",
  "type": "limit",
  "account": "unified",
  "side": "buy",
  "amount": "0.001",
  "price": "65000",
  "time_in_force": "gtc",
  "iceberg": "0",
  "left": "0",
  "filled_amount": "0.001",
  "fill_price": "63.4693",
  "filled_total": "63.4693",
  "avg_deal_price": "63469.3",
  "fee": "0.00000022",
  "fee_currency": "BTC",
  "point_fee": "0",
  "gt_fee": "0",
  "gt_maker_fee": "0",
  "gt_taker_fee": "0",
  "gt_discount": false,
  "rebated_fee": "0",
  "rebated_fee_currency": "USDT",
  "finish_as": "filled",
  "stop_profit": {
    "trigger_price": "67000",
    "order_price": "67000"
  },
  "stop_loss": {
    "trigger_price": "63000",
    "order_price": "63000"
  }
}

Responses

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

Response Schema

Status Code 201

Spot order details

Name	Type	Description
» id	string	Order ID
» text	string	User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- 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: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders liquidate represents isolated-margin liquidation orders
» amend_text	string	The custom data that the user remarked when amending the order
» create_time	string	Creation time of order
» update_time	string	Last modification time of order
» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
» status	string	Order status - open: to be filled - closed: closed order - cancelled: cancelled
» currency_pair	string	Currency pair
» trade_quote	string	Actual quote currency used for the trade; can be specified only in a unified market
» type	string	Order Type - limit : Limit Order - market : Market Order
» account	string	Account type, spot - spot account, margin - leveraged account, unified - unified account
» side	string	Buy or sell order
» amount	string	Trade amount When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT. When type is market, the meaning depends on the side: - side: buy refers to the quote currency, e.g. USDT in BTC_USDT - side: sell refers to the base currency, e.g. BTC in BTC_USDT
» price	string	Trading price, required when type=limit
» time_in_force	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market
» iceberg	string	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported
» auto_repay	boolean	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order
» left	string	Amount left to fill
» filled_amount	string	Amount filled
» fill_price	string	Total filled in quote currency. Deprecated in favor of filled_total
» filled_total	string	Total filled in quote currency
» avg_deal_price	string	Average fill price
» fee	string	Fee deducted
» fee_currency	string	Fee currency unit
» point_fee	string	Points used to deduct fee
» gt_fee	string	GT used to deduct fee
» gt_maker_fee	string	GT amount used to deduct maker fee
» gt_taker_fee	string	GT amount used to deduct taker fee
» gt_discount	boolean	Whether GT fee deduction is enabled
» rebated_fee	string	Rebated fee
» rebated_fee_currency	string	Rebated fee currency unit
» stp_id	integer	Orders between users in the same stp_id group are not allowed to be self-traded 1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker. 2. stp_id returns 0 by default for orders that have not been set for STP group
» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter. 3. If the user did not use stp_act when placing the order, stp_act will return '-' - cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled
» finish_as	string	How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only requirement not met because time-in-force is set to poc (maker-only); rejected after being detected as taker - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown
» stop_profit	object	Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged.
»» trigger_price	string	Take profit trigger price When side == "buy", trigger_price must be greater than price When side == "sell", trigger_price must be less than price
»» order_price	string	Take profit order price
» stop_loss	object	Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged.
»» trigger_price	string	Stop loss trigger price When side == "buy", trigger_price must be less than price When side == "sell", trigger_price must be greater than price
»» order_price	string	Stop-loss order price

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	liquidate_cancelled
finish_as	depth_not_enough
finish_as	trader_not_enough
finish_as	small
finish_as	ioc
finish_as	poc
finish_as	fok
finish_as	stp
finish_as	price_protect_cancelled
finish_as	unknown

WARNING

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

List orders

Code samples

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

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

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

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

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

GET /spot/orders

List orders

Note that query results default to spot order lists for spot, unified account, and isolated margin accounts.

When status is set to open (i.e., when querying pending order lists), only page and limit pagination controls are supported. limit can only be set to a maximum of 100. The side parameter and time range query parameters from and to are not supported.

When status is set to finished (i.e., when querying historical orders), in addition to pagination queries, from and to time range queries are also supported. Additionally, the side parameter can be set to filter one-sided history.

Time range filter parameters are processed according to the order end time.

Parameters

Name	In	Type	Required	Description
currency_pair	query	string	true	Query by specified currency pair. Required for open orders, optional for filled orders
status	query	string	true	List orders based on status open - order is waiting to be filled finished - order has been filled or cancelled
page	query	integer(int32)	false	Page number
limit	query	integer	false	Maximum number of records to be returned. If status is open, maximum of limit is 100
account	query	string	false	Specify query account
from	query	integer(int64)	false	Start timestamp for the query
to	query	integer(int64)	false	End timestamp for the query, defaults to current time if not specified
side	query	string	false	Specify all bids or all asks, both included if not specified

Detailed descriptions

status: List orders based on status

open - order is waiting to be filled
finished - order has been filled or cancelled

Example responses

200 Response

[
  {
    "id": "1852454420",
    "text": "t-abc123",
    "amend_text": "-",
    "create_time": "1710488334",
    "update_time": "1710488334",
    "create_time_ms": 1710488334073,
    "update_time_ms": 1710488334074,
    "status": "closed",
    "currency_pair": "BTC_USDT",
    "trade_quote": "USDC",
    "type": "limit",
    "account": "unified",
    "side": "buy",
    "amount": "0.001",
    "price": "65000",
    "time_in_force": "gtc",
    "iceberg": "0",
    "left": "0",
    "filled_amount": "0.001",
    "fill_price": "63.4693",
    "filled_total": "63.4693",
    "avg_deal_price": "63469.3",
    "fee": "0.00000022",
    "fee_currency": "BTC",
    "point_fee": "0",
    "gt_fee": "0",
    "gt_maker_fee": "0",
    "gt_taker_fee": "0",
    "gt_discount": false,
    "rebated_fee": "0",
    "rebated_fee_currency": "USDT",
    "finish_as": "filled",
    "stop_profit": {
      "trigger_price": "67000",
      "order_price": "67000"
    },
    "stop_loss": {
      "trigger_price": "63000",
      "order_price": "63000"
    }
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	[Spot order details]
» None	Order	Spot order details
»» id	string	Order ID
»» text	string	User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- 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: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders liquidate represents isolated-margin liquidation orders
»» amend_text	string	The custom data that the user remarked when amending the order
»» create_time	string	Creation time of order
»» update_time	string	Last modification time of order
»» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
»» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
»» status	string	Order status - open: to be filled - closed: closed order - cancelled: cancelled
»» currency_pair	string	Currency pair
»» trade_quote	string	Actual quote currency used for the trade; can be specified only in a unified market
»» type	string	Order Type - limit : Limit Order - market : Market Order
»» account	string	Account type, spot - spot account, margin - leveraged account, unified - unified account
»» side	string	Buy or sell order
»» amount	string	Trade amount When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT. When type is market, the meaning depends on the side: - side: buy refers to the quote currency, e.g. USDT in BTC_USDT - side: sell refers to the base currency, e.g. BTC in BTC_USDT
»» price	string	Trading price, required when type=limit
»» time_in_force	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market
»» iceberg	string	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported
»» auto_repay	boolean	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order
»» left	string	Amount left to fill
»» filled_amount	string	Amount filled
»» fill_price	string	Total filled in quote currency. Deprecated in favor of filled_total
»» filled_total	string	Total filled in quote currency
»» avg_deal_price	string	Average fill price
»» fee	string	Fee deducted
»» fee_currency	string	Fee currency unit
»» point_fee	string	Points used to deduct fee
»» gt_fee	string	GT used to deduct fee
»» gt_maker_fee	string	GT amount used to deduct maker fee
»» gt_taker_fee	string	GT amount used to deduct taker fee
»» gt_discount	boolean	Whether GT fee deduction is enabled
»» rebated_fee	string	Rebated fee
»» rebated_fee_currency	string	Rebated fee currency unit
»» stp_id	integer	Orders between users in the same stp_id group are not allowed to be self-traded 1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker. 2. stp_id returns 0 by default for orders that have not been set for STP group
»» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter. 3. If the user did not use stp_act when placing the order, stp_act will return '-' - cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled
»» finish_as	string	How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only requirement not met because time-in-force is set to poc (maker-only); rejected after being detected as taker - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown
»» stop_profit	object	Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged.
»»» trigger_price	string	Take profit trigger price When side == "buy", trigger_price must be greater than price When side == "sell", trigger_price must be less than price
»»» order_price	string	Take profit order price
»» stop_loss	object	Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged.
»»» trigger_price	string	Stop loss trigger price When side == "buy", trigger_price must be less than price When side == "sell", trigger_price must be greater than price
»»» order_price	string	Stop-loss order price

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	liquidate_cancelled
finish_as	depth_not_enough
finish_as	trader_not_enough
finish_as	small
finish_as	ioc
finish_as	poc
finish_as	fok
finish_as	stp
finish_as	price_protect_cancelled
finish_as	unknown

WARNING

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

Create order

Code samples

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

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

url = '/spot/orders'
query_param = ''
body='{"text":"t-abc123","currency_pair":"BTC_USDT","trade_quote":"USDC","type":"limit","account":"unified","side":"buy","amount":"0.001","price":"65000","time_in_force":"gtc","iceberg":"0","slippage":"0.05","stop_profit":{"trigger_price":"67000","order_price":"67000"},"stop_loss":{"trigger_price":"63000","order_price":"63000"}}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/orders"
query_param=""
body_param='{"text":"t-abc123","currency_pair":"BTC_USDT","trade_quote":"USDC","type":"limit","account":"unified","side":"buy","amount":"0.001","price":"65000","time_in_force":"gtc","iceberg":"0","slippage":"0.05","stop_profit":{"trigger_price":"67000","order_price":"67000"},"stop_loss":{"trigger_price":"63000","order_price":"63000"}}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /spot/orders

Create order

Supports placing orders from spot, margin, leveraged, and cross-margin accounts. Use the account field to select the account type. The default is spot, which places an order from the spot account. For a unified account, orders use the unified account by default.

When trading with a margin account by setting account to margin, you can set auto_borrow to true. If the account balance is insufficient, the system automatically calls POST /margin/uni/loans to borrow the shortfall. Whether assets received from a filled margin order are automatically used to repay an isolated-margin loan depends on the automatic repayment setting of the user's isolated-margin account. Use /margin/auto_repay to query or update this account-level automatic repayment setting.

When trading with a unified account by setting account to unified, auto_borrow can likewise be enabled to borrow any shortfall. Unlike an isolated-margin account, whether a unified-account order repays automatically depends on the order's auto_repay setting. This setting applies only to the current order, so only assets received when that order is filled are used to repay the cross-margin loan. Unified-account orders currently support enabling both auto_borrow and auto_repay.

Automatic repayment is triggered when the order finishes, that is, when status becomes cancelled or closed.

Order status

A resting order remains open until its entire quantity is filled. Once fully filled, the order finishes and its status becomes closed. If the order is cancelled before being fully filled, its status becomes cancelled regardless of whether it was partially filled.

Iceberg orders

Use iceberg to set the displayed quantity of an iceberg order. Fully hidden orders are not supported. Note that fills against the hidden portion are charged at the taker fee rate.

Self-trade prevention

Set stp_act to select the self-trade prevention action.

Unified market

A unified market supports matching orders that use different quote currencies. Specify the actual quote currency through trade_quote. For example, the BTC_USD market can match orders quoted in USDC, RLUSD, and other supported quote currencies. Query GET /spot/currency_pairs for the quote currencies supported by each unified market.

Body parameter

{
  "text": "t-abc123",
  "currency_pair": "BTC_USDT",
  "trade_quote": "USDC",
  "type": "limit",
  "account": "unified",
  "side": "buy",
  "amount": "0.001",
  "price": "65000",
  "time_in_force": "gtc",
  "iceberg": "0",
  "slippage": "0.05",
  "stop_profit": {
    "trigger_price": "67000",
    "order_price": "67000"
  },
  "stop_loss": {
    "trigger_price": "63000",
    "order_price": "63000"
  }
}

Parameters

Name	In	Type	Required	Description
x-gate-exptime	header	string	false	Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected
body	body	Order	true	none
» text	body	string	false	User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- prefix 3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders liquidate represents isolated-margin liquidation orders
» currency_pair	body	string	true	Currency pair
» trade_quote	body	string	false	Actual quote currency used for the trade; can be specified only in a unified market
» type	body	string	false	Order Type - limit : Limit Order - market : Market Order
» account	body	string	false	Account type, spot - spot account, margin - leveraged account, unified - unified account
» side	body	string	true	Buy or sell order
» amount	body	string	true	Trade amount When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT. When type is market, the meaning depends on the side: - side: buy refers to the quote currency, e.g. USDT in BTC_USDT - side: sell refers to the base currency, e.g. BTC in BTC_USDT
» price	body	string	false	Trading price, required when type=limit
» time_in_force	body	string	false	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market
» iceberg	body	string	false	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported
» auto_borrow	body	boolean	false	Used in margin or cross margin trading to allow automatic loan of insufficient amount if balance is not enough
» auto_repay	body	boolean	false	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order
» stp_act	body	string	false	Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter. 3. If the user did not use stp_act when placing the order, stp_act will return '-' - cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled
» action_mode	body	string	false	Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)
» slippage	body	string	false	Maximum supported slippage ratio for Spot Market Order Placement, calculated based on the latest market price at the time of order placement as the benchmark (Example: 0.03 means 3%)
» stop_profit	body	object	false	Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged.
»» trigger_price	body	string	false	Take profit trigger price When side == "buy", trigger_price must be greater than price When side == "sell", trigger_price must be less than price
»» order_price	body	string	false	Take profit order price
» stop_loss	body	object	false	Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged.
»» trigger_price	body	string	false	Stop loss trigger price When side == "buy", trigger_price must be less than price When side == "sell", trigger_price must be greater than price
»» order_price	body	string	false	Stop-loss order price

Detailed descriptions

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

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

Besides user defined information, reserved contents are listed below, denoting how the order is created:

- 101: from android
- 102: from IOS
- 103: from IPAD
- 104: from webapp
- 3: from web
- 2: from apiv2
- apiv4: from apiv4
pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders
liquidate represents isolated-margin liquidation orders

» type: Order Type

- limit : Limit Order
- market : Market Order

» amount: Trade amount
When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT.
When type is market, the meaning depends on the side:
- side: buy refers to the quote currency, e.g. USDT in BTC_USDT
- side: sell refers to the base currency, e.g. BTC in BTC_USDT

» time_in_force: Time in force

- gtc: GoodTillCancelled
- ioc: ImmediateOrCancelled, taker only
- poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee
- fok: FillOrKill, fill either completely or none
Only ioc and fok are supported when type=market

» auto_repay: Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that:

1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders.
2. auto_borrow and auto_repay can be both set to true in one order

» stp_act: Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies

1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy.
2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter.
3. If the user did not use stp_act when placing the order, stp_act will return '-'

- cn: Cancel newest, cancel new orders and keep old ones
- co: Cancel oldest, cancel old orders and keep new ones
- cb: Cancel both, both old and new orders will be cancelled

» action_mode: Processing Mode:
When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result
ACK: Asynchronous mode, only returns key order fields
RESULT: No clearing information
FULL: Full mode (default)

»» trigger_price: Take profit trigger price
When side == "buy", trigger_price must be greater than price
When side == "sell", trigger_price must be less than price

»» trigger_price: Stop loss trigger price
When side == "buy", trigger_price must be less than price
When side == "sell", trigger_price must be greater than price

Enumerated Values

Parameter	Value
» type	limit
» type	market
» side	buy
» side	sell
» time_in_force	gtc
» time_in_force	ioc
» time_in_force	poc
» time_in_force	fok
» stp_act	cn
» stp_act	co
» stp_act	cb
» stp_act	-

Example responses

ACK response body example

{
  "id": "12332324",
  "text": "t-123456",
  "amend_text": "test2"
}

RESULT response body example

{
  "id": "12332324",
  "text": "t-123456",
  "create_time": "1548000000",
  "update_time": "1548000100",
  "create_time_ms": 1548000000123,
  "update_time_ms": 1548000100123,
  "currency_pair": "ETH_BTC",
  "status": "cancelled",
  "type": "limit",
  "account": "spot",
  "side": "buy",
  "iceberg": "0",
  "amount": "1",
  "price": "5.00032",
  "time_in_force": "gtc",
  "auto_borrow": false,
  "left": "0.5",
  "filled_total": "2.50016",
  "avg_deal_price": "5.00032",
  "stp_act": "cn",
  "finish_as": "stp",
  "stp_id": 10240
}

FULL response body example

{
  "id": "1852454420",
  "text": "t-abc123",
  "amend_text": "-",
  "create_time": "1710488334",
  "update_time": "1710488334",
  "create_time_ms": 1710488334073,
  "update_time_ms": 1710488334074,
  "status": "closed",
  "currency_pair": "BTC_USDT",
  "trade_quote": "USDC",
  "type": "limit",
  "account": "unified",
  "side": "buy",
  "amount": "0.001",
  "price": "65000",
  "time_in_force": "gtc",
  "iceberg": "0",
  "left": "0",
  "filled_amount": "0.001",
  "fill_price": "63.4693",
  "filled_total": "63.4693",
  "avg_deal_price": "63469.3",
  "fee": "0.00000022",
  "fee_currency": "BTC",
  "point_fee": "0",
  "gt_fee": "0",
  "gt_maker_fee": "0",
  "gt_taker_fee": "0",
  "gt_discount": false,
  "rebated_fee": "0",
  "rebated_fee_currency": "USDT",
  "finish_as": "filled",
  "slippage": "0.05",
  "stop_profit": {
    "trigger_price": "67000",
    "order_price": "67000"
  },
  "stop_loss": {
    "trigger_price": "63000",
    "order_price": "63000"
  }
}

Responses

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

Response Schema

Status Code 201

Spot order details

Name	Type	Description
» id	string	Order ID
» text	string	User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- 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: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders liquidate represents isolated-margin liquidation orders
» amend_text	string	The custom data that the user remarked when amending the order
» create_time	string	Creation time of order
» update_time	string	Last modification time of order
» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
» status	string	Order status - open: to be filled - closed: closed order - cancelled: cancelled
» currency_pair	string	Currency pair
» trade_quote	string	Actual quote currency used for the trade; can be specified only in a unified market
» type	string	Order Type - limit : Limit Order - market : Market Order
» account	string	Account type, spot - spot account, margin - leveraged account, unified - unified account
» side	string	Buy or sell order
» amount	string	Trade amount When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT. When type is market, the meaning depends on the side: - side: buy refers to the quote currency, e.g. USDT in BTC_USDT - side: sell refers to the base currency, e.g. BTC in BTC_USDT
» price	string	Trading price, required when type=limit
» time_in_force	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market
» iceberg	string	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported
» auto_borrow	boolean	Used in margin or cross margin trading to allow automatic loan of insufficient amount if balance is not enough
» auto_repay	boolean	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order
» left	string	Amount left to fill
» filled_amount	string	Amount filled
» fill_price	string	Total filled in quote currency. Deprecated in favor of filled_total
» filled_total	string	Total filled in quote currency
» avg_deal_price	string	Average fill price
» fee	string	Fee deducted
» fee_currency	string	Fee currency unit
» point_fee	string	Points used to deduct fee
» gt_fee	string	GT used to deduct fee
» gt_maker_fee	string	GT amount used to deduct maker fee
» gt_taker_fee	string	GT amount used to deduct taker fee
» gt_discount	boolean	Whether GT fee deduction is enabled
» rebated_fee	string	Rebated fee
» rebated_fee_currency	string	Rebated fee currency unit
» stp_id	integer	Orders between users in the same stp_id group are not allowed to be self-traded 1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker. 2. stp_id returns 0 by default for orders that have not been set for STP group
» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter. 3. If the user did not use stp_act when placing the order, stp_act will return '-' - cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled
» finish_as	string	How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only requirement not met because time-in-force is set to poc (maker-only); rejected after being detected as taker - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown
» action_mode	string	Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)
» slippage	string	Maximum supported slippage ratio for Spot Market Order Placement, calculated based on the latest market price at the time of order placement as the benchmark (Example: 0.03 means 3%)
» stop_profit	object	Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged.
»» trigger_price	string	Take profit trigger price When side == "buy", trigger_price must be greater than price When side == "sell", trigger_price must be less than price
»» order_price	string	Take profit order price
» stop_loss	object	Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged.
»» trigger_price	string	Stop loss trigger price When side == "buy", trigger_price must be less than price When side == "sell", trigger_price must be greater than price
»» order_price	string	Stop-loss order price

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	liquidate_cancelled
finish_as	depth_not_enough
finish_as	trader_not_enough
finish_as	small
finish_as	ioc
finish_as	poc
finish_as	fok
finish_as	stp
finish_as	price_protect_cancelled
finish_as	unknown

WARNING

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

Cancel all open orders in specified currency pair

Code samples

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

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

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

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

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

DELETE /spot/orders

Cancel all open orders in specified currency pair

When the account parameter is not specified, all pending orders including spot, unified account, and isolated margin will be cancelled. When currency_pair is not specified, all trading pair pending orders will be cancelled. You can specify a particular account to cancel all pending orders under that account

Parameters

Name	In	Type	Required	Description
currency_pair	query	string	false	Currency pair
side	query	string	false	Specify all bids or all asks, both included if not specified
account	query	string	false	Specify account type Classic account: All are included if not specified Unified account: Specify unified
trade_quote	query	string	false	In a unified market only, specifies the actual quote currency for cancellation; when omitted, all orders matching the other criteria are cancelled
action_mode	query	string	false	Processing Mode When placing an order, different fields are returned based on the action_mode - ACK: Asynchronous mode, returns only key order fields - RESULT: No clearing information - FULL: Full mode (default)
x-gate-exptime	header	string	false	Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected

Detailed descriptions

account: Specify account type

Classic account: All are included if not specified
Unified account: Specify unified

action_mode: Processing Mode

When placing an order, different fields are returned based on the action_mode

- ACK: Asynchronous mode, returns only key order fields
- RESULT: No clearing information
- FULL: Full mode (default)

Example responses

200 Response

[
  {
    "id": "1852454420",
    "text": "t-abc123",
    "amend_text": "-",
    "succeeded": true,
    "create_time": "1710488334",
    "update_time": "1710488334",
    "create_time_ms": 1710488334073,
    "update_time_ms": 1710488334074,
    "status": "closed",
    "currency_pair": "BTC_USDT",
    "type": "limit",
    "account": "unified",
    "side": "buy",
    "amount": "0.001",
    "price": "65000",
    "time_in_force": "gtc",
    "iceberg": "0",
    "left": "0",
    "filled_amount": "0.001",
    "fill_price": "63.4693",
    "filled_total": "63.4693",
    "avg_deal_price": "63469.3",
    "fee": "0.00000022",
    "fee_currency": "BTC",
    "point_fee": "0",
    "gt_fee": "0",
    "gt_maker_fee": "0",
    "gt_taker_fee": "0",
    "gt_discount": false,
    "rebated_fee": "0",
    "rebated_fee_currency": "USDT",
    "finish_as": "filled"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	[Spot order details]
» None	OrderCancel	Spot order details
»» id	string	Order ID
»» text	string	User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- 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: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4
»» amend_text	string	The custom data that the user remarked when amending the order
»» succeeded	boolean	Request execution result
»» label	string	Error label, if any, otherwise an empty string
»» message	string	Detailed error message, if any, otherwise an empty string
»» create_time	string	Creation time of order
»» update_time	string	Last modification time of order
»» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
»» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
»» status	string	Order status - open: to be filled - closed: closed order - cancelled: cancelled
»» currency_pair	string	Currency pair
»» type	string	Order Type - limit : Limit Order - market : Market Order
»» account	string	Account type, spot - spot account, margin - leveraged account, unified - unified account
»» side	string	Buy or sell order
»» amount	string	Trading quantity When type is limit, it refers to the base currency (the currency being traded), such as BTC in BTC_USDT When type is market, it refers to different currencies based on the side: - side: buy refers to quote currency, BTC_USDT means USDT - side: sell refers to base currency, BTC_USDT means BTC
»» price	string	Trading price, required when type=limit
»» time_in_force	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market
»» iceberg	string	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported
»» auto_repay	boolean	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order
»» left	string	Amount left to fill
»» filled_amount	string	Amount filled
»» fill_price	string	Total filled in quote currency. Deprecated in favor of filled_total
»» filled_total	string	Total filled in quote currency
»» avg_deal_price	string	Average fill price
»» fee	string	Fee deducted
»» fee_currency	string	Fee currency unit
»» point_fee	string	Points used to deduct fee
»» gt_fee	string	GT used to deduct fee
»» gt_maker_fee	string	GT amount used to deduct maker fee
»» gt_taker_fee	string	GT amount used to deduct taker fee
»» gt_discount	boolean	Whether GT fee deduction is enabled
»» rebated_fee	string	Rebated fee
»» rebated_fee_currency	string	Rebated fee currency unit
»» stp_id	integer	Orders between users in the same stp_id group are not allowed to be self-traded 1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker. 2. stp_id returns 0 by default for orders that have not been set for STP group
»» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter. 3. If the user did not use stp_act when placing the order, stp_act will return '-' - cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled
»» finish_as	string	How the order was finished. - open: processing - filled: filled totally - cancelled: manually cancelled - ioc: time in force is IOC, finish immediately - stp: cancelled because self trade prevention

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	ioc
finish_as	stp

WARNING

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

Cancel batch orders by specified ID list

Code samples

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

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

url = '/spot/cancel_batch_orders'
query_param = ''
body='[{"currency_pair":"BTC_USDT","id":"123456"}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

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

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

POST /spot/cancel_batch_orders

Cancel batch orders by specified ID list

Multiple currency pairs can be specified, but maximum 20 orders are allowed per request

Body parameter

[
  {
    "currency_pair": "BTC_USDT",
    "id": "123456"
  }
]

Parameters

Name	In	Type	Required	Description
x-gate-exptime	header	string	false	Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected
body	body	array[CancelBatchOrder]	true	none

Example responses

200 Response

[
  {
    "currency_pair": "BTC_USDT",
    "id": "123456",
    "text": "123456",
    "succeeded": true,
    "label": null,
    "message": null
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
» CancelOrderResult	object	Order cancellation result
»» currency_pair	string	Order currency pair
»» id	string	Order ID
»» text	string	Custom order information
»» succeeded	boolean	Whether cancellation succeeded
»» label	string	Error label when failed to cancel the order; emtpy if succeeded
»» message	string	Error description when cancellation fails, empty if successful
»» account	string	Default is empty (deprecated)

WARNING

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

Query single order details

Code samples

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

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

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

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

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

GET /spot/orders/{order_id}

Query single order details

By default, queries orders for spot, unified account, and isolated margin accounts.

Parameters

Name	In	Type	Required	Description
order_id	path	string	true	The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field). Operations based on custom IDs can only be checked in pending orders. Only order ID can be used after the order is finished (transaction/cancel)
currency_pair	query	string	true	Specify the trading pair to query. This field is required when querying pending order records. This field can be omitted when querying filled order records.
account	query	string	false	Specify query account

Detailed descriptions

order_id: The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field).
Operations based on custom IDs can only be checked in pending orders. Only order ID can be used after the order is finished (transaction/cancel)

Example responses

200 Response

{
  "id": "1852454420",
  "text": "t-abc123",
  "amend_text": "-",
  "create_time": "1710488334",
  "update_time": "1710488334",
  "create_time_ms": 1710488334073,
  "update_time_ms": 1710488334074,
  "status": "closed",
  "currency_pair": "BTC_USDT",
  "trade_quote": "USDC",
  "type": "limit",
  "account": "unified",
  "side": "buy",
  "amount": "0.001",
  "price": "65000",
  "time_in_force": "gtc",
  "iceberg": "0",
  "left": "0",
  "filled_amount": "0.001",
  "fill_price": "63.4693",
  "filled_total": "63.4693",
  "avg_deal_price": "63469.3",
  "fee": "0.00000022",
  "fee_currency": "BTC",
  "point_fee": "0",
  "gt_fee": "0",
  "gt_maker_fee": "0",
  "gt_taker_fee": "0",
  "gt_discount": false,
  "rebated_fee": "0",
  "rebated_fee_currency": "USDT",
  "finish_as": "filled",
  "stop_profit": {
    "trigger_price": "67000",
    "order_price": "67000"
  },
  "stop_loss": {
    "trigger_price": "63000",
    "order_price": "63000"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Detail retrieved	Order

Response Schema

Status Code 200

Spot order details

Name	Type	Description
» id	string	Order ID
» text	string	User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- 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: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders liquidate represents isolated-margin liquidation orders
» amend_text	string	The custom data that the user remarked when amending the order
» create_time	string	Creation time of order
» update_time	string	Last modification time of order
» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
» status	string	Order status - open: to be filled - closed: closed order - cancelled: cancelled
» currency_pair	string	Currency pair
» trade_quote	string	Actual quote currency used for the trade; can be specified only in a unified market
» type	string	Order Type - limit : Limit Order - market : Market Order
» account	string	Account type, spot - spot account, margin - leveraged account, unified - unified account
» side	string	Buy or sell order
» amount	string	Trade amount When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT. When type is market, the meaning depends on the side: - side: buy refers to the quote currency, e.g. USDT in BTC_USDT - side: sell refers to the base currency, e.g. BTC in BTC_USDT
» price	string	Trading price, required when type=limit
» time_in_force	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market
» iceberg	string	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported
» auto_repay	boolean	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order
» left	string	Amount left to fill
» filled_amount	string	Amount filled
» fill_price	string	Total filled in quote currency. Deprecated in favor of filled_total
» filled_total	string	Total filled in quote currency
» avg_deal_price	string	Average fill price
» fee	string	Fee deducted
» fee_currency	string	Fee currency unit
» point_fee	string	Points used to deduct fee
» gt_fee	string	GT used to deduct fee
» gt_maker_fee	string	GT amount used to deduct maker fee
» gt_taker_fee	string	GT amount used to deduct taker fee
» gt_discount	boolean	Whether GT fee deduction is enabled
» rebated_fee	string	Rebated fee
» rebated_fee_currency	string	Rebated fee currency unit
» stp_id	integer	Orders between users in the same stp_id group are not allowed to be self-traded 1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker. 2. stp_id returns 0 by default for orders that have not been set for STP group
» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter. 3. If the user did not use stp_act when placing the order, stp_act will return '-' - cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled
» finish_as	string	How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only requirement not met because time-in-force is set to poc (maker-only); rejected after being detected as taker - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown
» stop_profit	object	Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged.
»» trigger_price	string	Take profit trigger price When side == "buy", trigger_price must be greater than price When side == "sell", trigger_price must be less than price
»» order_price	string	Take profit order price
» stop_loss	object	Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged.
»» trigger_price	string	Stop loss trigger price When side == "buy", trigger_price must be less than price When side == "sell", trigger_price must be greater than price
»» order_price	string	Stop-loss order price

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	liquidate_cancelled
finish_as	depth_not_enough
finish_as	trader_not_enough
finish_as	small
finish_as	ioc
finish_as	poc
finish_as	fok
finish_as	stp
finish_as	price_protect_cancelled
finish_as	unknown

WARNING

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

Amend single order

Code samples

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

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

url = '/spot/orders/12345'
query_param = ''
body='{"currency_pair":"BTC_USDT","account":"spot","amount":"1","stop_profit":{"trigger_price":"67000","order_price":"67000"},"stop_loss":{"trigger_price":"63000","order_price":"63000"}}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('PATCH', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('PATCH', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="PATCH"
url="/spot/orders/12345"
query_param=""
body_param='{"currency_pair":"BTC_USDT","account":"spot","amount":"1","stop_profit":{"trigger_price":"67000","order_price":"67000"},"stop_loss":{"trigger_price":"63000","order_price":"63000"}}'
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"

PATCH /spot/orders/{order_id}

Amend single order

Modify orders in spot, unified account and isolated margin account by default.

Currently both request body and query support currency_pair and account parameters, but request body has higher priority.

currency_pair must be filled in one of the request body or query parameters.

About rate limit: Order modification and order creation share the same rate limit rules.

About matching priority: Only reducing the quantity does not affect the matching priority. Modifying the price or increasing the quantity will adjust the priority to the end of the new price level.

Note: Modifying the quantity to be less than the filled quantity will trigger a cancellation and isolated margin account by default.

Currently both request body and query support currency_pair and account parameters, but request body has higher priority.

currency_pair must be filled in one of the request body or query parameters.

About rate limit: Order modification and order creation share the same rate limit rules.

About matching priority: Only reducing the quantity does not affect the matching priority. Modifying the price or increasing the quantity will adjust the priority to the end of the new price level.

Note: Modifying the quantity to be less than the filled quantity will trigger a cancellation operation.

Body parameter

{
  "currency_pair": "BTC_USDT",
  "account": "spot",
  "amount": "1",
  "stop_profit": {
    "trigger_price": "67000",
    "order_price": "67000"
  },
  "stop_loss": {
    "trigger_price": "63000",
    "order_price": "63000"
  }
}

Parameters

Name	In	Type	Required	Description
order_id	path	string	true	The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field). Operations based on custom IDs can only be checked in pending orders. Only order ID can be used after the order is finished (transaction/cancel)
currency_pair	query	string	false	Currency pair
account	query	string	false	Specify query account
x-gate-exptime	header	string	false	Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected
body	body	OrderPatch	true	none
» currency_pair	body	string	false	Currency pair
» account	body	string	false	Specify query account
» amount	body	string	false	Trading quantity. Either amount or price must be specified
» price	body	string	false	Trading price. Either amount or price must be specified
» amend_text	body	string	false	Custom info during order amendment
» action_mode	body	string	false	Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)
» stop_profit	body	object	false	Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged.
»» trigger_price	body	string	false	Take profit trigger price When side == "buy", trigger_price must be greater than price When side == "sell", trigger_price must be less than price
»» order_price	body	string	false	Take profit order price
» stop_loss	body	object	false	Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged.
»» trigger_price	body	string	false	Stop loss trigger price When side == "buy", trigger_price must be less than price When side == "sell", trigger_price must be greater than price
»» order_price	body	string	false	Stop-loss order price

Detailed descriptions

order_id: The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field).
Operations based on custom IDs can only be checked in pending orders. Only order ID can be used after the order is finished (transaction/cancel)

» action_mode: Processing Mode:
When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result
ACK: Asynchronous mode, only returns key order fields
RESULT: No clearing information
FULL: Full mode (default)

»» trigger_price: Take profit trigger price
When side == "buy", trigger_price must be greater than price
When side == "sell", trigger_price must be less than price

»» trigger_price: Stop loss trigger price
When side == "buy", trigger_price must be less than price
When side == "sell", trigger_price must be greater than price

Example responses

200 Response

{
  "id": "1852454420",
  "text": "t-abc123",
  "amend_text": "-",
  "create_time": "1710488334",
  "update_time": "1710488334",
  "create_time_ms": 1710488334073,
  "update_time_ms": 1710488334074,
  "status": "closed",
  "currency_pair": "BTC_USDT",
  "trade_quote": "USDC",
  "type": "limit",
  "account": "unified",
  "side": "buy",
  "amount": "0.001",
  "price": "65000",
  "time_in_force": "gtc",
  "iceberg": "0",
  "left": "0",
  "filled_amount": "0.001",
  "fill_price": "63.4693",
  "filled_total": "63.4693",
  "avg_deal_price": "63469.3",
  "fee": "0.00000022",
  "fee_currency": "BTC",
  "point_fee": "0",
  "gt_fee": "0",
  "gt_maker_fee": "0",
  "gt_taker_fee": "0",
  "gt_discount": false,
  "rebated_fee": "0",
  "rebated_fee_currency": "USDT",
  "finish_as": "filled",
  "stop_profit": {
    "trigger_price": "67000",
    "order_price": "67000"
  },
  "stop_loss": {
    "trigger_price": "63000",
    "order_price": "63000"
  }
}

Responses

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

Response Schema

Status Code 200

Spot order details

Name	Type	Description
» id	string	Order ID
» text	string	User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- 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: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders liquidate represents isolated-margin liquidation orders
» amend_text	string	The custom data that the user remarked when amending the order
» create_time	string	Creation time of order
» update_time	string	Last modification time of order
» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
» status	string	Order status - open: to be filled - closed: closed order - cancelled: cancelled
» currency_pair	string	Currency pair
» trade_quote	string	Actual quote currency used for the trade; can be specified only in a unified market
» type	string	Order Type - limit : Limit Order - market : Market Order
» account	string	Account type, spot - spot account, margin - leveraged account, unified - unified account
» side	string	Buy or sell order
» amount	string	Trade amount When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT. When type is market, the meaning depends on the side: - side: buy refers to the quote currency, e.g. USDT in BTC_USDT - side: sell refers to the base currency, e.g. BTC in BTC_USDT
» price	string	Trading price, required when type=limit
» time_in_force	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market
» iceberg	string	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported
» auto_repay	boolean	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order
» left	string	Amount left to fill
» filled_amount	string	Amount filled
» fill_price	string	Total filled in quote currency. Deprecated in favor of filled_total
» filled_total	string	Total filled in quote currency
» avg_deal_price	string	Average fill price
» fee	string	Fee deducted
» fee_currency	string	Fee currency unit
» point_fee	string	Points used to deduct fee
» gt_fee	string	GT used to deduct fee
» gt_maker_fee	string	GT amount used to deduct maker fee
» gt_taker_fee	string	GT amount used to deduct taker fee
» gt_discount	boolean	Whether GT fee deduction is enabled
» rebated_fee	string	Rebated fee
» rebated_fee_currency	string	Rebated fee currency unit
» stp_id	integer	Orders between users in the same stp_id group are not allowed to be self-traded 1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker. 2. stp_id returns 0 by default for orders that have not been set for STP group
» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter. 3. If the user did not use stp_act when placing the order, stp_act will return '-' - cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled
» finish_as	string	How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only requirement not met because time-in-force is set to poc (maker-only); rejected after being detected as taker - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown
» stop_profit	object	Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged.
»» trigger_price	string	Take profit trigger price When side == "buy", trigger_price must be greater than price When side == "sell", trigger_price must be less than price
»» order_price	string	Take profit order price
» stop_loss	object	Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged.
»» trigger_price	string	Stop loss trigger price When side == "buy", trigger_price must be less than price When side == "sell", trigger_price must be greater than price
»» order_price	string	Stop-loss order price

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	liquidate_cancelled
finish_as	depth_not_enough
finish_as	trader_not_enough
finish_as	small
finish_as	ioc
finish_as	poc
finish_as	fok
finish_as	stp
finish_as	price_protect_cancelled
finish_as	unknown

WARNING

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

Cancel single order

Code samples

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

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

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

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

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

DELETE /spot/orders/{order_id}

Cancel single order

By default, orders for spot, unified accounts and leveraged accounts are revoked.

Parameters

Name	In	Type	Required	Description
order_id	path	string	true	The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field). Operations based on custom IDs can only be checked in pending orders. Only order ID can be used after the order is finished (transaction/cancel)
currency_pair	query	string	true	Currency pair
account	query	string	false	Specify query account
action_mode	query	string	false	Processing Mode When placing an order, different fields are returned based on the action_mode - ACK: Asynchronous mode, returns only key order fields - RESULT: No clearing information - FULL: Full mode (default)
x-gate-exptime	header	string	false	Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected

Detailed descriptions

order_id: The order ID returned when the order was successfully created or the custom ID specified by the user's creation (i.e. the text field).
Operations based on custom IDs can only be checked in pending orders. Only order ID can be used after the order is finished (transaction/cancel)

action_mode: Processing Mode

When placing an order, different fields are returned based on the action_mode

- ACK: Asynchronous mode, returns only key order fields
- RESULT: No clearing information
- FULL: Full mode (default)

Example responses

200 Response

{
  "id": "1852454420",
  "text": "t-abc123",
  "amend_text": "-",
  "create_time": "1710488334",
  "update_time": "1710488334",
  "create_time_ms": 1710488334073,
  "update_time_ms": 1710488334074,
  "status": "closed",
  "currency_pair": "BTC_USDT",
  "trade_quote": "USDC",
  "type": "limit",
  "account": "unified",
  "side": "buy",
  "amount": "0.001",
  "price": "65000",
  "time_in_force": "gtc",
  "iceberg": "0",
  "left": "0",
  "filled_amount": "0.001",
  "fill_price": "63.4693",
  "filled_total": "63.4693",
  "avg_deal_price": "63469.3",
  "fee": "0.00000022",
  "fee_currency": "BTC",
  "point_fee": "0",
  "gt_fee": "0",
  "gt_maker_fee": "0",
  "gt_taker_fee": "0",
  "gt_discount": false,
  "rebated_fee": "0",
  "rebated_fee_currency": "USDT",
  "finish_as": "filled",
  "stop_profit": {
    "trigger_price": "67000",
    "order_price": "67000"
  },
  "stop_loss": {
    "trigger_price": "63000",
    "order_price": "63000"
  }
}

Responses

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

Response Schema

Status Code 200

Spot order details

Name	Type	Description
» id	string	Order ID
» text	string	User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- 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: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders liquidate represents isolated-margin liquidation orders
» amend_text	string	The custom data that the user remarked when amending the order
» create_time	string	Creation time of order
» update_time	string	Last modification time of order
» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
» status	string	Order status - open: to be filled - closed: closed order - cancelled: cancelled
» currency_pair	string	Currency pair
» trade_quote	string	Actual quote currency used for the trade; can be specified only in a unified market
» type	string	Order Type - limit : Limit Order - market : Market Order
» account	string	Account type, spot - spot account, margin - leveraged account, unified - unified account
» side	string	Buy or sell order
» amount	string	Trade amount When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT. When type is market, the meaning depends on the side: - side: buy refers to the quote currency, e.g. USDT in BTC_USDT - side: sell refers to the base currency, e.g. BTC in BTC_USDT
» price	string	Trading price, required when type=limit
» time_in_force	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market
» iceberg	string	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported
» auto_repay	boolean	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order
» left	string	Amount left to fill
» filled_amount	string	Amount filled
» fill_price	string	Total filled in quote currency. Deprecated in favor of filled_total
» filled_total	string	Total filled in quote currency
» avg_deal_price	string	Average fill price
» fee	string	Fee deducted
» fee_currency	string	Fee currency unit
» point_fee	string	Points used to deduct fee
» gt_fee	string	GT used to deduct fee
» gt_maker_fee	string	GT amount used to deduct maker fee
» gt_taker_fee	string	GT amount used to deduct taker fee
» gt_discount	boolean	Whether GT fee deduction is enabled
» rebated_fee	string	Rebated fee
» rebated_fee_currency	string	Rebated fee currency unit
» stp_id	integer	Orders between users in the same stp_id group are not allowed to be self-traded 1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker. 2. stp_id returns 0 by default for orders that have not been set for STP group
» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter. 3. If the user did not use stp_act when placing the order, stp_act will return '-' - cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled
» finish_as	string	How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only requirement not met because time-in-force is set to poc (maker-only); rejected after being detected as taker - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown
» stop_profit	object	Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged.
»» trigger_price	string	Take profit trigger price When side == "buy", trigger_price must be greater than price When side == "sell", trigger_price must be less than price
»» order_price	string	Take profit order price
» stop_loss	object	Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged.
»» trigger_price	string	Stop loss trigger price When side == "buy", trigger_price must be less than price When side == "sell", trigger_price must be greater than price
»» order_price	string	Stop-loss order price

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	liquidate_cancelled
finish_as	depth_not_enough
finish_as	trader_not_enough
finish_as	small
finish_as	ioc
finish_as	poc
finish_as	fok
finish_as	stp
finish_as	price_protect_cancelled
finish_as	unknown

WARNING

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

Query personal trading records

Code samples

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

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

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

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

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

GET /spot/my_trades

Query personal trading records

By default query of transaction records for spot, unified account and warehouse-by-site leverage accounts.

The history within a specified time range can be queried by specifying from or (and) to.

• If no time parameters are specified, only data for the last 7 days can be obtained.
• If only any parameter of from or to is specified, only 7-day data from the start (or end) of the specified time is returned.
• The range not allowed to exceed 30 days.

The parameters of the time range filter are processed according to the order end time.

The maximum number of pages when searching data using limit&page paging function is 100,000, that is, limit * (page - 1) <= 100,000.

Parameters

Name	In	Type	Required	Description
currency_pair	query	string	false	Retrieve results with specified currency pair
limit	query	integer	false	Maximum number of items returned in list. Default: 100, minimum: 1, maximum: 1000
page	query	integer(int32)	false	Page number
order_id	query	string	false	Filter trades with specified order ID. currency_pair is also required if this field is present
account	query	string	false	The accountparameter has been deprecated. The interface supports querying all transaction records of the account.
from	query	integer(int64)	false	Start timestamp for the query
to	query	integer(int64)	false	End timestamp for the query, defaults to current time if not specified

Example responses

200 Response

[
  {
    "id": "1232893232",
    "create_time": "1548000000",
    "create_time_ms": "1548000000123.456",
    "currency_pair": "BTC_USDT",
    "order_id": "4128442423",
    "side": "buy",
    "role": "maker",
    "amount": "0.15",
    "price": "0.03",
    "fee": "0.0005",
    "fee_currency": "ETH",
    "point_fee": "0",
    "gt_fee": "0",
    "sequence_id": "588018",
    "text": "t-test",
    "deal": "0.0045",
    "trade_quote": "USDC"
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» id	string	Fill ID
» create_time	string	Fill Time
» create_time_ms	string	Trading time, with millisecond precision
» currency_pair	string	Currency pair
» side	string	Buy or sell order
» role	string	Trade role, not returned in public endpoints
» amount	string	Trade amount
» price	string	Order price
» order_id	string	Related order ID, not returned in public endpoints
» fee	string	Fee deducted, not returned in public endpoints
» fee_currency	string	Fee currency unit, not returned in public endpoints
» point_fee	string	Points used to deduct fee, not returned in public endpoints
» gt_fee	string	GT used to deduct fee, not returned in public endpoints
» amend_text	string	The custom data that the user remarked when amending the order
» sequence_id	string	Consecutive trade ID within a single market. Used to track and identify trades in the specific market
» text	string	Order's Custom Information. This field is not returned by public interfaces. The scenarios pm_liquidate, comb_margin_liquidate, and scm_liquidate represent full-account forced liquidation orders. liquidate represents isolated-account forced liquidation orders.
» deal	string	Total Executed Value
» trade_quote	string	Actual quote currency used for the trade

Enumerated Values

Property	Value
side	buy
side	sell
role	taker
role	maker

WARNING

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

Get server current time

Code samples

# coding: utf-8
import requests

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

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

curl -X GET https://api.gateio.ws/api/v4/spot/time \
  -H 'Accept: application/json'

GET /spot/time

Get server current time

Example responses

200 Response

{
  "server_time": 1597026383085
}

Responses

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

Response Schema

Status Code 200

SystemTime

Name	Type	Description
» server_time	integer(int64)	Server current time(ms)

This operation does not require authentication

Countdown cancel orders

Code samples

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

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

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

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

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

POST /spot/countdown_cancel_all

Countdown cancel orders

Spot order heartbeat detection. If there is no "cancel existing countdown" or "set new countdown" when the user-set timeout time is reached, the related spot pending orders will be automatically cancelled. This interface can be called repeatedly to set a new countdown or cancel the countdown. Usage example: Repeat this interface at 30s intervals, setting the countdown timeout to 30 (seconds) each time. If this interface is not called again within 30 seconds, all pending orders on the market you specified will be automatically cancelled. If no market is specified, all market cancelled. If the timeout is set to 0 within 30 seconds, the countdown timer will be terminated and the automatic order cancellation function will be cancelled.

Body parameter

{
  "timeout": 30,
  "currency_pair": "BTC_USDT"
}

Parameters

Name	In	Type	Required	Description
body	body	CountdownCancelAllSpotTask	true	none
» timeout	body	integer(int32)	true	Countdown time in seconds At least 5 seconds, 0 means cancel countdown
» currency_pair	body	string	false	Currency pair

Detailed descriptions

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

Example responses

200 Response

{
  "triggerTime": "1660039145000"
}

Responses

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

Response Schema

Status Code 200

triggerTime

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

WARNING

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

Batch modification of orders

Code samples

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

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

url = '/spot/amend_batch_orders'
query_param = ''
body='[{"order_id":"121212","currency_pair":"BTC_USDT","account":"spot","amount":"1","amend_text":"test","stop_profit":{"trigger_price":"67000","order_price":"67000"},"stop_loss":{"trigger_price":"63000","order_price":"63000"}}]'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/amend_batch_orders"
query_param=""
body_param='[{"order_id":"121212","currency_pair":"BTC_USDT","account":"spot","amount":"1","amend_text":"test","stop_profit":{"trigger_price":"67000","order_price":"67000"},"stop_loss":{"trigger_price":"63000","order_price":"63000"}}]'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /spot/amend_batch_orders

Batch modification of orders

Modify orders in spot, unified account and isolated margin account by default. Modify uncompleted orders, up to 5 orders can be modified at a time. Request parameters should be passed in array format. If there are order modification failures during the batch modification process, the modification of the next order will continue to be executed, and the execution will return with the corresponding order failure information. The call order of batch modification orders is consistent with the order list order. The return content order of batch modification orders is consistent with the order list order.

Body parameter

[
  {
    "order_id": "121212",
    "currency_pair": "BTC_USDT",
    "account": "spot",
    "amount": "1",
    "amend_text": "test",
    "stop_profit": {
      "trigger_price": "67000",
      "order_price": "67000"
    },
    "stop_loss": {
      "trigger_price": "63000",
      "order_price": "63000"
    }
  }
]

Parameters

Name	In	Type	Required	Description
x-gate-exptime	header	string	false	Specify the expiration time (milliseconds); if the GATE receives the request time greater than the expiration time, the request will be rejected
body	body	array[BatchAmendItem]	true	none

Example responses

200 Response

[
  {
    "order_id": "12332324",
    "amend_text": "t-123456",
    "text": "t-123456",
    "succeeded": true,
    "label": "",
    "message": "",
    "id": "12332324",
    "create_time": "1548000000",
    "update_time": "1548000100",
    "create_time_ms": 1548000000123,
    "update_time_ms": 1548000100123,
    "currency_pair": "ETC_BTC",
    "status": "cancelled",
    "type": "limit",
    "account": "spot",
    "side": "buy",
    "amount": "1",
    "price": "5.00032",
    "time_in_force": "gtc",
    "iceberg": "0",
    "left": "0.5",
    "filled_amount": "1.242",
    "filled_total": "2.50016",
    "avg_deal_price": "5.00032",
    "fee": "0.005",
    "fee_currency": "ETH",
    "point_fee": "0",
    "gt_fee": "0",
    "gt_discount": false,
    "rebated_fee": "0",
    "rebated_fee_currency": "BTC",
    "stp_act": "cn",
    "finish_as": "stp",
    "stp_id": 10240
  }
]

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Order modification executed successfully	[BatchOrder]

Response Schema

Status Code 200

Name	Type	Description
None	array	[Batch order details]
» None	BatchOrder	Batch order details
»» order_id	string	Order ID
»» amend_text	string	The custom data that the user remarked when amending the order
»» text	string	Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: 1. Must start with t- 2. Excluding t-, length cannot exceed 28 bytes 3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.)
»» succeeded	boolean	Request execution result
»» label	string	Error label, if any, otherwise an empty string
»» message	string	Detailed error message, if any, otherwise an empty string
»» id	string	Order ID
»» create_time	string	Creation time of order
»» update_time	string	Last modification time of order
»» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
»» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
»» status	string	Order status - open: to be filled - closed: closed order - cancelled: cancelled
»» currency_pair	string	Currency pair
»» type	string	Order Type - limit : Limit Order - market : Market Order
»» account	string	Account type, spot - spot account, margin - leveraged account, unified - unified account
»» side	string	Buy or sell order
»» amount	string	Trade amount
»» price	string	Order price
»» time_in_force	string	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none
»» iceberg	string	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported
»» auto_repay	boolean	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order
»» left	string	Amount left to fill
»» filled_amount	string	Amount filled
»» fill_price	string	Total filled in quote currency. Deprecated in favor of filled_total
»» filled_total	string	Total filled in quote currency
»» avg_deal_price	string	Average fill price
»» fee	string	Fee deducted
»» fee_currency	string	Fee currency unit
»» point_fee	string	Points used to deduct fee
»» gt_fee	string	GT used to deduct fee
»» gt_discount	boolean	Whether GT fee deduction is enabled
»» rebated_fee	string	Rebated fee
»» rebated_fee_currency	string	Rebated fee currency unit
»» stp_id	integer	Orders between users in the same stp_id group are not allowed to be self-traded 1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker. 2. stp_id returns 0 by default for orders that have not been set for STP group
»» stp_act	string	Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group, he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy。 2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter。 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled
»» finish_as	string	How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only requirement not met because time-in-force is set to poc (maker-only); rejected after being detected as taker - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown
»» stop_profit	object	Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged.
»»» trigger_price	string	Take profit trigger price When side == "buy", trigger_price must be greater than price When side == "sell", trigger_price must be less than price
»»» order_price	string	Take profit order price
»» stop_loss	object	Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged.
»»» trigger_price	string	Stop loss trigger price When side == "buy", trigger_price must be less than price When side == "sell", trigger_price must be greater than price
»»» order_price	string	Stop-loss order price

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
account	spot
account	margin
account	cross_margin
account	unified
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	liquidate_cancelled
finish_as	depth_not_enough
finish_as	trader_not_enough
finish_as	small
finish_as	ioc
finish_as	poc
finish_as	fok
finish_as	stp
finish_as	price_protect_cancelled
finish_as	unknown

WARNING

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

Query spot insurance fund historical data

Code samples

# coding: utf-8
import requests

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

url = '/spot/insurance_history'
query_param = 'business=margin&currency=BTC&from=1547706332&to=1547706332'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

curl -X GET https://api.gateio.ws/api/v4/spot/insurance_history?business=margin&currency=BTC&from=1547706332&to=1547706332 \
  -H 'Accept: application/json'

GET /spot/insurance_history

Query spot insurance fund historical data

Parameters

Name	In	Type	Required	Description
business	query	string	true	Leverage business, margin - position by position; unified - unified account
currency	query	string	true	Currency
page	query	integer(int32)	false	Page number
limit	query	integer	false	The maximum number of items returned in the list, the default value is 30
from	query	integer(int64)	true	Start timestamp in seconds
to	query	integer(int64)	true	End timestamp in seconds

Example responses

200 Response

[
  {
    "currency": "BTC",
    "balance": "1021.21",
    "time": 1727054547
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	none
» currency	string	Currency
» balance	string	Balance
» time	integer(int64)	Creation time, timestamp, milliseconds

This operation does not require authentication

Query running auto order list

Code samples

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

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

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

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

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

GET /spot/price_orders

Query running auto order list

Parameters

Name	In	Type	Required	Description
status	query	string	true	Query order list based on status
market	query	string	false	Trading market
account	query	string	false	Trading account type. Unified account must be set to unified
limit	query	integer	false	Maximum number of records returned in a single list
offset	query	integer	false	List offset, starting from 0

Enumerated Values

Parameter	Value
status	open
status	finished
account	normal
account	margin
account	unified

Example responses

200 Response

[
  {
    "trigger": {
      "price": "100",
      "rule": ">=",
      "expiration": 3600
    },
    "put": {
      "type": "limit",
      "side": "buy",
      "price": "2.15",
      "amount": "2.00000000",
      "account": "normal",
      "time_in_force": "gtc",
      "text": "api"
    },
    "id": 1283293,
    "user": 1234,
    "market": "GT_USDT",
    "ctime": 1616397800,
    "ftime": 1616397801,
    "fired_order_id": 0,
    "status": "",
    "reason": ""
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	[Spot price order details]
» None	SpotPriceTriggeredOrder	Spot price order details
»» trigger	SpotPriceTrigger	none
»»» price	string	Trigger price
»»» rule	string	Price trigger condition - >=: triggered when market price is greater than or equal to price - <=: triggered when market price is less than or equal to price
»»» expiration	integer	Maximum wait time for trigger condition (in seconds). Order will be cancelled if timeout
»» put	SpotPricePutOrder	none
»»» type	string	Order type，default to limit - limit : Limit Order - market : Market Order
»»» side	string	Order side - buy: buy side - sell: sell side
»»» price	string	Order price
»»» amount	string	Trading quantity, refers to the trading quantity of the trading currency, i.e., the currency that needs to be traded, for example, the quantity of BTC in BTC_USDT.
»»» account	string	Trading account type. Unified account must be set to unified - normal: spot trading - margin: margin trading - unified: unified account
»»» time_in_force	string	time_in_force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only
»»» auto_borrow	boolean	Whether to borrow coins automatically
»»» auto_repay	boolean	Whether to repay the loan automatically
»»» text	string	The source of the order, including: - web: Web - api: API call - app: Mobile app
»» id	integer(int64)	Auto order ID
»» user	integer	User ID
»» market	string	Market
»» ctime	integer(int64)	Created time
»» ftime	integer(int64)	End time
»» fired_order_id	integer(int64)	ID of the order created after trigger
»» status	string	Status - open: Running - cancelled: Manually cancelled - finish: Successfully completed - failed: Failed to execute - expired: Expired
»» reason	string	Additional description of how the order was completed

Enumerated Values

Property	Value
rule	>=
rule	<=
type	limit
type	market
side	buy
side	sell
account	normal
account	margin
account	unified
time_in_force	gtc
time_in_force	ioc

WARNING

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

Create price-triggered order

Code samples

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

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

url = '/spot/price_orders'
query_param = ''
body='{"trigger":{"price":"100","rule":">=","expiration":3600},"put":{"type":"limit","side":"buy","price":"2.15","amount":"2.00000000","account":"normal","time_in_force":"gtc","text":"api"},"market":"GT_USDT"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/price_orders"
query_param=""
body_param='{"trigger":{"price":"100","rule":">=","expiration":3600},"put":{"type":"limit","side":"buy","price":"2.15","amount":"2.00000000","account":"normal","time_in_force":"gtc","text":"api"},"market":"GT_USDT"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /spot/price_orders

Create price-triggered order

Body parameter

{
  "trigger": {
    "price": "100",
    "rule": ">=",
    "expiration": 3600
  },
  "put": {
    "type": "limit",
    "side": "buy",
    "price": "2.15",
    "amount": "2.00000000",
    "account": "normal",
    "time_in_force": "gtc",
    "text": "api"
  },
  "market": "GT_USDT"
}

Parameters

Name	In	Type	Required	Description
body	body	SpotPriceTriggeredOrder	true	none
» trigger	body	SpotPriceTrigger	true	none
»» price	body	string	true	Trigger price
»» rule	body	string	true	Price trigger condition - >=: triggered when market price is greater than or equal to price - <=: triggered when market price is less than or equal to price
»» expiration	body	integer	false	Maximum wait time for trigger condition (in seconds). Order will be cancelled if timeout
» put	body	SpotPricePutOrder	true	none
»» type	body	string	false	Order type，default to limit - limit : Limit Order - market : Market Order
»» side	body	string	true	Order side - buy: buy side - sell: sell side
»» price	body	string	true	Order price
»» amount	body	string	true	Trading quantity, refers to the trading quantity of the trading currency, i.e., the currency that needs to be traded, for example, the quantity of BTC in BTC_USDT.
»» account	body	string	true	Trading account type. Unified account must be set to unified - normal: spot trading - margin: margin trading - unified: unified account
»» time_in_force	body	string	true	time_in_force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only
»» auto_borrow	body	boolean	false	Whether to borrow coins automatically
»» auto_repay	body	boolean	false	Whether to repay the loan automatically
»» text	body	string	false	The source of the order, including: - web: Web - api: API call - app: Mobile app
» market	body	string	true	Market

Detailed descriptions

»» rule: Price trigger condition

- >=: triggered when market price is greater than or equal to price
- <=: triggered when market price is less than or equal to price

»» type: Order type，default to limit

- limit : Limit Order
- market : Market Order

»» side: Order side

- buy: buy side
- sell: sell side

»» account: Trading account type. Unified account must be set to unified

- normal: spot trading
- margin: margin trading
- unified: unified account

»» time_in_force: time_in_force

- gtc: GoodTillCancelled
- ioc: ImmediateOrCancelled, taker only

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

Enumerated Values

Parameter	Value
»» rule	>=
»» rule	<=
»» type	limit
»» type	market
»» side	buy
»» side	sell
»» account	normal
»» account	margin
»» account	unified
»» time_in_force	gtc
»» time_in_force	ioc

Example responses

201 Response

{
  "id": 1432329
}

Responses

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

Response Schema

Status Code 201

TriggerOrderResponse

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

WARNING

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

Cancel all auto orders

Code samples

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

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

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

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

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

DELETE /spot/price_orders

Cancel all auto orders

Parameters

Name	In	Type	Required	Description
market	query	string	false	Trading market
account	query	string	false	Trading account type. Unified account must be set to unified

Enumerated Values

Parameter	Value
account	normal
account	margin
account	unified

Example responses

200 Response

[
  {
    "trigger": {
      "price": "100",
      "rule": ">=",
      "expiration": 3600
    },
    "put": {
      "type": "limit",
      "side": "buy",
      "price": "2.15",
      "amount": "2.00000000",
      "account": "normal",
      "time_in_force": "gtc",
      "text": "api"
    },
    "id": 1283293,
    "user": 1234,
    "market": "GT_USDT",
    "ctime": 1616397800,
    "ftime": 1616397801,
    "fired_order_id": 0,
    "status": "",
    "reason": ""
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	[Spot price order details]
» None	SpotPriceTriggeredOrder	Spot price order details
»» trigger	SpotPriceTrigger	none
»»» price	string	Trigger price
»»» rule	string	Price trigger condition - >=: triggered when market price is greater than or equal to price - <=: triggered when market price is less than or equal to price
»»» expiration	integer	Maximum wait time for trigger condition (in seconds). Order will be cancelled if timeout
»» put	SpotPricePutOrder	none
»»» type	string	Order type，default to limit - limit : Limit Order - market : Market Order
»»» side	string	Order side - buy: buy side - sell: sell side
»»» price	string	Order price
»»» amount	string	Trading quantity, refers to the trading quantity of the trading currency, i.e., the currency that needs to be traded, for example, the quantity of BTC in BTC_USDT.
»»» account	string	Trading account type. Unified account must be set to unified - normal: spot trading - margin: margin trading - unified: unified account
»»» time_in_force	string	time_in_force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only
»»» auto_borrow	boolean	Whether to borrow coins automatically
»»» auto_repay	boolean	Whether to repay the loan automatically
»»» text	string	The source of the order, including: - web: Web - api: API call - app: Mobile app
»» id	integer(int64)	Auto order ID
»» user	integer	User ID
»» market	string	Market
»» ctime	integer(int64)	Created time
»» ftime	integer(int64)	End time
»» fired_order_id	integer(int64)	ID of the order created after trigger
»» status	string	Status - open: Running - cancelled: Manually cancelled - finish: Successfully completed - failed: Failed to execute - expired: Expired
»» reason	string	Additional description of how the order was completed

Enumerated Values

Property	Value
rule	>=
rule	<=
type	limit
type	market
side	buy
side	sell
account	normal
account	margin
account	unified
time_in_force	gtc
time_in_force	ioc

WARNING

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

Query single auto order details

Code samples

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

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

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

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

GET /spot/price_orders/{order_id}

Query single auto order details

Parameters

Name	In	Type	Required	Description
order_id	path	string	true	ID returned when order is successfully created

Example responses

200 Response

{
  "trigger": {
    "price": "100",
    "rule": ">=",
    "expiration": 3600
  },
  "put": {
    "type": "limit",
    "side": "buy",
    "price": "2.15",
    "amount": "2.00000000",
    "account": "normal",
    "time_in_force": "gtc",
    "text": "api"
  },
  "id": 1283293,
  "user": 1234,
  "market": "GT_USDT",
  "ctime": 1616397800,
  "ftime": 1616397801,
  "fired_order_id": 0,
  "status": "",
  "reason": ""
}

Responses

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

Response Schema

Status Code 200

Spot price order details

Name	Type	Description
» trigger	SpotPriceTrigger	none
»» price	string	Trigger price
»» rule	string	Price trigger condition - >=: triggered when market price is greater than or equal to price - <=: triggered when market price is less than or equal to price
»» expiration	integer	Maximum wait time for trigger condition (in seconds). Order will be cancelled if timeout
» put	SpotPricePutOrder	none
»» type	string	Order type，default to limit - limit : Limit Order - market : Market Order
»» side	string	Order side - buy: buy side - sell: sell side
»» price	string	Order price
»» amount	string	Trading quantity, refers to the trading quantity of the trading currency, i.e., the currency that needs to be traded, for example, the quantity of BTC in BTC_USDT.
»» account	string	Trading account type. Unified account must be set to unified - normal: spot trading - margin: margin trading - unified: unified account
»» time_in_force	string	time_in_force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only
»» auto_borrow	boolean	Whether to borrow coins automatically
»» auto_repay	boolean	Whether to repay the loan automatically
»» text	string	The source of the order, including: - web: Web - api: API call - app: Mobile app
» id	integer(int64)	Auto order ID
» user	integer	User ID
» market	string	Market
» ctime	integer(int64)	Created time
» ftime	integer(int64)	End time
» fired_order_id	integer(int64)	ID of the order created after trigger
» status	string	Status - open: Running - cancelled: Manually cancelled - finish: Successfully completed - failed: Failed to execute - expired: Expired
» reason	string	Additional description of how the order was completed

Enumerated Values

Property	Value
rule	>=
rule	<=
type	limit
type	market
side	buy
side	sell
account	normal
account	margin
account	unified
time_in_force	gtc
time_in_force	ioc

WARNING

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

Cancel single auto order

Code samples

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

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

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

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

DELETE /spot/price_orders/{order_id}

Cancel single auto order

Parameters

Name	In	Type	Required	Description
order_id	path	string	true	ID returned when order is successfully created

Example responses

200 Response

{
  "trigger": {
    "price": "100",
    "rule": ">=",
    "expiration": 3600
  },
  "put": {
    "type": "limit",
    "side": "buy",
    "price": "2.15",
    "amount": "2.00000000",
    "account": "normal",
    "time_in_force": "gtc",
    "text": "api"
  },
  "id": 1283293,
  "user": 1234,
  "market": "GT_USDT",
  "ctime": 1616397800,
  "ftime": 1616397801,
  "fired_order_id": 0,
  "status": "",
  "reason": ""
}

Responses

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

Response Schema

Status Code 200

Spot price order details

Name	Type	Description
» trigger	SpotPriceTrigger	none
»» price	string	Trigger price
»» rule	string	Price trigger condition - >=: triggered when market price is greater than or equal to price - <=: triggered when market price is less than or equal to price
»» expiration	integer	Maximum wait time for trigger condition (in seconds). Order will be cancelled if timeout
» put	SpotPricePutOrder	none
»» type	string	Order type，default to limit - limit : Limit Order - market : Market Order
»» side	string	Order side - buy: buy side - sell: sell side
»» price	string	Order price
»» amount	string	Trading quantity, refers to the trading quantity of the trading currency, i.e., the currency that needs to be traded, for example, the quantity of BTC in BTC_USDT.
»» account	string	Trading account type. Unified account must be set to unified - normal: spot trading - margin: margin trading - unified: unified account
»» time_in_force	string	time_in_force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only
»» auto_borrow	boolean	Whether to borrow coins automatically
»» auto_repay	boolean	Whether to repay the loan automatically
»» text	string	The source of the order, including: - web: Web - api: API call - app: Mobile app
» id	integer(int64)	Auto order ID
» user	integer	User ID
» market	string	Market
» ctime	integer(int64)	Created time
» ftime	integer(int64)	End time
» fired_order_id	integer(int64)	ID of the order created after trigger
» status	string	Status - open: Running - cancelled: Manually cancelled - finish: Successfully completed - failed: Failed to execute - expired: Expired
» reason	string	Additional description of how the order was completed

Enumerated Values

Property	Value
rule	>=
rule	<=
type	limit
type	market
side	buy
side	sell
account	normal
account	margin
account	unified
time_in_force	gtc
time_in_force	ioc

WARNING

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

List Spot POV orders

Code samples

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

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

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

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

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

GET /spot/pov_orders

List Spot POV orders

Parameters

Name	In	Type	Required	Description
currency_pair	query	string	false	Currency pair
status	query	string	true	Order status. Defaults to open - open: Active orders - finished: Finished orders
side	query	string	false	Specify all bids or all asks, both included if not specified
page	query	integer(int32)	false	Page number, up to 100
limit	query	integer	false	Maximum number of records returned in a single list

Detailed descriptions

status: Order status. Defaults to open

- open: Active orders
- finished: Finished orders

Example responses

200 Response

[
  {
    "id": "1216",
    "currency_pair": "BTC_USDT",
    "side": "buy",
    "amount": "0.010000",
    "participation_rate": 10,
    "ttl": "1h",
    "limit_price": "63000",
    "trigger_price": "63000",
    "status": "CREATED",
    "terminated_as": "",
    "start_time_ms": 0,
    "end_time_ms": 0,
    "expire_time_ms": 1784365405074,
    "create_time_ms": 1784279005258,
    "update_time_ms": 1784279005258
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	[Spot POV order details]
» None	SpotPovOrder	Spot POV order details
»» id	string	Order ID
»» currency_pair	string	Currency pair
»» side	string	Buy or sell order
»» amount	string	Trade amount
»» participation_rate	integer	Target participation rate as a percentage. Allowed values: 5, 10, 20, and 40
»» ttl	string	Time to live. Valid values: 1h, 6h, 12h, 1d, 2d, 3d, 4d, 5d, 6d, and 7d
»» limit_price	string	Limit price. If omitted, the market price is used
»» trigger_price	string	Trigger price. If omitted, the order is triggered immediately
»» status	string	Order status - CREATED: Created - CANCELING: Canceling - RUNNING: Running - COMPLETED: Completed - EXPIRED: Expired - TERMINATED: Terminated
»» terminated_as	string	Order termination reason code
»» start_time_ms	integer(int64)	Order execution start time in milliseconds
»» end_time_ms	integer(int64)	Order execution end time in milliseconds
»» expire_time_ms	integer(int64)	Order expiration time in milliseconds
»» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
»» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
»» text	string	Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: 1. Must start with t- 2. Excluding t-, length cannot exceed 28 bytes 3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.)

WARNING

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

Create a Spot POV order

Code samples

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

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

url = '/spot/pov_orders'
query_param = ''
body='{"currency_pair":"BTC_USDT","side":"buy","amount":"1","participation_rate":5,"ttl":"1h","limit_price":"63000","trigger_price":"63000"}'
# for `gen_sign` implementation, refer to section `Authentication` above
sign_headers = gen_sign('POST', prefix + url, query_param, body)
headers.update(sign_headers)
r = requests.request('POST', host + prefix + url, headers=headers, data=body)
print(r.json())

key="YOUR_API_KEY"
secret="YOUR_API_SECRET"
host="https://api.gateio.ws"
prefix="/api/v4"
method="POST"
url="/spot/pov_orders"
query_param=""
body_param='{"currency_pair":"BTC_USDT","side":"buy","amount":"1","participation_rate":5,"ttl":"1h","limit_price":"63000","trigger_price":"63000"}'
timestamp=$(date +%s)
body_hash=$(printf "$body_param" | openssl sha512 | awk '{print $NF}')
sign_string="$method\n$prefix$url\n$query_param\n$body_hash\n$timestamp"
sign=$(printf "$sign_string" | openssl sha512 -hmac "$secret" | awk '{print $NF}')

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

POST /spot/pov_orders

Create a Spot POV order

Body parameter

{
  "currency_pair": "BTC_USDT",
  "side": "buy",
  "amount": "1",
  "participation_rate": 5,
  "ttl": "1h",
  "limit_price": "63000",
  "trigger_price": "63000"
}

Parameters

Name	In	Type	Required	Description
body	body	SpotPovOrderCreator	true	none
» currency_pair	body	string	true	Currency pair
» side	body	string	true	Buy or sell order
» amount	body	string	true	Trade amount
» participation_rate	body	integer	true	Target participation rate as a percentage. Valid values: 5, 10, 20, and 40
» ttl	body	string	true	Time to live. Valid values: 1h, 6h, 12h, 1d, 2d, 3d, 4d, 5d, 6d, and 7d
» limit_price	body	string	false	Limit price. If omitted, the market price is used
» trigger_price	body	string	false	Trigger price. If omitted, the order is triggered immediately
» text	body	string	false	Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: 1. Must start with t- 2. Excluding t-, length cannot exceed 28 bytes 3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.)

Detailed descriptions

» text: Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions:

1. Must start with t-
2. Excluding t-, length cannot exceed 28 bytes
3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.)

Enumerated Values

Parameter	Value
» side	buy
» side	sell

Example responses

201 Response

{
  "id": "1216",
  "currency_pair": "BTC_USDT",
  "side": "buy",
  "amount": "0.010000",
  "participation_rate": 10,
  "ttl": "1h",
  "limit_price": "63000",
  "trigger_price": "63000",
  "status": "CREATED",
  "terminated_as": "",
  "start_time_ms": 0,
  "end_time_ms": 0,
  "expire_time_ms": 1784365405074,
  "create_time_ms": 1784279005258,
  "update_time_ms": 1784279005258
}

Responses

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

Response Schema

Status Code 201

Spot POV order details

Name	Type	Description
» id	string	Order ID
» currency_pair	string	Currency pair
» side	string	Buy or sell order
» amount	string	Trade amount
» participation_rate	integer	Target participation rate as a percentage. Allowed values: 5, 10, 20, and 40
» ttl	string	Time to live. Valid values: 1h, 6h, 12h, 1d, 2d, 3d, 4d, 5d, 6d, and 7d
» limit_price	string	Limit price. If omitted, the market price is used
» trigger_price	string	Trigger price. If omitted, the order is triggered immediately
» status	string	Order status - CREATED: Created - CANCELING: Canceling - RUNNING: Running - COMPLETED: Completed - EXPIRED: Expired - TERMINATED: Terminated
» terminated_as	string	Order termination reason code
» start_time_ms	integer(int64)	Order execution start time in milliseconds
» end_time_ms	integer(int64)	Order execution end time in milliseconds
» expire_time_ms	integer(int64)	Order expiration time in milliseconds
» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
» text	string	Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: 1. Must start with t- 2. Excluding t-, length cannot exceed 28 bytes 3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.)

WARNING

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

Cancel Spot POV orders

Code samples

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

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

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

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

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

DELETE /spot/pov_orders

Cancel Spot POV orders

Parameters

Name	In	Type	Required	Description
currency_pair	query	string	false	Currency pair

Example responses

200 Response

[
  {
    "id": "1216",
    "currency_pair": "BTC_USDT",
    "side": "buy",
    "amount": "0.010000",
    "participation_rate": 10,
    "ttl": "1h",
    "limit_price": "63000",
    "trigger_price": "63000",
    "status": "CREATED",
    "terminated_as": "",
    "start_time_ms": 0,
    "end_time_ms": 0,
    "expire_time_ms": 1784365405074,
    "create_time_ms": 1784279005258,
    "update_time_ms": 1784279005258
  }
]

Responses

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

Response Schema

Status Code 200

Name	Type	Description
None	array	[Spot POV order details]
» None	SpotPovOrder	Spot POV order details
»» id	string	Order ID
»» currency_pair	string	Currency pair
»» side	string	Buy or sell order
»» amount	string	Trade amount
»» participation_rate	integer	Target participation rate as a percentage. Allowed values: 5, 10, 20, and 40
»» ttl	string	Time to live. Valid values: 1h, 6h, 12h, 1d, 2d, 3d, 4d, 5d, 6d, and 7d
»» limit_price	string	Limit price. If omitted, the market price is used
»» trigger_price	string	Trigger price. If omitted, the order is triggered immediately
»» status	string	Order status - CREATED: Created - CANCELING: Canceling - RUNNING: Running - COMPLETED: Completed - EXPIRED: Expired - TERMINATED: Terminated
»» terminated_as	string	Order termination reason code
»» start_time_ms	integer(int64)	Order execution start time in milliseconds
»» end_time_ms	integer(int64)	Order execution end time in milliseconds
»» expire_time_ms	integer(int64)	Order expiration time in milliseconds
»» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
»» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
»» text	string	Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: 1. Must start with t- 2. Excluding t-, length cannot exceed 28 bytes 3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.)

WARNING

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

Query Spot POV order details

Code samples

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

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

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

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

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

GET /spot/pov_orders/{order_id}

Query Spot POV order details

Parameters

Name	In	Type	Required	Description
order_id	path	string	true	The order ID returned after successful creation, or the custom ID specified by the user in the text field.

Example responses

200 Response

{
  "id": "1216",
  "currency_pair": "BTC_USDT",
  "side": "buy",
  "amount": "0.010000",
  "participation_rate": 10,
  "ttl": "1h",
  "limit_price": "63000",
  "trigger_price": "63000",
  "status": "CREATED",
  "terminated_as": "",
  "start_time_ms": 0,
  "end_time_ms": 0,
  "expire_time_ms": 1784365405074,
  "create_time_ms": 1784279005258,
  "update_time_ms": 1784279005258
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Detail retrieved	SpotPovOrder

Response Schema

Status Code 200

Spot POV order details

Name	Type	Description
» id	string	Order ID
» currency_pair	string	Currency pair
» side	string	Buy or sell order
» amount	string	Trade amount
» participation_rate	integer	Target participation rate as a percentage. Allowed values: 5, 10, 20, and 40
» ttl	string	Time to live. Valid values: 1h, 6h, 12h, 1d, 2d, 3d, 4d, 5d, 6d, and 7d
» limit_price	string	Limit price. If omitted, the market price is used
» trigger_price	string	Trigger price. If omitted, the order is triggered immediately
» status	string	Order status - CREATED: Created - CANCELING: Canceling - RUNNING: Running - COMPLETED: Completed - EXPIRED: Expired - TERMINATED: Terminated
» terminated_as	string	Order termination reason code
» start_time_ms	integer(int64)	Order execution start time in milliseconds
» end_time_ms	integer(int64)	Order execution end time in milliseconds
» expire_time_ms	integer(int64)	Order expiration time in milliseconds
» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
» text	string	Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: 1. Must start with t- 2. Excluding t-, length cannot exceed 28 bytes 3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.)

WARNING

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

Cancel a Spot POV order

Code samples

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

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

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

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

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

DELETE /spot/pov_orders/{order_id}

Cancel a Spot POV order

Parameters

Name	In	Type	Required	Description
order_id	path	string	true	The order ID returned after successful creation, or the custom ID specified by the user in the text field.

Example responses

200 Response

{
  "id": "1216",
  "currency_pair": "BTC_USDT",
  "side": "buy",
  "amount": "0.010000",
  "participation_rate": 10,
  "ttl": "1h",
  "limit_price": "63000",
  "trigger_price": "63000",
  "status": "CREATED",
  "terminated_as": "",
  "start_time_ms": 0,
  "end_time_ms": 0,
  "expire_time_ms": 1784365405074,
  "create_time_ms": 1784279005258,
  "update_time_ms": 1784279005258
}

Responses

Status	Meaning	Description	Schema
200	OK (opens new window)	Order cancelled	SpotPovOrder

Response Schema

Status Code 200

Spot POV order details

Name	Type	Description
» id	string	Order ID
» currency_pair	string	Currency pair
» side	string	Buy or sell order
» amount	string	Trade amount
» participation_rate	integer	Target participation rate as a percentage. Allowed values: 5, 10, 20, and 40
» ttl	string	Time to live. Valid values: 1h, 6h, 12h, 1d, 2d, 3d, 4d, 5d, 6d, and 7d
» limit_price	string	Limit price. If omitted, the market price is used
» trigger_price	string	Trigger price. If omitted, the order is triggered immediately
» status	string	Order status - CREATED: Created - CANCELING: Canceling - RUNNING: Running - COMPLETED: Completed - EXPIRED: Expired - TERMINATED: Terminated
» terminated_as	string	Order termination reason code
» start_time_ms	integer(int64)	Order execution start time in milliseconds
» end_time_ms	integer(int64)	Order execution end time in milliseconds
» expire_time_ms	integer(int64)	Order expiration time in milliseconds
» create_time_ms	integer(int64)	Creation time of order (in milliseconds)
» update_time_ms	integer(int64)	Last modification time of order (in milliseconds)
» text	string	Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: 1. Must start with t- 2. Excluding t-, length cannot exceed 28 bytes 3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.)

WARNING

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

Schemas

SpotPovOrder

{
  "id": "string",
  "currency_pair": "string",
  "side": "string",
  "amount": "string",
  "participation_rate": 0,
  "ttl": "string",
  "limit_price": "string",
  "trigger_price": "string",
  "status": "string",
  "terminated_as": "string",
  "start_time_ms": 0,
  "end_time_ms": 0,
  "expire_time_ms": 0,
  "create_time_ms": 0,
  "update_time_ms": 0,
  "text": "string"
}

Spot POV order details

Properties

Name	Type	Required	Restrictions	Description
id	string	true	read-only	Order ID
currency_pair	string	true	read-only	Currency pair
side	string	true	read-only	Buy or sell order
amount	string	true	read-only	Trade amount
participation_rate	integer	true	read-only	Target participation rate as a percentage. Allowed values: 5, 10, 20, and 40
ttl	string	true	read-only	Time to live. Valid values: 1h, 6h, 12h, 1d, 2d, 3d, 4d, 5d, 6d, and 7d
limit_price	string	false	read-only	Limit price. If omitted, the market price is used
trigger_price	string	false	read-only	Trigger price. If omitted, the order is triggered immediately
status	string	true	read-only	Order status - CREATED: Created - CANCELING: Canceling - RUNNING: Running - COMPLETED: Completed - EXPIRED: Expired - TERMINATED: Terminated
terminated_as	string	false	read-only	Order termination reason code
start_time_ms	integer(int64)	false	read-only	Order execution start time in milliseconds
end_time_ms	integer(int64)	false	read-only	Order execution end time in milliseconds
expire_time_ms	integer(int64)	false	read-only	Order expiration time in milliseconds
create_time_ms	integer(int64)	true	read-only	Creation time of order (in milliseconds)
update_time_ms	integer(int64)	false	read-only	Last modification time of order (in milliseconds)
text	string	false	none	Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: 1. Must start with t- 2. Excluding t-, length cannot exceed 28 bytes 3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.)

Currency

{
  "currency": "string",
  "name": "string",
  "delisted": true,
  "withdraw_disabled": true,
  "withdraw_delayed": true,
  "deposit_disabled": true,
  "trade_disabled": true,
  "fixed_rate": "string",
  "chain": "string",
  "chains": [
    {
      "name": "string",
      "addr": "string",
      "withdraw_disabled": true,
      "withdraw_delayed": true,
      "deposit_disabled": true
    }
  ],
  "total_supply": "string",
  "market_cap": "string",
  "category": [
    "string"
  ]
}

Properties

Name	Type	Required	Restrictions	Description
currency	string	false	none	Currency symbol
name	string	false	none	Currency name
delisted	boolean	false	none	Whether currency is de-listed
withdraw_disabled	boolean	false	none	Whether currency's withdrawal is disabled (deprecated)
withdraw_delayed	boolean	false	none	Whether currency's withdrawal is delayed (deprecated)
deposit_disabled	boolean	false	none	Whether currency's deposit is disabled (deprecated)
trade_disabled	boolean	false	none	Whether currency's trading is disabled
fixed_rate	string	false	none	Fixed fee rate. Only for fixed rate currencies, not valid for normal currencies
chain	string	false	none	The main chain corresponding to the coin
chains	array	false	none	All links corresponding to coins
» SpotCurrencyChain	object	false	none	none
»» name	string	false	none	Blockchain name
»» addr	string	false	none	token address
»» withdraw_disabled	boolean	false	none	Whether currency's withdrawal is disabled
»» withdraw_delayed	boolean	false	none	Whether currency's withdrawal is delayed
»» deposit_disabled	boolean	false	none	Whether currency's deposit is disabled
» total_supply	string	false	none	Total supply
» market_cap	string	false	none	Market cap
» category	array	false	none	Currency categories - stocks: Stocks - metals: Metals - indices: Indices - forex: Forex - commodities: Commodities

OpenOrders

{
  "currency_pair": "string",
  "total": 0,
  "orders": [
    {
      "id": "string",
      "text": "string",
      "amend_text": "string",
      "create_time": "string",
      "update_time": "string",
      "create_time_ms": 0,
      "update_time_ms": 0,
      "status": "open",
      "currency_pair": "string",
      "trade_quote": "string",
      "type": "limit",
      "account": "spot",
      "side": "buy",
      "amount": "string",
      "price": "string",
      "time_in_force": "gtc",
      "iceberg": "string",
      "auto_borrow": true,
      "auto_repay": true,
      "left": "string",
      "filled_amount": "string",
      "fill_price": "string",
      "filled_total": "string",
      "avg_deal_price": "string",
      "fee": "string",
      "fee_currency": "string",
      "point_fee": "string",
      "gt_fee": "string",
      "gt_maker_fee": "string",
      "gt_taker_fee": "string",
      "gt_discount": true,
      "rebated_fee": "string",
      "rebated_fee_currency": "string",
      "stp_id": 0,
      "stp_act": "cn",
      "finish_as": "open",
      "action_mode": "string",
      "slippage": "string",
      "stop_profit": {},
      "stop_loss": {}
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
currency_pair	string	false	none	Currency pair
total	integer	false	none	Total number of open orders for this trading pair on the current page
orders	array	false	none	none
» None	object	false	none	Spot order details
»» id	string	false	read-only	Order ID
»» text	string	false	none	User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- prefix 3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders liquidate represents isolated-margin liquidation orders
»» amend_text	string	false	read-only	The custom data that the user remarked when amending the order
»» create_time	string	false	read-only	Creation time of order
»» update_time	string	false	read-only	Last modification time of order
»» create_time_ms	integer(int64)	false	read-only	Creation time of order (in milliseconds)
»» update_time_ms	integer(int64)	false	read-only	Last modification time of order (in milliseconds)
»» status	string	false	read-only	Order status - open: to be filled - closed: closed order - cancelled: cancelled
»» currency_pair	string	true	none	Currency pair
»» trade_quote	string	false	none	Actual quote currency used for the trade; can be specified only in a unified market
»» type	string	false	none	Order Type - limit : Limit Order - market : Market Order
»» account	string	false	none	Account type, spot - spot account, margin - leveraged account, unified - unified account
»» side	string	true	none	Buy or sell order
»» amount	string	true	none	Trade amount When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT. When type is market, the meaning depends on the side: - side: buy refers to the quote currency, e.g. USDT in BTC_USDT - side: sell refers to the base currency, e.g. BTC in BTC_USDT
»» price	string	false	none	Trading price, required when type=limit
»» time_in_force	string	false	none	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market
»» iceberg	string	false	none	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported
»» auto_borrow	boolean	false	write-only	Used in margin or cross margin trading to allow automatic loan of insufficient amount if balance is not enough
»» auto_repay	boolean	false	none	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order
»» left	string	false	read-only	Amount left to fill
»» filled_amount	string	false	read-only	Amount filled
»» fill_price	string	false	read-only	Total filled in quote currency. Deprecated in favor of filled_total
»» filled_total	string	false	read-only	Total filled in quote currency
»» avg_deal_price	string	false	read-only	Average fill price
»» fee	string	false	read-only	Fee deducted
»» fee_currency	string	false	read-only	Fee currency unit
»» point_fee	string	false	read-only	Points used to deduct fee
»» gt_fee	string	false	read-only	GT used to deduct fee
»» gt_maker_fee	string	false	read-only	GT amount used to deduct maker fee
»» gt_taker_fee	string	false	read-only	GT amount used to deduct taker fee
»» gt_discount	boolean	false	read-only	Whether GT fee deduction is enabled
»» rebated_fee	string	false	read-only	Rebated fee
»» rebated_fee_currency	string	false	read-only	Rebated fee currency unit
»» stp_id	integer	false	read-only	Orders between users in the same stp_id group are not allowed to be self-traded 1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker. 2. stp_id returns 0 by default for orders that have not been set for STP group
»» stp_act	string	false	none	Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter. 3. If the user did not use stp_act when placing the order, stp_act will return '-' - cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled
»» finish_as	string	false	read-only	How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only requirement not met because time-in-force is set to poc (maker-only); rejected after being detected as taker - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown
»» action_mode	string	false	write-only	Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)
»» slippage	string	false	write-only	Maximum supported slippage ratio for Spot Market Order Placement, calculated based on the latest market price at the time of order placement as the benchmark (Example: 0.03 means 3%)
»» stop_profit	object	false	none	Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged.
»»» trigger_price	string	false	none	Take profit trigger price When side == "buy", trigger_price must be greater than price When side == "sell", trigger_price must be less than price
»»» order_price	string	false	none	Take profit order price
»» stop_loss	object	false	none	Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged.
»»» trigger_price	string	false	none	Stop loss trigger price When side == "buy", trigger_price must be less than price When side == "sell", trigger_price must be greater than price
»»» order_price	string	false	none	Stop-loss order price

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	liquidate_cancelled
finish_as	depth_not_enough
finish_as	trader_not_enough
finish_as	small
finish_as	ioc
finish_as	poc
finish_as	fok
finish_as	stp
finish_as	price_protect_cancelled
finish_as	unknown

BatchOrder

{
  "order_id": "string",
  "amend_text": "string",
  "text": "string",
  "succeeded": true,
  "label": "string",
  "message": "string",
  "id": "string",
  "create_time": "string",
  "update_time": "string",
  "create_time_ms": 0,
  "update_time_ms": 0,
  "status": "open",
  "currency_pair": "string",
  "type": "limit",
  "account": "spot",
  "side": "buy",
  "amount": "string",
  "price": "string",
  "time_in_force": "gtc",
  "iceberg": "string",
  "auto_borrow": true,
  "auto_repay": true,
  "left": "string",
  "filled_amount": "string",
  "fill_price": "string",
  "filled_total": "string",
  "avg_deal_price": "string",
  "fee": "string",
  "fee_currency": "string",
  "point_fee": "string",
  "gt_fee": "string",
  "gt_discount": true,
  "rebated_fee": "string",
  "rebated_fee_currency": "string",
  "stp_id": 0,
  "stp_act": "cn",
  "finish_as": "open",
  "slippage": "string",
  "stop_profit": {
    "trigger_price": "string",
    "order_price": "string"
  },
  "stop_loss": {
    "trigger_price": "string",
    "order_price": "string"
  }
}

Batch order details

Properties

Name	Type	Required	Restrictions	Description
order_id	string	false	none	Order ID
amend_text	string	false	none	The custom data that the user remarked when amending the order
text	string	false	none	Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: 1. Must start with t- 2. Excluding t-, length cannot exceed 28 bytes 3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.)
succeeded	boolean	false	none	Request execution result
label	string	false	none	Error label, if any, otherwise an empty string
message	string	false	none	Detailed error message, if any, otherwise an empty string
id	string	false	read-only	Order ID
create_time	string	false	read-only	Creation time of order
update_time	string	false	read-only	Last modification time of order
create_time_ms	integer(int64)	false	read-only	Creation time of order (in milliseconds)
update_time_ms	integer(int64)	false	read-only	Last modification time of order (in milliseconds)
status	string	false	read-only	Order status - open: to be filled - closed: closed order - cancelled: cancelled
currency_pair	string	false	none	Currency pair
type	string	false	none	Order Type - limit : Limit Order - market : Market Order
account	string	false	none	Account type, spot - spot account, margin - leveraged account, unified - unified account
side	string	false	none	Buy or sell order
amount	string	false	none	Trade amount
price	string	false	none	Order price
time_in_force	string	false	none	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none
iceberg	string	false	none	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported
auto_borrow	boolean	false	write-only	Used in margin or cross margin trading to allow automatic loan of insufficient amount if balance is not enough
auto_repay	boolean	false	none	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order
left	string	false	read-only	Amount left to fill
filled_amount	string	false	read-only	Amount filled
fill_price	string	false	read-only	Total filled in quote currency. Deprecated in favor of filled_total
filled_total	string	false	read-only	Total filled in quote currency
avg_deal_price	string	false	read-only	Average fill price
fee	string	false	read-only	Fee deducted
fee_currency	string	false	read-only	Fee currency unit
point_fee	string	false	read-only	Points used to deduct fee
gt_fee	string	false	read-only	GT used to deduct fee
gt_discount	boolean	false	read-only	Whether GT fee deduction is enabled
rebated_fee	string	false	read-only	Rebated fee
rebated_fee_currency	string	false	read-only	Rebated fee currency unit
stp_id	integer	false	read-only	Orders between users in the same stp_id group are not allowed to be self-traded 1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker. 2. stp_id returns 0 by default for orders that have not been set for STP group
stp_act	string	false	none	Self-Trading Prevention Action. Users can use this field to set self-trade prevetion strategies 1. After users join the STP Group, he can pass stp_act to limit the user's self-trade prevetion strategy. If stp_act is not passed, the default is cn strategy。 2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter。 3. If the user did not use 'stp_act' when placing the order, 'stp_act' will return '-' - cn: Cancel newest, Cancel new orders and keep old ones - co: Cancel oldest, new ones - cb: Cancel both, Both old and new orders will be cancelled
finish_as	string	false	read-only	How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only requirement not met because time-in-force is set to poc (maker-only); rejected after being detected as taker - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown
slippage	string	false	write-only	Maximum supported slippage ratio for Spot Market Order Placement, calculated based on the latest market price at the time of order placement as the benchmark (Example: 0.03 means 3%)
stop_profit	object	false	none	Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged.
» trigger_price	string	false	none	Take profit trigger price When side == "buy", trigger_price must be greater than price When side == "sell", trigger_price must be less than price
» order_price	string	false	none	Take profit order price
stop_loss	object	false	none	Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged.
» trigger_price	string	false	none	Stop loss trigger price When side == "buy", trigger_price must be less than price When side == "sell", trigger_price must be greater than price
» order_price	string	false	none	Stop-loss order price

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
account	spot
account	margin
account	cross_margin
account	unified
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	liquidate_cancelled
finish_as	depth_not_enough
finish_as	trader_not_enough
finish_as	small
finish_as	ioc
finish_as	poc
finish_as	fok
finish_as	stp
finish_as	price_protect_cancelled
finish_as	unknown

TriggerTime

{
  "triggerTime": "1660039145000"
}

triggerTime

Properties

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

CurrencyPair

{
  "id": "string",
  "base": "string",
  "base_name": "string",
  "quote": "string",
  "quote_name": "string",
  "trade_quotes": [
    "string"
  ],
  "fee": "string",
  "min_base_amount": "string",
  "min_quote_amount": "string",
  "max_base_amount": "string",
  "max_quote_amount": "string",
  "amount_precision": 0,
  "precision": 0,
  "trade_status": "untradable",
  "sell_start": 0,
  "buy_start": 0,
  "delisting_time": 0,
  "type": "string",
  "trade_url": "string",
  "st_tag": true,
  "up_rate": "string",
  "down_rate": "string",
  "slippage": "string",
  "market_order_max_stock": "string",
  "market_order_max_money": "string"
}

Spot currency pair

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	Currency pair
base	string	false	none	Base currency
base_name	string	false	none	Base currency name
quote	string	false	none	Quote currency
quote_name	string	false	none	Quote currency name
trade_quotes	array|null	false	none	Quote currencies supported by the unified market; null means that the market does not support unified quote currencies
fee	string	false	none	Trading fee rate(deprecated)
min_base_amount	string	false	none	Minimum amount of base currency to trade, null means no limit
min_quote_amount	string	false	none	Minimum amount of quote currency to trade, null means no limit
max_base_amount	string	false	none	Maximum amount of base currency to trade, null means no limit
max_quote_amount	string	false	none	Maximum amount of quote currency to trade, null means no limit
amount_precision	integer	false	none	Quantity precision
precision	integer	false	none	Price precision
trade_status	string	false	none	Trading status - untradable: cannot be traded - buyable: can be bought - sellable: can be sold - tradable: can be bought and sold
sell_start	integer(int64)	false	none	Sell start unix timestamp in seconds
buy_start	integer(int64)	false	none	Buy start unix timestamp in seconds
delisting_time	integer(int64)	false	none	Expected time to remove the shelves, Unix timestamp in seconds
type	string	false	none	Trading pair type, normal: normal, premarket: pre-market
trade_url	string	false	none	Transaction link
st_tag	boolean	false	none	Whether the trading pair is in ST risk assessment, false - No, true - Yes
up_rate	string	false	none	Maximum Quote Rise Percentage
down_rate	string	false	none	Maximum Quote Decline Percentage
slippage	string	false	none	Maximum supported slippage ratio for Spot Market Order Placement, calculated based on the latest market price at the time of order placement as the benchmark (Example: 0.03 means 3%)
market_order_max_stock	string	false	none	Maximum market order quantity. null or 0 means no limit
market_order_max_money	string	false	none	Maximum market order amount. null or 0 means no limit

Enumerated Values

Property	Value
trade_status	untradable
trade_status	buyable
trade_status	sellable
trade_status	tradable

SpotInsuranceHistory

{
  "currency": "string",
  "balance": "string",
  "time": 0
}

Properties

Name	Type	Required	Restrictions	Description
currency	string	false	none	Currency
balance	string	false	none	Balance
time	integer(int64)	false	none	Creation time, timestamp, milliseconds

BatchAmendItem

{
  "order_id": "string",
  "currency_pair": "string",
  "account": "string",
  "amount": "string",
  "price": "string",
  "amend_text": "string",
  "action_mode": "string",
  "stop_profit": {
    "trigger_price": "string",
    "order_price": "string"
  },
  "stop_loss": {
    "trigger_price": "string",
    "order_price": "string"
  }
}

Order information that needs to be modified

Properties

Name	Type	Required	Restrictions	Description
order_id	string	true	none	The order ID returned upon successful creation or the custom ID specified by the user during creation (i.e., the 'text' field)
currency_pair	string	true	none	Currency pair
account	string	false	none	Default spot, unified account and warehouse-by-store leverage account
amount	string	false	none	Trading Quantity. Only one of amount or price can be specified
price	string	false	none	Trading Price. Only one of amount or price can be specified
amend_text	string	false	none	Custom info during order amendment
action_mode	string	false	none	Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)
stop_profit	object	false	none	Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged.
» trigger_price	string	false	none	Take profit trigger price When side == "buy", trigger_price must be greater than price When side == "sell", trigger_price must be less than price
» order_price	string	false	none	Take profit order price
stop_loss	object	false	none	Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged.
» trigger_price	string	false	none	Stop loss trigger price When side == "buy", trigger_price must be less than price When side == "sell", trigger_price must be greater than price
» order_price	string	false	none	Stop-loss order price

CountdownCancelAllSpotTask

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

CountdownCancelAllSpotTask

Properties

Name	Type	Required	Restrictions	Description
timeout	integer(int32)	true	none	Countdown time in seconds At least 5 seconds, 0 means cancel countdown
currency_pair	string	false	none	Currency pair

LiquidateOrder

{
  "text": "string",
  "currency_pair": "string",
  "amount": "string",
  "price": "string",
  "action_mode": "string"
}

Spot liquidation order details

Properties

Name	Type	Required	Restrictions	Description
text	string	false	none	Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: 1. Must start with t- 2. Excluding t-, length cannot exceed 28 bytes 3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.)
currency_pair	string	true	none	Currency pair
amount	string	true	none	Trade amount
price	string	true	none	Order price
action_mode	string	false	none	Processing mode: Different fields are returned when placing an order based on action_mode. This field is only valid during the request and is not included in the response ACK: Asynchronous mode, only returns key order fields RESULT: No liquidation information FULL: Full mode (default)

Ticker

{
  "currency_pair": "string",
  "last": "string",
  "lowest_ask": "string",
  "lowest_size": "string",
  "highest_bid": "string",
  "highest_size": "string",
  "change_percentage": "string",
  "change_utc0": "string",
  "change_utc8": "string",
  "base_volume": "string",
  "quote_volume": "string",
  "high_24h": "string",
  "low_24h": "string",
  "etf_net_value": "string",
  "etf_pre_net_value": "string",
  "etf_pre_timestamp": 0,
  "etf_leverage": "string"
}

Properties

Name	Type	Required	Restrictions	Description
currency_pair	string	false	none	Currency pair
last	string	false	none	Last trading price
lowest_ask	string	false	none	Recent lowest ask
lowest_size	string	false	none	Latest seller's lowest price quantity; not available for batch queries; available for single queries, empty if no data
highest_bid	string	false	none	Recent highest bid
highest_size	string	false	none	Latest buyer's highest price quantity; not available for batch queries; available for single queries, empty if no data
change_percentage	string	false	none	24h price change percentage (negative for decrease, e.g., -7.45)
change_utc0	string	false	none	UTC+0 timezone, 24h price change percentage, negative for decline (e.g., -7.45)
change_utc8	string	false	none	UTC+8 timezone, 24h price change percentage, negative for decline (e.g., -7.45)
base_volume	string	false	none	Base currency trading volume in the last 24h
quote_volume	string	false	none	Quote currency trading volume in the last 24h
high_24h	string	false	none	24h High
low_24h	string	false	none	24h Low
etf_net_value	string	false	none	ETF net value
etf_pre_net_value	string|null	false	none	ETF net value at previous rebalancing point
etf_pre_timestamp	integer(int64)|null	false	none	ETF previous rebalancing time
etf_leverage	string|null	false	none	ETF current leverage

OrderCancel

{
  "id": "string",
  "text": "string",
  "amend_text": "string",
  "succeeded": true,
  "label": "string",
  "message": "string",
  "create_time": "string",
  "update_time": "string",
  "create_time_ms": 0,
  "update_time_ms": 0,
  "status": "open",
  "currency_pair": "string",
  "type": "limit",
  "account": "spot",
  "side": "buy",
  "amount": "string",
  "price": "string",
  "time_in_force": "gtc",
  "iceberg": "string",
  "auto_borrow": true,
  "auto_repay": true,
  "left": "string",
  "filled_amount": "string",
  "fill_price": "string",
  "filled_total": "string",
  "avg_deal_price": "string",
  "fee": "string",
  "fee_currency": "string",
  "point_fee": "string",
  "gt_fee": "string",
  "gt_maker_fee": "string",
  "gt_taker_fee": "string",
  "gt_discount": true,
  "rebated_fee": "string",
  "rebated_fee_currency": "string",
  "stp_id": 0,
  "stp_act": "cn",
  "finish_as": "open",
  "action_mode": "string"
}

Spot order details

Properties

Name	Type	Required	Restrictions	Description
id	string	false	read-only	Order ID
text	string	false	none	User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- prefix 3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4
amend_text	string	false	read-only	The custom data that the user remarked when amending the order
succeeded	boolean	false	none	Request execution result
label	string	false	none	Error label, if any, otherwise an empty string
message	string	false	none	Detailed error message, if any, otherwise an empty string
create_time	string	false	read-only	Creation time of order
update_time	string	false	read-only	Last modification time of order
create_time_ms	integer(int64)	false	read-only	Creation time of order (in milliseconds)
update_time_ms	integer(int64)	false	read-only	Last modification time of order (in milliseconds)
status	string	false	read-only	Order status - open: to be filled - closed: closed order - cancelled: cancelled
currency_pair	string	true	none	Currency pair
type	string	false	none	Order Type - limit : Limit Order - market : Market Order
account	string	false	none	Account type, spot - spot account, margin - leveraged account, unified - unified account
side	string	true	none	Buy or sell order
amount	string	true	none	Trading quantity When type is limit, it refers to the base currency (the currency being traded), such as BTC in BTC_USDT When type is market, it refers to different currencies based on the side: - side: buy refers to quote currency, BTC_USDT means USDT - side: sell refers to base currency, BTC_USDT means BTC
price	string	false	none	Trading price, required when type=limit
time_in_force	string	false	none	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market
iceberg	string	false	none	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported
auto_borrow	boolean	false	write-only	Used in margin or cross margin trading to allow automatic loan of insufficient amount if balance is not enough
auto_repay	boolean	false	none	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order
left	string	false	read-only	Amount left to fill
filled_amount	string	false	read-only	Amount filled
fill_price	string	false	read-only	Total filled in quote currency. Deprecated in favor of filled_total
filled_total	string	false	read-only	Total filled in quote currency
avg_deal_price	string	false	read-only	Average fill price
fee	string	false	read-only	Fee deducted
fee_currency	string	false	read-only	Fee currency unit
point_fee	string	false	read-only	Points used to deduct fee
gt_fee	string	false	read-only	GT used to deduct fee
gt_maker_fee	string	false	read-only	GT amount used to deduct maker fee
gt_taker_fee	string	false	read-only	GT amount used to deduct taker fee
gt_discount	boolean	false	read-only	Whether GT fee deduction is enabled
rebated_fee	string	false	read-only	Rebated fee
rebated_fee_currency	string	false	read-only	Rebated fee currency unit
stp_id	integer	false	read-only	Orders between users in the same stp_id group are not allowed to be self-traded 1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker. 2. stp_id returns 0 by default for orders that have not been set for STP group
stp_act	string	false	none	Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter. 3. If the user did not use stp_act when placing the order, stp_act will return '-' - cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled
finish_as	string	false	read-only	How the order was finished. - open: processing - filled: filled totally - cancelled: manually cancelled - ioc: time in force is IOC, finish immediately - stp: cancelled because self trade prevention
action_mode	string	false	write-only	Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	ioc
finish_as	stp

OrderBook

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

Properties

Name	Type	Required	Restrictions	Description
id	integer(int64)	false	none	Order book ID, which is updated whenever the order book is changed. Valid only when with_id is set to true
current	integer(int64)	false	none	The timestamp of the response data being generated (in milliseconds)
update	integer(int64)	false	none	The timestamp of when the orderbook last changed (in milliseconds)
asks	array	true	none	Ask Depth
» None	array	false	none	Price and Quantity Pair
bids	array	true	none	Bid Depth
» None	array	false	none	Price and Quantity Pair

TriggerOrderResponse

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

TriggerOrderResponse

Properties

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

SpotAccount

{
  "currency": "string",
  "available": "string",
  "locked": "string",
  "update_id": 0
}

Properties

Name	Type	Required	Restrictions	Description
currency	string	false	none	Currency detail
available	string	false	none	Available amount
locked	string	false	none	Locked amount, used in trading
update_id	integer(int64)	false	none	Version number

Trade

{
  "id": "string",
  "create_time": "string",
  "create_time_ms": "string",
  "currency_pair": "string",
  "side": "buy",
  "role": "taker",
  "amount": "string",
  "price": "string",
  "order_id": "string",
  "fee": "string",
  "fee_currency": "string",
  "point_fee": "string",
  "gt_fee": "string",
  "amend_text": "string",
  "sequence_id": "string",
  "text": "string",
  "deal": "string",
  "trade_quote": "string"
}

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	Fill ID
create_time	string	false	none	Fill Time
create_time_ms	string	false	none	Trading time, with millisecond precision
currency_pair	string	false	none	Currency pair
side	string	false	none	Buy or sell order
role	string	false	none	Trade role, not returned in public endpoints
amount	string	false	none	Trade amount
price	string	false	none	Order price
order_id	string	false	none	Related order ID, not returned in public endpoints
fee	string	false	none	Fee deducted, not returned in public endpoints
fee_currency	string	false	none	Fee currency unit, not returned in public endpoints
point_fee	string	false	none	Points used to deduct fee, not returned in public endpoints
gt_fee	string	false	none	GT used to deduct fee, not returned in public endpoints
amend_text	string	false	none	The custom data that the user remarked when amending the order
sequence_id	string	false	none	Consecutive trade ID within a single market. Used to track and identify trades in the specific market
text	string	false	none	Order's Custom Information. This field is not returned by public interfaces. The scenarios pm_liquidate, comb_margin_liquidate, and scm_liquidate represent full-account forced liquidation orders. liquidate represents isolated-account forced liquidation orders.
deal	string	false	none	Total Executed Value
trade_quote	string	false	none	Actual quote currency used for the trade

Enumerated Values

Property	Value
side	buy
side	sell
role	taker
role	maker

Order

{
  "id": "string",
  "text": "string",
  "amend_text": "string",
  "create_time": "string",
  "update_time": "string",
  "create_time_ms": 0,
  "update_time_ms": 0,
  "status": "open",
  "currency_pair": "string",
  "trade_quote": "string",
  "type": "limit",
  "account": "spot",
  "side": "buy",
  "amount": "string",
  "price": "string",
  "time_in_force": "gtc",
  "iceberg": "string",
  "auto_borrow": true,
  "auto_repay": true,
  "left": "string",
  "filled_amount": "string",
  "fill_price": "string",
  "filled_total": "string",
  "avg_deal_price": "string",
  "fee": "string",
  "fee_currency": "string",
  "point_fee": "string",
  "gt_fee": "string",
  "gt_maker_fee": "string",
  "gt_taker_fee": "string",
  "gt_discount": true,
  "rebated_fee": "string",
  "rebated_fee_currency": "string",
  "stp_id": 0,
  "stp_act": "cn",
  "finish_as": "open",
  "action_mode": "string",
  "slippage": "string",
  "stop_profit": {
    "trigger_price": "string",
    "order_price": "string"
  },
  "stop_loss": {
    "trigger_price": "string",
    "order_price": "string"
  }
}

Spot order details

Properties

Name	Type	Required	Restrictions	Description
id	string	false	read-only	Order ID
text	string	false	none	User defined information. If not empty, must follow the rules below: 1. prefixed with t- 2. no longer than 28 bytes without t- prefix 3. can only include 0-9, A-Z, a-z, underscore(_), hyphen(-) or dot(.) Besides user defined information, reserved contents are listed below, denoting how the order is created: - 101: from android - 102: from IOS - 103: from IPAD - 104: from webapp - 3: from web - 2: from apiv2 - apiv4: from apiv4 pm_liquidate, comb_margin_liquidate, and scm_liquidate represent cross-margin liquidation orders liquidate represents isolated-margin liquidation orders
amend_text	string	false	read-only	The custom data that the user remarked when amending the order
create_time	string	false	read-only	Creation time of order
update_time	string	false	read-only	Last modification time of order
create_time_ms	integer(int64)	false	read-only	Creation time of order (in milliseconds)
update_time_ms	integer(int64)	false	read-only	Last modification time of order (in milliseconds)
status	string	false	read-only	Order status - open: to be filled - closed: closed order - cancelled: cancelled
currency_pair	string	true	none	Currency pair
trade_quote	string	false	none	Actual quote currency used for the trade; can be specified only in a unified market
type	string	false	none	Order Type - limit : Limit Order - market : Market Order
account	string	false	none	Account type, spot - spot account, margin - leveraged account, unified - unified account
side	string	true	none	Buy or sell order
amount	string	true	none	Trade amount When type is limit, this is the base currency to trade (the currency being bought or sold), e.g. BTC in BTC_USDT. When type is market, the meaning depends on the side: - side: buy refers to the quote currency, e.g. USDT in BTC_USDT - side: sell refers to the base currency, e.g. BTC in BTC_USDT
price	string	false	none	Trading price, required when type=limit
time_in_force	string	false	none	Time in force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only - poc: PendingOrCancelled, makes a post-only order that always enjoys a maker fee - fok: FillOrKill, fill either completely or none Only ioc and fok are supported when type=market
iceberg	string	false	none	Amount to display for the iceberg order. Null or 0 for normal orders. Hiding all amount is not supported
auto_borrow	boolean	false	write-only	Used in margin or cross margin trading to allow automatic loan of insufficient amount if balance is not enough
auto_repay	boolean	false	none	Enable or disable automatic repayment for automatic borrow loan generated by cross margin order. Default is disabled. Note that: 1. This field is only effective for cross margin orders. Margin account does not support setting auto repayment for orders. 2. auto_borrow and auto_repay can be both set to true in one order
left	string	false	read-only	Amount left to fill
filled_amount	string	false	read-only	Amount filled
fill_price	string	false	read-only	Total filled in quote currency. Deprecated in favor of filled_total
filled_total	string	false	read-only	Total filled in quote currency
avg_deal_price	string	false	read-only	Average fill price
fee	string	false	read-only	Fee deducted
fee_currency	string	false	read-only	Fee currency unit
point_fee	string	false	read-only	Points used to deduct fee
gt_fee	string	false	read-only	GT used to deduct fee
gt_maker_fee	string	false	read-only	GT amount used to deduct maker fee
gt_taker_fee	string	false	read-only	GT amount used to deduct taker fee
gt_discount	boolean	false	read-only	Whether GT fee deduction is enabled
rebated_fee	string	false	read-only	Rebated fee
rebated_fee_currency	string	false	read-only	Rebated fee currency unit
stp_id	integer	false	read-only	Orders between users in the same stp_id group are not allowed to be self-traded 1. If the stp_id of two orders being matched is non-zero and equal, they will not be executed. Instead, the corresponding strategy will be executed based on the stp_act of the taker. 2. stp_id returns 0 by default for orders that have not been set for STP group
stp_act	string	false	none	Self-Trading Prevention Action. Users can use this field to set self-trade prevention strategies 1. After users join the STP Group, they can pass stp_act to limit the user's self-trade prevention strategy. If stp_act is not passed, the default is cn strategy. 2. When the user does not join the STP group, an error will be returned when passing the stp_act parameter. 3. If the user did not use stp_act when placing the order, stp_act will return '-' - cn: Cancel newest, cancel new orders and keep old ones - co: Cancel oldest, cancel old orders and keep new ones - cb: Cancel both, both old and new orders will be cancelled
finish_as	string	false	read-only	How the order finished: - open: Pending processing - filled: Fully filled - cancelled: Cancelled by user - liquidate_cancelled: Cancelled by liquidation - small: Order size too small - depth_not_enough: Cancelled due to insufficient order book depth - trader_not_enough: Cancelled due to insufficient counterparty liquidity - ioc: Not filled immediately because time-in-force is IOC - poc: Post-only requirement not met because time-in-force is set to poc (maker-only); rejected after being detected as taker - fok: Not fully filled immediately because time-in-force is FOK - stp: Cancelled due to self-trade prevention - price_protect_cancelled: Cancelled due to price protection - unknown: Unknown
action_mode	string	false	write-only	Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)
slippage	string	false	write-only	Maximum supported slippage ratio for Spot Market Order Placement, calculated based on the latest market price at the time of order placement as the benchmark (Example: 0.03 means 3%)
stop_profit	object	false	none	Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged.
» trigger_price	string	false	none	Take profit trigger price When side == "buy", trigger_price must be greater than price When side == "sell", trigger_price must be less than price
» order_price	string	false	none	Take profit order price
stop_loss	object	false	none	Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged.
» trigger_price	string	false	none	Stop loss trigger price When side == "buy", trigger_price must be less than price When side == "sell", trigger_price must be greater than price
» order_price	string	false	none	Stop-loss order price

Enumerated Values

Property	Value
status	open
status	closed
status	cancelled
type	limit
type	market
side	buy
side	sell
time_in_force	gtc
time_in_force	ioc
time_in_force	poc
time_in_force	fok
stp_act	cn
stp_act	co
stp_act	cb
stp_act	-
finish_as	open
finish_as	filled
finish_as	cancelled
finish_as	liquidate_cancelled
finish_as	depth_not_enough
finish_as	trader_not_enough
finish_as	small
finish_as	ioc
finish_as	poc
finish_as	fok
finish_as	stp
finish_as	price_protect_cancelled
finish_as	unknown

SpotAccountBook

{
  "id": "string",
  "time": 0,
  "currency": "string",
  "change": "string",
  "balance": "string",
  "type": "string",
  "code": "string",
  "text": "string"
}

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	Balance change record ID
time	integer(int64)	false	none	The timestamp of the change (in milliseconds)
currency	string	false	none	Currency changed
change	string	false	none	Amount changed. Positive value means transferring in, while negative out
balance	string	false	none	Balance after change
type	string	false	none	Account change type; deprecated (see code for account change type encoding)
code	string	false	none	Account change code, see [Asset Record Code] (Asset Record Code)
text	string	false	none	Additional information

SpotFee

{
  "user_id": 0,
  "taker_fee": "string",
  "maker_fee": "string",
  "rpi_maker_fee": "string",
  "gt_discount": true,
  "gt_taker_fee": "string",
  "gt_maker_fee": "string",
  "loan_fee": "string",
  "point_type": "string",
  "currency_pair": "string",
  "debit_fee": 0,
  "rpi_mm": 0
}

Properties

Name	Type	Required	Restrictions	Description
user_id	integer(int64)	false	none	User ID
taker_fee	string	false	none	taker fee rate
maker_fee	string	false	none	maker fee rate
rpi_maker_fee	string	false	none	RPI MM maker fee rate
gt_discount	boolean	false	none	Whether GT deduction discount is enabled
gt_taker_fee	string	false	none	Taker fee rate if using GT deduction. It will be 0 if GT deduction is disabled
gt_maker_fee	string	false	none	Maker fee rate with GT deduction. Returns 0 if GT deduction is disabled
loan_fee	string	false	none	Loan fee rate of margin lending
point_type	string	false	none	Point card type: 0 - Original version, 1 - New version since 202009
currency_pair	string	false	none	Currency pair
debit_fee	integer	false	none	Deduction types for rates, 1 - GT deduction, 2 - Point card deduction, 3 - VIP rates
rpi_mm	integer	false	none	RPI MM Level

CancelBatchOrder

{
  "currency_pair": "string",
  "id": "string",
  "account": "string",
  "action_mode": "string"
}

Info of order to be cancelled

Properties

Name	Type	Required	Restrictions	Description
currency_pair	string	true	none	Order currency pair
id	string	true	none	Order ID or user custom ID. Custom ID are accepted only within 30 minutes after order creation
account	string	false	none	If the canceled order is a unified account apikey, this field must be specified and set to unified
action_mode	string	false	none	Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)

SpotPovOrderCreator

{
  "currency_pair": "string",
  "side": "buy",
  "amount": "string",
  "participation_rate": 0,
  "ttl": "string",
  "limit_price": "string",
  "trigger_price": "string",
  "text": "string"
}

Spot POV order creation request

Properties

Name	Type	Required	Restrictions	Description
currency_pair	string	true	none	Currency pair
side	string	true	none	Buy or sell order
amount	string	true	none	Trade amount
participation_rate	integer	true	none	Target participation rate as a percentage. Valid values: 5, 10, 20, and 40
ttl	string	true	none	Time to live. Valid values: 1h, 6h, 12h, 1d, 2d, 3d, 4d, 5d, 6d, and 7d
limit_price	string	false	none	Limit price. If omitted, the market price is used
trigger_price	string	false	none	Trigger price. If omitted, the order is triggered immediately
text	string	false	none	Order custom information. Users can set custom ID with this field. Custom fields must meet the following conditions: 1. Must start with t- 2. Excluding t-, length cannot exceed 28 bytes 3. Can only contain numbers, letters, underscore(_), hyphen(-) or dot(.)

Enumerated Values

Property	Value
side	buy
side	sell

SystemTime

{
  "server_time": 0
}

SystemTime

Properties

Name	Type	Required	Restrictions	Description
server_time	integer(int64)	false	none	Server current time(ms)

SpotPriceTriggeredOrder

{
  "trigger": {
    "price": "string",
    "rule": ">=",
    "expiration": 0
  },
  "put": {
    "type": "limit",
    "side": "buy",
    "price": "string",
    "amount": "string",
    "account": "normal",
    "time_in_force": "gtc",
    "auto_borrow": false,
    "auto_repay": false,
    "text": "string"
  },
  "id": 0,
  "user": 0,
  "market": "string",
  "ctime": 0,
  "ftime": 0,
  "fired_order_id": 0,
  "status": "string",
  "reason": "string"
}

Spot price order details

Properties

Name	Type	Required	Restrictions	Description
trigger	SpotPriceTrigger	true	none	none
put	SpotPricePutOrder	true	none	none
id	integer(int64)	false	read-only	Auto order ID
user	integer	false	read-only	User ID
market	string	true	none	Market
ctime	integer(int64)	false	read-only	Created time
ftime	integer(int64)	false	read-only	End time
fired_order_id	integer(int64)	false	read-only	ID of the order created after trigger
status	string	false	read-only	Status - open: Running - cancelled: Manually cancelled - finish: Successfully completed - failed: Failed to execute - expired: Expired
reason	string	false	read-only	Additional description of how the order was completed

OrderPatch

{
  "currency_pair": "string",
  "account": "string",
  "amount": "string",
  "price": "string",
  "amend_text": "string",
  "action_mode": "string",
  "stop_profit": {
    "trigger_price": "string",
    "order_price": "string"
  },
  "stop_loss": {
    "trigger_price": "string",
    "order_price": "string"
  }
}

Spot order details

Properties

Name	Type	Required	Restrictions	Description
currency_pair	string	false	none	Currency pair
account	string	false	none	Specify query account
amount	string	false	none	Trading quantity. Either amount or price must be specified
price	string	false	none	Trading price. Either amount or price must be specified
amend_text	string	false	none	Custom info during order amendment
action_mode	string	false	none	Processing Mode: When placing an order, different fields are returned based on action_mode. This field is only valid during the request and is not included in the response result ACK: Asynchronous mode, only returns key order fields RESULT: No clearing information FULL: Full mode (default)
stop_profit	object	false	none	Take profit for limit orders. Pass {} to cancel take profit; pass null to leave take profit unchanged.
» trigger_price	string	false	none	Take profit trigger price When side == "buy", trigger_price must be greater than price When side == "sell", trigger_price must be less than price
» order_price	string	false	none	Take profit order price
stop_loss	object	false	none	Stop loss for limit orders. Pass {} to cancel stop loss; pass null to leave stop loss unchanged.
» trigger_price	string	false	none	Stop loss trigger price When side == "buy", trigger_price must be less than price When side == "sell", trigger_price must be greater than price
» order_price	string	false	none	Stop-loss order price

SpotPricePutOrder

{
  "type": "limit",
  "side": "buy",
  "price": "string",
  "amount": "string",
  "account": "normal",
  "time_in_force": "gtc",
  "auto_borrow": false,
  "auto_repay": false,
  "text": "string"
}

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	Order type，default to limit - limit : Limit Order - market : Market Order
side	string	true	none	Order side - buy: buy side - sell: sell side
price	string	true	none	Order price
amount	string	true	none	Trading quantity, refers to the trading quantity of the trading currency, i.e., the currency that needs to be traded, for example, the quantity of BTC in BTC_USDT.
account	string	true	none	Trading account type. Unified account must be set to unified - normal: spot trading - margin: margin trading - unified: unified account
time_in_force	string	true	none	time_in_force - gtc: GoodTillCancelled - ioc: ImmediateOrCancelled, taker only
auto_borrow	boolean	false	none	Whether to borrow coins automatically
auto_repay	boolean	false	none	Whether to repay the loan automatically
text	string	false	none	The source of the order, including: - web: Web - api: API call - app: Mobile app

Enumerated Values

Property	Value
type	limit
type	market
side	buy
side	sell
account	normal
account	margin
account	unified
time_in_force	gtc
time_in_force	ioc

SpotPriceTrigger

{
  "price": "string",
  "rule": ">=",
  "expiration": 0
}

Properties

Name	Type	Required	Restrictions	Description
price	string	true	none	Trigger price
rule	string	true	none	Price trigger condition - >=: triggered when market price is greater than or equal to price - <=: triggered when market price is less than or equal to price
expiration	integer	false	none	Maximum wait time for trigger condition (in seconds). Order will be cancelled if timeout

Enumerated Values

Property	Value
rule	>=
rule	<=