欢迎使用[TokenBetter][]开发者文档。 本文档提供了TokenBetter交易平台的币币交易(Spot)业务的行情查询、交易、账户管理等API使用方法的介绍。 行情API是公开接口,提供币币交易市场的行情数据;交易和账户API需要身份验证,提供下单、撤单、查询订单和帐户信息等功能。
REST,即Representational State Transfer的缩写,是一种流行的互联网传输架构。它具有结构清晰、符合标准、易于理解、扩展方便的,正得到越来越多网站的采用。其优点如下:
- 在RESTful架构中,每一个URL代表一种资源;
- 客户端和服务器之间,传递这种资源的某种表现层;
- 客户端通过四个HTTP指令,对服务器端资源进行操作,实现“表现层状态转化”。 建议开发者使用REST API进行行情查询、币币交易和账户管理等操作。
在对任何请求进行签名之前,您必须通过 TokenBetter网站【用户中心】-【API】创建一个API KEY。 创建API KEY后,您将获得3个必须记住的信息:
- API Key
- Secret Key
- Passphrase API Key和Secret Key将随机生成,Passphrase由用户自己设定。
所有REST请求都必须包含以下标题:
- ACCESS-KEY API Key作为一个字符串
- ACCESS-SIGN 使用base64编码签名(请参阅签名消息)
- ACCESS-TIMESTAMP 作为您的请求的时间戳
- ACCESS-PASSPHRASE 您在创建API KEY时设置的Passphrase
- 所有请求都应该含有application/json类型内容,并且是有效的JSON
ACCESS-SIGN的请求头是对 timestamp + method + requestPath + "?" + queryString + body 字符串(+表示字符串连接)使用HMAC SHA256方法加密,通过BASE64编码输出而得到的。其中,timestamp的值与ACCESS-TIMESTAMP请求头相同。
- method是请求方法(POST/GET/PUT/DELETE),字母全部大写
- requestPath是请求接口路径
- queryString是GET请求中的查询字符串
- body是指请求主体的字符串,如果请求没有主体(通常为GET请求),则body可省略 例如:对于如下的请求参数进行签名
- 获取深度信息,以LTC_BTC为例
Timestamp = 1540286290170
Method = "GET"
requestPath = "/openapi/exchange/public/LTC_BTC/orderBook"
queryString= "?size=100"
生成待签名的字符串
Message = '1540286290170GET/openapi/exchange/public/LTC_BTC/orderBook?size=100'
- 下单,以LTC_BTC为例
Timestamp = 1540286476248
Method = "POST"
requestPath = "/openapi/exchange/LTC_BTC/orders"
body = {"price":"1","side":"buy","source":"web","systemOrderType":"limit","volume":"1"}
生成待签名的字符串
Message = '1540286476248POST/openapi/exchange/LTC_BTC/orders{"price":"1","side":"buy","source":"web","systemOrderType":"limit","volume":"1"}'
然后,将待签名字符串添加私钥参数生成最终待签名字符串
hmac = hmac(secretkey, Message, SHA256)
在使用前需要对于hmac进行base64编码
Signature = base64.encode(hmac.digest())
REST访问的根URL:https://www.tokenbetter.com
所有请求基于Https协议,请求头信息中Content-Type需要统一设置为:'application/json’。 请求交互说明 1、请求参数:根据接口请求参数规定进行参数封装。 2、提交请求参数:将封装好的请求参数通过POST/GET/DELETE等方式提交至服务器。 3、服务器响应:服务器首先对用户请求数据进行参数安全校验,通过校验后根据业务逻辑将响应数据以JSON格式返回给用户。 4、数据处理:对服务器响应数据进行处理。 成功 HTTP状态码200表示成功响应,并可能包含内容。如果响应含有内容,则将显示在相应的返回内容里面。 常见错误码
- 400 Bad Request – Invalid request forma 请求格式无效
- 401 Unauthorized – Invalid API Key 无效的API Key
- 403 Forbidden – You do not have access to the requested resource 请求无权限
- 404 Not Found – 没有找到请求
- 429 Too Many Requests – 请求太频繁被系统限流
- 500 Internal Server Error – We had a problem with our server 服务器内部错误 如果失败,Response body带有错误描述信息
除非另外指定,API中的所有时间戳均以微秒为单位返回。 请求签名中的ACCESS-TIMESTAMP的单位是秒,允许用小数表示更精确的时间。请求的时间戳必须在API服务时间的30秒内,否则请求将被视为过期并被拒绝。如果本地服务器时间和API服务器时间之间存在较大的偏差,那么我们建议您使用通过查询API服务器时间来更新Http Header。
1524801032573
为了保持跨平台时精度的完整性,十进制数字作为字符串返回。建议您在发起请求时也将数字转换为字符串以避免截断和精度错误。 整数(如交易编号和顺序)不加引号。
如果请求过于频繁系统将自动限制请求,并在Http Header中返回429 too many requests状态码。
- 公共接口:我们通过IP限制公共接口的调用:每2秒最多6个请求。
- 私人接口:我们通过用户ID限制私人接口的调用:每2秒最多6个请求。
- 某些接口的特殊限制在具体的接口上注明
请求
# Request
GET /openapi/exchange/public/currencies
响应
# Response
[{
"baseIncrement": 0,
"baseSymbol": "BTC",
"makerFeesRate": "0",
"maxPrice": 4,
"maxVolume": 4,
"minTrade": 0.00001000,
"online": 0,
"pairCode": "BTC_USDT",
"quoteIncrement": 0,
"quotePrecision": 0,
"quoteSymbol": "USDT",
"sort": 1,
"tickerFeesRate": "0"
}, {
"baseIncrement": 0,
"baseSymbol": "ETH",
"makerFeesRate": "0",
"maxPrice": 4,
"maxVolume": 4,
"minTrade": 0.01000000,
"online": 0,
"pairCode": "ETH_USDT",
"quoteIncrement": 0,
"quotePrecision": 0,
"quoteSymbol": "USDT",
"sort": 2,
"tickerFeesRate": "0"
},...]
返回值说明
返回字段 | 字段说明 |
---|---|
baseIncrement | 交易数量最小交易变动单位 |
baseSymbol | 交易货币 |
makerFeesRate | maker 费率 |
maxPrice | 交易价格小数位数 |
maxVolume | 交易数量小数位数 |
minTrade | 最小委托量 |
online | 是否上线 |
pairCode | 是Base和quote之间的组合 BTC_USD |
quoteIncrement | 最小交易单位 |
quotePrecision | 计价货币数量单位精度 |
quoteSymbol | 计价货币 |
sort | 排序值 |
tickerFeesRate | ticker 费率 |
请求
# Request
GET /openapi/exchange/public/{pairCode}/orderBook
响应
# Response
{
"asks":[
[
"10463.3399",
"0.0025"
],
...
],
"bids":[
[
"7300.2456",
"0.0022"
],
...
]
}
返回值说明
返回字段 | 字段说明 |
---|---|
asks | 卖方深度 |
bids | 买方深度 |
请求参数
参数名 | 参数类型 | 必填 | 描述 |
---|---|---|---|
pairCode | String | 是 | 币对,如LTC_BTC |
最新成交价、买一价、卖一价、24h最高价、24h最低价、24h开盘价和24h成交量的快照信息。 请求
# Request
GET /openapi/exchange/public/{pairCode}/ticker
响应
# Response
{
"buy": "9512.70000000",
"change24": "19.60000000",
"changePercentage": "",
"changeRate24": "0.0020000000000000",
"close": "",
"createOn": 1564404929000,
"high": "9729.50000000",
"high24": "9729.50000000",
"last": "9525.20000000",
"low": "9171.80000000",
"low24": "9171.80000000",
"open": "9505.60000000",
"pairCode": "BTC_USDT",
"quoteVolume": "39140860.67498000",
"sell": "9515.60000000",
"volume": "4101.34040000"
}
返回值说明
返回字段 | 字段说明 |
---|---|
buy | 最新买入价 |
change24 | 24小时变化值 |
changePercentage | 变化百分比 |
changeRate24 | 24小时涨跌比例 |
close | 24小时 close |
createOn | 创建时间 |
high | 最高成交价 |
high24 | 24小时最高成交价 |
last | 最新成交价 |
low | 最低成交价 |
low24 | 24小时最低成交价 |
open | 24小时 open |
pairCode | 币对信息 |
quoteVolume | 计价币的成交量 |
sell | 最新卖出价 |
volume | 基准币的成交量 |
请求参数
参数名 | 参数类型 | 必填 | 描述 |
---|---|---|---|
pairCode | String | 是 | 币对,如ETH_BTC |
请求
# Request
GET /openapi/exchange/public/{pairCode}/fills
响应
# Response
{
["9581.4","0.091084","sell",1590897543720]
...
}
返回值说明(按顺序)
返回字段 | 字段说明 |
---|---|
9581.4 | 成交价 |
0.091084 | 数量 |
sell | 买卖方向 |
1590897543720 | 时间 |
请求参数
参数名 | 参数类型 | 必填 | 描述 |
---|---|---|---|
pairCode | String | 是 | 币对如btc_usdt |
请求
# Request
GET /openapi/exchange/public/{pairCode}/candles?interval=1min&start=start_time&end=end_time
响应
# Response
{
[ 1415398768, 0.32, 0.42, 0.36, 0.41, 12.3 ]
...
}
返回值说明(按顺序)
返回字段 | 字段说明 |
---|---|
1415398768 | K线开始时间戳 |
0.32 | 最低价 |
0.42 | 最高价 |
0.36 | 开盘价(第一笔交易) |
0.41 | 收盘价(最后一笔交易) |
12.3 | 交易量(按交易币统计) |
请求参数 |
参数名 | 参数类型 | 必填 | 描述 |
---|---|---|---|
pairCode | String | 是 | 币对如btc_usdt |
interval | String | 是 | K线周期类型如1min/1hour/day/week/month |
start | String | 否 | 基于ISO 8601标准的开始时间 |
end | String | 否 | 基于ISO 8601标准的结束时间 |
获取API服务器的时间的接口。 请求
# Request
GET /openapi/exchange/public/time
响应
# Reponse
{
"epoch": "1524801032.573"
"iso": "2015-01-07T23:47:25.201Z",
"timestamp": 1524801032573
}
返回值说明
返回字段 | 字段说明 |
---|---|
epoch | 以秒为时间戳形式表达的服务器时间 |
iso | 为ISO 8061标准的时间字符串表达的服务器时间 |
timestamp | 以毫秒为时间戳形式表达的服务器时间 |
获取币币交易账户余额列表,查询各币种的余额,冻结和可用情况。 请求
# Request
GET /openapi/exchange/assets
响应
# Response
[
{
"brokerId":10000,
"symbol":"BTC",
"available":"1",
"hold":"0",
"baseBTC":1,
"withdrawLimit":"1",
},
...
]
返回值说明
返回字段 | 字段说明 |
---|---|
brokerId | 券商id |
symbol | 币种 |
available | 余额 |
hold | 冻结 |
baseBTC | 折合BTC |
withdrawLimit | 提币限额 |
提供限价和市价两种订单类型。 请求
# Request
POST /openapi/exchange/{pairCode}/orders
响应
# Response
10000
返回值说明 订单id
请求参数
参数名 | 参数类型 | 必填 | 描述 |
---|---|---|---|
pairCode | String | 是 | 币对,如BTC_USDT |
side | String | 是 | 买入为buy,卖出为sell |
systemOrderType | String | 是 | 限价委托为limit,市价委托为market |
volume | String | 否 | 限价委托以及市价卖出时传递,代表交易币的数量 |
price | String | 否 | 限价委托时传递,代表交易价格 |
quoteVolume | String | 否 | 市价买入时传递,代表计价币的数量 |
撤销目标币对下所有未成交委托,最多撤销50条。由于是异步撤单,所以该接口没有返回值。 请求
# Request
DELETE /openapi/exchange/{pairCode}/cancel-all
响应
# Response
{ ...}
请求参数
参数名 | 参数类型 | 必填 | 描述 |
---|---|---|---|
pairCode | String | 是 | 币对, 如BTC_USDT |
目前批量撤销200个挂单 |
按照订单id撤销指定订单。由于是异步撤单,所以该接口没有返回值。 请求
# Request
DELETE /openapi/exchange/{pairCode}/orders/{id}
响应
# Response
{...}
请求参数
参数名 | 参数类型 | 必填 | 描述 |
---|---|---|---|
code | String | 是 | 币对,如BTC_USDT |
orderId | String | 是 | 需要撤销的未成交委托的id |
按照订单状态查询订单。
请求
# Request
GET /openapi/exchange/orders
响应
# Response
[
[
"id": 1524801032573,
"pairCode": "BTC_USDT",
"userId": 1001,
"brokerId": 10000,
"side": "buy",
"entrustPrice": "1",
"amount": "1",
"dealAmount": "1",
"quoteAmount": "1",
"dealQuoteAmount": "1",
"systemOrderType": "limit",
"status": 0,
"sourceInfo": "web",
"createOn": 1524801032573,
"updateOn": 1524801032573,
"symbol": "BTC",
"trunOver": "1",
"notStrike": "0",
"averagePrice": "1",
"openAmount": "1"
],
...
]
返回值说明
返回字段 | 字段说明 |
---|---|
id | 订单id |
pairCode | 是Base和quote之间的组合 BTC_USD |
userId | 用户id |
brokerId | 券商id |
side | 方向 买、卖 |
entrustPrice | 下单价格 |
amount | 下单数量 |
dealAmount | 成交数量 |
quoteAmount | 基准币数量 只有在市价买的情况下会用到 |
dealQuoteAmount | 基准币已成交数量 |
systemOrderType | 10:限价 11:市价 |
status | 0:未成交 1:部分成交 2:完全成交 3:撤单中 -1:已撤单 |
sourceInfo | 下单来源 web,api,Ios,android |
createOn | 创建时间 |
updateOn | 修改时间 |
symbol | 币种 |
trunOver | 成交金额 dealQuoteAmount * dealAmount |
notStrike | 尚未成交的数量 |
averagePrice | 平均成交价 |
openAmount | 下单数量 |
请求参数
参数名 | 参数类型 | 必填 | 描述 |
---|---|---|---|
pairCode | String | 否 | 币对,如BTC_USDT |
startDate | Long | 否 | 开始时间 毫秒 |
endDate | Long | 否 | 结束时间 毫秒 |
price | BigDecimal | 否 | 下单价格 |
amount | BigDecimal | 否 | 下单数量 |
systemOrderType | Integer | 否 | 10:限价 11:市价 |
source | String | 否 | 币对,如LTC_BTCweb,api,Ios,android |
page | Integer | 否 | 第几页 |
pageSize | Integer | 否 | 每页条数 |
获取币币交易账单。 请求
# Request
GET /openapi/exchange/bills
响应
# Response
{
"bills": [{
"afterAssets": 97.0000000000000000,
"amount": -2.00000000,
"assets": 97,
"beforeAssets": 99.0000000000000000,
"brokerId": 10000,
"createOn": 1565590577000,
"fee": 0E-8,
"id": 0,
"makerTaker": "maker",
"pairCode": "LTC_USDT",
"price": 400.0000000000000000,
"referId": 51815389100048,
"symbol": "LTC",
"tradeNo": "",
"type": 8,
"updateOn": 0,
"userId": 0
}, {
"afterAssets": 899.1000000000000000,
"amount": 800.00000000,
"assets": 899.1,
"beforeAssets": 99.9000000000000000,
"brokerId": 10000,
"createOn": 1565590577000,
"fee": -0.80000000,
"id": 0,
"makerTaker": "maker",
"pairCode": "LTC_USDT",
"price": 400.0000000000000000,
"referId": 51815389100048,
"symbol": "USDT",
"tradeNo": "",
"type": 7,
"updateOn": 0,
"userId": 0
}],
"paginate": {
"page": 1,
"pageSize": 2,
"total": 4
}
}
返回值说明
返回字段 | 字段说明 |
---|---|
afterAssets | 变动后资产 |
amount | 变换金额 |
beforeAssets | 变动前资产 |
brokerId | 券商id |
createOn | 创建时间 |
fee | 手续费 |
makerTaker | maker挂单taker吃单 |
pairCode | 币对 |
price | 价格 |
referId | 关联id |
symbol | 币种 |
tradeNo | 交易号 转账时有唯一交易号 |
type | 账单类型 |
updateOn | 修改时间 |
userId | 用户id |
请求参数
参数名 | 参数类型 | 必填 | 描述 |
---|---|---|---|
page | Integer | 是 | 当前第几页 |
pageSize | Integer | 是 | 每页获取条数 |
startDate | Long | 否 | 开始时间戳毫秒 |
endDate | Long | 否 | 结束时间戳毫秒 |
symbol | String | 否 | 币种 如BTC |
type | Integer | 否 | RECHARGE(1),WITHDRAW(2),BUY(7),SELL(8),TRANSFER_IN(43),TRANSFER_OUT(44),SERVICE_FEE_BUY(88),SERVICE_FEE_SELL(89) |
isHistory | Boolean | 否 | 是否历史数据 |
获取所请求交易对的历史成交信息,该请求支持分页。 请求
# Request
GET /openapi/exchange/{pairCode}/fulfillment
响应
# Response
[
[
"id": 1524801032573,
"pairCode": "BTC_USDT",
"userId": 1001,
"brokerId": 10000,
"side": "buy",
"entrustPrice": "1",
"amount": "1",
"dealAmount": "1",
"quoteAmount": "1",
"dealQuoteAmount": "1",
"systemOrderType": "limit",
"status": 0,
"sourceInfo": "web",
"createOn": 1524801032573,
"updateOn": 1524801032573,
"symbol": "BTC",
"trunOver": "1",
"notStrike": "0",
"averagePrice": "1",
"openAmount": "1"
],
...
]
返回值说明
返回字段 | 字段说明 |
---|---|
id | 订单id |
pairCode | 是Base和quote之间的组合 BTC_USD |
userId | 用户id |
brokerId | 券商id |
side | 方向 买、卖 |
entrustPrice | 下单价格 |
amount | 下单数量 |
dealAmount | 成交数量 |
quoteAmount | 基准币数量 只有在市价买的情况下会用到 |
dealQuoteAmount | 基准币已成交数量 |
systemOrderType | 10:限价 11:市价 |
status | 0:未成交 1:部分成交 2:完全成交 3:撤单中 -1:已撤单 |
sourceInfo | 下单来源 web,api,Ios,android |
createOn | 创建时间 |
updateOn | 修改时间 |
symbol | 币种 |
trunOver | 成交金额 dealQuoteAmount * dealAmount |
notStrike | 尚未成交的数量 |
averagePrice | 平均成交价 |
openAmount | 下单数量 |
请求参数
参数名 | 参数类型 | 必填 | 描述 |
---|---|---|---|
pairCode | String | 是 | 币对,如LTC_BTC |
startDate | Long | 否 | 开始时间,如1524801032573 |
endDate | Long | 否 | 结束时间,如1524801032573 |
systemOrderType | Integer | 否 | 10:限价 11:市价 |
price | BigDecimal | 否 | 价格 |
amount | BigDecimal | 否 | 数量 |
source | String | 否 | 币对,如LTC_BTCweb,api,Ios,android |
isHistory | Boolean | 否 | 是否查历史数据、一周前成交的数据是历史数据、默认false |
page | Integer | 否 | 第几页 |
pageSize | Integer | 否 | 每页条数 |
解释说明
- 交易方向 side 表示每一笔成交订单中 maker 下单方向,maker 是指将订单挂在订单深度列表上的交易用户,即被动成交方。
- buy 代表行情下跌,因为 maker 是买单,maker 的买单被成交,所以价格下跌;相反的情况下,sell代表行情上涨,因为此时maker是卖单,卖单被成交,表示上涨。