基本信息

Rest 基本信息¶

接口可能需要用户的 API Key，如何创建API-KEY请参考这里
本篇列出REST接口的baseurl https://fapi.asterdex.com
所有接口的响应都是JSON格式
响应中如有数组，数组元素以时间升序排列，越早的数据越提前。
所有时间、时间戳均为UNIX时间，单位为毫秒
所有数据类型采用JAVA的数据类型定义

HTTP 返回代码¶

HTTP 4XX 错误码用于指示错误的请求内容、行为、格式。
HTTP 403 错误码表示违反WAF限制(Web应用程序防火墙)。
HTTP 429 错误码表示警告访问频次超限，即将被封IP
HTTP 418 表示收到429后继续访问，于是被封了。
HTTP 5XX 错误码用于指示Aster Finance服务侧的问题。
HTTP 503 表示API服务端已经向业务核心提交了请求但未能获取响应，特别需要注意的是其不代表请求失败，而是未知。很可能已经得到了执行，也有可能执行失败，需要做进一步确认。

接口错误代码¶

每个接口都有可能抛出异常

异常响应格式如下：

{
  "code": -1121,
  "msg": "Invalid symbol."
}

具体的错误码及其解释在错误码页面

接口的基本信息¶

GET方法的接口, 参数必须在query string中发送.
POST, PUT, 和 DELETE 方法的接口, 参数可以在 query string中发送，也可以在 request body中发送(content type application/x-www-form-urlencoded)。允许混合这两种方式发送参数。但如果同一个参数名在query string和request body中都有，query string中的会被优先采用。
对参数的顺序不做要求。

访问限制¶

在 /fapi/v1/exchangeInfo接口中rateLimits数组里包含有REST接口(不限于本篇的REST接口)的访问限制。包括带权重的访问频次限制、下单速率限制。本篇枚举定义章节有限制类型的进一步说明。
违反上述任何一个访问限制都会收到HTTP 429，这是一个警告.

IP 访问限制¶

每个请求将包含一个X-MBX-USED-WEIGHT-(intervalNum)(intervalLetter)的头，其中包含当前IP所有请求的已使用权重。
每个路由都有一个"权重"，该权重确定每个接口计数的请求数。较重的接口和对多个交易对进行操作的接口将具有较重的"权重"。
收到429时，您有责任作为API退回而不向其发送更多的请求。
如果屡次违反速率限制和/或在收到429后未能退回，将导致API的IP被禁(http状态418)。
频繁违反限制，封禁时间会逐渐延长，对于重复违反者，将会被封从2分钟到3天。
访问限制是基于IP的，而不是API Key

下单频率限制¶

每个下单请求回报将包含一个X-MBX-ORDER-COUNT-(intervalNum)(intervalLetter)的头，其中包含当前账户已用的下单限制数量。
被拒绝或不成功的下单并不保证回报中包含以上头内容。
下单频率限制是基于每个账户计数的。

接口鉴权类型¶

每个接口都有自己的鉴权类型，鉴权类型决定了访问时应当进行何种鉴权
如果需要 API-key，应当在HTTP头中以X-MBX-APIKEY字段传递
API-key 与 API-secret 是大小写敏感的
可以在网页用户中心修改API-key 所具有的权限，例如读取账户信息、发送交易指令、发送提现指令

鉴权类型	描述
NONE	不需要鉴权的接口
TRADE	需要有效的API-KEY和签名
USER_DATA	需要有效的API-KEY和签名
USER_STREAM	需要有效的API-KEY
MARKET_DATA	需要有效的API-KEY

需要签名的接口 (TRADE 与 USER_DATA)¶

调用这些接口时，除了接口本身所需的参数外，还需要传递signature即签名参数。
签名使用HMAC SHA256算法. API-KEY所对应的API-Secret作为 HMAC SHA256 的密钥，其他所有参数作为HMAC SHA256的操作对象，得到的输出即为签名。
签名大小写不敏感。
当同时使用query string和request body时，HMAC SHA256的输入query string在前，request body在后

时间同步安全¶

签名接口均需要传递timestamp参数, 其值应当是请求发送时刻的unix时间戳(毫秒)
服务器收到请求时会判断请求中的时间戳，如果是5000毫秒之前发出的，则请求会被认为无效。这个时间窗口值可以通过发送可选参数recvWindow来自定义。
另外，如果服务器计算得出客户端时间戳在服务器时间的‘未来’一秒以上，也会拒绝请求。

逻辑伪代码：

if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow) {
  // process request
} else {
  // reject request
}

关于交易时效性 互联网状况并不100%可靠，不可完全依赖,因此你的程序本地到服务器的时延会有抖动. 这是我们设置recvWindow的目的所在，如果你从事高频交易，对交易时效性有较高的要求，可以灵活设置recvWindow以达到你的要求。

POST /fapi/v1/order 的示例¶

以下是在linux bash环境下使用 echo openssl 和curl工具实现的一个调用接口下单的示例 apikey、secret仅供示范

Key	Value
apiKey	dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83
secretKey	2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9

参数	取值
symbol	BTCUSDT
side	BUY
type	LIMIT
timeInForce	GTC
quantity	1
price	9000
recvWindow	5000
timestamp	1591702613943

示例 1: 所有参数通过 query string 发送¶

示例1:

HMAC SHA256 签名:

    $ echo -n "symbol=BTCUSDT&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000&timestamp=1591702613943" | openssl dgst -sha256 -hmac "2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9"
    (stdin)= 3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9

curl 调用:

    (HMAC SHA256)
    $ curl -H "X-MBX-APIKEY: dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83" -X POST 'https://fapi.asterdex.com/fapi/v1/order?symbol=BTCUSDT&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000&timestamp=1591702613943&signature= 3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9'

queryString:

symbol=BTCUSDT
&side=BUY
&type=LIMIT
&timeInForce=GTC
&quantity=1
&price=0.1
&recvWindow=5000
&timestamp=1499827319559

示例 2: 所有参数通过 request body 发送¶

示例2:

HMAC SHA256 签名:

    $ echo -n "symbol=BTCUSDT&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000&timestamp=1591702613943" | openssl dgst -sha256 -hmac "2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9"
    (stdin)= 3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9

curl 调用:

    (HMAC SHA256)
    $ curl -H "X-MBX-APIKEY: dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83" -X POST 'https://fapi.asterdex.com/fapi/v1/order' -d 'symbol=BTCUSDT&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000&timestamp=1591702613943&signature= 3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9'

requestBody:

symbol=BTCUSDT
&side=BUY
&type=LIMIT
&timeInForce=GTC
&quantity=1
&price=9000
&recvWindow=5000
&timestamp=1591702613943

示例 3: 混合使用 query string 与 request body¶

示例3:

HMAC SHA256 签名:

    $ echo -n "symbol=BTCUSDT&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000&timestamp=1591702613943" | openssl dgst -sha256 -hmac "2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9"
    (stdin)= 3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9

curl 调用:

    (HMAC SHA256)
    $ curl -H "X-MBX-APIKEY: dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83" -X POST 'https://fapi.asterdex.com/fapi/v1/order?symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTC' -d 'quantity=1&price=9000&recvWindow=5000&timestamp=1591702613943&signature=3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9'

queryString: symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTC
requestBody: quantity=1&price=9000&recvWindow=5000&timestamp= 1591702613943

请注意，示例3中的签名有些许不同，在"GTC"和"quantity=1"之间没有"&"字符。

公开API参数¶

术语解释¶

base asset 指一个交易对的交易对象，即写在靠前部分的资产名
quote asset 指一个交易对的定价资产，即写在靠后部分资产名

枚举定义¶

交易对类型:

FUTURE 期货

合约类型 (contractType):

PERPETUAL 永续合约

合约状态 (contractStatus, status):

PENDING_TRADING 待上市
TRADING 交易中
PRE_SETTLE 预结算
SETTLING 结算中
CLOSE 已下架

订单状态 (status):

NEW 新建订单
PARTIALLY_FILLED 部分成交
FILLED 全部成交
CANCELED 已撤销
REJECTED 订单被拒绝
EXPIRED 订单过期(根据timeInForce参数规则)

订单种类 (orderTypes, type):

LIMIT 限价单
MARKET 市价单
STOP 止损限价单
STOP_MARKET 止损市价单
TAKE_PROFIT 止盈限价单
TAKE_PROFIT_MARKET 止盈市价单
TRAILING_STOP_MARKET 跟踪止损单

订单方向 (side):

BUY 买入
SELL 卖出

持仓方向:

BOTH 单一持仓方向
LONG 多头(双向持仓下)
SHORT 空头(双向持仓下)

有效方式 (timeInForce):

GTC - Good Till Cancel 成交为止
IOC - Immediate or Cancel 无法立即成交(吃单)的部分就撤销
FOK - Fill or Kill 无法全部立即成交就撤销
GTX - Good Till Crossing 无法成为挂单方就撤销
HIDDEN - HIDDEN 该类型订单在订单薄里不可见

条件价格触发类型 (workingType)

MARK_PRICE
CONTRACT_PRICE

响应类型 (newOrderRespType)

ACK
RESULT

K线间隔:

m -> 分钟; h -> 小时; d -> 天; w -> 周; M -> 月

1m
3m
5m
15m
30m
1h
2h
4h
6h
8h
12h
1d
3d
1w
1M

限制种类 (rateLimitType)

REQUEST_WEIGHT

  {
    "rateLimitType": "REQUEST_WEIGHT",
    "interval": "MINUTE",
    "intervalNum": 1,
    "limit": 2400
  }

ORDERS

  {
    "rateLimitType": "ORDERS",
    "interval": "MINUTE",
    "intervalNum": 1,
    "limit": 1200
   }

REQUESTS_WEIGHT 单位时间请求权重之和上限
ORDERS 单位时间下单(撤单)次数上限

限制间隔

MINUTE

过滤器¶

过滤器，即Filter，定义了一系列交易规则。共有两类，分别是针对交易对的过滤器symbol filters，和针对整个交易所的过滤器exchange filters(暂不支持)

交易对过滤器¶

/exchangeInfo 响应中的格式:

  {
    "filterType": "PRICE_FILTER",
    "minPrice": "0.00000100",
    "maxPrice": "100000.00000000",
    "tickSize": "0.00000100"
  }

价格过滤器用于检测order订单中price参数的合法性

minPrice 定义了 price/stopPrice 允许的最小值
maxPrice 定义了 price/stopPrice 允许的最大值。
tickSize 定义了 price/stopPrice 的步进间隔，即price必须等于minPrice+(tickSize的整数倍) 以上每一项均可为0，为0时代表这一项不再做限制。

逻辑伪代码如下：

price >= minPrice
price <= maxPrice
(price-minPrice) % tickSize == 0

LOT_SIZE 订单尺寸¶

/exchangeInfo 响应中的格式:*

  {
    "filterType": "LOT_SIZE",
    "minQty": "0.00100000",
    "maxQty": "100000.00000000",
    "stepSize": "0.00100000"
  }

lots是拍卖术语，这个过滤器对订单中的quantity也就是数量参数进行合法性检查。包含三个部分：

minQty 表示 quantity 允许的最小值.
maxQty 表示 quantity 允许的最大值
stepSize 表示 quantity允许的步进值。

逻辑伪代码如下：

quantity >= minQty
quantity <= maxQty
(quantity-minQty) % stepSize == 0

MARKET_LOT_SIZE 市价订单尺寸¶

参考LOT_SIZE，区别仅在于对市价单还是限价单生效

MAX_NUM_ORDERS 最多订单数¶

/exchangeInfo 响应中的格式:

  {
    "filterType": "MAX_NUM_ORDERS",
    "limit": 200
  }

定义了某个交易对最多允许的挂单数量(不包括已关闭的订单)

普通订单与条件订单均计算在内

MAX_NUM_ALGO_ORDERS 最多条件订单数¶

/exchangeInfo format:

  {
    "filterType": "MAX_NUM_ALGO_ORDERS",
    "limit": 100
  }

定义了某个交易对最多允许的条件订单的挂单数量(不包括已关闭的订单)。

条件订单目前包括STOP, STOP_MARKET, TAKE_PROFIT, TAKE_PROFIT_MARKET, 和 TRAILING_STOP_MARKET

PERCENT_PRICE 价格振幅过滤器¶

/exchangeInfo 响应中的格式:

  {
    "filterType": "PERCENT_PRICE",
    "multiplierUp": "1.1500",
    "multiplierDown": "0.8500",
    "multiplierDecimal": 4
  }

PERCENT_PRICE 定义了基于标记价格计算的挂单价格的可接受区间.

挂单价格必须同时满足以下条件：

买单: price <= markPrice * multiplierUp
卖单: price >= markPrice * multiplierDown

MIN_NOTIONAL 最小名义价值¶

/exchangeInfo 响应中的格式:

  {
    "filterType": "MIN_NOTIONAL",
    "notioanl": "1"
  }

MIN_NOTIONAL过滤器定义了交易对订单所允许的最小名义价值(成交额)。订单的名义价值是价格*数量。由于MARKET订单没有价格，因此会使用 mark price 计算。

基本信息

Rest 基本信息¶

HTTP 返回代码¶

接口错误代码¶

接口的基本信息¶

访问限制¶

IP 访问限制¶

下单频率限制¶

接口鉴权类型¶

需要签名的接口 (TRADE 与 USER_DATA)¶

时间同步安全¶

POST /fapi/v1/order 的示例¶

示例 1: 所有参数通过 query string 发送¶

示例 2: 所有参数通过 request body 发送¶

示例 3: 混合使用 query string 与 request body¶

公开API参数¶

术语解释¶

枚举定义¶

过滤器¶

交易对过滤器¶

PRICE_FILTER 价格过滤器¶

LOT_SIZE 订单尺寸¶

MARKET_LOT_SIZE 市价订单尺寸¶

MAX_NUM_ORDERS 最多订单数¶

MAX_NUM_ALGO_ORDERS 最多条件订单数¶

PERCENT_PRICE 价格振幅过滤器¶

MIN_NOTIONAL 最小名义价值¶