REST行情与交易接口 (2021-05-12)

基本信息

本篇列出REST接口的baseurl https://api.binance.com
如果上面的baseURL访问有性能问题，请访问下面的API集群:
- https://api1.binance.com
- https://api2.binance.com
- https://api3.binance.com
所有接口的响应都是JSON格式
响应中如有数组，数组元素以时间升序排列，越早的数据越提前。
所有时间、时间戳均为UNIX时间，单位为毫秒
HTTP 4XX 错误码用于指示错误的请求内容、行为、格式。
HTTP 429 错误码表示警告访问频次超限，即将被封IP
HTTP 418 表示收到429后继续访问，于是被封了。
HTTP 5XX 错误码用于指示Binance服务侧的问题。
HTTP 504 表示API服务端已经向业务核心提交了请求但未能获取响应，特别需要注意的是504代码不代表请求失败，而是未知。很可能已经得到了执行，也有可能执行失败，需要做进一步确认。
每个接口都有可能抛出异常，异常响应格式如下：

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

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

访问限制

在 /api/v3/exchangeInfo接口中rateLimits数组里包含有REST接口(不限于本篇的REST接口)的访问限制。包括带权重的访问频次限制、下单速率限制。本篇枚举定义章节有限制类型的进一步说明。
违反上述任何一个访问限制都会收到HTTP 429，这是一个警告.
每一个接口均有一个相应的权重(weight)，有的接口根据参数不同可能拥有不同的权重。越消耗资源的接口权重就会越大。
当收到429告警时，调用者应当降低访问频率或者停止访问。
收到429后仍然继续违反访问限制，会被封禁IP，并收到418错误码
频繁违反限制，封禁时间会逐渐延长，从最短2分钟到最长3天.

数据来源

因为API系统是异步的, 所以返回的数据有延时很正常, 也在预期之中。
在每个接口中，都列出了其数据的来源，可以用于理解数据的时效性。

系统一共有3个数据来源，按照更新速度的先后排序。排在前面的数据最新，在后面就有可能存在延迟。

撮合引擎 - 表示数据来源于撮合引擎
缓存 - 表示数据来源于内部或者外部的缓存
数据库 - 表示数据直接来源于数据库

有些接口有不止一个数据源, 比如 缓存 => 数据库, 这表示接口会先从第一个数据源检查，如果没有数据，则检查下一个数据源。

接口鉴权类型

每个接口都有自己的鉴权类型，鉴权类型决定了访问时应当进行何种鉴权
如果需要 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以达到你的要求。 不推荐使用5秒以上的recvWindow

POST /api/v3/order 的示例

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

Key	Value
apiKey	vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
secretKey	NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j

参数	取值
symbol	LTCBTC
side	BUY
type	LIMIT
timeInForce	GTC
quantity	1
price	0.1
recvWindow	5000
timestamp	1499827319559

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

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

HMAC SHA256 签名:

[linux]$ echo -n "symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71

curl 调用:

(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api.binance.com/api/v3/order?symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559&signature=c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71'

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

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

HMAC SHA256 签名:

[linux]$ echo -n "symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71

curl 调用:

(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api.binance.com/api/v3/order' -d 'symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559&signature=c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71'

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

queryString: symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC
requestBody: quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559

HMAC SHA256 签名:

[linux]$ echo -n "symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTCquantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= 0fd168b8ddb4876a0358a8d14d0c9f3da0e9b20c5d52b2a00fcf7d1c602f9a77

curl 调用:

(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api.binance.com/api/v3/order?symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC' -d 'quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559&signature=0fd168b8ddb4876a0358a8d14d0c9f3da0e9b20c5d52b2a00fcf7d1c602f9a77'

Note that the signature is different in example 3. There is no & between "GTC" and "quantity=1".

公开API接口

术语解释

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

枚举定义

交易对状态 (status):

PRE_TRADING 盘前交易
TRADING 正常交易中
POST_TRADING 盘后交易
END_OF_DAY 收盘
HALT 交易终止(该交易对已下线)
AUCTION_MATCH 集合竞价
BREAK 交易暂停

交易对类型:

SPOT 现货

订单状态 (status):

NEW 新建订单
PARTIALLY_FILLED 部分成交
FILLED 全部成交
CANCELED 已撤销
PENDING_CANCEL 正在撤销中(目前不会遇到这个状态)
REJECTED 订单被拒绝
EXPIRED 订单过期(根据timeInForce参数规则)

订单种类 (orderTypes, type):

LIMIT 限价单
MARKET 市价单
STOP_LOSS 止损单
STOP_LOSS_LIMIT 限价止损单
TAKE_PROFIT 止盈单
TAKE_PROFIT_LIMIT 限价止盈单
LIMIT_MAKER 限价做市单

订单返回类型 (newOrderRespType):

ACK
RESULT
FULL

订单方向 (side):

BUY - 买入
SELL - 卖出

Time in force (timeInForce):

GTC - Good Till Cancel 成交为止
IOC - Immediate or Cancel 无法立即成交(吃单)的部分就撤销
FOK - Fill or Kill 无法全部立即成交就撤销

K线间隔 (interval):

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

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

限制种类 (rateLimitType):

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

限制间隔 (interval):

SECOND
MINUTE
DAY

通用接口

测试服务器连通性 PING

GET /api/v3/ping

测试能否联通

权重: 1

参数: NONE

数据源: 缓存

响应:

{}

获取服务器时间

GET /api/v3/time

获取服务器时间

权重: 1

参数: NONE

数据源: 缓存

响应:

{
  "serverTime": 1499827319559
}

交易规范信息

GET /api/v3/exchangeInfo

获取此时的交易规范信息

权重: 10

参数:

有三种用法

用法	举例
不需要交易对	curl -X GET "https://api.binance.com/api/v3/exchangeInfo"
单个交易对	curl -X GET "https://api.binance.com/api/v3/exchangeInfo?symbol=BNBBTC"
多个交易对	curl -X GET "https://api.binance.com/api/v3/exchangeInfo?symbols=%5B%22BNBBTC%22,%22BTCUSDT%22%5D" or curl -g GET 'https://api.binance.com/api/v3/exchangeInfo?symbols=["BTCUSDT","BNBBTC"]'

如果传入的交易对不存在, 接口会返回错误。

数据源: 缓存

响应:

{
  "timezone": "UTC",
  "serverTime": 1508631584636,
  "rateLimits": [{
      "rateLimitType": "REQUESTS_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 1200 //每分钟调用的所有接口权重之和不得超过1200
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "SECOND",
      "intervalNum": 1,
      "limit": 10 //每秒钟所有订单/撤单次数不得超过10
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "DAY",
      "intervalNum": 1,
      "limit": 100000 //每天订单/撤单不得超过10万
    },
    {
      "rateLimitType": "RAW_REQUESTS",
      "interval": "MINUTE",
      "intervalNum": 5,
      "limit": 5000 //每5分钟调用订单次数不得超过5000
    }
  ],
  "exchangeFilters": [],
  "symbols": [{
    "symbol": "ETHBTC",
    "status": "TRADING",
    "baseAsset": "ETH",
    "baseAssetPrecision": 8,
    "quoteAsset": "BTC",
    "quotePrecision": 8,
    "quoteAssetPrecision": 8,
    "orderTypes": ["LIMIT", "MARKET"],
    "icebergAllowed": false,
    "filters": [{
      "filterType": "PRICE_FILTER",
      "minPrice": "0.00000100",
      "maxPrice": "100000.00000000",
      "tickSize": "0.00000100"
    }, {
      "filterType": "LOT_SIZE",
      "minQty": "0.00100000",
      "maxQty": "100000.00000000",
      "stepSize": "0.00100000"
    }, {
      "filterType": "MIN_NOTIONAL",
      "minNotional": "0.00100000",
      "applyToMarket": true,
      "avgPriceMins": 5
    }]
  }]
}

行情接口

深度信息

GET /api/v3/depth

权重:

Limit	Weight
5, 10, 20, 50, 100	1
500	5
1000	10

参数:

名称	类型	是否必须	描述
symbol	STRING	YES
limit	INT	NO	默认 100; 最大 1000. 可选值:[5, 10, 20, 50, 100, 500, 1000]

注意: limit=0 返回全部orderbook，但数据量会非常非常非常非常大！

数据源: 缓存

响应:

{
  "lastUpdateId": 1027024,
  "bids": [
    [
      "4.00000000",     // 价位
      "431.00000000",   // 挂单量
      []                // 请忽略.
    ]
  ],
  "asks": [
    [
      "4.00000200",
      "12.00000000",
      []
    ]
  ]
}

近期成交

GET /api/v3/trades

获取近期成交

权重: 1

参数:

Name	Type	Mandatory	Description
symbol	STRING	YES
limit	INT	NO	Default 500; max 1000.

数据源: 缓存

响应:

[
  {
    "id": 28457,
    "price": "4.00000100",
    "qty": "12.00000000",
    "time": 1499865549590,
    "isBuyerMaker": true,
    "isBestMatch": true
  }
]

查询历史成交(MARKET_DATA)

GET /api/v3/historicalTrades

权重: 5

参数:

Name	Type	Mandatory	Description
symbol	STRING	YES
limit	INT	NO	Default 500; max 1000.
fromId	LONG	NO	从哪一条成交id开始返回. 缺省返回最近的成交记录

数据源: 数据库

响应:

[
  {
    "id": 28457,
    "price": "4.00000100",
    "qty": "12.00000000",
    "time": 1499865549590,
    "isBuyerMaker": true,
    "isBestMatch": true
  }
]

近期成交(归集)

GET /api/v3/aggTrades

与trades的区别是，同一个taker在同一时间同一价格与多个maker的成交会被合并为一条记录

权重: 1

参数:

Name	Type	Mandatory	Description
symbol	STRING	YES
fromId	LONG	NO	从包含fromID的成交开始返回结果
startTime	LONG	NO	从该时刻之后的成交记录开始返回结果
endTime	LONG	NO	返回该时刻为止的成交记录
limit	INT	NO	默认 500; 最大 1000.

如果同时发送startTime和endTime，间隔必须小于一小时
如果没有发送任何筛选参数(fromId, startTime,endTime)，默认返回最近的成交记录

数据源: 数据库

响应:

[
  {
    "a": 26129,         // 归集成交ID
    "p": "0.01633102",  // 成交价
    "q": "4.70443515",  // 成交量
    "f": 27781,         // 被归集的首个成交ID
    "l": 27781,         // 被归集的末个成交ID
    "T": 1498793709153, // 成交时间
    "m": true,          // 是否为主动卖出单
    "M": true           // 是否为最优撮合单(可忽略，目前总为最优撮合)
  }
]

K线数据

GET /api/v3/klines

每根K线的开盘时间可视为唯一ID

权重: 1

参数:

Name	Type	Mandatory	Description
symbol	STRING	YES
interval	ENUM	YES	详见枚举定义：K线间隔
startTime	LONG	NO
endTime	LONG	NO
limit	INT	NO	Default 500; max 1000.

缺省返回最近的数据

数据源: 数据库

响应:

[
  [
    1499040000000,      // 开盘时间
    "0.01634790",       // 开盘价
    "0.80000000",       // 最高价
    "0.01575800",       // 最低价
    "0.01577100",       // 收盘价(当前K线未结束的即为最新价)
    "148976.11427815",  // 成交量
    1499644799999,      // 收盘时间
    "2434.19055334",    // 成交额
    308,                // 成交笔数
    "1756.87402397",    // 主动买入成交量
    "28.46694368",      // 主动买入成交额
    "17928899.62484339" // 请忽略该参数
  ]
]

当前平均价格

GET /api/v3/avgPrice

权重: 1 参数:

Name	Type	Mandatory	Description
symbol	STRING	YES

数据源: 缓存

响应:

{
  "mins": 5,
  "price": "9.35751834"
}

24hr价格变动情况

GET /api/v3/ticker/24hr

请注意，不携带symbol参数会返回全部交易对数据，不仅数据庞大，而且权重极高

权重: 带symbol为1 不带为40

参数:

Name	Type	Mandatory	Description
symbol	STRING	NO

数据源: 缓存

响应:

{
  "symbol": "BNBBTC",
  "priceChange": "-94.99999800",
  "priceChangePercent": "-95.960",
  "weightedAvgPrice": "0.29628482",
  "prevClosePrice": "0.10002000",
  "lastPrice": "4.00000200",
  "lastQty": "200.00000000",
  "bidPrice": "4.00000000",
  "askPrice": "4.00000200",
  "openPrice": "99.00000000",
  "highPrice": "100.00000000",
  "lowPrice": "0.10000000",
  "volume": "8913.30000000",
  "quoteVolume": "15.30000000",
  "openTime": 1499783499040,
  "closeTime": 1499869899040,
  "firstId": 28385,   // 首笔成交id
  "lastId": 28460,    // 末笔成交id
  "count": 76         // 成交笔数
}

OR

[
  {
    "symbol": "BNBBTC",
    "priceChange": "-94.99999800",
    "priceChangePercent": "-95.960",
    "weightedAvgPrice": "0.29628482",
    "prevClosePrice": "0.10002000",
    "lastPrice": "4.00000200",
    "lastQty": "200.00000000",
    "bidPrice": "4.00000000",
    "askPrice": "4.00000200",
    "openPrice": "99.00000000",
    "highPrice": "100.00000000",
    "lowPrice": "0.10000000",
    "volume": "8913.30000000",
    "quoteVolume": "15.30000000",
    "openTime": 1499783499040,
    "closeTime": 1499869899040,
  "firstId": 28385,   // 首笔成交id
  "lastId": 28460,    // 末笔成交id
  "count": 76         // 成交笔数
  }
]

最优挂单接口

GET /api/v3/ticker/bookTicker

返回当前最优的挂单(最高买单，最低卖单)

权重: 单交易对1 无交易对2

参数:

Name	Type	Mandatory	Description
symbol	STRING	NO

不发送交易对参数，则会返回所有交易对信息

数据源: 缓存

响应:

{
  "symbol": "LTCBTC",
  "bidPrice": "4.00000000",//最优买单价
  "bidQty": "431.00000000",//挂单量
  "askPrice": "4.00000200",//最优卖单价
  "askQty": "9.00000000"//挂单量
}

OR

[
  {
    "symbol": "LTCBTC",
    "bidPrice": "4.00000000",
    "bidQty": "431.00000000",
    "askPrice": "4.00000200",
    "askQty": "9.00000000"
  },
  {
    "symbol": "ETHBTC",
    "bidPrice": "0.07946700",
    "bidQty": "9.00000000",
    "askPrice": "100000.00000000",
    "askQty": "1000.00000000"
  }
]

账户接口

下单 (TRADE)

POST /api/v3/order  (HMAC SHA256)

权重: 1

参数:

Name	Type	Mandatory	Description
symbol	STRING	YES
side	ENUM	YES	详见枚举定义：订单方向
type	ENUM	YES	详见枚举定义：订单种类
timeInForce	ENUM	NO	详见枚举定义：Time in force
quantity	DECIMAL	NO
quoteOrderQty	DECIMAL	NO
price	DECIMAL	NO
newClientOrderId	STRING	NO	用户自定义的orderid，如空缺系统会自动赋值
stopPrice	DECIMAL	NO	仅 `STOP_LOSS`, `STOP_LOSS_LIMIT`, `TAKE_PROFIT`, `TAKE_PROFIT_LIMIT` 需要此参数
icebergQty	DECIMAL	NO	仅有限价单(包括条件限价单与限价做事单)可以使用该参数，含义为创建冰山订单并指定冰山订单的尺寸
newOrderRespType	ENUM	NO	指定响应类型 `ACK`, `RESULT`, or `FULL`; `MARKET` 与 `LIMIT` 订单默认为`FULL`, 其他默认为`ACK`.
recvWindow	LONG	NO
timestamp	LONG	YES

根据 order type的不同，某些参数强制要求，具体如下:

Type	强制要求的参数
`LIMIT`	`timeInForce`, `quantity`, `price`
`MARKET`	`quantity`
`STOP_LOSS`	`quantity`, `stopPrice`
`STOP_LOSS_LIMIT`	`timeInForce`, `quantity`, `price`, `stopPrice`
`TAKE_PROFIT`	`quantity`, `stopPrice`
`TAKE_PROFIT_LIMIT`	`timeInForce`, `quantity`, `price`, `stopPrice`
`LIMIT_MAKER`	`quantity`, `price`

其他:

LIMIT_MAKER 订单大部分情况下与普通的限价单没有区别，但是如果在当前价格会立即吃对手单并成交则下单会被拒绝。因此使用这个订单类型可以保证订单一定是挂单方，不会成为吃单方。
STOP_LOSS 与 TAKE_PROFIT 的执行逻辑是当 stopPrice 到达时，触发一个市价单。
冰山订单的 timeInForce必须设置为GTC.

条件单的触发价格必须:

比下单时当前市价高: STOP_LOSS BUY, TAKE_PROFIT SELL
比下单时当前市价低: STOP_LOSS SELL, TAKE_PROFIT BUY

关于 newOrderRespType的三种选择

数据源: 撮合引擎

Response ACK: 返回速度最快，不包含成交信息，信息量最少

{
  "symbol": "BTCUSDT",
  "orderId": 28,
  "clientOrderId": "6gCrw2kRUAF9CvJDGP16IP",
  "transactTime": 1507725176595
}

Response RESULT: 返回速度居中，返回吃单成交的少量信息

{
  "symbol": "BTCUSDT",
  "orderId": 28,
  "clientOrderId": "6gCrw2kRUAF9CvJDGP16IP",
  "transactTime": 1507725176595,
  "price": "1.00000000",
  "origQty": "10.00000000",
  "executedQty": "10.00000000",
  "cummulativeQuoteQty": "10.00000000",
  "status": "FILLED",
  "timeInForce": "GTC",
  "type": "MARKET",
  "side": "SELL"
}

Response FULL: 返回速度最慢，返回吃单成交的详细信息

{
  "symbol": "BTCUSDT",
  "orderId": 28,
  "clientOrderId": "6gCrw2kRUAF9CvJDGP16IP",
  "transactTime": 1507725176595,
  "price": "1.00000000",
  "origQty": "10.00000000",
  "executedQty": "10.00000000",
  "cummulativeQuoteQty": "10.00000000",
  "status": "FILLED",
  "timeInForce": "GTC",
  "type": "MARKET",
  "side": "SELL",
  "fills": [
    {
      "price": "4000.00000000",
      "qty": "1.00000000",
      "commission": "4.00000000",
      "commissionAsset": "USDT"
    },
    {
      "price": "3999.00000000",
      "qty": "5.00000000",
      "commission": "19.99500000",
      "commissionAsset": "USDT"
    },
    {
      "price": "3998.00000000",
      "qty": "2.00000000",
      "commission": "7.99600000",
      "commissionAsset": "USDT"
    },
    {
      "price": "3997.00000000",
      "qty": "1.00000000",
      "commission": "3.99700000",
      "commissionAsset": "USDT"
    },
    {
      "price": "3995.00000000",
      "qty": "1.00000000",
      "commission": "3.99500000",
      "commissionAsset": "USDT"
    }
  ]
}

测试下单接口 (TRADE)

POST /api/v3/order/test (HMAC SHA256)

用于测试订单请求，但不会提交到撮合引擎

权重: 1

参数:

参考 POST /api/v3/order

数据源: 缓存

响应:

{}

查询订单 (USER_DATA)

GET /api/v3/order (HMAC SHA256)

查询订单状态

权重: 2

参数:

Name	Type	Mandatory
symbol	STRING	YES
orderId	LONG	NO
origClientOrderId	STRING	NO
recvWindow	LONG	NO
timestamp	LONG	YES

注意:

至少需要发送 orderId 与 origClientOrderId中的一个
某些订单中cummulativeQuoteQty<0，是由于这些订单是cummulativeQuoteQty功能上线之前的订单。

数据源: 数据库

响应:

{
  "symbol": "LTCBTC",
  "orderId": 1,
  "clientOrderId": "myOrder1",
  "price": "0.1",
  "origQty": "1.0",
  "executedQty": "0.0",
  "cummulativeQuoteQty": "0.0",
  "status": "NEW",
  "timeInForce": "GTC",
  "type": "LIMIT",
  "side": "BUY",
  "stopPrice": "0.0",
  "icebergQty": "0.0",
  "time": 1499827319559,
  "updateTime": 1499827319559,
  "isWorking": true
}

撤销订单 (TRADE)

DELETE /api/v3/order  (HMAC SHA256)

权重: 1

Parameters:

Name	Type	Mandatory	Description
symbol	STRING	YES
orderId	LONG	NO
origClientOrderId	STRING	NO
newClientOrderId	STRING	NO	用户自定义的本次撤销操作的ID(注意不是被撤销的订单的自定义ID)。如无指定会自动赋值。
recvWindow	LONG	NO
timestamp	LONG	YES

orderId 与 origClientOrderId 必须至少发送一个

数据源: 撮合引擎

响应:

{
  "symbol": "LTCBTC",
  "orderId": 28,
  "origClientOrderId": "myOrder1",
  "clientOrderId": "cancelMyOrder1",
  "transactTime": 1507725176595,
  "price": "1.00000000",
  "origQty": "10.00000000",
  "executedQty": "8.00000000",
  "cummulativeQuoteQty": "8.00000000",
  "status": "CANCELED",
  "timeInForce": "GTC",
  "type": "LIMIT",
  "side": "SELL"
}

查看账户当前挂单 (USER_DATA)

GET /api/v3/openOrders  (HMAC SHA256)

请小心使用不带symbol参数的调用

权重: 带symbol 3 不带40

参数:

Name	Type	Mandatory
symbol	STRING	NO
recvWindow	LONG	NO
timestamp	LONG	YES

不带symbol参数，会返回所有交易对的挂单

数据源: 数据库

响应:

[
  {
    "symbol": "LTCBTC",
    "orderId": 1,
    "clientOrderId": "myOrder1",
    "price": "0.1",
    "origQty": "1.0",
    "executedQty": "0.0",
    "cummulativeQuoteQty": "0.0",
    "status": "NEW",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "stopPrice": "0.0",
    "icebergQty": "0.0",
    "time": 1499827319559,
    "updateTime": 1499827319559,
    "isWorking": true
  }
]

查询所有订单（包括历史订单） (USER_DATA)

GET /api/v3/allOrders (HMAC SHA256)

权重: 10

Parameters:

Name	Type	Mandatory	Description
symbol	STRING	YES
orderId	LONG	NO	只返回此orderID之后的订单，缺省返回最近的订单
startTime	LONG	NO
endTime	LONG	NO
limit	INT	NO	Default 500; max 1000.
recvWindow	LONG	NO
timestamp	LONG	YES

注意:

如设置 orderId , 订单量将 >= orderId。否则将返回最新订单。
一些历史订单 cummulativeQuoteQty < 0, 是指数据此时不存在。
如果设置 startTime 和 endTime, orderId 就不需要设置。

数据源: 数据库

响应:

[
  {
    "symbol": "LTCBTC",
    "orderId": 1,
    "clientOrderId": "myOrder1",
    "price": "0.1",
    "origQty": "1.0",
    "executedQty": "0.0",
    "cummulativeQuoteQty": "0.0",
    "status": "NEW",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "stopPrice": "0.0",
    "icebergQty": "0.0",
    "time": 1499827319559,
    "updateTime": 1499827319559,
    "isWorking": true
  }
]

账户信息 (USER_DATA)

GET /api/v3/account (HMAC SHA256)

权重: 10

参数:

Name	Type	Mandatory	Description
recvWindow	LONG	NO
timestamp	LONG	YES

数据源: 缓存 => 数据库

响应:

{
  "makerCommission": 15,
  "takerCommission": 15,
  "buyerCommission": 0,
  "sellerCommission": 0,
  "canTrade": true,
  "canWithdraw": true,
  "canDeposit": true,
  "updateTime": 123456789,
  "balances": [
    {
      "asset": "BTC",
      "free": "4723846.89208129",
      "locked": "0.00000000"
    },
    {
      "asset": "LTC",
      "free": "4763368.68006011",
      "locked": "0.00000000"
    }
  ]
}

账户成交历史 (USER_DATA)

GET /api/v3/myTrades  (HMAC SHA256)

获取某交易对的成交历史

权重: 10

参数:

Name	Type	Mandatory	Description
symbol	STRING	YES
startTime	LONG	NO
endTime	LONG	NO
fromId	LONG	NO	返回该fromId之后的成交，缺省返回最近的成交
limit	INT	NO	Default 500; max 1000.
recvWindow	LONG	NO
timestamp	LONG	YES

数据源: 数据库

响应:

[
  {
    "symbol": "BNBBTC",
    "id": 28457,
    "orderId": 100234,
    "price": "4.00000100",
    "qty": "12.00000000",
    "commission": "10.10000000",
    "commissionAsset": "BNB",
    "time": 1499865549590,
    "isBuyer": true,
    "isMaker": false,
    "isBestMatch": true
  }
]

用户数据流订阅接口

此处仅列出如何得到数据流名称及如何维持有效期的接口，具体订阅方式参考另一篇websocket接口文档

新建用户数据流 (USER_STREAM)

POST /api/v3/userDataStream

从创建起60分钟有效

权重: 1

Parameters: NONE

数据源: 缓存

响应:

{
  "listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1" //用于订阅的数据流名
}

Keepalive (USER_STREAM)

PUT /api/v3/userDataStream

延长用户数据流有效期到60分钟之后。建议每30分钟调用一次

权重: 1

参数:

Name	Type	Mandatory	Description
listenKey	STRING	YES

数据源: 缓存

响应:

{}

关闭用户数据流 (USER_STREAM)

DELETE /api/v3/userDataStream

权重: 1

参数:

Name	Type	Mandatory	Description
listenKey	STRING	YES

数据源: 缓存

响应:

{}

过滤器

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

交易对过滤器

PRICE_FILTER 价格过滤器

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

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

逻辑伪代码如下：

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

/exchangeInfo 响应中的格式:

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

PERCENT_PRICE 价格振幅过滤器

可以理解为一个瞬时的涨跌停限制，不允许价格瞬间剧烈浮动。 avgPriceMins 指用过去几分钟的平均价格来计算价格基准. 0 表示用最新成交价格作为价格计准。

逻辑伪代码如下：

price <= weightedAveragePrice * multiplierUp
price >= weightedAveragePrice * multiplierDown

/exchangeInfo 响应中的格式:

  {
    "filterType": "PERCENT_PRICE",
    "multiplierUp": "1.3000",
    "multiplierDown": "0.7000",
    "avgPriceMins": 5
  }

LOT_SIZE 订单尺寸

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

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

逻辑伪代码如下：

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

/exchangeInfo 响应中的格式:

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

MIN_NOTIONAL 最小金额

这个过滤器用于检查订单的最小金额。金额的单位是quoteAsset，可以通过 price * quantity得到

如果applyToMarket 为真，则市价单也需要服从最小金额过滤器。由于市价单不存在price参数，当对市价单计算订单金额时，使用过去avgPriceMins分钟的平均价格。如果avgPriceMins为0则使用最新成交价格。

/exchangeInfo 响应中的格式:

  {
    "filterType": "MIN_NOTIONAL",
    "minNotional": "0.00100000",
    "applyToMarket": true,
    "avgPriceMins": 5
  }

ICEBERG_PARTS 冰山订单拆分数

ICEBERG_PARTS 代表冰山订单最多可以拆分成多少个小订单。计算方法为 向上取整(qty / icebergQty).

/exchangeInfo 响应中的格式:

  {
    "filterType": "ICEBERG_PARTS",
    "limit": 10
  }

MARKET_LOT_SIZE 市价订单尺寸

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

MAX_NUM_ORDERS 最多订单数

定义了某个交易对最多允许的挂单数量（不包括已关闭的订单）普通订单与条件订单均计算在内

/exchangeInfo 响应中的格式:

  {
    "filterType": "MAX_NUM_ORDERS",
    "maxNumOrders": 25
  }

MAX_NUM_ALGO_ORDERS 最多条件单数

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

/exchangeInfo 响应中的格式:

  {
    "filterType": "MAX_ALGO_ORDERS",
    "maxNumAlgoOrders": 5
  }

MAX_NUM_ICEBERG_ORDERS 最多冰山单数

定义了某个交易对最多允许的冰山订单数 icebergQty > 0.

/exchangeInfo 响应中的格式:

  {
    "filterType": "MAX_NUM_ICEBERG_ORDERS",
    "maxNumIcebergOrders": 5
  }

MAX_POSITION 过滤器

这个过滤器定义账户允许的基于base asset的最大仓位。一个用户的仓位可以定义为如下资产的总和:

base asset的可用余额
base asset的锁定余额
所有处于open的买单的数量总和

如果用户的仓位大于最大的允许仓位，买单会被拒绝。

/exchangeInfo 响应中的格式:

{
  "filterType": "MAX_POSITION",
  "maxPosition": "10.00000000"
}

交易所级别过滤器

EXCHANGE_MAX_NUM_ORDERS 最多订单数

/exchangeInfo 响应中的格式:

  {
    "filterType": "EXCHANGE_MAX_NUM_ORDERS",
    "maxNumOrders": 1000
  }

EXCHANGE_MAX_NUM_ALGO_ORDERS 最多条件单数

/exchangeInfo 响应中的格式:

  {
    "filterType": "EXCHANGE_MAX_ALGO_ORDERS",
    "maxNumAlgoOrders": 200
  }

Files

rest-api_CN.md

Latest commit

History

rest-api_CN.md

File metadata and controls

REST行情与交易接口 (2021-05-12)

基本信息

访问限制

数据来源

接口鉴权类型

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

时间同步安全

POST /api/v3/order 的示例

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

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

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

公开API接口

术语解释

枚举定义

通用接口

测试服务器连通性 PING

获取服务器时间

交易规范信息

行情接口

深度信息

近期成交

查询历史成交(MARKET_DATA)

近期成交(归集)

K线数据

当前平均价格

24hr价格变动情况

最新价格接口

最优挂单接口

账户接口

下单 (TRADE)

测试下单接口 (TRADE)

查询订单 (USER_DATA)

撤销订单 (TRADE)

查看账户当前挂单 (USER_DATA)

查询所有订单（包括历史订单） (USER_DATA)

账户信息 (USER_DATA)

账户成交历史 (USER_DATA)

用户数据流订阅接口

新建用户数据流 (USER_STREAM)

Keepalive (USER_STREAM)

关闭用户数据流 (USER_STREAM)

过滤器

交易对过滤器

PRICE_FILTER 价格过滤器

PERCENT_PRICE 价格振幅过滤器

LOT_SIZE 订单尺寸

MIN_NOTIONAL 最小金额

ICEBERG_PARTS 冰山订单拆分数

MARKET_LOT_SIZE 市价订单尺寸

MAX_NUM_ORDERS 最多订单数

MAX_NUM_ALGO_ORDERS 最多条件单数

MAX_NUM_ICEBERG_ORDERS 最多冰山单数

MAX_POSITION 过滤器

交易所级别过滤器

EXCHANGE_MAX_NUM_ORDERS 最多订单数

EXCHANGE_MAX_NUM_ALGO_ORDERS 最多条件单数