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 指一个交易对的定价资产，即写在靠后部分资产名

枚举定义

交易对状态:

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

交易对类型:

SPOT 现货

订单状态:

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

订单种类:

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

订单返回类型:

ACK
RESULT
FULL

订单方向:

买入
卖出

Time in force:

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

K线间隔:

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 单位时间请求次数上限

限制间隔

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
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
quantity	DECIMAL	YES
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 最多条件单数