API概述
API简介
欢迎使用Coinsuper Exchange API，此文档旨在为API用户提供便捷的交易体验。您可以使用此 API 获得市场行情数据，进行交易，并且管理您的账户。
API分为查询、交易和行情三类。在网站创建API Key后，您可以根据自身需求建立不同权限的API，并利用API进行自动交易，同时支持您使用指定的IP地址访问API。
我们支持三种调用方式: REST、WebSocket和FIX，您可根据自己的使用场景和偏好选择适合自己的方式。
在文档的右侧是代码，目前我们仅提供针对JSON格式的代码示例。
交易规则
撮合规则
Coinsuper按照“价格优先-时间优先”的规则进行撮合。
价格优先是指，价格较高的买入订单优先于价格较低的买入成交，价格较低的卖出订单优先于价格较高的卖出成交。
时间优先是指，同价位、同用户类型的挂单，依照挂单时间的先后决定成交顺序，先挂单的先成交，后挂单的后成交。
订单撮合时成交价将按maker挂单价格成交，而非taker吃单价格。
订单生命周期
订单进入撮合引擎后是"未成交" UNDEAL状态；
如果一个订单被撮合而全部成交，那么它会变成"完全成交"DEAL状态；一个订单被撮合可能出现部分成交，那么它的状态会变成"部分成交"PARTDEAL状态，并且继续留在撮合队列中进行撮合；
一个未成交订单撤单成功，那么它的状态会变成"已撤销"CANCEL状态；
发起撤销到完成撤销的过程中有一个过程状态"撤单中"PENDING_CANCEL；
被撤销或者全部成交的订单将被从撮合队列中剔除。
费用
此处为交易手续费规则简介，详情请查看费率表。
手续费等级
Coinsuper实行阶梯手续费政策，根据用户近30天的累计交易量划分不同的手续费等级，成交量越高，手续费等级越高，手续费越低。同时采用maker-taker收费规则，为鼓励挂单，maker挂单成交的手续费会比taker吃单成交的手续费低。
CEN抵扣手续费
在Coinsuper平台上交易任何代币时，如持有CEN，并同意使用CEN支付交易手续费，可按一定折扣率以CEN 支付手续费。
做市商计划
除了手续费优惠，Coinsuper还为提供流动性的专业用户提供了市商计划。参与市商计划后，只要您能够提供稳定的深度以及盘口点差，即可分享手续费收入或获得Maker手续费返还。请 点击此处 获得详情，发送申请邮件至 vip@coinsuper.com.
服务器
Coinsuper的服务器运行在香港。为了最大限度地减少API访问延迟，建议您使用与香港通讯通畅的服务器。
API Key
创建API Key
在能够发起任何请求之前，您必须通过Coinsuper创建一个API Key，点此查看详细图文教程
根据以上步骤操作，Coinsuper将随机生成两个信息，您需要记住它们:
- Access Key
- Secret Key
API Key权限
您可以限制API Key的权限。在创建API Key的时候进行选择。权限包括:
- 查询权限: 用户仅能通过此API进行查询账户资产信息、订单信息等只读操作，不能进行下单、撤单等操作。
- 交易权限: 可以下单、撤单。
- 行情权限: 可以快速的获取当前市场最新行情。
接入URLs
REST API
| 序号 | 接口访问前缀 | 说明 |
|---|---|---|
| 1 | https://api.coinsuper.info | 主线路 |
| 2 | https://api.coinsuper.net | 备用1 |
接口链接请求示例(获取个人资产信息链接):
WebSocket Feed（行情）
| 序号 | host | port | isSSL | 说明 |
|---|---|---|---|---|
| 1 | apimqtt.coinsuper.info | 1883 | false | mqtt客户端连接参数 |
| 2 | apiwss.coinsuper.info | 443 | true | Javascript WebSocket客户端连接参数 |
WebSocket Feed（资产和订单）
| 序号 | host | port | isSSL | 说明 |
|---|---|---|---|---|
| 1 | apimqtt.coinsuper.info | 1883 | false | mqtt客户端连接参数 |
| 2 | apiwss.coinsuper.info | 443 | true | Javascript WebSocket客户端连接参数 |
Fix
| 序号 | 接口访问域名 | 说明 |
|---|---|---|
| 1 | apifix.coinsuper.info | 主域名 |
- 接口访问端口: 1443
- 接口访问协议: TCP(SSL)
SDK与代码示例
SDK
Python SDK
用python的SDK安装命令: pip install coinsuper_api_rest_sdk
代码示例
*REST代码示例: *https://github.com/coinsuperapi/REST_API_demos
WebSocket代码示例: https://github.com/coinsuperapi/websocket_API_demos
FIX代码示例: https://github.com/coinsuperapi/FIX_API_demos
REST接入说明
请求格式
接口规则
- 采用HTTPS方式访问
- 接口请求均采用 POST 协议
- 接口统一请求数据为 JSON 格式
- 接口统一返回数据为 JSON 格式
- 当某一字段无数据时, 该字段不返回数据(若返回类型为数组, 则会返回空数组)
- 接口调用非公共参数需加密验签, 具体规则及秘钥对由Coinsuper提供
- 所有POST请求接口header中都需要指定Content-Type=application/json
请求参数
请求数据JSON格式定义
{
"common":{
"accesskey" : "1900000109", // 通行证
"sign":"sdfsdfa1231231sdfsdfsd", // MD5加密签名
"timestamp":"1500000000000" //UTC时间戳(毫秒数)
},
"data":{
...... //请求业务数据
}
}
响应数据JSON格式定义
{
"code":"1000", // 状态码
"msg":"success", // 返回信息
"data":{
"timestamp":"1500000000000", //系统时间戳(毫秒数)
"result":{
....
} //系统返回结果
.....
} // 返回数据
}
所有的接口请求都是 JSON 格式。一个合法的请求由common部分和data部分组成。
common部分
common为公有参数，每次调用非公共接口都必须传common，且common必须包含如下3个参数:
- API 访问密钥（asccesskey）: 您申请的 API Key 中的 Access Key。
- 时间戳（timestamp）: 您发出请求的时间 (UTC 时间) 。在查询请求中包含此值有助于防止第三方截取您的请求。
- 签名（sign）: 签名计算得出的值，用于确保签名有效和未被篡改。
data部分
data为私有业务参数，每次调用接口都必须传data。每个接口都会定义API调用的必需参数和可选参数。data子项根据每个接口可能会有不同。即使data子项为空，调用接口也要传data。
响应参数
所有的接口返回都是JSON格式。在JSON最上层有两个表示请求状态和属性的字段: "code", "msg"，实际的接口返回内容在"data"字段里。
其中code返回"1000"为成功，返回其它值则表明业务请求有异常, 具体异常说明请参考下方的【全局通用状态码】表。
签名认证
完整请求数据格式 :
{
"common":{
"accesskey":"zhangsan",
"sign":"sdfsdfa1231231sdfsdfsd",
"timestamp":"1500000000000"
},
"data":{
"symbol":"BTC/USD",
"num" :"50"
}
}
API 请求在通过 internet 传输的过程中极有可能被篡改，为了确保请求未被更改，所有非公共接口均必须使用您的 API Key 做签名认证。每一个API Key需要有适当的权限才能访问相应的接口，在使用接口前请确认您的API Key有相应的权限。
签名步骤
以查询当前订单簿行情数据为例:
业务参数如下 :
symbol : BTC/USD
num : 50
公共请求参数如下:
accesskey : zhangsan
secretkey : zhangsan
timestamp : 1500000000000
1.将以上所有的参数，按照ASCII码从小到大排序（字母顺序）
2.按以上顺序，将各参数使用字符&拼接:
accesskey=zhangsan&num=50&secretkey=zhangsan&symbol=BTC/USD×tamp=1500000000000
3.对以上的string进行md5运算，得到 32位小写的数字签名:
signValue = md5(string)
标准规范
时间戳
API中的所有时间戳必须使用UTC时间(格式化时指定时区为0时区), 时间毫秒均采用原子时。
精度
使用该接口查询Coinsuper可交易的交易对列表: POST /api/v1/market/symbolList
响应参数会返回交易对的挂单数量精度"quantityScale"、挂单价格精度"priceScale"及挂单金额精度"amountScale"。精度以这三个Scale数据为准。
为了保持精度的完整性，数字将作为字符串返回。建议您在发起请求时也将数字转换为字符串以避免截断和精度错误。
全局通用状态码
| 状态码 | 状态描述 | 说明及建议 |
|---|---|---|
| 1000 | success | 接口调用成功 |
| 2000 | system upgrading | 系统升级中, 请稍后再试(详请参考官网公告) |
| 2001 | system internal error | 非业务异常。请先检查是否正确地按照接口文档使用接口(详请参考上方通用的"参数约定"及下方具体接口的请求参数) |
| 2002 | interface is unavailability | 接口不可用。请在WEB官网API申请页面确认您当前的API key是否有调用该接口的权限(具体的接口可参考下方"接口分组及限流") |
| 2003 | request is too frequently | 请求太频繁。请求频率超过了限流(具体限流值请参考下方"接口分组及限流") |
| 2004 | fail to check sign | 接口参数验签失败。请确认是否正确地按照接口文档说明进行参数签名(具体签名方式参考上方"签名描述"及"签名生成方法示例", 也可直接参考REST接口调用示例代码) |
| 2005 | parameter is invalid | 无效的参数。缺少必要的参数, 或参数错误(详请参考上方通用的"参数约定"及下方具体接口的请求参数) |
| 2006 | request failure | 接口调用异常。请先检查是否正确地按照接口文档使用接口(详请参考上方通用的"参数约定"及下方具体接口的请求参数) |
| 2007 | accesskey has been forbidden | 当前用户已被禁止调用API接口 |
| 2008 | user not exist | 该用户未开通API。请先检查accessKey是否正确, 申请accessKey和接口调用的环境是否一致 |
| 3001 | account balance is not enough | 账户余额不足。请用下方"获取个人资产信息"确认对应资产账户的可用余额, 也可登录WEB官网或APP进行查看 |
| 3002 | orderNo is not exist | 指定的单号不存在。请确认传入的orderNo是否正确(若传入的单号后三位都是0, 则有可能是下单接口响应单号后, 调用方未正确保存, 丢失了后三位的精度。建议用字符串保存) |
| 3003 | price is invalid | 无效的价格。请确认price参数是否正确地按照接口文档的描述传入 |
| 3004 | symbol is invalid | 无效的交易对。请确认symbol参数是否正确地按照接口文档的描述传入(若是调用的下单接口, 则可通过下方"可交易的交易对列表"接口查看有效的可交易的交易对) |
| 3005 | quantity is invalid | 无效的数量。请确认quantity参数是否正确地按照接口文档的描述传入 |
| 3006 | ordertype is invalid | 无效的委托单类型。请确认orderType参数是否正确地按照接口文档的描述传入 |
| 3007 | action is invalid | 无效的买卖类型。请确认action参数是否正确地按照接口文档的描述传入 |
| 3008 | state is invalid | 无效的状态值。请确认state参数是否正确地按照接口文档的描述传入 |
| 3009 | num is invalid | 无效的num参数。请确认num参数是否正确地按照接口文档的描述传入 |
| 3010 | amount is invalid | 无效的amount参数。请确认amount参数是否正确地按照接口文档的描述传入 |
| 3011 | cancel order failure | 撤单失败。因其他暂未详细定义的原因导致撤单失败(已定义的有3002, 3021, 3018等) |
| 3012 | create order failure | 下单失败。因其他暂未详细定义的原因导致下单失败(已定义的有3001, 3003, 3004, 3005等) |
| 3013 | orderList is invalid | 无效的orderList参数。orderList中的参数为空或数量超过限制或包含错误的order参数 |
| 3014 | symbol not trading | 交易对不能交易。该交易对暂未开放交易 |
| 3015 | order amount or quantity less than min setting | amount或quantity小于最小挂单量。具体交易对的标的币及计价币最小挂单量请参考下方"可交易的交易对列表"接口 |
| 3016 | price greater than max setting | price超过了最大挂单价。具体数值请参考下方"可交易的交易对列表"接口 |
| 3017 | user account forbidden | 用户对应的币种账户已被禁止交易 |
| 3018 | order has execute | 订单已成交。在撤单接口中表示订单已成交, 不能撤销 |
| 3019 | orderNo num is more than the max setting | 订单号数量超过最大上限。请参考对应接口的订单号数量上限说明 |
| 3020 | price out of range | 挂单价格超出范围。(价格范围的计算方式为: 最大值=(1+deviationRatio)x最新成交价, 最小值=(1-deviationRatio)x最新成交价 。其中最新成交价来自/api/v1/market/tickers接口第一条数据的价格, deviationRatio来自 /api/v1/market/symbolList 接口对应交易对的deviationRatio值) |
| 3021 | order has canceled | 订单已撤销 |
| 3027 | this symbol's API trading channel is not available | 该交易对不能通过API进行交易 |
| 3028 | duplicate clientOrderId | 重复的clientOrderId |
| 3029 | Market price deviation is too large, market order is not recommended | 市场价格偏差过大，不建议您进行市价操作 |
| 3030 | Market price deviation is too large, market order is not recommended | 市场价格偏差过大，不建议您进行市价操作 |
| 3031 | batch create order more or less than limit | 批量下单订单数不满足限制数 |
| 3032 | batch create order symbol not unique | 批量下单交易对不唯一 |
| 3033 | batch create order action not unique | 批量下单买卖类型不唯一 |
| 3034 | clientOrderIdList and orderNoList should and only pass one | clientOrderIdList和orderNoList参数需要且仅需要传其中一个 |
| 3035 | order cancel param error | 撤单参数错误 |
| 3036 | not usual ip | 您现在的IP，不是您常用的IP |
接口分组及限流
| 接口分组 | 包含接口 | 限流值 |
|---|---|---|
| 1.行情 | 价格行情 (/api/public/v1/market/orderBook) 分时行情 (/api/public/v1/market/kline) 实时成交 (/api/public/v1/market/tickers) |
10/s |
| 2.交易 | 买入委托 (/api/v1/order/buy) 卖出委托 (/api/v1/order/sell) 取消委托 (/api/v1/order/cancel) 批量委托 (/api/v1/order/batchPlace) 批量取消委托 (/api/v1/order/batchCancel) |
10/s |
| 3.查询 | 获取个人资产信息 (/api/v1/asset/userAssetInfo) 查询委托单状态 (/api/v1/order/list) 查询订单交易详情 (/api/v1/order/details) 查询委托单状态(根据客户端委托单ID列表) (/api/v1/order/clList) 挂单单号列表 (/api/v1/order/openList) 查询个人历史委托单列表 (/api/v1/order/history) 查询个人历史成交列表 (/api/v1/order/tradeHistory) 可交易的交易对列表 (/api/v1/market/symbolList) |
10/s |
公共行情数据
1.公共价格行情(最新订单簿数据)
请求示例:
{
"data":{
"symbol":"ETC/BTC", // 交易对
"num":"50" // 请求条数
}
}
返回示例:
{
"code":"1000",
"msg":"success",
"data":{
"timestamp":"1500000000000",
"result":{
"asks":[{"limitPrice":"123.00000000","quantity":"161.1300"},...],
"bids":[{"limitPrice":"86.06000000","quantity":"0.7800"},..],
}
}
}
功能描述:
获取指定交易对的当前订单簿行情数据
HTTP请求:
POST /api/public/v1/market/orderBook
请求参数:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| num | 必填 | 数量 |
| symbol | 必填 | 交易对 |
响应参数:
| 字段名 | 描述 |
|---|---|
| timestamp | 时间戳(毫秒数) |
| result | 返回结果 |
| asks | 卖盘深度数据 |
| bids | 买盘深度数据 |
| limitPrice | 委托价格(注: 交易对价格精度请参考symbolList接口) |
| quantity | 委托数量(注: 交易对数量精度请参考symbolList接口) |
- aks和bids最多各返回50条记录
2. 公共分时行情(最新K线数据)
请求示例:
{
"data":{
"symbol":"ETC/BTC", // 交易对
"num":"300" // 请求条数
}
}
返回示例:
{
"code":"1000",
"msg":"success",
"data":{
"timestamp":"1500000000000",
"result":[
{
"close": "0.00205900",
"high": "0.00206080",
"low": "0.00205340",
"open": "0.00205660",
"volume": "100.1218",
"timestamp": "1500000000000"
},
...
]
}
}
功能描述:
获取指定交易对的历史K线数据
HTTP请求:
POST /api/public/v1/market/kline
请求参数:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| symbol | 必填 | 交易对 |
| num | 必填 | 条数最大300条 |
| range | 非必填 | 返回数据时间粒度，也就是每根蜡烛的时间区间(可选值:5min,15min,30min,1hour, 6hour,12hour,1day),不传时默认值为5min |
响应参数:
| 字段名 | 描述 |
|---|---|
| timestamp | 时间戳(毫秒数) |
| result | 返回结果 |
| volume | 交易量 |
| high | 最高价 |
| low | 最低价 |
| open | 开盘价 |
| close | 收盘价 |
3. 公共实时成交行情(最新成交行情数据)
请求示例:
{
"data":{
"symbol":"ETC/BTC", // 交易对
"num":"20" // 请求条数
}
}
返回示例:
{
"code":"1000",
"msg":"success",
"data":{
"timestamp":"1500000000000",
"result":[
{
"price": "0.00212320",
"tradeType": "SELL",
"volume": "0.3499",
"timestamp": "1500000000000"
},
...
]
}
}
功能描述:
获取指定交易对的最新成交行情数据(最新的成交数据, 按成交时间倒序，最多50条)
HTTP请求:
POST /api/public/v1/market/tickers
请求参数:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| symbol | 必填 | 交易对 |
| num | 非必填 | 数量 |
响应参数:
| 字段名 | 描述 |
|---|---|
| timestamp | 时间戳(毫秒数) |
| result | 返回结果 |
| volume | 交易数量 |
| timestamp | 交易时间(时间戳) |
| price | 交易价格 |
| tradeType | 交易类型 BUY-买,SELL-卖 |
下单交易
1. 买入委托
请求示例:
{
"common":{
"accesskey" : "1900000109", // 通行证
"timestamp": "1500000000000", // 时间戳
"sign":"sdfsdfa1231231sdfsdfsd" // MD5加密签名
},
"data":{
"orderType":"LMT",
"symbol":"ETC/BTC",
"priceLimit":"12345.67",
"amount":"0",
"quantity":"2.34"
}
}
返回示例:
{
"code":"1000",
"msg":"success",
"data":{
"timestamp":"1500000000000",
"result":{
"orderNo":"2134123412"
}
}
}
功能描述:
用户委托买入(挂单)
您可以通过API下两种订单: limit和market。仅当您的帐户有足够的资金时才能下单。
HTTP请求:
POST /api/v1/order/buy
请求参数:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| symbol | 必填 | 交易对 |
| priceLimit | 必填 | 买入价格(字符串类型) |
| orderType | 必填 | 委托单类型 MKT-市价, LMT-限价 |
| quantity | 必填 | 需要买入的标的币数量(字符串类型) |
| amount | 必填 | 订单金额-计价币数量(字符串类型) |
| clientOrderId | 非必填 | 客户自编订单号(任意字符串，不能含特殊符号，不要重复，长度10~50) |
响应参数:
| 字段名 | 描述 |
|---|---|
| timestamp | 系统时间戳(毫秒数) |
| result | 返回结果 |
| orderNo | 委托单号(为避免接收时丢失单号精度, 请使用字符串接收) |
2. 卖出委托
请求示例:
{
"common":{
"accesskey" : "1900000109", // 通行证
"timestamp": "1500000000000", // 时间戳
"sign":"sdfsdfa1231231sdfsdfsd" // MD5加密签名
},
"data":{
"orderType":"LMT",
"symbol":"ETC/BTC",
"priceLimit":"12345.67",
"amount":"0",
"quantity":"2.34"
}
}
返回示例:
{
"code":"1000",
"msg":"success",
"data":{
"timestamp":"1500000000000",
"result":{
"orderNo":"2134123412"
}
}
}
功能描述:
用户委托卖出(挂单)
HTTP请求:
POST /api/v1/order/sell
请求参数:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| symbol | 必填 | 交易对 |
| priceLimit | 必填 | 卖出价格(字符串类型) |
| orderType | 必填 | 委托单类型: MKT-市价, LMT-限价 |
| quantity | 必填 | 需要卖出的标的币数量(字符串类型) |
| amount | 必填 | 订单金额-计价币数量(此处为卖出, 请用固定值0) |
| clientOrderId | 非必填 | 客户自编订单号(任意字符串，不能含特殊符号，不要重复，长度10~50) |
响应参数:
| 字段名 | 描述 |
|---|---|
| timestamp | 系统时间戳(毫秒数) |
| result | 返回结果 |
| orderNo | 委托单号 |
3. 取消委托
请求示例:
{
"common":{
"accesskey" : "1900000109", // 通行证
"timestamp": "1500000000000", // 时间戳
"sign":"sdfsdfa1231231sdfsdfsd" // MD5加密签名
},
"data":{
"orderNo":"12341235123412" // 委托单号
}
}
返回示例:
{
"code":"1000",
"msg":"success",
"data":{
"timestamp":"1500000000000",
"result":{
"operate":"success"
}
}
}
功能描述:
用户取消委托单
HTTP请求:
POST /api/v1/order/cancel
请求参数:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| orderNo | 必填 | 要取消的委托单号。 |
响应参数:
| 字段名 | 描述 |
|---|---|
| timestamp | 系统时间戳(毫秒数) |
| result | 返回结果 |
| operate | 操作结果 : success-成功, failure-失败 |
4. 批量委托
请求示例:
{
"common":{
"accesskey" : "1900000109", // 通行证
"timestamp": "1500000000000", // 时间戳
"sign":"sdfsdfa1231231sdfsdfsd" // MD5加密签名
},
"data":[
{
"action":"BUY",
"amount":"0",
"clientOrderId":"10000000001",
"orderType":"LMT",
"priceLimit":"12345.67",
"quantity":"2.34",
"symbol":"ETC/BTC"
},
{
"action":"BUY",
"amount":"0.1",
"clientOrderId":"10000000002",
"orderType":"MKT",
"priceLimit":"0",
"quantity":"0",
"symbol":"ETC/BTC"
},
...
{
"action":"BUY",
"amount":"0",
"clientOrderId":"10000000010",
"orderType":"LMT",
"priceLimit":"12345.69",
"quantity":"1.23",
"symbol":"ETC/BTC"
}
]
}
返回示例:
{
"code":"1000",
"msg":"success",
"data":{
"timestamp":"1500000000000",
"result":[
{
"orderNo":"1612930403329875969",
"clientOrderId":"10000000001"
},
{
"orderNo":"1612930403329876214",
"clientOrderId":"10000000010"
},
...
{
"orderNo":"1612930403329886537",
"clientOrderId":"10000000002"
}
]
}
}
功能描述:
批量下单
HTTP请求:
/api/v1/order/batchPlace
请求参数:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| symbol | 必填 | 交易对 |
| priceLimit | 必填 | 买入价格(字符串类型) |
| orderType | 必填 | 委托单类型 MKT-市价，LMT-限价 |
| action | 必填 | 买卖类型 SELL-卖，BUY-买 |
| quantity | 必填 | 买入数量(字符串类型) |
| amount | 必填 | 金额(字符串类型) |
| clientOrderId | 必填 | 客户端订单ID（不能含特殊符号，不要重复，长度为10~50） |
响应参数:
| 字段名 | 描述 |
|---|---|
| timestamp | 时间戳(毫秒) |
| result | 响应结果列表 |
| orderNo | 委托单号 |
| clientOrderId | 对应请求中的clientOrderId |
5. 批量取消委托
请求示例:
{
"common":{
"accesskey" : "1900000109", // 通行证
"timestamp": "1500000000000", // 时间戳
"sign":"sdfsdfa1231231sdfsdfsd" // MD5加密签名
},
"data":{
"orderNoList":"1612930403329875969,1612930403329875970" // 委托单号
}
}
返回示例:
{
"code":"1000",
"msg":"success",
"data":{
"timestamp":"1500000000000",
"result":{
"failResultList": [
{
"errMsg": "orderNo is invalid",
"orderNo": "1612930403329875969"
}
],
"successNoList": ["1612930403329875970"]
}
}
}
功能描述:
用户批量取消委托单
HTTP请求:
/api/v1/order/batchCancel
请求参数:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| orderNoList | 选填 | 要取消的委托单号列表。 |
| clientOrderIdList | 选填 | 客户自编订单id列表(英文逗号隔开)，orderNoList和clientOrderIdList仅需要传入其中一个参数 |
响应参数:
| 字段名 | 描述 |
|---|---|
| timestamp | 系统时间戳(毫秒数) |
| result | 返回结果 |
| successNoList | 撤单成功的委托单号列表（传入的单号列表是orderNoList时响应） |
| successIdList | 撤单成功的客户自编订单号列表（传入的单号列表是clientOrderIdList时响应） |
| failResultList | 撤单失败的单号列表 |
| orderNo | 撤单失败的委托单号（传入的单号列表是orderNoList时响应） |
| clientOrderId | 撤单成功的客户自编订单号（传入的单号列表是clientOrderIdList时响应） |
| errMsg | 撤单失败原因说明 |
个人数据查询
1. 获取个人资产信息
请求示例:
{
"common":{
"accesskey" : "1900000109", // 通行证
"timestamp": "1500000000000", // 时间戳
"sign":"sdfsdfa1231231sdfsdfsd" // MD5加密签名
},
"data":{
}
}
返回示例:
{
"code":"1000",
"msg":"success",
"data":{
"timestamp":"1500000000000",
"result":{
"userNo":"12345",
"email":"demouser@demo.domain",
"asset":{
"USD":
{
"total":"123",
"available": "12"
},
"BTC":
{
"total":"1234",
"available": "123"
}
...
}
}
}
}
功能描述:
获取用户个人资产详细信息
HTTP请求:
POST /api/v1/asset/userAssetInfo
请求参数:
使用公有参数
响应参数:
| 字段名 | 描述 |
|---|---|
| userNo | 用户的UID编号 |
| 用户邮箱 | |
| timestamp | 系统时间戳(毫秒数) |
| result | 返回结果 |
| total | 总余额 |
| available | 可用余额 |
2. 查询委托单状态(根据委托单号)
请求示例:
{
"common":{
"accesskey" : "1900000109", // 通行证
"timestamp": "1500000000000", // 时间戳
"sign":"sdfsdfa1231231sdfsdfsd" // MD5加密签名
},
"data":{
"orderNoList":"1234123412,1234223452" // 委托单号列表字符串
}
}
返回示例:
{
"code":"1000",
"msg":"success",
"data":{
"timestamp":"1500000000123",
"result":[
{
"orderNo":"123412313", //委托订单号
"action":"SELL", //买卖类型
"orderType":"MKT", //委托单类型
"priceLimit":"0.00000000", //委托价格
"symbol":"ETC/BTC", //交易对
"quantity" :"0.00010000", //委托数量
"quantityRemaining":"0.00010000", //剩余数量
"amount":"0.00000000", //委托金额
"amountRemaining":"0.00000000", //剩余金额
"fee":"0.00000000", //手续费
"utcUpdate":"1500000000000", //最后成交时间
"utcCreate":"1500000000000", //委托时间
"state":"CANCEL" //委托单状态
},
...
]
}
}
功能描述:
获取用户的委托单状态(单次查询最大限50条记录)。
HTTP请求:
POST /api/v1/order/list
请求参数:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| orderNoList | 必填 | 要查询的委托单号列表(将委托单号拼接为字符串, 中间用英文逗号分隔开)单次最大查询单号为50条 |
响应参数:
| 字段名 | 描述 |
|---|---|
| timestamp | 时间戳(毫秒数) |
| result | 返回结果 |
| orderNo | 委托单号 |
| action | 买卖类型 SELL-卖, BUY-买 |
| orderType | 委托单类型 MKT-市价, LMT-限价 |
| priceLimit | 委托价格 |
| state | 委托单状态 UNDEAL:未成交, PARTDEAL:部分成交, DEAL:完全成交, CANCEL: 已撤销, PROCESSING: 处理中 |
| quantity | 委托数量 |
| quantityRemaining | 剩余数量 |
| amount | 委托金额 |
| amountRemaining | 剩余金额 |
| fee | 手续费(忽略, 请以成交明细中的fee和feeCurrency为准) |
| symbol | 交易对 |
| utcUpdate | 最后成交时间戳(毫秒级) |
| utcCreate | 委托时间戳(毫秒级) |
3. 查询订单交易详情(根据委托单号)
请求示例:
{
"common":{
"accesskey" : "1900000109", // 通行证
"timestamp": "1500000000", // 时间戳
"sign":"sdfsdfa1231231sdfsdfsd" // MD5加密签名
},
"data":{
"orderNoList":"1234123412,1234223452" // 委托单号列表字符串
}
}
返回示例:
{
"code":1000,
"msg":"success",
"data":{
"timestamp":"1500000000",
"result":[
{
"orderNo":"213412341", //委托单号
"priceLimit": "0.00000000", //委托价格
"quantity": "1.00000000", //委托数量
"symbol":"ETC/BTC", //交易币种
"action":"SELL", //买卖类型
"orderType":"MKT", //委托单类型
"quantityRemaining": "0.00000000", //剩余金额
"amount": "0.00000000", //委托金额
"amountRemaining": "0.00000000", //剩余金额
"state":"DEAL", //委托单状态
"detail":[
{
"matchType":"MAKER", //匹配类型
"price": "0.00213640", //交易价格
"volume": "0.42220000", //成交数量
"utcDeal":"123123412", //交易时间
"fee":"0.01", //交易手续费
"feeCurrency":"BTC" //手续费币种
},
...
]
}
...
]
}
}
功能描述:
获取用户已成交委托单详细交易信息(一次最大查询50条已成交委托单的交易详情信息)
HTTP请求:
/api/v1/order/details
请求参数:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| orderNoList | 必填 | 要查询的委托单号列表(将委托单号拼接为字符串, 中间用逗号分隔开) |
响应参数:
| 字段名 | 描述 |
|---|---|
| timestamp | 时间戳(毫秒数) |
| result | 返回结果 |
| orderNo | 委托单号 |
| priceLimit | 委托价格 |
| price | 交易价格 |
| quantity | 委托数量 |
| quantityRemaining | 委托剩余数量 |
| amount | 委托金额 |
| amountRemaining | 剩余金额 |
| volume | 成交数量 |
| action | 买卖类型 SELL-卖, BUY-买 |
| orderType | 委托单类型 MKT-市价, LMT-限价 |
| fee | 交易手续费(请以detail中的fee和feeCurrency为准) |
| feeCurrency | 交易手续费币种 |
| state | 委托单状态 UNDEAL:未成交, PARTDEAL:部分成交, DEAL:完全成交, CANCEL: 已撤销, PROCESSING: 处理中 |
| matchType | 匹配类型: MAKER-被动匹配, TAKER-主动匹配 |
| symbol | 交易对 |
| detail | 交易明细 |
| utcDeal | 交易时间戳(毫秒级) |
4. 查询委托单状态(根据客户自编订单号列表)
请求示例:
{
"common":{
"accesskey" : "1900000109", // 通行证
"timestamp": "1500000000000", // 时间戳
"sign":"sdfsdfa1231231sdfsdfsd" // MD5加密签名
},
"data":{
"clientOrderIdList":"8075ab7b-9888-11e9-a2a3-2a2ae2dbcca4,1561605101081" // 委托单号列表字符串
}
}
返回示例:
{
"code":"1000",
"msg":"success",
"data":{
"timestamp":1500000000123,
"result":[
{
"orderNo":"123412313", //委托订单号
"clientOrderId":"8075ab7b-9888-11e9-a2a3-2a2ae2dbcca4", //clientOrderId
"action":"SELL", //买卖类型
"orderType":"MKT", //委托单类型
"priceLimit":"0.00000000", //委托价格
"symbol":"ETC/BTC", //交易对
"quantity" :"0.00010000", //委托数量
"quantityRemaining":"0.00010000", //剩余数量
"amount":"0.00000000", //委托金额
"amountRemaining":"0.00000000", //剩余金额
"fee":"0.00000000", //手续费（忽略，请以成交明细(从details接口或历史成交接口等获取)中的手续费为准）
"utcUpdate":"1500000000000", //最后成交时间
"utcCreate":"1500000000000", //委托时间
"state":"CANCEL" //委托单状态
},
...
]
}
}
功能描述:
获取用户委托单状态(单次查询最大限50条记录)。
HTTP请求:
POST /api/v1/order/clList
请求参数:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| clientOrderIdList | 必填 | 要查询的自编订单号列表(将clientOrderId拼接为字符串，中间用英文逗号分隔开)单次最大查询单号为50条 |
响应参数:
| 字段名 | 描述 |
|---|---|
| timestamp | 时间戳(毫秒数) |
| result | 返回结果 |
| orderNo | 委托单号 |
| clientOrderId | 下单时传入的clientOrderId |
| action | 买卖类型 SELL-卖，BUY-买 |
| orderType | 委托单类型 MKT-市价，LMT-限价 |
| priceLimit | 委托价格 |
| state | 委托单状态 UNDEAL:未成交，PARTDEAL:部分成交，DEAL:完全成交，CANCEL: 已撤销，PROCESSING: 处理中 |
| quantity | 委托数量 |
| quantityRemaining | 剩余数量 |
| amount | 委托金额 |
| amountRemaining | 剩余金额 |
| fee | 手续费（忽略，请以成交明细(从details接口或历史成交接口等获取)中的手续费为准） |
| symbol | 交易对 |
| utcUpdate | 最后成交时间戳(毫秒级) |
| utcCreate | 委托时间戳(毫秒级) |
5. 挂单单号列表(个人未完全成交委托单列表)
请求示例:
{
"common":{
"accesskey" : "1900000109", // 通行证
"timestamp": "1500000000000", // 时间戳
"sign":"sdfsdfa1231231sdfsdfsd" // MD5加密签名
},
"data":{
"symbol":"ETC/BTC", // 交易对
"num":"1000" //返回的单号条数(最大不超过1000)
}
}
返回示例:
{
"code":"1000",
"msg":"success",
"data":{
"timestamp":"1500000000000",
"result":[
"1603147161792831491",
"1603147093327106049",
"1603147072028430337",
...
]
}
}
功能描述:
请求最新挂单单号列表(时间最近的委托单单号列表, 最多返回1000条)
HTTP请求:
POST /api/v1/order/openList
请求参数:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| symbol | 非必填 | 交易对, 若不填则查询所有交易对 |
| num | 必填 | 请求的单号条数, 最大不超过1000 |
响应参数:
| 字段名 | 描述 |
|---|---|
| timestamp | 时间戳(毫秒数) |
| result | 返回结果 |
6. 查询个人历史委托单列表
请求示例:
{
"common":{
"accesskey" : "1900000109", // 通行证
"timestamp": "1500000000000", // 时间戳
"sign":"sdfsdfa1231231sdfsdfsd" // MD5加密签名
},
"data":{
"symbol":"ETC/BTC", // 交易对
"utcStart":"1536818874583", // 查询开始时间
"utcEnd":"1536905274583", // 查询结束时间
"withTrade":"true" // 是否需要返回对应委托单的交易明细
}
}
返回示例:
{
"code":"1000",
"msg":"success",
"data":{
"timestamp":1500000000123,
"result":[
{
"orderNo":"123412313", //委托订单号
"action":"SELL", //买卖类型
"orderType":"MKT", //委托单类型
"priceAverage": "0.00000000",
"priceLimit":"0.00000000", //委托价格
"symbol":"ETC/BTC", //交易对
"quantity" :"0.00010000", //委托数量
"quantityRemaining":"0.00010000", //剩余数量
"amount":"0.00000000", //委托金额
"amountRemaining":"0.00000000", //剩余金额
"fee":"0.00000000", //手续费
"utcUpdate":"1500000000000", //最后成交时间
"utcCreate":"1500000000000", //委托时间
"state":"CANCEL", //委托单状态
"detail": [
{
"dealNo": "234234114241",
"matchType": "ACTIVE",
"price": "0.00001000",
"utcDeal": "1500000000000",
"volume": "1.4266",
"fee":"0.01",
"feeCurrency":"BTC"
},
{
"dealNo": "24234212312",
"matchType": "PASSIVE",
"price": "0.00001000",
"utcDeal": "1500000000000",
"volume": "0.00001000",
"fee":"0.01",
"feeCurrency":"BTC"
}
],
},
...
]
}
}
功能描述:
请求个人历史委托单列表
HTTP请求:
POST /api/v1/order/history
请求参数:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| symbol | 必填 | 交易对 |
| utcStart | 必填 | 查询开始时间(查询下单时间≥该时间的委托单, 毫秒时间戳。utcStart与utcEnd跨度不能超过一周) |
| utcEnd | 必填 | 查询结束时间(查询下单时间≤该时间的委托单,毫秒时间戳。utcStart与utcEnd跨度不能超过一周) |
| startOrderNo | 非必填 | 起始委托单号(查询单号>该单号) |
| withTrade | 非必填 | 是否需要返回对应委托单的交易明细(true-返回, false-不返回(小写)，默认不返回) |
| size | 非必填 | 查询条数(取值范围1~100) |
响应参数:
| 字段名 | 描述 |
|---|---|
| timestamp | 时间戳(毫秒数) |
| result | 返回结果 |
| orderNo | 委托单号 |
| action | 买卖类型 SELL-卖, BUY-买 |
| orderType | 委托单类型 MKT-市价, LMT-限价 |
| priceLimit | 委托价格 |
| priceAverage | 成交均价 |
| state | 委托单状态 UNDEAL:未成交, PARTDEAL:部分成交,DEAL:完全成交,CANCEL: 已撤销 |
| quantity | 委托数量 |
| quantityRemaining | 剩余数量 |
| amount | 委托金额 |
| amountRemaining | 剩余金额 |
| fee | 手续费(请以detail中的fee和feeCurrency为准) |
| feeCurrency | 交易手续费币种 |
| symbol | 交易对 |
| utcUpdate | 最后成交时间戳(毫秒级) |
| utcCreate | 委托时间戳(毫秒级) |
| detail | 交易明细 |
| matchType | 匹配类型: PASSIVE-被动匹配, ACTIVE-主动匹配 |
| dealNo | 交易单号 |
| volume | 成交数量 |
| price | 交易价格 |
| utcDeal | 交易时间戳(毫秒级) |
7. 查询个人历史成交列表
请求示例:
{
"common":{
"accesskey" : "1900000109", // 通行证
"timestamp": "1500000000000", // 时间戳
"sign":"sdfsdfa1231231sdfsdfsd" // MD5加密签名
},
"data":{
"symbol":"BTC/USD", // 交易对
"utcStart":"1536818874583", // 查询开始时间
"utcEnd":"1536905274583", // 查询结束时间
"withTrade":"true" // 是否需要返回对应委托单的交易明细
}
}
返回示例:
{
"code":"1000",
"msg":"success",
"data":{
"timestamp": "1500000000",
"result":[
{
"dealNo":"12312312312312", //交易单号
"symbol": "BTC/USD", //交易对
"matchType":"PASSIVE", //匹配类型
"orderNo":"32423412412", //委托单号
"orderType":"MKT", //匹配类型
"action":"SELL", //买卖类型
"price": "0.00213640", //交易价格
"volume": "0.42220000", //成交数量
"utcDeal": "123123412", //交易时间
"fee":"0.01", //交易手续费
"feeCurrency":"USD" //手续费币种
},
...
]
}
}
功能描述:
基于搜索条件查询个人历史成交列表
HTTP请求:
POST /api/v1/order/tradeHistory
请求参数:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| symbol | 非必填 | 交易对 |
| utcStart | 必填 | 查询开始时间(查询成交时间≥该时间的成交明细, 毫秒时间戳。utcStart与utcEnd跨度不能超过一周) |
| utcEnd | 必填 | 查询结束时间(查询成交时间≤该时间的成交明细, 毫秒时间戳。utcStart与utcEnd跨度不能超过一周) |
| startDealNo | 非必填 | 起始交易单号(查询单号>该单号) |
| size | 非必填 | 查询条数(取值范围1~100) |
响应参数:
| 字段名 | 描述 |
|---|---|
| timestamp | 时间戳(毫秒数) |
| result | 返回结果 |
| orderNo | 委托单号 |
| action | 买卖类型 SELL-卖, BUY-买 |
| orderType | 委托单类型 MKT-市价, LMT-限价 |
| symbol | 交易对 |
| matchType | 匹配类型: PASSIVE-被动匹配, ACTIVE-主动匹配 |
| dealNo | 交易单号 |
| volume | 成交数量 |
| price | 交易价格 |
| fee | 交易手续费 |
| feeCurrency | 交易手续费币种 |
| utcDeal | 交易时间戳(毫秒级) |
8. 可交易的交易对列表
请求示例:
{
"common":{
"accesskey" : "1900000109", // 通行证
"timestamp": "1500000000000", // 时间戳
"sign":"sdfsdfa1231231sdfsdfsd" // MD5加密签名
},
"data":{
}
}
返回示例:
{
"code":"1000",
"msg":"success",
"data":{
"timestamp":"1500000000000",
"result":[
{
"symbol": "BTC/USD", //交易对
"quantityMin": "0.00100000000", //quantity最小委托量
"quantityMax": "5000.00000000000", //quantity最大委托量
"priceMin": "0.00100000000", //amount最小委托量
"priceMax": "9999.00000000000", //amount最大委托量
"deviationRatio": "0.3", //委托价最大偏差系数
"quantityScale": "4", //挂单quantity精度
"amountScale": "2", //挂单amount精度
"priceScale": "2" //挂单价格精度
},
{
"symbol": "ETH/BTC", //交易对
"quantityMin": "0.00001000000", //quantity最小委托量
"quantityMax": "8000.00000000000", //quantity最大委托量
"priceMin": "0.00001000000", //amount最小委托量
"priceMax": "8000.00000000000", //amount最大委托量
"deviationRatio": "0.3", //委托价最大偏差系数
"quantityScale": "4", //挂单quantity精度
"amountScale": "8", //挂单amount精度
"priceScale": "8" //挂单价格精度
},
...
]
}
}
功能描述:
查询当前可交易的交易对列表
HTTP请求:
POST /api/v1/market/symbolList
请求参数:
使用公有参数
响应参数:
| 字段名 | 描述 |
|---|---|
| timestamp | 时间戳(毫秒数) |
| result | 返回结果 |
| symbol | 交易对 |
| quantityMin | quantity最小委托量 |
| quantityMax | quantity最大委托量 |
| priceMin | amount最小委托量 |
| priceMax | amount最大委托量 |
| deviationRatio | 委托价最大偏差系数(下单时，委托价格需在该范围内: (1-deviationRatio)x最新成交价<=委托价<=(1+deviationRatio)x最新成交价。其中最新成交价来自/api/v1/market/tickers接口第一条数据的价格) |
| quantityScale | 挂单quantity精度 |
| amountScale | 挂单amount精度 |
| priceScale | 挂单价格精度 |
FIX API
1. 全局规则
接口访问地址信息
- 接口访问地址:
| 序号 | 接口访问域名 | 说明 |
|---|---|---|
| 1 | apifix.coinsuper.info | 主域名 |
接口访问端口: 1443
接口访问协议: TCP(SSL)
接口规则
- 采用SSL socket长连接访问
- 接口请求均采用 FIX(4.4) 协议
- 接口统一请求数据满足FIX协议数据格式
- 接口统一返回数据满足FIX协议数据格式
- 当服务端接收到用户请求后, 会在稍后进行相应, 具体的响应格式参考下列参数列表
- 接口调用前均需要登录, 登录方式及参数请参考下列参数列表
全局数据格式定义
参数约定
- 参数说明:
1.1 请求参数:
客户端固定参数:
BeginString=FIX.4.4
TargetCompID=COINSUPER
HeartBtInt=30
1.2 响应参数:
具体响应信息请参考下方接口列表, 异常说明请参考下方的【全局通用状态码】表。 - 业务参数精度:
请以symbolList接口返回的scale数据为准。 - 签名:
所有请求均需要按本文档中的签名规则传递参数签名, 签名生成规则请参考下方的参数签名规范。 - 其它行情数据等可通过REST接口或WebSocket接口获取。
- 发送请求之前, 需先发送Logon消息进行登录。
登录签名描述
交易所将对请求数据的内容进行验签, 以确定携带的信息是否未经篡改, 因此定义生成 sign 字符串的方法。
a. Logon请求中, 将SendingTime, MsgType, MsgSeqNum, SenderCompID, TargetCompID, $secretKey将参数按参数名从小到大排序, 并用","连接进行组合md5加密签名生成签名sign。
b. Logon请求中, SendingTime, MsgType, MsgSeqNum, SenderCompID, TargetCompID为必传字段。
c. 为了账户安全, Logon请求中, 请勿传递$secretKey。
d. Logon请求中, 将sign作为RawData设置到Logon的message中, sign中的字母请采用小写。
签名生成方法示例
假设有一个调用请求, 其中,
$accesskey : zhangsan,
$secretkey : zhangsan,
TargetCompID : SERVERTARGET
Logon请求参数如下:
"MsgSeqNum" -> "1"
"MsgType" -> "A"
"SenderCompID" -> "zhangsan"
"SendingTime" -> "20181228-13:08:08.091"
"TargetCompID" -> "SERVERTARGET"
i: 经过 a 过程排序后的字符串 string 为:
1,A,zhangsan,20181228-13:26:54.497,SERVERTARGET,zhangsan
ii: 经过 b 过程后得到 sign 为 :
signValue = md5(string)
完整请求数据 :
8=FIX.4.49=11735=A34=149=zhangsan52=20181228-13:26:54.49756=SERVERTARGET95=3296=74c544ec967aae34fe84a30bae59520798=0108=3010=188
FIX请求标准消息头
注: 每个接口请求必须传递的消息参数, 具体使用方式请参考下方接口定义及请求示例
| 字段名 | 字段Code | 填写类型 | 描述 |
|---|---|---|---|
| BeginString | 8 | 必填 | FIX协议版本(固定值: FIX.4.4) |
| BodyLength | 9 | 必填 | 消息长度的字节数. 永远在整条消息的第二个字段(不加密). |
| MsgType | 35 | 必填 | 请求消息类型 |
| MsgSeqNum | 34 | 必填 | 整型消息序列号. |
| SenderCompID | 49 | 必填 | $accesskey, 通过开通API获得 |
| SendingTime | 52 | 必填 | 请求发送时间(UTC时间) |
| TargetCompID | 56 | 必填 | 服务端标识符, 请参考上方[登录签名描述] |
全局通用异常信息
| 异常text | 异常描述 |
|---|---|
| user not exist! | 错误的TargetCompID |
| has no authentication | 无对应的接口访问权限 |
| request too frequently | 请求超过限流值 |
| SendingTime accuracy problem | 客户端UTC时间和服务端UTC时间不匹配(请对照标准世界时) |
| system internal error | 系统内部异常 |
2. 详细接口定义
1. 会话类
1.1 登录
请求示例:
8=FIX.4.49=11435=A34=249=zhangsan52=20190102-03:41:14.32956=COINSUPER95=3296=6cc719376923d980cbb5c882191d4e2898=0108=3010=058
返回示例:
8=FIX.4.49=7235=A34=449=COINSUPER52=20190102-03:41:14.46156=zhangsan98=0108=3010=011
功能描述:
登录请求(会话长连接由登录成功时创建, 其他所有请求都需依赖登录成功)
请求MsgType:
Logon(A)
接口请求参数:
| 字段名 | 字段Code | 填写类型 | 描述 |
|---|---|---|---|
| SendingTime | 52 | 必填 | 请求发送时间(UTC时间) |
| MsgType | 35 | 必填 | 消息类型 |
| MsgSeqNum | 34 | 必填 | 消息序列号 |
| SenderCompID | 49 | 必填 | API用户accessKey |
| TargetCompID | 56 | 必填 | 固定参数, 请使用上方[参数约定]中描述的值 |
| RawData | 96 | 必填 | 登录参数签名( 签名规则请参考上方[登录签名描述] ) |
响应MsgType:
Logon(A)
响应参数:
| 字段名 | 字段Code | 描述 |
|---|---|---|
| ClOrdID | 11 | 用户的编号 |
| OrderID | 37 | 用户邮箱 |
| ExecType | 150 | 系统时间戳(毫秒数) |
| OrdStatus | 39 | 返回结果 |
| TransactTime | 60 | 总余额 |
1.2 注销
请求示例:
8=FIX.4.49=11435=534=249=zhangsan52=20190102-03:41:14.32956=COINSUPER95=3296=6cc719376923d980cbb5c882191d4e2898=0108=3010=058
返回示例:
8=FIX.4.49=7235=534=449=COINSUPER52=20190102-03:41:14.46156=zhangsan98=0108=3010=011
功能描述:
注销请求, 发起后将会关闭会话长连接
请求MsgType:
Logout(5)
接口请求参数:
无
响应MsgType:
Logout(5)
响应参数:
无
1.3 心跳
请求示例:
8=FIX.4.49=6035=034=349=zhangsan52=20190102-07:31:01.57256=COINSUPER10=223
返回示例:
8=FIX.4.49=6235=034=46349=COINSUPER52=20190102-07:31:01.69056=zhangsan10=076
功能描述:
心跳请求, 固定时间发送, 用于维持会话长连接, 服务端30秒内仅会响应一次
请求MsgType:
Heartbeat(0)
接口请求参数:
无
响应MsgType:
Heartbeat(0)
响应参数:
无
2. 交易类
2.1 下单委托
请求示例:
8=FIX.4.49=16735=D34=3249=zhangsan52=20190104-10:08:43.31456=COINSUPER11=ord000138=0.340=244=450054=255=BTC/USD60=20190104-18:08:43.308152=010=091
返回示例:
8=FIX.4.49=22335=834=18349=COINSUPER52=20190104-10:08:42.34256=zhangsan6=014=017=a0cbfd23455e4b6faaacbe5fb36caf9920=037=162172399493790924939=054=255=BTC/USD60=20190104-18:08:42.341150=0151=0.310=036
功能描述:
交易下单委托请求
请求MsgType:
NewOrderSingle(D)
接口请求参数:
| 字段名 | 字段Code | 填写类型 | 描述 |
|---|---|---|---|
| ClOrdID | 11 | 必填 | 客户端自定义的订单ID(不能重复) |
| Symbol | 55 | 必填 | 交易对 |
| Price | 44 | 必填 | 成交限价(限价单专用, 市价单请传入0) |
| Side | 54 | 必填 | 买卖类型( BUY(1)=买单, SELL(2)=卖单 ) |
| OrdType | 40 | 必填 | 委托单类型( MARKET(1)=市价,LIMIT(2)=限价 ) |
| OrderQty | 38 | 必填 | 标的币数量(限价买, 限价卖, 市价卖时使用。市价买请填0) |
| CashOrderQty | 152 | 必填 | 计价币数量(市价买时使用。限价买, 限价卖, 市价卖时请填0) |
| TransactTime | 60 | 必填 | 请求时间(UTC时间) |
响应MsgType:
ExecutionReport(8)
响应参数:
| 字段名 | 字段Code | 描述 |
|---|---|---|
| ClOrdID | 11 | 客户端自定义的订单ID |
| OrderID | 37 | 服务端生成的订单ID |
| ExecType | 150 | 执行结果(固定为NEW) |
| OrdStatus | 39 | 委托状态(固定为NEW) |
| TransactTime | 60 | 响应消息发送时间(UTC时间) |
| 异常text | 异常描述 |
|---|---|
| symbol not trading | 交易对不能交易 |
| order amount or quantity less than min setting | 交易数量小于要求的值 |
| price out of range | 价格超出范围 |
| action not support | 不支持的交易类型 |
| order type not support | 不支持的订单类型 |
| user account forbidden | 账户禁止交易 |
| balance not enough | 余额不足 |
2.2 撤单委托
请求示例:
8=FIX.4.49=11235=F34=6549=zhangsan52=20190104-09:40:25.49556=COINSUPER37=162172076101837209710=112
返回示例:
8=FIX.4.49=15435=834=12749=COINSUPER52=20190104-09:40:24.38956=zhangsan20=137=162172076101837209739=460=20190104-17:40:24.389150=410=041
功能描述:
交易撤单委托请求
请求MsgType:
OrderCancelRequest(F)
接口请求参数:
| 字段名 | 字段Code | 填写类型 | 描述 |
|---|---|---|---|
| OrderID | 37 | 必填 | 服务端生成的订单ID |
| ClOrdID | 11 | 必填 | 客户端自定义的订单ID |
响应MsgType:
ExecutionReport(8)
响应参数:
| 字段名 | 字段Code | 描述 |
|---|---|---|
| OrderID | 37 | 服务端生成的订单ID |
| ExecType | 150 | 执行结果(撤单处理中: PENDING_CANCEL) |
| OrdStatus | 39 | 委托状态(撤单处理中: PENDING_CANCEL) |
| TransactTime | 60 | 响应消息发送时间(UTC时间) |
| 异常text | 异常描述 |
|---|---|
| order no not exist | 未完成订单不存在 |
| order has canceled | 订单已撤销 |
| order has execute | 订单已成交 |
2.3 成交消息
返回示例:
8=FIX.4.49=24735=834=40449=COINSUPER52=20190402-11:24:46.89056=pkucestestkey6=123.5711=925418490717412=0.00214=117=05bbb56b8c074ab1aa07e970404c95e432=137=162970131356271001739=244=123.5754=155=ETH/USD60=20190402-19:24:46.890150=F151=0479=ETH10=177
功能描述:
当订单有成交时(部分成交和完全成交)会向客户端推送一条消息返回成交数据。这完全由系统主动发起, 客户端只需要被动接收。
响应MsgType:
ExecutionReport(8)
响应参数:
| 字段名 | 字段Code | 描述 |
|---|---|---|
| OrderID | 37 | 服务端生成的订单ID |
| ClOrdID | 11 | 客户端的订单 id |
| Side | 54 | 买卖单类型(1-买单, 2-卖单) |
| ExecType | 150 | 返回消息类型(F-交易) |
| OrdStatus | 39 | 订单状态(1-部分成交, 2-完全成交) |
| AvgPx | 6 | 此订单的平均成交价 |
| CumQty | 14 | 已成交的总数量 |
| LeavesQty | 151 | 剩余成交数量(CumQty+LeavesQty=下单时总数量) |
| Symbol | 55 | 交易对 |
| Price | 44 | 成交价格 |
| LastQty | 32 | 本次成交数量 |
| Commission | 12 | 本次成交时的手续费 |
| CommCurrency | 479 | 本次成交时的手续费币种 |
| TransactTime | 60 | 响应消息发送时间(UTC时间) |
3. 信息查询类
3.1 查询未完成订单
请求示例:
8=FIX.4.49=11235=H34=1849=zhangsan52=20190104-10:01:52.86256=COINSUPER37=162172183852353945710=111
返回示例:
8=FIX.4.49=22335=834=16949=COINSUPER52=20190104-10:01:51.70456=dba8ef1f-6e3f-43ed-ae67-0668c3e933636=014=017=37e01f58367948fdaedf8dace2ea62ff20=337=162172183852353945739=A54=255=BTC/USD60=20190104-18:01:51.704150=I151=0.210=199
功能描述:
查询未全部成交且未撤销的委托单
请求MsgType:
OrderStatusRequest(H)
接口请求参数:
| 字段名 | 字段Code | 填写类型 | 描述 |
|---|---|---|---|
| OrderID | 37 | 必填 | 服务端生成的订单ID(*表示查询最近20条下单信息) |
| ClOrdID | 11 | 必填 | 客户端自定义的订单ID |
响应MsgType:
ExecutionReport(8)
响应参数:
| 字段名 | 字段Code | 描述 |
|---|---|---|
| OrderID | 37 | 服务端生成的订单ID |
| Side | 54 | 买卖类型( BUY(1)=买单, SELL(2)=卖单 ) |
| ExecType | 150 | 执行结果(ORDER_STATUS) |
| OrdStatus | 39 | 委托状态(PENDING_NEW/PARTIALLY_FILLED) |
| AvgPx | 6 | 订单成交均价 |
| CumQty | 14 | 已成交数量 |
| LeavesQty | 151 | 剩余未成交数量 (CumQty+LeavesQty=下单时总数量) |
| Symbol | 55 | 交易对 |
| TransactTime | 60 | 响应消息发送时间(UTC时间) |
| 异常text | 异常描述 |
|---|---|
| order no not exist | 未完成订单不存在 |
WebSocket API
1. 全局规则
接口规则
- 所有接口均需要提前订阅
- 采用WebSocket方式推送
- 接口统一推送数据为 JSON 格式订阅
- 当某一字段无数据时, 该字段不返回数据(若返回类型为数组, 则会返回空数组)
- 订阅客户端若链接断掉, 请自行制定断线重连策略进行重新链接及订阅
- 客户端需要通过特定方式发送指定的参数进行订阅
订阅参数约定
1. 公共行情订阅参数
1. 服务端域名与端口:
| 序号 | host | port | isSSL | 说明 |
|---|---|---|---|---|
| 1 | apimqtt.coinsuper.info | 1883 | false | mqtt客户端连接参数 |
| 2 | apiwss.coinsuper.info | 443 | true | Javascript WebSocket客户端连接参数 |
2. 客户端ID:
每个用户拥有自己的客户端ID, 若不按以下规则, 可能接收不了服务端推送的数据。
客户端ID生成方式: md5(access_key) + md5(email) + md5(topic) 即: 将自身的API access_key与email账号、订阅的完整topic分别做32位小写md5后进行拼接(直接拼接, 无需分隔符)。
3. 订阅者用户名(userName):
api_subscriber
4. 订阅者识别码(userCode):
da65be18f44b33b69603c39fd03ddf49
5. 订阅topic:
topic=$env$subTopic
其中$env=exchange_ha_prod_hk, $subTopic详见下方详细接口定义
2. 用户私有数据订阅参数
1. 服务端域名与端口:
| 序号 | host | port | isSSL | 说明 |
|---|---|---|---|---|
| 1 | apimqtt.coinsuper.info | 1883 | false | mqtt客户端连接参数 |
| 2 | apiwss.coinsuper.info | 443 | true | Javascript WebSocket客户端连接参数 |
2. 客户端ID:
clientId = $access_key
3. 订阅者用户名(userName):
userName = api_private
4. 订阅者识别码(userCode):
userCode=$email+","+$timeStamp+","+$sign
5. 订阅topic:
topic=$env$subTopic
其中$env=exchange_ha_prod_hk, $subTopic详见下方详细接口定义
2. 详细接口定义
API 接口定义
1. 行情
1.1 价格行情(最新订单簿数据)
topic示例:
exchange_ha_prod_hk/api/ws/v1/market/orderBook/BTC_USD/0.01
推送示例:
{"asks":[{"amount":"349.76","limitPrice":"6674.89","quantity":"0.0524"},{"amount":"1601.32","limitPrice":"6674.96","quantity":"0.2399"},{"amount":"1744.18","limitPrice":"6675.02","quantity":"0.2613"},{"amount":"3495.73","limitPrice":"6675.08","quantity":"0.5237"},{"amount":"1987.85","limitPrice":"6675.13","quantity":"0.2978"},{"amount":"1614.04","limitPrice":"6675.14","quantity":"0.2418"},{"amount":"556.03","limitPrice":"6675.15","quantity":"0.0833"},{"amount":"3542.57","limitPrice":"6675.29","quantity":"0.5307"},{"amount":"1948.53","limitPrice":"6675.34","quantity":"0.2919"},{"amount":"1073.40","limitPrice":"6675.39","quantity":"0.1608"},{"amount":"1230.94","limitPrice":"6675.40","quantity":"0.1844"},{"amount":"1293.70","limitPrice":"6675.47","quantity":"0.1938"},{"amount":"1696.24","limitPrice":"6675.50","quantity":"0.2541"},{"amount":"1169.55","limitPrice":"6675.52","quantity":"0.1752"},{"amount":"658.87","limitPrice":"6675.55","quantity":"0.0987"}],"bids":[{"amount":"5666.70","limitPrice":"6674.56","quantity":"0.8490"},{"amount":"817.97","limitPrice":"6617.89","quantity":"0.1236"},{"amount":"336.18","limitPrice":"6617.84","quantity":"0.0508"},{"amount":"1715.64","limitPrice":"6616.43","quantity":"0.2593"},{"amount":"1926.69","limitPrice":"6616.40","quantity":"0.2912"},{"amount":"1663.90","limitPrice":"6615.92","quantity":"0.2515"},{"amount":"1404.30","limitPrice":"6614.73","quantity":"0.2123"},{"amount":"448.47","limitPrice":"6614.69","quantity":"0.0678"},{"amount":"1738.04","limitPrice":"6613.57","quantity":"0.2628"},{"amount":"945.71","limitPrice":"6613.39","quantity":"0.1430"},{"amount":"1605.04","limitPrice":"6613.28","quantity":"0.2427"},{"amount":"942.30","limitPrice":"6612.69","quantity":"0.1425"},{"amount":"1768.89","limitPrice":"6612.68","quantity":"0.2675"},{"amount":"840.35","limitPrice":"6611.76","quantity":"0.1271"},{"amount":"1350.11","limitPrice":"6611.72","quantity":"0.2042"}],"limitSize":15,"step":"0.01","symbol":"BTC/USD","timestamp":1532686075803}
功能描述:
订阅当前订单簿行情数据(买盘和卖盘每次最多各返15条)
订阅topic:
$env/api/ws/v1/market/orderBook/$topicSymbol/$step
推送频率:
每1~2秒1次(视客户端网络情况, 客户端接收到的时间有所不同)
topic参数说明:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| topicSymbol | 必填 | 订阅交易对 |
| step | 必填 | 聚合深度(各个交易对有各自的step, 可选值:请参考WEB官网或APP行情页面的订单薄查看各个交易对的可选精度, 其中最大精度可参考REST接口中, symbolList接口的priceScale值) |
推送字段说明:
| 字段名 | 描述 |
|---|---|
| symbol | 交易对 |
| step | 深度 |
| timestamp | 时间戳(毫秒数) |
| limitSize | 订单最大推送条数 |
| asks | 卖盘深度数据 |
| bids | 买盘深度数据 |
| limitPrice | 委托价格。注: 交易对价格精度请参考symbolList接口 |
| quantity | 数量。注:交易对数量精度请参考symbolList接口 |
| amount | 待移除字段, 请忽略 |
1.2 分时行情(最新K线数据)
topic示例:
exchange_ha_prod_hk/api/ws/v1/market/kline/BTC_USD/60000
推送示例:
{"symbol":"BTC/USD","first":"6616.40","last":"6616.45","max":"6616.48","min":"6616.40","quantity":"31.76239814","timestamp":1532686140000}
功能描述:
根据K线周期获取K线行情数据(每次推送1条数据)
订阅topic:
$env/api/ws/v1/market/kline/$topicSymbol/$range
推送频率:
每1~2秒1次(视客户端网络情况, 客户端接收到的时间有所不同)
topic参数说明:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| topicSymbol | 必填 | 订阅交易对 |
| range | 必填 | K线周期(1分钟:60000, 5分钟:300000, 15分钟:900000, 30分钟:1800000, 1小时:3600000, 2小时:7200000, 4小时:14400000, 6小时:21600000, 12小时:43200000, 1天:86400000, 1周:604800000) |
推送字段说明:
| 字段名 | 描述 |
|---|---|
| symbol | 交易对 |
| range | K线周期 |
| timestamp | 时间戳(毫秒数) |
| quantity | 交易量 |
| max | 最高价 |
| min | 最低价 |
| first | 开盘价 |
| last | 收盘价 |
1.3 实时成交行情(最新成交行情数据)
topic示例:
exchange_ha_prod_hk/api/ws/v1/market/tickers/BTC_USD
推送示例:
[{"symbol":"BTC/USD","price":"6089.34","quantity":"0.4337","action":"BUY","timestamp":1532623321348},{"symbol":"BTC/USD","price":"6088.84","quantity":"0.0010","action":"BUY","timestamp":1532607467417},{"symbol":"BTC/USD","price":"6088.84","quantity":"0.2197","action":"SELL","timestamp":1532606712073},{"symbol":"BTC/USD","price":"6311.06","quantity":"0.1760","action":"BUY","timestamp":1532590562930},{"symbol":"BTC/USD","price":"6311.06","quantity":"0.0010","action":"SELL","timestamp":1532590547420},{"symbol":"BTC/USD","price":"6311.50","quantity":"0.8951","action":"SELL","timestamp":1532587958810},{"symbol":"BTC/USD","price":"6314.70","quantity":"0.0158","action":"SELL","timestamp":1532398791628},{"symbol":"BTC/USD","price":"6674.89","quantity":"0.0008","action":"SELL","timestamp":1532090050033},{"symbol":"BTC/USD","price":"6674.89","quantity":"0.0801","action":"SELL","timestamp":1531987659236},{"symbol":"BTC/USD","price":"6674.87","quantity":"0.2954","action":"SELL","timestamp":1531987655248},{"symbol":"BTC/USD","price":"6674.85","quantity":"0.1632","action":"SELL","timestamp":1531987653252},{"symbol":"BTC/USD","price":"6674.83","quantity":"0.1153","action":"SELL","timestamp":1531987651953},{"symbol":"BTC/USD","price":"6674.80","quantity":"0.2112","action":"SELL","timestamp":1531987651001},{"symbol":"BTC/USD","price":"6674.74","quantity":"0.2580","action":"SELL","timestamp":1531987646413},{"symbol":"BTC/USD","price":"6674.72","quantity":"0.1417","action":"SELL","timestamp":1531987643644},{"symbol":"BTC/USD","price":"6674.67","quantity":"0.2332","action":"SELL","timestamp":1531987642840},{"symbol":"BTC/USD","price":"6674.61","quantity":"0.1909","action":"BUY","timestamp":1531987599048},{"symbol":"BTC/USD","price":"6674.56","quantity":"0.1510","action":"BUY","timestamp":1531987571826},{"symbol":"BTC/USD","price":"6674.56","quantity":"0.0946","action":"BUY","timestamp":1531118165770},{"symbol":"BTC/USD","price":"6674.49","quantity":"0.1612","action":"BUY","timestamp":1531118165685}]
功能描述:
请求最新成交行情数据(每次最多推送50条)
订阅topic:
$env/api/ws/v1/market/tickers/$topicSymbol
推送频率:
每1~2秒1次(视客户端网络情况, 客户端接收到的时间有所不同)
topic参数说明:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| topicSymbol | 必填 | 订阅交易对 |
推送字段说明:
| 字段名 | 描述 |
|---|---|
| symbol | 交易对 |
| timestamp | 交易时间(时间戳) |
| quantity | 交易数量 |
| price | 交易价格 |
| action | 交易类型 BUY-买,SELL-卖 |
2. 用户私有数据
2.1 用户账户资产变更
topic示例:
exchange_ha_prod_hk/api/ws/personal/v1/asset/change/demouser@demo.domain
推送示例:
{"asset":[{"available":0.738763122563248000000000000000,"currency":"BTC","total":1.306763122563248000000000000000,"utcUpdate":1542786801575},{"available":3226.058257880000000000000000000000,"currency":"USD","total":3226.058257880000000000000000000000,"utcUpdate":1542786801518}],"email":"demouser@demo.domain","timestamp":1542786802283,"userNo":"1600000000000000000"}
功能描述:
订阅自身的账户变更后的资产数据。为了保障资金信息安全, 资产变更推送接口需要在官方API技术群申请获批后才能正常使用。(请注意, 该topic的推送数据有可能会漏推送或重复推送)
订阅topic:
$env/api/ws/personal/v1/asset/change/$email
topic参数说明:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| 必填 | 用户账户邮箱 |
推送字段说明:
| 字段名 | 描述 |
|---|---|
| userNo | 用户编号 |
| 用户账户邮箱 | |
| total | 总余额 |
| available | 可用余额 |
| currency | 资产名称 |
| utcUpdate | 更新时间 |
| timestamp | 查询时间 |
2.2 订单状态变更
topic示例:
exchange_ha_prod_hk/ws/personal/v1/order/change/demouser@demo.domain
推送示例:
{"action":"SELL","amount":"0.00000000","amountRemaining":"0.00000000","fee":"0.00000000","orderNo":"1616391691960328193","orderType":"MKT","priceAverage":"1234.56000000","priceLimit":"1234.56000000","quantity":"100.00000000","quantityRemaining":"99.97894000","state":"CANCEL","symbol":"ETC/BTC","utcCreate":"1541511242411","utcUpdate":"1541511806925"}
功能描述:
订阅用户订单状态变更数据(目前仅支持委托单新建及撤销两种状态的推送。请注意, 该topic的推送数据有可能会漏推送或重复推送)
订阅topic:
$env/api/ws/personal/v1/order/change/$email
topic参数说明:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| 必填 | 用户账户邮箱 |
推送字段说明:
| 字段名 | 描述 |
|---|---|
| symbol | 交易对 |
| orderNo | 委托单号 |
| quantity | 委托数量 |
| quantityRemaining | 剩余数量 |
| priceLimit | 委托价格 |
| action | 交易类型 BUY-买,SELL-卖 |
| priceAverage | 成交均价 |
| amount | 委托金额 |
| amountRemaining | 剩余金额 |
| fee | 手续费(忽略, 请以成交明细中的fee和feeCurrency为准) |
| state | 委托单状态 NEW:新建, CANCEL: 已撤销 |
| utcCreate | 委托时间戳(毫秒级) |
| utcUpdate | 更新时间戳(毫秒级) |
2.3 订单成交信息
topic示例:
exchange_ha_prod_hk/ws/personal/v1/trade/change/demouser@demo.domain
推送示例:
{"action":"BUY","dealNo":"1616392748072460289","fee":"0.30000000","feeCurrency":"ETC","matchType":"TAKER","orderNo":"1616392747273428993","orderType":"MKT","price":"1234.56000000","quantity":"0.00081000","symbol":"ETC/BTC","utcDeal":"1541512249094"}
功能描述:
订阅用户的订单成交信息(请注意, 该topic的推送数据有可能会漏推送或重复推送)
订阅topic:
$env/api/ws/personal/v1/trade/change/$email
topic参数说明:
| 字段名 | 填写类型 | 描述 |
|---|---|---|
| 必填 | 用户账户邮箱 |
推送字段说明:
| 字段名 | 描述 |
|---|---|
| dealNo | 交易单号 |
| orderNo | 委托单号 |
| orderType | 委托单类型 MKT-市价, LMT-限价 |
| symbol | 交易对 |
| matchType | 匹配类型: MAKER-被动匹配, TAKER-主动匹配 |
| utcDeal | 交易时间(时间戳) |
| quantity | 交易数量 |
| price | 交易价格 |
| action | 交易类型 BUY-买,SELL-卖 |
| fee | 交易手续费(请以detail中的fee和feeCurrency为准) |
| feeCurrency | 交易手续费币种 |
更新日志
| 版本 | 时间 | 说明 | 作者 |
|---|---|---|---|
| v1.0.1(R) | 20180626 | 创建文档 | liyong |
| v1.0.1(α) | 20180731 | 新增WebSocket接口 | liyong |
| v1.0.1(β) | 20181129 | 接口进行分组限流 | liyong |
| v1.0.1(R) | 20190117 | 新增FIX接口 | liyong |
| v1.0.2(α) | 20190715 | 下单和订单状态查询支持clientOrderId | liyong |
| v1.0.3 | 20191009 | 新增REST批量下单接口 | liyong |
| v1.0.4 | 20191120 | 公共REST行情接口不需要API Key | liyong |
常见问题
点击此处查看常见问题
联系我们
如需帮助请加入以下API问题交流群(加入申请备注:Coinsuper email 账号):
| 序号 | 联系方式 |
|---|---|
| 1 | QQ群: 472488338 |
| 2 | Telegram电报群: https://t.me/joinchat/HEgiSxBKVx6nwQ33otJ3Zg |
同时，我们有一份关于Coinsuper Exchange API的调研问卷，期待收到您的反馈。
点击填写问卷: https://jinshuju.net/f/oV7zxP