貔貅开发者接口包含两类API: Public API是不需要任何验证就可以使用的接口,而Private API是需要进行签名验证的接口。下表列出了两者的主要区别:
Public API | Private API |
---|---|
无需验证 | 需要验证 |
无限制 | 对于每个用户, 最多6000个请求每5分钟(平均20个请求/秒); 如果有更高需求可以联系貔貅管理员 |
无需准备立即可用 | 先要向貔貅管理员申请access/secret key |
在给一个Private API请求签名之前, 你必须准备好你的access/secret key. 在注册并认证通过后之后,只需访问API密钥页面就可以得到您的密钥。
所有的Private API都需要这3个用于身份验证的参数:
access_key | 你的access key |
tonce | tonce是一个用正整数表示的时间戳,代表了从Unix epoch到当前时间所经过的毫秒(ms)数。tonce与服务器时间不得超过正负30秒。一个tonce只能使用一次。 |
signature | 使用你的secret key生成的签名 |
签名的生成很简单,先把请求表示为一个字符串, 然后对这个字符串做hash:
hash = HMAC-SHA256(payload, secret_key).to_hex
Payload就是代表这个请求的字符串, 通过组合HTTP方法, 请求地址和请求参数得到:
# canonical_verb是HTTP方法,例如GET
# canonical_uri是请求地址, 例如/api/v2/markets
# canonical_query是请求参数通过&连接而成的字符串,参数包括access_key和tonce, 参数必须按照字母序排列,例如access_key=xxx&foo=bar&tonce=123456789
# 最后再把这三个字符串通过'|'字符连接起来,看起来就像这样:
# GET|/api/v2/markets|access_key=xxx&foo=bar&tonce=123456789
def payload
"#{canonical_verb}|#{canonical_uri}|#{canonical_query}"
end
假设我的secret key是"yyy", 那么使用SHA256算法对上面例子中的payload计算HMAC的结果是(以hex表示):
hash = HMAC-SHA256('GET|/api/v2/markets|access_key=xxx&foo=bar&tonce=123456789', 'yyy').to_hex
= 'e324059be4491ed8e528aa7b8735af1e96547fbec96db962d51feb7bf1b64dee'
现在我们就可以这样来使用这个签名请求(以curl为例):
curl -X GET 'https://isbit.co/api/v2/markets?access_key=xxx&foo=bar&tonce=123456789&signature=e324059be4491ed8e528aa7b8735af1e96547fbec96db962d51feb7bf1b64dee'
如果API调用失败,返回的请求会使用对应的HTTP status code, 同时返回包含了详细错误信息的JSON数据, 比如:
{"error":{"code":1001,"message":"market does not have a valid value"}}
所有错误都遵循上面例子的格式,只是code和message不同。code是貔貅自定义的一个错误代码, 表明此错误的类别, message是具体的出错信息.
对于成功的API请求, 貔貅则会返回200作为HTTP status code, 同时返回请求的JSON数据.
数据类型 | 数据结构/示例 | 备注 |
---|---|---|
Market |
| Market包含了某一个市场(例如btcmxn)的所有信息: at: 以秒为单位的时间戳 buy/sell: 当前买入/卖出价 low/high: 过去24小时之内的最低/最高成交价 last: 最后成交价 vol: 过去24小时之内的总成交量 |
Member |
| Member包含了某一个用户的所有信息: sn: 用户的唯一编号 name: 用户名字 email: 用户email activated: 用户是否已激活 accounts: 用户的所有账户信息, 参见Account |
Account |
| Account包含了用户某一个币种账户的信息: currency: 账户的币种, 如mxn, btc balance: 账户余额, 不包括冻结资金 locked: 冻结资金 |
Order |
| Order包含了某一个订单的所有信息: id: 唯一的Order ID side: Buy/Sell, 代表买单/卖单. price: 出价 avg_price: 平均成交价 state: 订单的当前状态, wait, done或者cancel. wait表明订单正在市场上挂单, 是一个active order, 此时订单可能部分成交或者尚未成交; done代表订单已经完全成交; cancel代表订单已经被撤销. market: 订单参与的交易市场 created_at: 下单时间, ISO8601格式 volume: 购买/卖出数量 remaining_volume: 还未成交的数量. remaining_volume总是小于等于volume, 在订单完全成交时变成0. executed_volume: 已成交的数量. volume = remaining_volume + executed_volume trades_count: 订单的成交数,整数值。未成交的订单为0, 有一笔成交的订单为1, 以此类推。通过该字段可以判断订单是否处于部分成交状态。 trades: 订单的详细成交记录,参见Trade. 注意: 只有某些返回详细订单数据的API才会包含trades数据. |
Trade |
| Trade代表订单撮合后形成的一笔交易: id: 交易的唯一ID price: 成交价 volume: 成交数量 market: 交易所属的市场 created_at: 成交时间 side: buy/sell, 买或者卖, 只有/api/v2/trades/my返回的trade才会包含这个字段,代表这个trade是由你的买单或者卖单产生的./api/v2/trades返回的trade中此字段永远为空. order_id: 只有/api/v2/trades/my返回的trade才会包含这个字段,代表这个trade属于哪一个order. |
OrderBook |
| OrderBook包含了当前市场的挂单信息: asks: 卖单列表 bids: 买单列表 |
Deposits |
| Deposits 返回用户最近24小时内的充值信息: currency: 充值种类 amount: 充值总量 fee: 交易费用 txid: 交易id created_at: 创建时间 done_at: 处理时间 memo: 交易备注 state: 状态 ----state---- accepted 表示 充值成功 |
Deposit |
| Deposits 返回用户某条充值信息: 属性 同上 若txid 不存在 返回 {error: {code: 2012,message: "Deposit##txid=4 doesn't exist."}} |
以4000MXN的价格买入1BTC:
curl -X POST 'https://isbit.co/api/v2/orders' -d 'access_key=your_access_key&tonce=1234567&signature=computed_signature&market=btcmxn&price=4000&side=buy&volume=1'
同时创建多个委托:
curl -X POST 'https://isbit.co/api/v2/orders/multi' -d 'access_key=your_access_key&tonce=123456789&signature=computed_signature&market=btcmxn&orders[][price]=4000&orders[][side]=sell&orders[][volume]=0.5&orders[][price]=3999&orders[][side]=sell&orders[][volume]=0.99'
API | Detail |
---|---|
POST /api/v2/order/delete | 取消挂单. 取消挂单是一个异步操作,api成功返回仅代表取消请求已经成功提交,服务器正在处理,不代表订单已经取消. 当你的挂单有尚未处理的成交(trade)事务,或者取消请求队列繁忙时,该订单会延迟取消. api返回被取消的订单,返回结果中的订单不一定处于取消状态,你的代码不应该依赖api返回结果,而应该通过/api/v2/order或者websocket api来得到该订单的最新状态. |
POST /api/v2/orders/clear | 取消你所有的挂单. 取消挂单是一个异步操作, api成功返回代表取消请求已经提交,服务器正在处理. api返回的结果是你当前挂单的集合,结果中的订单不一定处于取消状态. |
以下是详细的API列表,展开可以看到每个API的URI和可接受的参数。所有需要access_key/tonce/signature的都是Private API, 其他的则是Public API。