本文介紹FCoin API
介紹
通過了解以下信息，您可以方便的使用 FCoin 提供的 API 來接入 FCoin 交易平台。
認證
執行下面的代碼進行用戶驗證：
import fcoin api = fcoin.authorize('key', 'secret', timestamp) FCoin 使用 API key 和 API secret 進行驗證，請訪問 設置中心，並注冊成為開發者，獲取 API key 和 API secret。
FCoin 的 API 請求，除公開的 API 外都需要攜帶 API key 以及簽名
訪問限制
目前訪問頻率為每個用戶 100次 / 10秒，未來會按照業務區分訪問頻率限制。
API 簽名
簽名前准備的數據如下：
HTTP_METHOD + HTTP_REQUEST_URI + TIMESTAMP + POST_BODY
連接完成后，進行 Base64 編碼，對編碼后的數據進行 HMAC-SHA1 簽名，並對簽名進行二次 Base64編碼，各部分解釋如下：
請注意需要進行兩次 `Base64` 編碼！
HTTP_METHOD
GET, POST, DELETE, PUT 需要大寫
HTTP_REQUEST_URI
https://api.fcoin.com/v2/ 為 v2 API 的請求前綴
后面再加上真正要訪問的資源路徑，如 orders?param1=value1，最終即 https://api.fcoin.com/v2/orders?param1=value1
對於請求的 URI 中的參數，需要按照按照字母表排序！
即如果請求的 URI 為 https://api.fcoin.com/v2/orders?c=value1&b=value2&a=value3，則進行簽名時，應先將請求參數按照字母表排序，最終進行簽名的 URI 為 https://api.fcoin.com/v2/orders?a=value3&b=value2&c=value1， 請注意，原請求 URI 中的三個參數順序為 c, b, a，排序后為 a, b, c。
TIMESTAMP
訪問 API 時的 UNIX EPOCH 時間戳，需要和服務器之間的時間差少於 30 秒
POST_BODY
如果是 POST 請求，POST 請求數據也需要被簽名，簽名規則如下：
所有請求的 key 按照字母順序排序，然后進行 url 參數化，並使用 & 連接。
請注意 POST_BODY 的鍵值需要按照字母表排序！
如果請求數據為：
{ "username": "username", "password": "passowrd" }則先將 key 按照字母排序，然后進行 url 參數化，即：
password=password
username=username
因為
p在字母表中的排序在u之前，所以password要放在username之前，然后使用&進行連接，即：
password=password&username=username
完整示例
對於如下的請求：
POST https://api.fcoin.com/v2/orders
{
"type": "limit",
"side": "buy",
"amount": "100.0",
"price": "100.0",
"symbol": "btcusdt"
}
timestamp: 1523069544359
簽名前的准備數據如下：
POSThttps://api.fcoin.com/v2/orders1523069544359amount=100.0&price=100.0&side=buy&symbol=btcusdt&type=limit
進行 Base64 編碼，得到：
UE9TVGh0dHBzOi8vYXBpLmZjb2luLmNvbS92Mi9vcmRlcnMxNTIzMDY5NTQ0MzU5YW1vdW50PTEwMC4wJnByaWNlPTEwMC4wJnNpZGU9YnV5JnN5bWJvbD1idGN1c2R0JnR5cGU9bGltaXQ=
拷貝在申請 API Key 時獲得的秘鑰（API SECRET），下面的簽名結果采用
3600d0a74aa3410fb3b1996cca2419c8作為示例，對得到的結果使用秘鑰進行
HMAC-SHA1簽名，並對二進制結果進行Base64編碼，得到：
DeP6oftldIrys06uq3B7Lkh3a0U=
即生成了用於向 API 服務器進行驗證的最終簽名
參數名稱
FC-ACCESS-KEYFC-ACCESS-SIGNATUREFC-ACCESS-TIMESTAMP
說明
可以使用開發者工具（暫未開放）進行在線聯調測試。
公開接口
查詢服務器時間
import fcoin api = fcoin.authorize('key', 'secret', timestamp) server_time = api.server_time() 響應結果如下：
{ "status": 0, "data": 1523430502977 }此 API 用於獲取服務器時間。
HTTP Request
GET https://api.fcoin.com/v2/public/server-time
查詢可用幣種
import fcoin api = fcoin.authorize('key', 'secret', timestamp) currencies = api.currencies() 響應結果如下：
{ "status": 0, "data": [ "btc", "eth" ] }此 API 用於獲取可用幣種。
HTTP Request
GET https://api.fcoin.com/v2/public/currencies
查詢可用交易對
import fcoin api = fcoin.authorize('key', 'secret', timestamp) symbols = api.symbols() 響應結果如下：
{ "status": 0, "data": [ { "name": "btcusdt", "base_currency": "btc", "quote_currency": "usdt", "price_decimal": 2, "amount_decimal": 4 }, { "name": "ethusdt", "base_currency": "eth", "quote_currency": "usdt", "price_decimal": 2, "amount_decimal": 4 } ] }此 API 用於獲取可用交易對。
HTTP Request
GET https://api.fcoin.com/v2/public/symbols
行情
行情概述
行情是一個全公開的 API, 當前同時提供了 HTTP 和 WebSocket 的 API. 為確保可以更及時的獲得行情, 推薦使用 WebSocket 進行接入. 為盡可能行情的實時性能, 當前公開部分只能獲取最近一段時間的行情, 如果有需要獲取全量或者歷史行情, 請咨詢 support@fcoin.com
所有 HTTP 請求的 URL base 為: https://api.fcoin.com/v2/market
所有 WebSocket 請求的 URL 為: wss://api.fcoin.com/v2/ws
下文會統一術語:
topic表示訂閱的主題symbol表示對應交易幣種. 所有幣種區分的 topic 都在 topic 末尾.ticker行情 tick 信息, 包含最新成交價, 最新成交量, 買一賣一, 近 24 小時成交量.depth表示行情深度, 買賣盤, 盤口.level表示行情深度類型. 如L20,L100.trade表示最新成交, 最新交易.candle表示蠟燭圖, 蠟燭棒, K 線.resolution表示蠟燭圖的種類. 如M1,M15.base volume表示基准貨幣成交量, 如 btcusdt 中 btc 的量.quote volume表示計價貨幣成交量, 如 btcusdt 中 usdt 的量ts表示推送服務器的時間. 是毫秒為單位的數字型字段, unix epoch in millisecond.
WebSocket 首次建立連接
服務器會發送一個歡迎信息
服務器返回
{ "type":"hello", "ts":1523693784042 }ts: 推送服務器當前的時間.
WebSocket 連接保持 - heartbeat
WebSocket 客戶端和 WebSocket 服務器建立連接之后，推薦 WebSocket Client 每隔 30s（這個頻率可能會變化） 向服務器發起一次 ping 請求，如果服務器長時間沒有接收到客戶端的 ping 請求將會主動斷開連接（300s）。
WebSocket 請求
import time import fcoin api = fcoin.authorize('key', 'secret', timestamp) now_ms = int(time.time()) api.market.ping(now_ms) 服務器返回
{ "type":"ping", "ts":1523693784042, "gap":112 }gap: 推送服務器處理此語句的時間和客戶端傳輸的時間差.ts: 推送服務器當前的時間.
獲取推送服務器時間
可以通過 ping 請求時服務器返回的 ts 和 gap 值獲取推送服務器時間和數據傳輸時間差
- gap: 推送服務器處理此語句的時間和客戶端傳輸的時間差.
- ts: 推送服務器當前的時間.
獲取 ticker 數據
為了使得 ticker 信息組足夠小和快, 我們強制使用了列表格式.
ticker 列表對應字段含義說明:
[ "最新成交價", "最近一筆成交的成交量", "最大買一價", "最大買一量", "最小賣一價", "最小賣一量", "24小時前成交價", "24小時內最高價", "24小時內最低價", "24小時內基准貨幣成交量, 如 btcusdt 中 btc 的量", "24小時內計價貨幣成交量, 如 btcusdt 中 usdt 的量" ]HTTP 請求
GET https://api.fcoin.com/v2/market/ticker/$symbol
import fcoin api = fcoin.authorize('key', 'secret', timestamp) api.market.get_ticker("ethbtc") { "status": 0, "data": { "type": "ticker.btcusdt", "seq": 680035, "ticker": [ 7140.890000000000000000, 1.000000000000000000, 7131.330000000, 233.524600000, 7140.890000000, 225.495049866, 7140.890000000, 7140.890000000, 7140.890000000, 1.000000000, 7140.890000000000000000 ] } }WebSocket 訂閱
topic: ticker.$symbol
import fcoin fcoin_ws = fcoin.init_ws() topics = ["ticker.ethbtc", "ticker.btcusdt"] fcoin_ws.handle(print) fcoin_ws.sub(topics) 訂閱成功的響應結果如下：
{ "type": "topics", "topics": ["ticker.ethbtc", "ticker.btcusdt"] }常規訂閱的通知消息格式如下:
{ "type": "ticker.btcusdt", "seq": 680035, "ticker": [ 7140.890000000000000000, 1.000000000000000000, 7131.330000000, 233.524600000, 7140.890000000, 225.495049866, 7140.890000000, 7140.890000000, 7140.890000000, 1.000000000, 7140.890000000000000000 ] }獲取最新的深度明細
HTTP Request
GET https://api.fcoin.com/v2/market/depth/$level/$symbol
$level 包含的種類:
| 類型 | 說明 |
|---|---|
L20 |
20 檔行情深度. |
L100 |
100 檔行情深度. |
full |
全量的行情深度, 不做時間保證和推送保證. |
其中 L20 的推送時間會略早於 L100, 推送頻次會略多於 L100, 看具體的壓力和情況. 此處請按需使用.
WebSocket 訂閱
訂閱 topic: depth.$level.$symbol
import fcoin fcoin_ws = fcoin.init_ws() topics = ["depth.L20.ethbtc", "depth.L100.btcusdt"] fcoin_ws.handle(print) fcoin_ws.sub(topics) 訂閱成功的響應結果如下：
{ "type": "topics", "topics": ["depth.L20.ethbtc", "depth.L100.btcusdt"] }常規的推送結果
bids 和 asks 對應的數組一定是偶數條目, 買(賣)1價, 買(賣)1量, 依次往后排列.
{ "type": "depth.L20.ethbtc", "ts": 1523619211000, "seq": 120, "bids": [0.000100000, 1.000000000, 0.000010000, 1.000000000], "asks": [1.000000000, 1.000000000] }獲取最新的成交明細
通過對比其中的成交 id 大小才能決定是否是更新的成交.{trade id} 需要注意, 常規由於 trade 到 transaction 過程的存在, 公開行情的成交 id 並不實際對應清算系統中的成交 id. 即使成交是一條記錄, 也無法保證最新成交在重新獲取時候 id 永遠保持一致.
PS: 歷史行情中, 是可以保證成交 id 保持恆定. {transaction id} 此處只作為行情更新通知, 不應依賴歸檔使用.
HTTP Request
GET https://api.fcoin.com/v2/market/trades/$symbol
查詢參數(HTTP Query)
| 參數 | 默認值 | 描述 |
|---|---|---|
| before | 查詢某個 id 之前的 Trade | |
| limit | 默認為 20 條 |
WebSocket 獲取最近的成交
topic: trade.$symbol limit: 最近的成交條數 args: [topic, limit]
import fcoin fcoin_ws = fcoin.init_ws() topic = "trade.ethbtc" limit = 3 args = [topic, limit] fcoin_ws.req(args, rep_handler) 請求成功的響應結果如下：
{"id":null, "ts":1523693400329, "data":[ { "amount":1.000000000, "ts":1523419946174, "id":76000, "side":"sell", "price":4.000000000 }, { "amount":1.000000000, "ts":1523419114272, "id":74000, "side":"sell", "price":4.000000000 }, { "amount":1.000000000, "ts":1523415182356, "id":71000, "side":"sell", "price":3.000000000 } ] }WebSocket 訂閱
import fcoin fcoin_ws = fcoin.init_ws() topics = ["trade.ethbtc", "trade.btcusdt"] fcoin_ws.handle(print) fcoin_ws.sub(topics) 訂閱成功的響應結果如下：
{ "type": "topics", "topics": ["trade.ethbtc"] }常規的推送結果
{ "type":"trade.ethbtc", "id":76000, "amount":1.000000000, "ts":1523419946174, "side":"sell", "price":4.000000000 }獲取 Candle 信息
HTTP Request
GET https://api.fcoin.com/v2/market/candles/$resolution/$symbol
查詢參數(HTTP Query)
| 參數 | 默認值 | 描述 |
|---|---|---|
| before | 查詢某個 id 之前的 Candle | |
| limit | 默認為 20 條 |
$resolution 包含的種類
| 類型 | 說明 |
|---|---|
M1 |
1 分鍾 |
M3 |
3 分鍾 |
M5 |
5 分鍾 |
M15 |
15 分鍾 |
M30 |
30 分鍾 |
H1 |
1 小時 |
H4 |
4 小時 |
H6 |
6 小時 |
D1 |
1 日 |
W1 |
1 周 |
MN |
1 月 |
Weboskcet 訂閱 Candle 數據
topic: candle.$resolution.$symbol
import fcoin fcoin_ws = fcoin.init_ws() topics = ["candle.M1.ethbtc", "depth.L20.ethbtc", "trade.ethbtc"] fcoin_ws.handle(print) fcoin_ws.sub(topics) 訂閱成功的響應結果如下：
{ "type": "topics", "topics": ["candle.M1.ethbtc"] }常規訂閱的通知消息格式如下:
{ "type":"candle.M1.ethbtc", "id":1523691480, "seq":11400000, "open":2.000000000, "close":2.000000000, "high":2.000000000, "low":2.000000000, "count":0, "base_vol":0, "quote_vol":0 }賬戶與資產
查詢賬戶資產
import fcoin api = fcoin.authorize('key', 'secret', timestamp) api.accounts_balance 響應結果如下：
{ "status": 0, "data": [ { "currency": "btc", "available": "50.0", "frozen": "50.0", "balance": "100.0" } ] }此 API 用於查詢用戶的資產列表。
HTTP Request
GET https://api.fcoin.com/v2/accounts/balance
訂單
訂單模型說明
訂單模型由以下屬性構成：
| 屬性 | 類型 | 含義解釋 |
|---|---|---|
id |
String |
訂單 ID |
symbol |
String |
交易對 |
side |
String |
交易方向（buy, sell） |
type |
String |
訂單類型（limit，market） |
price |
String |
下單價格 |
amount |
String |
下單數量 |
state |
String |
訂單狀態 |
executed_value |
String |
已成交 |
filled_amount |
String |
成交量 |
fill_fees |
String |
手續費 |
created_at |
Long |
創建時間 |
source |
String |
來源 |
訂單狀態說明：
| 屬性 | 含義解釋 |
|---|---|
submitted |
已提交 |
partial_filled |
部分成交 |
partial_canceled |
部分成交已撤銷 |
filled |
完全成交 |
canceled |
已撤銷 |
pending_cancel |
撤銷已提交 |
創建新的訂單
import fcoin api = fcoin.authorize('key', 'secret', timestamp) order_create_param = fcoin.order_create_param('btcusdt', 'buy', 'limit', '8000.0', '1.0') api.orders.create(order_create_param) 響應結果如下：
{ "status": 0, "data": "9d17a03b852e48c0b3920c7412867623" }此 API 用於創建新的訂單。
HTTP Request
POST https://api.fcoin.com/v2/orders
請求參數
| 參數 | 默認值 | 描述 |
|---|---|---|
| symbol | 無 | 交易對 |
| side | 無 | 交易方向 |
| type | 無 | 訂單類型 |
| price | 無 | 價格 |
| amount | 無 | 下單量 |
查詢訂單列表
import fcoin api = fcoin.authorize('key', 'secret', timestamp) api.orders.get() 響應結果如下：
{ "status": 0, "data": [ { "id": "string", "symbol": "string", "type": "limit", "side": "buy", "price": "string", "amount": "string", "state": "submitted", "executed_value": "string", "fill_fees": "string", "filled_amount": "string", "created_at": 0, "source": "web" } ] }此 API 用於查詢訂單列表。
HTTP Request
GET https://api.fcoin.com/v2/orders
查詢參數
| 參數 | 默認值 | 描述 |
|---|---|---|
| symbol | 交易對 | |
| states | 訂單狀態 | |
| before | 查詢某個頁碼之前的訂單 | |
| after | 查詢某個頁碼之后的訂單 | |
| limit | 每頁的訂單數量，默認為 20 條 |
獲取指定訂單
import fcoin api = fcoin.authorize('key', 'secret', timestamp) api.orders.get('9d17a03b852e48c0b3920c7412867623') 響應結果如下：
{ "status": 0, "data": { "id": "9d17a03b852e48c0b3920c7412867623", "symbol": "string", "type": "limit", "side": "buy", "price": "string", "amount": "string", "state": "submitted", "executed_value": "string", "fill_fees": "string", "filled_amount": "string", "created_at": 0, "source": "web" } }此 API 用於返回指定的訂單詳情。
HTTP Request
GET https://api.fcoin.com/v2/orders/{order_id}
URL 參數
| 參數 | 描述 |
|---|---|
| order_id | 訂單 ID |
申請撤銷訂單
import fcoin api = fcoin.authorize('key', 'secret', timestamp) api.orders.submit_cancel(2) 響應結果如下：
{ "status": 0, "msg": "string", "data": true }此 API 用於撤銷指定訂單，訂單撤銷過程是異步的，即此 API 的調用成功代表着訂單已經進入撤銷申請的過程，需要等待撮合的進一步處理，才能進行訂單的撤銷確認。
HTTP Request
POST https://api.fcoin.com/v2/orders/{order_id}/submit-cancel
URL 參數
| 參數 | 解釋 |
|---|---|
| order_id | 訂單 ID |
查詢指定訂單的成交記錄
import fcoin api = fcoin.authorize('key', 'secret', timestamp) api.orders.get('9d17a03b852e48c0b3920c7412867623').match_results() 響應結果如下：
{ "status": 0, "data": [ { "price": "string", "fill_fees": "string", "filled_amount": "string", "side": "buy", "type": "limit", "created_at": 0 } ] }此 API 用於獲取指定訂單的成交記錄
HTTP Request
GET https://api.fcoin.com/v2/orders/{order_id}/match-results
URL 參數
| 參數 | 解釋 |
|---|---|
| order_id | 訂單 ID |
訂單錯誤代碼
| 錯誤代碼 | 含義解釋 |
|---|---|
| 2000 | 賬戶錯誤 |
錯誤代碼
| 錯誤代碼 | 含義解釋 |
|---|---|
| 400 | Bad Request -- 錯誤的請求 |
| 401 | Unauthorized -- API key 或者簽名，時間戳有誤 |
| 403 | Forbidden -- 禁止訪問 |
| 404 | Not Found -- 未找到請求的資源 |
| 405 | Method Not Allowed -- 使用的 HTTP 方法不適用於請求的資源 |
| 406 | Not Acceptable -- 請求的內容格式不是 JSON |
| 429 | Too Many Requests -- 請求受限，請降低請求頻率 |
| 500 | Internal Server Error -- 服務內部錯誤，請稍后再進行嘗試 |
| 503 | Service Unavailable -- 服務不可用，請稍后再進行嘗試 |