貔貅开发者接口 (API version 2)

接口URI前缀: /api/v2
返回结果格式: JSON

Websocket接口 | OAuth认证接口

Public/Private API

貔貅开发者接口包含两类API: Public API是不需要任何验证就可以使用的接口，而Private API是需要进行签名验证的接口。下表列出了两者的主要区别:

Public APIPrivate API
无需验证需要验证
无限制对于每个用户, 最多6000个请求每5分钟(平均20个请求/秒); 如果有更高需求可以联系貔貅管理员
无需准备立即可用先要向貔貅管理员申请access/secret key

如何签名 (验证)

在给一个Private API请求签名之前, 你必须准备好你的access/secret key. 在注册并认证通过后之后，只需访问API密钥页面就可以得到您的密钥。

所有的Private API都需要这3个用于身份验证的参数:

access_key你的access key
toncetonce是一个用正整数表示的时间戳，代表了从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
{"at":1398410899, "ticker":{"buy":"3000.0","sell":"3100.0","low":"3000.0","high":"3000.0","last":"3000.0","vol":"0.11"}}

Market包含了某一个市场(例如btcmxn)的所有信息:

at: 以秒为单位的时间戳

buy/sell: 当前买入/卖出价

low/high: 过去24小时之内的最低/最高成交价

last: 最后成交价

vol: 过去24小时之内的总成交量

Member
{"sn":"PEA5TFFOGQHTIO","name":"foo","email":"ilovehacking@ispos.mx","activated":true,"accounts":[{"currency":"mxn","balance":"100243840.0","locked":"0.0"},{"currency":"btc","balance":"99999708.26","locked":"210.8"}]}

Member包含了某一个用户的所有信息:

sn: 用户的唯一编号

name: 用户名字

email: 用户email

activated: 用户是否已激活

accounts: 用户的所有账户信息, 参见Account

Account
{"currency":"mxn","balance":"100243840.0","locked":"0.0"}

Account包含了用户某一个币种账户的信息:

currency: 账户的币种, 如mxn, btc

balance: 账户余额, 不包括冻结资金

locked: 冻结资金

Order
{"id":7,"side":"sell","price":"3100.0","avg_price":"3101.2","state":"wait","market":"btcmxn","created_at":"2014-04-18T02:02:33Z","volume":"100.0","remaining_volume":"89.8","executed_volume":"10.2","trades_count": 1, "trades":[{"id":2,"price":"3100.0","volume":"10.2","market":"btcmxn","created_at":"2014-04-18T02:04:49Z","side":"sell"}]}

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
{"id":2,"price":"3100.0","volume":"10.2","market":"btcmxn","created_at":"2014-04-18T02:04:49Z","order_id":101,"side":"sell"}

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
{"asks": [...],"bids": [...]}

OrderBook包含了当前市场的挂单信息:

asks: 卖单列表

bids: 买单列表

Deposits
[{"currency": "mxn","amount": "520.0","fee": "0.0","txid": null,"created_at": "2014-11-29T15:24:26Z","memo": null,"done_at": null,"state": "submitting"},{"currency": "mxn","amount": "1000.0","fee": "0.0","txid": "3","created_at": "2014-11-29T13:45:03Z","memo": null,"done_at": "2014-11-29T13:54:37Z","state": "accepted"}]

Deposits 返回用户最近24小时内的充值信息:

currency: 充值种类

amount: 充值总量

fee: 交易费用

txid: 交易id

created_at: 创建时间

done_at: 处理时间

memo: 交易备注

state: 状态

----state----

accepted 表示 充值成功

Deposit
{"currency": "mxn","amount": "520.0","fee": "0.0","txid": "8","created_at": "2014-11-29T15:24:26Z","memo": null,"done_at": "2014-12-02T02:46:24Z","state": "accepted"}

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'

注意事项

APIDetail
POST /api/v2/order/delete取消挂单. 取消挂单是一个异步操作,api成功返回仅代表取消请求已经成功提交,服务器正在处理,不代表订单已经取消. 当你的挂单有尚未处理的成交(trade)事务,或者取消请求队列繁忙时,该订单会延迟取消. api返回被取消的订单,返回结果中的订单不一定处于取消状态,你的代码不应该依赖api返回结果,而应该通过/api/v2/order或者websocket api来得到该订单的最新状态.
POST /api/v2/orders/clear取消你所有的挂单. 取消挂单是一个异步操作, api成功返回代表取消请求已经提交,服务器正在处理. api返回的结果是你当前挂单的集合,结果中的订单不一定处于取消状态.

相关库/工具列表

API列表

以下是详细的API列表，展开可以看到每个API的URI和可接受的参数。所有需要access_key/tonce/signature的都是Private API, 其他的则是Public API。