FCoin API

本文介绍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-KEY
• FC-ACCESS-SIGNATURE
• FC-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 -- 服务不可用，请稍后再进行尝试