程序接口


簽名生成規則(參數 signature)

先把將要發起的請求表示為壹個字符串,然後對這個字符串做 HMAC-SHA256 運算:

hash = HMAC-SHA256(payload, secret_key).to_hex

其中 payload 就是代表這個請求的字符串, 通過組合 HTTP方法、請求地址和請求參數將會得到:

# canonical_verb 請求方法,例如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,那麽使用 HMAC-SHA256 算法對上面例子中的 payload 計算的結果是 (以hex表示):

payload = 'GET|/api/v2/markets|access_key=xxx&foo=bar&tonce=123456789'
hash = HMAC-SHA256(payload, 'yyy').to_hex
# e324059be4491ed8e528aa7b8735af1e96547fbec96db962d51feb7bf1b64dee

現在我們就可以這樣來使用這個簽名請求(以curl為例):

curl -X GET 'https://www.688ex.com/api/v2/markets?access_key=xxx&foo=bar&tonce=123456789&signature=e324059be4491ed8e528aa7b8735af1e96547fbec96db962d51feb7bf1b64dee'

註意:生成payload的時候,canonical_query 請按照首字母順序排列,例如: t=1&b=2&c=3 應該要轉化為 b=2&c=3&t=1之後,再生成簽名。

Market

GET /api/v2/markets

無參數

返回結果

[
    {
        "id": "btcusd",
        "name": "BTC/USD"
    },
    ....
]

Order

GET /api/v2/orders

參數名 參數類型 必填 描述
access_key String true API訪問秘鑰
tonce Integer true 時間戳
signature String true 參數簽名
market String true 交易市場
state String false 掛單狀態(cancel,wait,done)
limit Integer false 獲取掛單數量
page Integer false 分頁數量
order_by String false 獲取記錄排序(asc, desc)

返回結果

[
    {
        "id": 114214,
        "side": "buy",
        "ord_type": "limit",
        "price": "19883.32",
        "avg_price": "0.0",
        "state": "wait",
        "market": "btcusd",
        "created_at": "2017-09-06T18:12:20+08:00",
        "volume": "0.3845",
        "remaining_volume": "0.3845",
        "executed_volume": "0.0",
        "trades_count": 0
    },
    ....
]

GET /api/v2/order

參數名 參數類型 必填 描述
access_key String true API訪問秘鑰
tonce Integer true 時間戳
signature String true 參數簽名
id Integer true 掛單ID

返回結果

{
    "id": 116196,
    "side": "sell",
    "ord_type": "limit",
    "price": "34107.02",
    "avg_price": "0.0",
    "state": "wait",
    "market": "btcusd",
    "created_at": "2017-09-06T20:29:39+08:00",
    "volume": "0.4196",
    "remaining_volume": "0.4196",
    "executed_volume": "0.0",
    "trades_count": 0,
    "trades": [ ]
}

POST /api/v2/orders/multi
POST /api/v2/orders

參數名 參數類型 必填 描述
access_key String true API訪問秘鑰
tonce Integer true 時間戳
signature String true 參數簽名
market String true 交易市場
side String true 掛單(sell,buy)
volume Integer true 掛單數量
price Integer true 掛單價格
ord_type String false 交易種類(limit,market)

返回結果

[
    {
        "id": 114214,
        "side": "buy",
        "ord_type": "limit",
        "price": "19883.32",
        "avg_price": "0.0",
        "state": "wait",
        "market": "btcusd",
        "created_at": "2017-09-06T18:12:20+08:00",
        "volume": "0.3845",
        "remaining_volume": "0.3845",
        "executed_volume": "0.0",
        "trades_count": 0
    },
    ....
]

POST /api/v2/order/delete

參數名 參數類型 必填 描述
access_key String true API訪問秘鑰
tonce Integer true 時間戳
signature String true 參數簽名
id Integer true 掛單ID

返回結果

[
    {
        "id": 114214,
        "side": "buy",
        "ord_type": "limit",
        "price": "19883.32",
        "avg_price": "0.0",
        "state": "wait",
        "market": "btcusd",
        "created_at": "2017-09-06T18:12:20+08:00",
        "volume": "0.3845",
        "remaining_volume": "0.3845",
        "executed_volume": "0.0",
        "trades_count": 0
    },
    ....
]

POST /api/v2/orders/clear

參數名 參數類型 必填 描述
access_key String true API訪問秘鑰
tonce Integer true 時間戳
signature String true 參數簽名
side String false 掛單(sell,buy)

返回結果

[
   {
        "id": 114699,
        "side": "sell",
        "ord_type": "limit",
        "price": "35092.44",
        "avg_price": "0.0",
        "state": "wait",
        "market": "btcusd",
        "created_at": "2017-09-06T18:43:35+08:00",
        "volume": "0.7591",
        "remaining_volume": "0.7591",
        "executed_volume": "0.0",
        "trades_count": 0
    },
    ....
]

GET /api/v2/order_book

參數名 參數類型 必填 描述
market String true 交易市場
asks_limit Integer false 獲取賣單記錄數(1..100)
bids_limit Integer false 獲取買單記錄數(1..100)

返回結果

{
    "asks": [
        {
            "id": 115035,
            "side": "sell",
            "ord_type": "limit",
            "price": "28390.37",
            "avg_price": "0.0",
            "state": "wait",
            "market": "btcusd",
            "created_at": "2017-09-06T19:05:52+08:00",
            "volume": "0.4263",
            "remaining_volume": "0.4263",
            "executed_volume": "0.0",
            "trades_count": 0
        },
        ......
    ],
    "bids": [
        {
            "id": 115169,
            "side": "buy",
            "ord_type": "limit",
            "price": "28198.91",
            "avg_price": "0.0",
            "state": "wait",
            "market": "btcusd",
            "created_at": "2017-09-06T19:15:28+08:00",
            "volume": "0.9437",
            "remaining_volume": "0.9437",
            "executed_volume": "0.0",
            "trades_count": 0
        },
        ......
    ]
}

Ticker

GET /api/v2/tickers

無參數

返回結果

{
    "btcusd": {
        "at": 1504696667,
        "ticker": {
            "buy": "28198.91",
            "sell": "28202.08",
            "low": "25649.02",
            "high": "28401.15",
            "last": "28202.82",
            "vol": "1487.0246"
        }
    },
    ......
}

GET /api/v2/tickers/:market

參數名 參數類型 必填 描述
market String true 交易市場

返回結果(market為btcusd)

{
    "at": 1504696728,
    "ticker": {
        "buy": "28198.91",
        "sell": "28201.34",
        "low": "25649.02",
        "high": "28401.15",
        "last": "28201.85",
        "vol": "1486.6039"
    }
}

Trade

GET /api/v2/trades

參數名 參數類型 必填 描述
market String true 交易市場
limit Integer false 獲取記錄的數量
timestamp Integer false 掛單(sell,buy)
from Integer false 掛單數量
to Integer false 掛單價格
order_by String false 交易種類(limit,market)

返回結果(market為btcusd)

[
    {
        "id": 37597,
        "price": "28198.83",
        "volume": "0.603",
        "funds": "17003.89449",
        "market": "btcusd",
        "created_at": "2017-09-06T19:19:51+08:00",
        "at": 1504696791,
        "side": "down"
    },
    ......
]

GET /api/v2/trades/my

參數名 參數類型 必填 描述
access_key String true API訪問秘鑰
tonce Integer true 時間戳
signature String true 參數簽名
market String true 交易市場
limit Integer false 獲取交易數量(1…1000)
timestamp Integer false 時間戳
from Integer false from交易ID
to Integer false to交易ID
order_by String false 獲取記錄排序(asc, desc)

返回結果

{
    "id": 37798,
    "price": "28220.09",
    "volume": "0.1277",
    "funds": "3603.705493",
    "market": "btcusd",
    "created_at": "2017-09-06T20:29:44+08:00",
    "at": 1504700984,
    "side": "ask",
    "order_id": 116200
}

Member

GET /api/v2/members/me

參數名 參數類型 必填 描述
access_key String true API訪問秘鑰
tonce Integer true 時間戳
signature String true 參數簽名

返回結果

{
    "sn": "PEAQXYPX4WMTIO",
    "name": nil,
    "email": "test@gmail.com",
    "activated": true,
    "memo": "5912",
    "accounts": [
        {
            "currency": "usd",
            "balance": "0.0",
            "locked": "0.0"
        },
        {
            "currency": "btc",
            "balance": "0.0",
            "locked": "0.0"
        },
        ...
    ]
}